SmartThings LIFX Connector C2C Endpoint App

This project is an example webhook C2C device connector app that uses the SmartThings API to import LIFX bulbs into your SmartThings account. It's written in NodeJS and can either be deployed to an internet accessible server or run locally with tunneling to the internet provided by a tool such as ngrok. It uses Redis for storing LIFX API credentials.

Folder structure

• config
  • default.json -- Keys, IDs, and other instance specific configuration values
  • smartthings_rsa.pub -- Public key for validating callback from SmartThings
• lib
  • api
    • lifx.js -- Methods for communicating to LIFX required by this app
    • st.js -- Prototype framework to abstract away some endpoint app implementation details, not specific to this app
  • lifecycle
    • configuration.js -- CONFIGURATION lifecycle event handling
    • crud.js -- INSTALL, UPDATE, and UNINSTALL lifecycle event handling
    • event.js -- EVENT lifecycle handling
    • oauth.js -- OAUTH lifecycle handling
  • local
    • db.js -- Simple Redis-based store of state data for this application
    • log.js -- Simple wrapper around console.log, not specific to this app
• docker-compose.yml -- Docker file for bringing up Redis data store
• package.json -- Node package file
• server.js -- This application

Prerequisites

• Node.js and npm installed.
• ngrok installed to create a secure tunnel to create a globally available URL for fast testing.
• Docker for running Redis. Alternative you can install and run Redis manually
• A Samsung ID and SmartThings account
• A SmartThings Developer Workspace account
• At least one LIFX light bulb and the LIFX Mobile app (to install the light)
• Either a LIFX clientId and clientSecret (from LIFX) or a LIFX personal API Token (You can generate the personal API token during the connector installation process)

Setup instructions

1. Clone this repository, and open a command prompt or terminal to the lifx-demo directory.

2. If you have a LIFX clientId and clientSecret copy them into the appropriate fields in config/default.json. If you don't then skip to the next step (Note that LIFX does not allow the general public to register apps and get client IDs and secrets. You need to contact them for that)

3. If you don't have a LIFX client ID and secret then go to the LIFX Cloud site and generate a personal access token from the Settings menu accessed from the upper right of the page. Save this token for later use (you may want to do that on your mobile device so that you can copy and paste it)

4. Install the dependencies: npm install.

5. Bring up Redis with docker-compose up -d

6. Start the server: npm start.

7. Start ngrok: ngrok http 3000. Copy the https: URL to your clipboard.

8. Log into the SmartThings Developer Workspace and go to the Cloud-To-Cloud devices page. Click Create to start the process of creating a device profile and connector app.

   1. 01 Device info. Enter and save a Service name such as "My LIFX Connector"
   2. 01 Device info. Click Add a device profile to create a device profile for your light. Give the device a name such as "LIFX Color Bulb" a VID such as "lifx-color-bulb" and an optional description. Set the Device type to Light. Click the plus (+) sign to add capabilities and select the Color Control, Color Temperature, Switch and Switch Level capabilities and click ADD. Finally scroll down and select Switch: main for main state and Main action and click Save to create the device profile. Then click Next.
   3. 02 Connector info Enter a connector name and description. You can leave Multi instance set to _Single and should leave the Connector type set to Webhook endpoint.
   4. 02 Connector info Click Settings to define API scopes. Select the r:devices:*, w:devices:*, i:deviceprofiles, r:schedules and w:schedules scopes and click Set.
   5. 02 Connector info Paste the ngrok URL you coppied in step 7 into the Target URL page and click SAVE AND NEXT. You should notice messages in your server log indicating that it received the PING lifecycle event.
   6. 03 Self-publish Copy the Public key text into the config/smartthings_rsa.pub file in your server directory. Also copy the Client ID and Client Secret values into the config/default.json into the corresponding entries under "connector".
   7. 03 Self-publish Enter a name you will recognize under Model code and click NEXT and then CLOSE.
   8. Click on your entry in the list and select the Device info. tab and paste the Device profile ID field into the config/default.json file in the "deviceProfiles": {"color": ""} entry.

9. Stop and restart the server: CTRL-C, npm start.

10. On the Devices page of the SmartThings mobile app tap ADD DEVICES, tap ADD DEVICE MANUALLY and then select your device from My Testing Devices at the bottom of the page (you can also install the devices in the ST Classic app from Marketplace -> SmartApps -> My Apps).

11. If you have configured your server for OAuth with clientId and clientSecret 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 without you seeing it via the standard OAuth process. If your server isn't configured for OAuth (i.e. no clientId and clientSecret) then you will be prompted to manually enter a personal access token. You can get such a token by tapping the Get a LIFX Personal Access Token >> link at the bottom of the page, logging into LIFX, tapping the Generate New Token button, and copying the token to the clipboard (LIFX won't show it to you again). Then tap Done and paste the token into the Enter your LIFX API token field.

12. Whichever method you use to get a token, tap NEXT to go to the next configuration page and tap Select location to select which LIFX location you want to import into this SmartThings location. Tap DONE to install the connector app and create the devices.