Skip to main content
DocsSmartThings APIEnterprise API
Docs

Create and Register Your Schema App

Create Your Schema App​

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

Your Schema App can be either:

  • An AWS Lambda function
  • A webhook endpoint

Below, we look at each Schema App 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 at least one of the following regions, based on your availability:

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

Get Started​

Get started 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. Select a runtime (we use Node.js in our example)
  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 Schema App 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 Schema App Code​

Use the Schema App example code found below for your Lambda function. The code includes generic responses for SmartThings interaction requests and serves as a starting point for adding the required interaction types.

  1. Create a directory in your local device.
  2. Paste and save the Schema App example code found 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.

Schema App example 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 Schema App​

After creating your Schema App, you are now ready to register your app with the SmartThings platform.

The Schema Cloud Connector provides an interactive UI for you to register and manage your Schema App. Ensure you are signed in using the same account you intend to use to apply for WWST or are a member of the same organization as the account you intend to use when applying for WWST.

Before registering your Schema App, make sure you have the following information available:

From your OAuth 2 client application:

  • Client ID or client_id
    • A unique public string used to ID your cloud.
  • Client secret or client_secret
    • Used to authenticate with the Access Token URL. This is combined with the Client ID to identify the request.
  • OAuth URL or authorization_url
    • The authorization URL provided by your OAuth application.
  • OAuth scope or scopes
    • Specified the OAuth scopes required for your cloud to communicate with the SmartThings cloud.
  • Token refresh URL or token_url
    • The refresh URL provided by your OAuth application.
  • Alert notification email
    • An email address used to inform you if errors are identified on the SmartThings platform.

If using AWS Lambda:

  • Target ARNs for the following regions (if applicable to your product region availability):
    • North America
    • Europe
    • Asia Pacific

If using a webhook endpoint:

  • Target URL
    • A secure URL that can receive incoming JSON payloads from SmartThings using HTTP POST requests.
important

After completing registration, you will be presented with a SmartThings Client ID and SmartThings Client Secret. Save these values in a secure location! You will not be able to retrieve these values after this point. You can generate new values using the SmartThings API.

Up Next​

  • After registering your Schema App with SmartThings, be sure to verify that your Schema App supports the required interaction types.

  • Devices using SmartThings Schema must be associated with a Device Handler Type. Review Device Handler Types to find a pre-made device handler type that fits your device.

  • Implement optional app-to-app linking to create an even more seamless experience for Android and iOS users to link their SmartThings account with your platform.