Skip to content

Home

Jump to bottom
Keith Kolmos edited this page May 19, 2020 · 14 revisions

SmartThings Core SDK

The SmartThings Core SDK is a wrapper designed to simplify the use of the SmartThings REST API from JavaScript and TypeScript applications. This is the very first release of this SDK and should be considered a work in progress. Changes may still be made that are not backwardly compatible.

Installation

npm install @smartthings/core-sdk

Importing

NodeJS:

const {SmartThingsClient} = require('@smartthings/core-sdk')

Or ES2015+:

import {SmartThingsClient} from '@smartthings/core-sdk'

Example Usage

Substitue your Personal Access Token (PAT) with at least the r:locations:* scope for {YOUR-PAT-TOKEN} in the following code.

const {SmartThingsClient, BearerTokenAuthenticator} = require('@smartthings/core-sdk')
const client = new SmartThingsClient(new BearerTokenAuthenticator('{YOUR-PAT-TOKEN}'))

client.locations.list().then(locations => {
    console.log(`Found ${locations.length} locations`)
})

Reference

Authenticators

This SDK supports multiple ways of authenticating with the SmartThings platform. The currently available authenticators are:

  • BearerTokenAuthenticator -- Authenticator that is instantiated with any valid bearer token. This is the authenticator you would use with a PAT (Personal Access) Token.

  • RefreshTokenAuthenticator -- Authenticator that is instantiated with a bearer token and a RefreshTokenStore that provides methods for retrieving and storing access and refresh tokens. When this authenticator is used the API will automatically refresh expired access tokens, save the new tokens, and retry the original request.

  • SequentialRefreshTokenAuthenticator

Endpoints

  • apps -- A SmartApp can be an AWS Lambda function or a WebHook endpoint.

  • capabilities -- Operations to read standard capability definitions as well as create and modify custom capabilities

  • deviceProfiles -- A device profile contains the components, capabilities, and metadata (ID, name, ownership, etc.) that define a SmartThings device. Capabilities define the features of the device, and capabilities are grouped into components. Changes made with this API are currently not reflected in the Developer Workspace, so for the most part creating and modifying capabilities should still be done there.

  • devices -- Operations to access, control, create, update, and delete devices. These operations include the ability to query for device statue and send commands to devices.

  • installedApps -- Apps are installed by users and these operations are not explicitly called, but they may be useful for creating developer tools and automating tests.

  • locations -- Locations can include hubs, devices, and Automations. Automations allow control of the devices in a Location, the ability to monitor and receive notifications about what's happening at the Location, and more.

  • modes -- Operations to change the current mode of a location.

  • notifications -- Operations to send push notifications to SmartThings mobile app clients.

  • rooms -- Operations related to Rooms. Rooms are a grouping of devices within a location.

  • rules -- Operations for working with Rules. Rules allow you to create automations that can operate on SmartThings connected devices.

  • scenes -- Operations to list and execute scenes. Currently this endpoint does not support creating or updating scenes.

  • schedules -- Operations for schedules for use in SmartApps.

  • schema - Operations for ST Schema connectors and installed instances, along with operations to list the devices owned by each installed instance.

  • services - Operations to query for and subscribe to location service data, currently consisting of current weather conditions, weather forecast, and air quality data.

  • subscriptions -- Operations for subscribing to events, for use in SmartApps and API Access apps.

Clone this wiki locally