Event Subscription API App Example

Overview

This NodeJS Express application illustrates how to create an API Access SmartApp that connects to your SmartThings account with OAuth2 to control devices and subscribe to device events. The application uses the SmartThings SmartApp SDK NPM module for making the API calls to control switch devices and subscribe to switch events. The app create a web page that displays the state of all switches in a location and allows those switches to be turned on and off.

API access tokens and web session state are stored in AWS DynamoDB, so you will need an AWS account to run the app as it is written. The app uses the SmartThings dynamodb-context-store to store the API tokens and the dynamodb-store) for storing session state.

Files and directories

public
- images -- image assets used by the web pages
- javascript -- javascript used by the web page for rendering and controlling devices
- stylesheets -- stylesheets used by the web pages
views
- devices.ejs -- page that displays switch devices and allows them to be controlled
- error.ejs -- error page
- index.ejs -- initial page with link to connect to SmartThings
server.js -- the Express server and SmartApp
.env -- file you create with AWS and app credentials

Getting Started

Prerequisites

A Samsung Developer Workspace account with API Access app approval. Submit requests for approval using this form
Node.js and npm installed
ngrok or similar tool to create a secure tunnel to a publically available URL
AWS Account for hosting DynamoDB database or local DynamoDB instance (though that option has not been tested with this app)

Instructions

Clone this GitHub repository, cd into the directory, and install the Node modules with NPM:

git clone https://github.com/SmartThingsCommunity/api-app-subscription-example-js.git
cd api-app-subscription-example-js
npm install

Create a file named .env in the project directory and set the base URL of the server to your ngrok URL (or the URL you configured in your local hosts file), your AWS credentials, and the AWS region where the DynamoDB table is to be created (you can also configure AWS region and credentials in other ways). For example:

SERVER_URL=https://your-subdomain-name.ngrok.io
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPQRST
AWS_SECRET_ACCESS_KEY=aaGFHJHG457kJH++kljsdgIKLHJFD786sdghDFKL

Start your server and make note of the information it prints out:

node server.js

Redirect URI -- Copy this value into the "Redirection URI(s)" field in the Developer Workspace:
https://your-subdomain-name.ngrok.io/oauth/callback

Target URL -- Use this URL to log into SmartThings and connect this app to your account:
https://your-subdomain-name.ngrok.io

Go to the SmartThings Developer Workspace and create an new API Access project in your organization. If the previous link doesn't work and you don't see an option for creating an API Access project, then your access has not yet been approved.
After creating the project click the Register an Application link and fill in the fields using the Redirect URI and Target URI values from your server logs. Click Save.
On the next page select the r:locations:*, r:devices:*, and x:devices:* scopes and click Save.
Look in you server logs for a link similar to this one:

CONFIRMATION request for app f9a665e7-5a76-4b1e-bdfe-31135eccc2f3, to enable events visit 
https://api.smartthings.com/apps/f9a665e7-5a76-4b1e-bdfe-31135eccc2f3/confirm-registration?token=fd95...

Paste this link into a browser or request it with a utility like curl to enable callbacks to your app. The response should contain the targetURL value you entered in the dev workspace, for example:

{
    targetUrl: "https://your-subdomain-name.ngrok.io"
}

Add the APP_ID, CLIENT_ID and CLIENT_SECRET properties from the Developer Workspace to your .env file. For example:

APP_ID=aaaaaaaa-aaaa-aaaa-aaaaaaaaaaaa
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx

Restart your server:

node server.js

Go to webside URL from the server log, log in with your SmartThings account credentials, and choose a location. You should see a page listing all devices in that location with the switch capability. Tapping the device on the page should turn the switch on and off. You should also see the states of the switches on the page change when you turn them on and off with the SmartThings mobile app.

bflorian / api-app-subscription-example-js