Skip to main content

Get Started with SmartThings Schema

tip

Already have an Alexa or Google cloud-to-cloud device integration? SmartThings Schema is a great place to start.

SmartThings Schema is the quickest method of integrating your Cloud Connected Device with SmartThings. After creating a SmartThings Schema integration, you can use a JSON payload to communicate interactions, device state events, and commands between your cloud and SmartThings. SmartThings Schema specifies an interaction type when sending a request to your server. In turn, your server responds with the appropriate information in a JSON payload.

info

In order to use SmartThings Schema, your cloud must support OAuth 2.0 (including the authorization code flow) and multiple redirect URIs. For an overview of the OAuth flow when working with the SmartThings Platform, visit OAuth Integrations.

A SmartThings Schema integration consists of two parts:

Get started by creating your OAuth2 client application below.

Create Your OAuth2 Client Application​

You must generate an OAuth2 application from your cloud that supports the following SmartThings redirect URIs:

After creating your OAuth2 client, you should have the following information supplied by your cloud:

  • client_id and client_secret
  • authorization_url and token_url
  • scopes that specify the exact permissions for your cloud to access devices, retrieve device states, and control devices authorized by the user.

You'll need the above information when registering your Cloud Connector in the Developer Workspace in a later step.

Create Your Cloud Connector​

A Cloud Connector is used to handle the interaction between your cloud and the SmartThings Cloud. You will need to set up a Cloud Connector to handle the interaction types.

Your Cloud Connector can be either:

  • An AWS Lambda function
  • A webhook endpoint

Below, we look at each Cloud Connector option and how you can get started.

Option 1: AWS Lambda​

Lambdas for SmartThings Schema must be deployed in one of the following regions, based on your availability:

  • ap-northeast-1 (Tokyo)
  • us-east-1 (N. Virginia)
  • eu-west-1 (Ireland)

Start by creating a new Lambda function at https://aws.amazon.com. Select Author from Scratch for your Lambda function.

Enter the following details for your new Lambda function:

  1. A name for your function (we use demoSTSchema in our example)
  2. Runtime: Node.js
  3. Role: Create a new role
  4. Role Name (we use demoSTSchema in our example)

Click Create function when you are satisfied with your Lambda function details.

Locate the ARN​

Next, locate the ARN after creating your Lambda function. It will look something like this:

arn:aws:lambda:us-east-1:123456789000:function:demoSTSchema

You will provide the ARN to SmartThings when registering your Connector in the Developer Workspace in a later step.

Provide SmartThings With Permissions to Your Function​

Using the AWS CLI, give SmartThings permissions to access your Lambda function with the following command:

%> aws lambda add-permission --profile default --function-name demoSTSchema --statement-id smartthings --principal 148790070172 --action lambda:InvokeFunction
  • --profile is your named profile for your CLI (ee AWS CLI documentation for details).
  • --function-name is the Lambda function we just created.
  • --principal 148790070172 is the SmartThings account you are granting permissions to.
info

The principal ID for SmartThings Schema (148790070172) must not be modified as it identifies the authorized account to invoke your Lambda function.

Add Cloud Connector Code​

Use the example Cloud Connector code below for your Lambda function. The code includes generic responses for SmartThings interaction requests.

  1. Create a directory in your local device.
  2. Paste and save the code below into a file named index.js.
  3. Navigate to the newly created directory using your terminal and install the SmartThings Schema library.
tip

st-schema is a package published to npm by SmartThings. Install with npm install st-schema.

  1. Add index.js and node_modules to a ZIP file.
  2. In your Lambda function's "code source" section, select upload from a .zip file and upload the file you just created.
  3. Deploy your Lambda function.

Cloud Connector code:

'use strict';

const {SchemaConnector} = require('st-schema')

const connector = new SchemaConnector()
    .enableEventLogging(2)
    .discoveryHandler((accessToken, response) => {
        response.addDevice('3rd-party-device-0001', 'Kitchen Light', 'c2c-color-temperature-bulb')
            .manufacturerName('Your Company')
            .modelName("Model A Tunable White Bulb")
            .hwVersion('v1 US Tunable White Bulb')
            .swVersion('1.0.0')
            .roomName('Kitchen')
            .addGroup('Kitchen Table Lights')
    })
    .stateRefreshHandler((accessToken, response) => {
        const device = response.addDevice('3rd-party-device-0001');
        const component = device.addComponent('main');
        component.addState('st.switch', 'switch', 'off');
        component.addState('st.switchLevel', 'level', 80);
        component.addState('st.colorTemperature', 'colorTemperature', 3000);
        component.addState('st.healthCheck', 'healthStatus', 'online');
    })
    .commandHandler((accessToken, response, devices) => {
        for (const it of devices) {
            const device = response.addDevice(it.externalDeviceId);
            const component = device.addComponent("main");
            for (const command of it.commands) {
                switch(command.capability) {
                    case 'st.switch':
                        component.addState('st.switch', 'switch', command.command);
                        break;
                    case 'st.switchLevel':
                        component.addState('st.switchLevel', 'level', command['arguments'][0]);
                        break;
                    case 'st.colorTemperature':
                        component.addState('st.colorTemperature', 'colorTemperature', command['arguments'][0]);
                        break;
                }
            }
        }
    })
    .callbackAccessHandler(async (accessToken, callbackAuthentication, callbackUrls) => {
        // TODO -- store the tokens and URLs for use in proactive state callbacks
    })
    .integrationDeletedHandler(accessToken => {
        // TODO -- any cleanup necessary when an integration is removed from SmartThings
    });

exports.handler = async (evt, context) => {
    await connector.handleLambdaCallback(evt, context);
};

Option 2: Webhook Endpoint​

If you want to use a webhook endpoint for your Cloud Connector, you can find a tutorial walking you through the process in the SmartThings Community.

Register Your Cloud Connector in the Developer Workspace​

Now that you have your Cloud Connector, you are ready to register it with the Developer Workspace.

Begin by creating a new project in the Developer Workspace. Select New Project > Device Integration > SmartThings Cloud Connector > SmartThings Schema Connector. From here, the Developer Workspace will guide you through the process for registering your Cloud Connector.

note
  • AWS Lambda requires a Target ARN for each region in which you plan to distribute your integration. For better execution latency, you should deploy your Lambda function in an AWS region that is geographically closer to the end-user's Location.
  • Webhook Endpoint requires a Target URL where the Connector will be hosted.

You will need to enter the Device Cloud Credentials obtained when you created your OAuth client application.

  • Client ID is a unique public string used to identify the device cloud.
  • Client Secret is a credential used to authenticate with the Access Token URI. This is combined with the client ID to identify the request.
  • Authorization URL is where users will be redirected to enter login credentials.
  • Refresh Token URL where refresh tokens can be obtained in order to get a new access token or ID token.
  • OAuth Scope(s) specifies the OAuth scopes required for your cloud to communicate with the SmartThings Cloud.

After entering the device cloud credentials, you will have the opportunity to provide an app display name and logo that will appear in the SmartThings app.

After saving the above information, click DEPLOY TO TEST. Return to the Cloud Connector page in the Workspace to access the client ID and client secret for this Connector.