Skip to main content

Connect Your Device with a SmartApp

You can use a SmartApp to connect your Cloud Connected Device to the SmartThings Platform. SmartApps allow you to provide a custom experience to your users, such as creating a unique onboarding experience or integrating your products into a custom application that enhanced your product's functionality. When using a SmartApp to connect your product to the SmartThings Cloud, the SmartApp will serve as a Cloud Connector, providing similar functionality to the Cloud Connector used with SmartThings Schema.

Your SmartApp used to connect your product to the SmartThings Cloud can be made using either:

  • An AWS Lambda function
  • A webhook endpoint
info

Your integration must support various lifecycles.

You can learn more about SmartApps here.

note

If you do not need this level of customization and your cloud supports OAuth 2.0, we recommend using SmartThings Schema to connect your Cloud Connected Device.

Get Started Using Our Sample Code#

tip

Looking for step-by-step tutorials? Visit our Community for more examples.

Below, we demonstrate creating a SmartApp to connect a LIFX cloud connected light bulb. The sample code uses the SmartThings API to import LIFX bulbs into your SmartThings account.

Our workflow will cover:

  • SmartApp installation and configuration flow.
  • HTTP Signature verification to ensure that the incoming requests are from SmartThings.
  • Integrating with a third-party API (LIFX API, in this case).

Prerequisites#

  • Node.js and npm installed (verified with npm version 4.0.5 and Node 7.4.0).
  • ngrok installed to create a secure tunnel for a globally available URL for fast testing.
  • Docker for running Redis. Alternatively, install and run Redis manually.
  • A Samsung account and the SmartThings app (currently available for Android).
  • At least one LIFX light bulb and the LIFX Mobile app (to install the light).
  • Either a LIFX Client ID and Client Secret (obtained from LIFX) or a LIFX personal API Token(generated during Connector installation).

Create Your SmartApp#

Our sample SmartApp acts as a connector between your LIFX bulb and the SmartThings Cloud. To get started:

  1. Download the SmartThings LIFX Connector. The README will help you get your connector up and running.
  2. Set your OAuth configuration:
  3. If you have a LIFX Client ID and Client Secret (must be obtained directly from LIFX, which does not allow the general public to register apps), copy them into the appropriate fields in config/default.json. If you do not have a Client ID and Secret, skip to the next step.
  4. If you do not have a LIFX Client ID and Client Secret:
    • Visit the [LIFX Cloud site] and sign in.
    • Tap your email ID and click settings.
    • Click Generate New Token and enter a meaningful label.
    • Click Generate. Copy the token for later use. LIFX will not show you the token again.
  5. Run the webhook service:
    • Install dependencies: npm install
    • Bring up Redis: docker-compose up -d
    • Start the server: npm start
    • Start ngrok: ngrok http 3000. Copy the https: URL. This URL is used when registering your SmartApp in the Developer Workspace.

Create a Device Profile#

Your SmartApp requires a Device Profile in order to communicate with your Cloud Connected Device.

Create a new Device Profile from the Developer Workspace Develop menu:

  • Enter My Bulb as the Device Profile Name.
  • For the Device Type, select Light.
  • Inside the main component, add the following capabilities:
    • Color Control
    • Color Temperature
    • Switch
    • Switch Level
  • For both Dashboard State and Dashboard Action, select main as a component and Switch as a Capability.

Register Your SmartApp in the Developer Workspace#

You now have all the information required to register your SmartApp in the Developer Workspace.

Select SmartApp Connector and select the Webhook Endpoint hosting type.

  • Select the My Bulb Device Profile you created in an earlier step.
  • Select WebHook endpoint.
    • For the Target URL, paste the ngrok URL you previously copied when setting up your LIFX connector.
  • Select the i:deviceprofiles scope.
  • Enter a Connector Display Name to be shown in the SmartThings app.
  • Set SmartApp Instances to Single.
note

Any custom parameters used in your Cloud Connector can be added here.

After saving your Connector info, return to the Cloud Connector page to find the following information:

  • Public Key
  • App ID
  • Client ID & Secret

Copy the Public Key and replace the contents of the config/smartthings_rsa.pub file with your copied Public Key.

Copy the Client ID and Client Secret values into the corresponding entries in config/default.json under "Connector".

Find the Device Profile ID on the Device Profile page.

Copy and paste the device profile ID field into config/default.json in the "deviceProfiles": {"color": ""} entry.

Restart Your Webhook Service#

  1. Stop the npm server: CTRL-C.
  2. Start the server again: npm start (this ensures that the Public Key will be used to verify requests from SmartThings).

Test your device#

Start testing your device with the SmartThings app.

After adding your device in the app, you will see your bulb - tap it to install.

Check your OAuth configuration:

  • If you have configured your server for OAuth with a Client ID and Client Secret from LIFX, you will be prompted to connect to the LIFX site to import your devices into SmartThings. In this case, the LIFX access token is stored for use by your app via the standard OAuth process.
  • If your server isn't configured for OAuth (i.e. no Client ID and Client Secret) then you will be prompted to manually enter a personal access token. Generate a new token (Step 3 of setting up the SmartThings LIFX Connector) and paste the token into the "Enter your LIFX API token" field.

Troubleshooting#

When installing the SmartApp, you may see the error Something went wrong. Please try to install the SmartApp again. If you encounter this error, make sure you restart the npm server. If you did not restart the npm server, you will see the following error in the npm server terminal: forbidden - failed verifySignature.