SmartApp Basics

You develop a SmartApp either to integrate a third-party cloud-to-cloud device into SmartThings Cloud, or to create an Automation. You can combine both the Automation and the device integration in a single SmartApp, or you can create them in separate SmartApps.

Basic concept

The basic concept of a SmartApp is as follows:

  • The SmartApp can either be an AWS Lambda function, or a WebHook endpoint with a RESTful API interface.
  • A WebHook endpoint in this context is a web services application, that is, an API endpoint on the internet, which can receive incoming HTTP POST requests. You can write and host your application / API endpoint using the language and the tools of your choice. However, the WebHook endpoint must be an HTTPS URL.
  • To publish your application, you must register your WebHook endpoint or Lambda function on Developer Workspace. See App Registration.
  • Next you will need to implement lifecycle event handlers in your WebHook endpoint or Lambda function to complete the integration. And you will also need to implement the event handlers for the device events from the device cloud. See Lifecycles for a comprehensive overview of lifecycles, and SmartApp API reference for the API your SmartApp must implement.
  • When the integration is complete, your SmartApp will begin a lifecycle, and will interact with SmartThings Cloud on a lifecycle phase-basis.

Interaction with SmartThings Cloud

A SmartApp comes to exist when it is successfully registered in SmartThings Cloud, and continues its life until it is uninstalled by the end-user. Throughout its lifecycle, the SmartApp is called by SmartThings Cloud during specific lifecycle phases. The SmartApp, in turn, can call into the SmartThings RESTful API.

Automation

For example, consider an Automation. When the end-user configures the Automation to monitor an open/close sensor, the Automation subscribes to open/close sensor events. SmartThings Cloud waits on these open/close sensor events. Anytime an open/close event occurs, it is first noticed by SmartThings Cloud, which then calls back the SmartApp.

In this way, SmartThings Cloud is constantly listening to the Automation-specific lifecycle events generated in SmartThings Cloud, and is making RESTful calls to Automation, always associating each call with a particular lifecycle phase.

Cloud Connector

Similarly, consider a cloud-to-cloud device integration. To communicate with a cloud-to-cloud device and SmartThings Cloud, create a Connector using SmartApp or SmartThings Schema.

For example, assume that you create a Connector for LIFX bulb using SmartApp. With this integration the LIFX bulb will appear in the end-user’s SmartThings app. The end-user can then view and actuate this LIFX bulb from an Automation within the SmartThings app. For example, when the end-user turns on the LIFX bulb in the mobile app, SmartThings Cloud notices this device command, and calls the SmartApp with the device command. The SmartApp then relays this device command to the LIFX cloud, which then sends the on command to the LIFX bulb, and the user’s mobile app is updated.

In addition to the lifecycle event handlers for SmartThings Cloud, a SmartApp can contain other functionality. For example it can interface with a third-party service, or it can define its own user interface.