SmartThings Schema

The SmartThings Schema is a specification for use in a cloud-connected device integration. It does not require using the SmartThings API.

This article demonstrates how to create a SmartThings Schema Connector using AWS Lambda or WebHook endpoint.

Basic concept

SmartThings Schema recognizes three interaction types.

  • Discovery: Return a list of devices.
  • State Refresh: Return the state of the devices.
  • Command: Issue commands to the device.

SmartThings specifies an interaction type when sending a request to your server. In turn, your server responds with the appropriate information in a JSON payload.

OAuth2 client

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

  • https://c2c-us.smartthings.com/oauth/callback (United States)
  • https://c2c-eu.smartthings.com/oauth/callback (European Union)
  • https://c2c-ap.smartthings.com/oauth/callback (Asia-Pacific)

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.

The above information is needed when registering your Connector in Developer Workspace.

Cloud Connector

You will set up a Connector to handle the interaction types. This Connector can be a WebHook endpoint or AWS Lambda function.

Option 1: AWS Lambda

Example

Create 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:

  • Name: "demoSTSchema" (to follow our example)
  • Runtime: "Node.js" (we used version 8.10)
  • Role: Create a new role
  • Role Name: "demoSTSchema"
  • Click Create function

ARN for your Lambda function

Locate the ARN after creating your Lambda function. It will look like the below example:

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

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

Provide SmartThings permissions to your Lambda function

Using the AWS CLI, give SmartThings permissions to access your Lambda function.

Run 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. See documentation.
  • --function-name is the Lambda function we just created.
  • --principal 148790070172 is the SmartThings account you are granting permissions to.

Cloud Connector code

Use the following example code for your AWS Lambda. The code includes generic responses for SmartThings interaction requests.

Paste and save this into the index.js file.

st-schema is a package published to npm by SmartThings. Download the package using npm install.

'use strict';

const { lambda } = require("st-schema");

async function discoveryRequest(request, response) {
    console.log(JSON.stringify(request,null,2))
    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')
}

async function stateRefreshRequest(request, response) {
    console.log(JSON.stringify(request,null,2))
    const device = response.addDevice('3rd-party-device-0001');
    const component = device.addComponent('main');
    component.addState('switch', 'switch', 'off');
    component.addState('switchLevel', 'level', 80);
    component.addState('colorTemperature', 'colorTemperature', 3000);
}

async function commandRequest(request, response) {
    console.log(JSON.stringify(request,null,2))
    request.devices.forEach(async (it) => {
        const device = response.addDevice(it.externalDeviceId);
        const component = device.addComponent("main");
        it.commands.forEach(async (command) => {
            switch(command.capability) {
                case 'st.switch':
                    component.addState('switch', 'switch', command.command);
                    break;
                case 'st.switchLevel':
                    component.addState('switchLevel', 'level', command.arguments[0]);
                    break;
                case 'st.colorTemperature':
                    component.addState('colorTemperature', 'colorTemperature', command.arguments[0]);
                    break;
            }
        });
    });
}

module.exports.handler = lambda({
    discoveryRequest,
    commandRequest,
    stateRefreshRequest
});

Save the index.js file.

Option 2: WebHook endpoint

You can use a WebHook endpoint for your Cloud Connector.

See the example instructions here.

Register Connector in Developer Workspace

You should now have all the information required to register your Connector in Developer Workspace.

Select SmartThings Schema Connector and follow the insructions for AWS Lambda or WebHook Endpoint.

You will also fill in the OAuth2 client credentials obtained earlier.

Next steps