Create a new cloud-connected device with a SmartApp

A cloud-connected device communicates to SmartThings Cloud through a third-party cloud and a Cloud Connector.

A SmartApp Connector is typically used for implementing certain advanced features or customizing your device onboarding UX.

Cloud-connected device

This article demonstrates how to create a cloud-connected light bulb. We provide a WebHook SmartApp that serves as the Connector. The sample code uses the SmartThings API to import LIFX bulbs into your SmartThings account.

In this tutorial, we 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 npn 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 Redismanually.
  • 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).

Step 1. Set up the Connector

Use our sample Cloud Connector to enable communication between LIFX and SmartThings Cloud.

  1. Download the SmartThings LIFX Connector on GitHub, using steps 1-7 in the README to set up the sample.
  2. Set your OAuth configuration.
  3. Run WebHook Service.

Step 2. Create a device profile

A device profile contains the components, capabilities, and metadata (ID, name, ownership, etc.) that define a SmartThings device.

  • Follow the steps to create a device profile.
  • 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 select Switch as a capability.
  • Click SAVE.

Step 3. Register Connector in Developer Workspace

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

  • Select SmartApp Connector.
  • Select My Bulb (created in Step 2) as the device profile.
  • Select WebHook endpoint.
  • For the Target URL paste the ngrok URL you previously copied (Step 7 of setting up the SmartThings LIFX Connector).
  • Set SmartApp Instances to Single.
  • For the App Scope, select the following:
    • r:devices:*
    • w:devices:*
    • i:deviceprofiles

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

  • Copy the Public Key and replace the contents of the file config/smartthings_rsa.pub with it.
  • 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.

Step 4. 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).

Step 5. Test your device

Start testing your device with the SmartThings app.

  1. Make sure you enable the Developer Mode.
  2. Go to the Devices tab in the SmartThings app and add your device. After a moment you will see the light bulb. Tap on it to install it.
  3. 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.
  4. Test your device.

Troubleshooting

  • When installing the SmartApp, if you get the error Something went wrong. Please try to install the SmartApp again, then:
  • Make sure you restart the npm server as specified in Step 4 above. If you did not restart the npm server, you will see this error in the npm server terminal: forbidden - failed verifySignature.

More information