Create a new cloud-connected device with SmartThings Schema

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

This article demonstrates how to create a SmartThings Schema Connector hosted with AWS Lambda.

Prerequisites

  • Your cloud MUST support OAuth2 with Authorization Code grant type and multiple redirect URIs.
  • An AWS account to host the Cloud Connector on AWS Lambda.

Step 1. Set up an OAuth2 client

You must generate an OAuth2 application from your cloud. You supply the OAuth2 credentials and details for your application when registering your Connector in Developer Workspace.

When creating your OAuth2 application, you will need to supply the following SmartThings redirect URIs:

  • https://c2c-us.smartthings.com/oauth/callback (United States)
  • https://c2c-eu.smartthings.com/oauth/callback (Europe)
  • 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.

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

Step 2. Host your AWS Lambda function

We will use AWS Lambda to host our Cloud Connector.

Create AWS Lambda

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.

Example ARN

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.

Step 3. 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.

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

Step 4. Register Connector in Developer Workspace

Register Connector in Developer Workspace

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

Step 5. Test your device

Start testing your device with the SmartThings app.


More information