SmartThings Schema Connector

A cloud-connected device communicates to SmartThings Cloud through a third-party cloud and a Cloud Connector.

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:

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 select the hosting type: AWS Lambda or WebHook Endpoint.

  • 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.

Enter the Device Cloud Credentials obtained earlier.

  • 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 URI 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.
  • Partner OAuth scope specifies the OAuth scopes required for the device cloud to communicate with SmartThings Cloud.
    • Click Next to open the Catalog Info tab.
    • Enter a Connector Display Name to show in the SmartThings app.
    • Upload a Logo (240x240px) to be used in the SmartThings app.

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

SmartThings Schema Connector info

See also