Getting Started

Create a new cloud-to-cloud device with SmartThings Schema

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

This article demonstrates how to create a Cloud Connector using the SmartThings Schema and host the Connector with AWS Lambda.

When using the SmartThings Schema, your Connector responds to each request from SmartThings with a JSON payload.

Prerequisites

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

Step 1. OAuth2 client from your own cloud.

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:

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.

At a later step input the above information to SmartThings when registering your Connector in the Developer Workspace.

Step 2. Host your AWS Lambda function

We will use AWS Lambda to host our Connector.

Create AWS Lambda

  1. Create a new Lambda function from https://aws.amazon.com
  2. Select Author from Scratch for your Lambda function.

Enter details for your new Lambda function

  1. Name: “demoSTSchema”
  2. Runtime: “Node.js” (we used version 8.10)
  3. Role: Create a new role
  4. Role Name: “demoSTSchema”
  5. Click Create function

You can use any name for your Lambda function, or choose “demoSTSchema” to continue our example.

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 SmartThings the ARN when registering your Connector in the Developer Workspace at a later step.

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.

See details in Implement the Schema.

Paste and save this into the index.js file.

exports.handler = async (event, context) => {

    var headers        = event.headers;
    var authentication = event.authentication;

    var responseBody = {};
    var responseData = {};

    if(headers.interactionType == 'discoveryRequest') {
        //return the "deviceIds" from your cloud associated with the token.
        responseData = responseSampleDiscovery(headers.requestId, authentication.token);
    } else if (headers.interactionType == 'stateRefresh') {
        //return the "state" of the device(s)
        responseData = responseSampleStateRefresh(headers.requestId, authentication.token);
    } else if (headers.interactionType == 'command') {
        //handle the command for the device and return the "state" of the device.
        responseData = responseSampleCommand(headers.requestId, authentication.token);
    }

    const response = {
        statusCode: 200,
        body: JSON.stringify(responseData),
    };

    return response;

};

// Returning a generic schema response for Discovery
function responseSampleDiscovery(requestId, token) {

   return {
      "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "discoveryResponse",
        "requestId": requestId
      },
      "devices": [
        {
          "externalDeviceId": "3rd-party-device-0001",
          "deviceCookie": {"optional_cookie": "optional_value"},
          "friendlyName": "Kitchen Bulb",
          "manufacturerInfo": {
            "manufacturerName": "Your Company",
            "modelName": "Model A Color Bulb",
            "hwVersion": "v1 US Color Bulb",
            "swVersion": "123.123.123"
          },
          "deviceContext": {
            "roomName": "Kitchen",
            "groups": [ "Kitchen Lights", "House Bulbs"]
          },
          "deviceHandlerType": "c2c-rgbw-color-bulb"
        }
      ]
    }
}

// Returning a generic schema response for StateRefresh
function responseSampleStateRefresh(requestId, token) {

    return {
        "headers": {
            "schema": "st-schema",
            "version": "1.0",
            "interactionType": "stateRefreshResponse",
            "requestId": requestId
        },
        "deviceState": [
            {
                "externalDeviceId": "3rd-party-device-0001",
                "states": [
                    {
                        "component": "main",
                        "capability": "st.switch",
                        "attribute": "switch",
                        "value": "on"
                    },
                    {
                        "component": "main",
                        "capability": "st.switchLevel",
                        "attribute": "level",
                        "value": 80
                    }
                ]
            }
        ]
    }
}

// Returning a generic schema response for Command
function responseSampleCommand(requestId, token) {

    return  {
        "headers": {
            "schema": "st-schema",
            "version": "1.0",
            "interactionType": "commandResponse",
            "requestId": requestId
        },
        "deviceState": [
            {
                "externalDeviceId": "3rd-party-device-0001",
                "states": [
                    {
                        "component": "main",
                        "capability": "st.switch",
                        "attribute": "switch",
                        "value": "off"
                    },
                    {
                        "component": "main",
                        "capability": "st.switchLevel",
                        "attribute": "level",
                        "value": 80
                    }
                ]
            }
        ]
    }
}

Save the index.js file.

Step 4. Register Connector in Developer Workspace

Register Connector in Developer Workspace

At this point you should have all required information to register your Connector in the Developer Workspace.

  1. Select Develop > Devices > Device Integration in Developer Workspace
  2. Select the Cloud-to-cloud device connected to your cloud for connection type and select with SmartThings Schema.
  3. Set the Connector information. For more information on each field, see here
    • Enter Display name to represent your Connector, e.g. yourcompany-Connector.
    • For the Hosting type, select AWS Lambda.
    • Enter Target ARN from eariler. E.g. arn:aws:lambda:us-east-1:123456789000:function:demoSTSchema.
    • Enter Client ID, Client Secret, Authorization URI, and Refresh token URL for your cloud.
    • Enter Partner OAuth scope required for your Cloud. This field is optional.
    • Enter your Brand name and upload Brand logo image with 240X240 pixcels in dimensions.

Step 5. Test your device

Enable Developer Mode and start testing your device with the SmartThings app.

Additional resources and examples

Check the GitHub repository for the following additional resources.