Skip to main content

Get Started With SmartThings Schema

important

In order to use SmartThings Schema, your cloud must support OAuth 2.0, including the authorization code flow and multiple redirect URIs. We strongly encourage the use of an OAuth 2.0 provider or library.

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.

A SmartThings Schema integration consists of two parts:

Get started by creating your OAuth2 client application below.

Tutorials

Want to see SmartThings Schema in action without integrating your existing cloud? Check out the WebRTC SmartThings Schema tutorial. In this tutorial, you will learn how to integrate your existing webcam with SmartThings, enabling you to see a live view of your camera feed from within the SmartThings app.

You can also see an example OAuth Schema integration in the SmartThings Community GitHub repo.

Create Your OAuth2 Client Application​

important

During the account linking flow, if user credentials have been cached, you must display an authorization page to the user that explicitly requires the user to tap on an authorization button to proceed with the cloud-to-cloud account linking flow.

To accomplish this, user credentials should be cached for a short duration (we recommend 60 minutes). This should be paired with an authorization page explicitly stating that SmartThings is requesting access to user data from your platform (the "partner"). The authorization page must have an allow/authorize button that must be tapped by the user in order to proceed with the account linking flow; an optional Cancel button allows the user to cancel the authorization flow.

Alternatively, request the user to re-login every time the authorization URL is called.

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 SmartThings CLI 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.

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 your users' location.

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 your 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 SmartThings CLI 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 AWS CLI (see AWS CLI documentation for details).
  • --function-name is the Lambda function created.
  • --principal 148790070172 is the SmartThings account you are granting permissions to.
important

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);
};

Register Your Cloud Connector Using the SmartThings CLI​

Now that you have your Cloud Connector, you are ready to register it to the SmartThings platform using the SmartThings CLI.

If you intend to seek Works with SmartThings certification for your Schema integration

Ensure you are signed in to the SmartThings CLI using the same account you intend to use to register your products in the Certification Console or are a member of the same organization as the account you intend to use when registering your products in the Certification Console.

If using AWS Lambda, you will be asked to provide the following when registering your Schema integration in the CLI:

  • Partner name: The name of the entity or organization publishing this integration.
  • User email: An email address to associate with this integration.
  • App name: The desired name of your integration. This name will be displayed to users in the SmartThings app.
  • OAuth authorization URL: The authorization URL provided by your OAuth application.
  • Partner OAuth refresh token URL: The refresh token URL provided by your OAuth application.
  • Icon URL (optional): URL of the icon to display when users authenticate with your cloud. When registering your devices in the Console in a later step, this value will be overridden by any value provided in your Console certification submission.
  • 2x Icon URL (optional): URL of the icon to display when using 2x.
  • 3x Icon URL (optional): URL of the icon to display when using 3x.
  • Partner OAuth Client Id: A unique public string used to identify the device cloud.
  • Partner OAuth client Secret: Used to authenticate with the Access Token URI. This is combined with the client ID to identify the request.
  • Partner OAuth Scope (optional): Specifies the OAuth scopes required for your cloud to communicate with the SmartThings Cloud.
  • Lambda ARN for US region (optional): Lambda ARN to use for United States region.
  • Lambda ARN for EU region (optional): Lambda ARN to use for European Union region.
  • Lambda ARN for AP region (optional): Lambda ARN to use for Asia-Pacific region.
  • Enable app-to-app linking?: App-to-App Account Linking allows users to link their account on your platform with their SmartThings account when your app and the SmartThings app are installed on the user's mobile device. Linking is initiated from within the SmartThings app.
    • Android Link: Android App Link to your application.
    • iOS Link: iOS universal link to your application.

After installing the SmartThings CLI and ensuring you are signed in with the desired SmartThings account, run the following command in the SmartThings CLI to begin the registration process:

smartthings schema:create

After completing all fields, you will have a chance to change values or preview the final JSON or YAML files before finishing the registration process.

important

When your Schema integration is successfully registered, you will be presented with the following items:

  • Endpoint App Id
  • St Client Id
  • St Client Secret

Ensure you save these values in a secure location! You will not be able to retrieve these values after this point. If these values are lost, you will need to TODO PROCESS