Skip to main content

A python library for interacting with the SmartThings cloud API.

Project description


Build Status Coverage Status image image image image

A python library for interacting with the SmartThings cloud API.


The package is still in beta, but the following features are available:

  1. Locations: List, Get
  2. Devices: List, Get, Command, Status
  3. Apps: List, Get, Create, Update, Delete, Settings Get & Update, OAuth: Get & Update
  4. InstalledApps: List, Get, Delete
  5. Subscriptions: List, Get, Create, Delete, Delete All


pip install pysmartthings


pip install --use-wheel pysmartthings



Call create and pass in your personal access token. Create will return an instance of the SmartThings class.

>>> import pysmartthings
>>> st = pysmartthings.create("PERSONAL_ACCESS_TOKEN")


A list of locations in SmartThings can be retrieved by invoking SmartThings.locations().

>>> locations = st.locations()
>>> len(locations)
>>> location = locations[0]
'Test Home'
>>> location.location_id


A list of devices across all locations in SmartThings can be retrieved by invoking SmartThings.devices(location_ids=None, capabilities=None, device_ids=None). The optional parameters allow filtering the returned list.

>>> devices = st.devices()
>>> len(devices)
>>> device = devices[0]
>>> device.device_id
'GE In-Wall Smart Dimmer'
>>> device.label
'Back Patio Light'
>>> device.capabilities
['switch', 'switchLevel', 'refresh', 'indicator', 'button', 'sensor', 'actuator', 'healthCheck', 'light']

For Device Type Handlers (DTH) additional information is available about the handler:

>>> device.type.value
>>> device.device_type_name
'GE Dimmer Switch 14294'
>>> device.device_type_network
>>> device.device_type_id

The current status of the device is populated when Device.status.refresh() is called. The DeviceStatus class represents the current values of the capabilities and provides several normalized property accessors.

>>> device.status.refresh()

>>> device.status.attributes
{'button': 'pressed', 'numberOfButtons': None, 'supportedButtonValues': None, 'indicatorStatus': 'when off', 'switch': 'on', 'checkInterval': 1920, 'healthStatus': None, 'DeviceWatch-DeviceStatus': None, 'level': 100}
>>> device.status.switch
>>> device.status.level

Device Commands

You can execute a command on a device by calling the Device.command(capability, command, args=None) function. The capability parameter corresponds to one of the capabilities detected and command is one of the define commands. args is an array of parameters to pass to the command (optional). See the SmartThings Capability Reference for more information.

>>> device.command("switch", "on")
>>> device.command("switchLevel", "setLevel", [75, 2])

Devices with the switch capability have the following functions:

>>> device.switch_on()
>>> device.switch_off()

Devices with the switchLevel capability have the following function that sets the target brightness level and transitions using a specific duration (seconds).

>>> device.set_level(75, 2)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pysmartthings-0.3.4.tar.gz (21.7 kB view hashes)

Uploaded Source

Built Distribution

pysmartthings-0.3.4-py3-none-any.whl (29.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page