Skip to main content

SmartApp Basics

SmartApps are custom applications that execute outside of the SmartThings Platform. All of the SmartApp execution will happen on the server or Lambda that you control. The complexity of execution and the number of expected users will need to be examined to understand the hardware or execution requirements your app needs to handle. Your application will respond to lifecycle events sent from SmartThings to perform actions on behalf of your users and will execute any scheduled tasks that you have created in the SmartApp.

There are typically three types of SmartApps you can create. Which one you choose will depend entirely on your specific application. Choosing to start with a Simple SmartApp will not preclude you from enabling more advanced features later.

Simple SmartApp#

If you need to create something more complex than a rule, but do not need to hold outside authentication information or other data, you will use a simple SmartApp. We have created an example tutorial on building a simple SmartApp that sets the color of a light based on the weather in a given zip code.

https://community.smartthings.com/t/simple-smartapp-tutorial-smartapp-sdk/194664

Services with a Complex SmartApp#

If your SmartApp needs to allow external communication or authentication with a third party, you will need a context store. We have created a tutorial on building a SmartApp with Context Store here:

https://community.smartthings.com/t/endpoint-smartapps-with-file-store-contexts/219761

Cloud Connected Devices with SmartApp Connectors#

It is possible to create and control cloud connected devices with a SmartApp. For more complete instructions on how to work with cloud connected devices please visit the Devices documentation section.

Execution Timeout#

An execution timeout is enforced for every request sent to a SmartApp from the SmartThings cloud. If the SmartApp does not respond within 10 seconds, a TargetTimeoutError will be thrown and any later responses from the SmartApp ignored for that request.

InstalledApp#

An InstalledApp is the user’s instance of the app you have created. These installs include details of the installations like the access the app has, the subscriptions setup, and the schedules created for the app. The InstalledApp is attached to the user account of the end user who installed it.

When an installedApp is uninstalled by the user, all tokens, subscriptions, and schedules associated with that install will be revoked.

Configuration#

This lifecycle event allows you to send configuration information from the user to your backend service.

Read More about configuration here.

Subscriptions#

Subscriptions allows for an installed application to listen for events, and react to them as necessary. For example, assuming you granted permission to the devices during app installation, you could subscribe to a motion sensor and turn on lights when motion is detected. Common use cases for subscriptions include:

  • Allowing a third party to sync a remote system
  • Allowing an App to react to a device event which can trigger other actions to occur
  • Allowing a third party to gather analytics on how their devices are behaving

Subscriptions are sent to the webhook callback Url or Lambda function defined in your SmartApp configuration.

Read More about subscriptions here.

Schedules#

Schedules allow an InstalledApp to be notified via the same method as a subscription that a scheduled event has occurred. These scheduled events are either a one time event or an event that triggers on a recurring basis set up using a cron expression.

Read More about scheduling here.