Demonstration of how to write APIs that communicate with SmartThings
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
images - ... Feb 2, 2014
.jshintrc cleanup Feb 26, 2015 auto commit/push package.json Dec 26, 2015
Gruntfile.js cleanup Feb 26, 2015
LICENSE.txt distributed Feb 10, 2015 note shards May 22, 2017
package.json new release May 9, 2018
smartthings.groovy #21 May 9, 2018
smartthings.js cleanup Feb 26, 2015 Fix raise_api_error naming convention May 25, 2017
smartthingslib.js cleanup Feb 26, 2015


Well-documented code to:

  • Demo how to write using the SmartThings API
  • Control / Monitor SmartThings from Python
  • Control / Monitor SmartThings from Node-JS
  • Broadcast SmartThings events to MQTT

Courtesy of IOTDB. Follow us on Twitter:

  • @iotdb
  • @dpjanes

Important Notes

The SmartThings code broadcasts everything you do to MQTT. It's anonymous enough but you may find it creepy and it's easily turned off by editing smartthings.groovy.


If you are having trouble connecting to SmartThings, you may have to change your shard. Add to smartthings.json

"api_location": "<shard-url>"

You can find out your shard following the instructions here:


This is somewhat developer-y. At some point we'll make a more general user friendly version of this.

Clone this project into a local directory

git clone

Log into SmartThings

If necessary, do what it takes to become a Developer

Create New App

Go to:

Click on "+ New SmartApp"

Fill in the App Details

Make sure to "Enable OAuth" and to copy the two values produced. You'll need them them later. Press the Create (or Update maybe) button. Authorize access to as much as your comfortable with, you can always change this later from your iPhone or Android app.

Add the code

  • Press the Code button
  • Copy the code from smartthings.groovy and paste
  • Press Save
  • Press Publish


To access the API key, you need an access_token. Normally this is a real pain in the arse to generate, but we've done the hard work.

You'll need the OAuth Client ID and OAuth Client Secret, which you copied from the last major step. If you didn't, you can go back and get them now.

  • Go to this page:
  • Fill in the form
  • Press Submit
  • You'll be brought to the SmartThings website, where you'll allow access to your stuff
  • When that's done, you'll be brought back to IOTDB OAuthorize
  • copy the JSON data displayed and save it in a file called smartthings.json in the same directory

Keep that file to yourself. If you need to turn off access to your things, you can just go generate new OAuth keys in SmartThings.

If you add new devices to your SmartThings setup, you can give the API access using your SmartThings phone app.

API Access


List all the motion detectors

$ python --type motion
    "label": "Motion LivingRoom", 
    "type": "motion", 
    "url": "", 
    "value": {
      "motion": false, 
      "timestamp": "2014-02-03T13:30:31.361Z"

Turn off a switch

$ python --type switch --id "My Z-Wave Switch" --request switch=0

Toggle a switch

$ python --type switch --id "My Z-Wave Switch" --request switch=-1


A work in progress. The code is solid, but there's no command line argument parsing