SmartThings Schema is the quickest method of integrating your Cloud Connected Device with SmartThings (especially if your device is already working with Alexa or Google). It defines the interactions (JSON payloads) between the SmartThings Cloud and your existing cloud, allowing your products to return their current state to your cloud, and to handle commands from SmartThings. SmartThings Schema specifies an interaction type when sending a request to your server. In turn, your server responds with the appropriate information in a JSON payload.
In order to use SmartThings Schema, your cloud must support OAuth 2.0 (including the authorization code flow) and multiple redirect URIs. For an overview of the OAuth flow when working with the SmartThings Platform, visit OAuth Integrations.
In order to work with SmartThings Schema, you will need:
- An Oauth 2.0 client application for your cloud
- A Cloud Connector supporting various interaction types as specified in the Interaction Types.
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:
scopesthat specify the exact permissions for your cloud to access devices, retrieve device states, and control devices authorized by the user.
You'll need the above information when registering your Cloud Connector in the Developer Workspace in a later step.
A Cloud Connector is used to handle the interaction between your cloud and the SmartThings Cloud. You will need to set up a Cloud Connector to handle the interaction types.
Your Cloud Connector can be either:
- An AWS Lambda function
- A webhook endpoint
Below, we look at each Cloud Connector option and how you can get started.
The Cloud Connected Device tutorial on our Community demonstrates using SmartThings Schema and AWS Lambda to build a Cloud Connected Device with Custom Capabilities and automating a light based on your Zoom status.
Lambdas for SmartThings Schema must be deployed in one of the following regions, based on your availability:
- ap-northeast-1 (Tokyo)
- us-east-1 (N. Virginia)
- eu-west-1 (Ireland)
Start 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:
- A name for your function (we use
demoSTSchemain our example)
- Role: Create a new role
- Role Name (we use
demoSTSchemain our example)
Click Create function when you are satisfied with your Lambda function details.
Next, locate the ARN after creating your Lambda function. It will look something like this:
You will provide the ARN to SmartThings when registering your Connector in the Developer Workspace in a later step.
Using the AWS CLI, give SmartThings permissions to access your Lambda function with the following command:
--profileis your named profile for your CLI (ee AWS CLI documentation for details).
--function-nameis the Lambda function we just created.
--principal148790070172 is the SmartThings account you are granting permissions to.
The principal ID for SmartThings Schema (
148790070172) must not be modified as it identifies the authorized account to invoke your Lambda function.
Use the example Cloud Connector code below for your Lambda function. The code includes generic responses for SmartThings interaction requests.
- Create a directory in your local device.
- Paste and save the code below into a file named
- Navigate to the newly created directory using your terminal and install the SmartThings Schema library.
st-schema is a package published to npm by SmartThings. Install with
npm install st-schema.
node_modulesto a ZIP file.
- In your Lambda function's "code source" section, select upload from a .zip file and upload the file you just created.
- Deploy your Lambda function.
Cloud Connector code:
If you want to use a webhook endpoint for your Cloud Connector, you can find a tutorial walking you through the process in our Glitch project.
Now that you have your Cloud Connector, you are ready to register it with the Developer Workspace.
Begin by creating a new project in the Developer Workspace. Select New Project > Device Integration > SmartThings Cloud Connector > SmartThings Schema Connector. From here, the Developer Workspace will guide you through the process for registering your Cloud Connector.
- 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.
You will need to enter the Device Cloud Credentials obtained when you created your OAuth client application.
- 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 URL is 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.
- OAuth Scope(s) specifies the OAuth scopes required for your cloud to communicate with the SmartThings Cloud.
After entering the device cloud credentials, you will have the opportunity to provide an app display name and logo that will appear in the SmartThings app.
After saving the above information, click DEPLOY TO TEST. Return to the Cloud Connector page in the Workspace to access the client ID and client secret for this Connector.