Skip to main content

A python library for interacting with the SmartThings cloud API build with asyncio and aiohttp.

Project description

pysmartthings

Build Status Coverage Status image image image image

A python library for interacting with the SmartThings cloud API build with asyncio and aiohttp.

Features

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

  1. Locations: List, Get
  2. Rooms: List, Get, Create, Update, Delete
  3. Devices: List, Get, Command, Status
  4. Apps: List, Get, Create, Update, Delete, Settings Get & Update, OAuth: Get, Update, & Generate
  5. InstalledApps: List, Get, Delete
  6. Subscriptions: List, Get, Create, Delete, Delete All
  7. Scenes: List, Execute
  8. OAuth: Generate refresh/access token pair

Installation

pip install pysmartthings

or

pip install --use-wheel pysmartthings

Usage

Initialization

The SmartThings class encapsulates the API operations and the constructor accepts the aiohttp WebSession and your personal access token.

import aiohttp
import pysmartthings

token = 'PERSONAL_ACCESS_TOKEN'

async with aiohttp.ClientSession() as session:
    api = pysmartthings.SmartThings(session, token)
    # ...

Locations

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

    locations = await api.locations()
    print(len(locations))

    location = locations[0]
    print(location.name)
    print(location.location_id)

Outputs:

2
'Test Home'
'5c03e518-118a-44cb-85ad-7877d0b302e4'

Devices

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

    devices = await api.devices()
    print(len(devices))

    device = devices[0]
    print(device.device_id)
    print(device.name)
    print(device.label)
    print(device.capabilities)

Outputs:

19
'0d38d5ca-705f-44f7-89bd-36a8cf73678d'
'GE In-Wall Smart Dimmer'
'Back Patio Light'
['switch', 'switchLevel', 'refresh', 'indicator', 'button', 'sensor', 'actuator', 'healthCheck', 'light']

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

    await device.status.refresh()
    print(device.status.values)
    print(device.status.switch)
    print(device.status.level)

Outputs:

{'button': 'pressed', 'numberOfButtons': None, 'supportedButtonValues': None, 'indicatorStatus': 'when off', 'switch': 'on', 'checkInterval': 1920, 'healthStatus': None, 'DeviceWatch-DeviceStatus': None, 'level': 100}
True
100

Device Commands

You can execute a command on a device by calling the coroutine command(component_id, capability, command, args=None) function. The component_id parameter is the identifier of the component within the device (main is the device itself); capability is the name of the capability implemented by the device; and command is one of the defined operations within the capability. args is an array of parameters to pass to the command when it accepts parameters (optional). See the SmartThings Capability Reference for more information.

    result = await device.command("main", "switch", "on")
    assert result == True

    result = await device.command("main", "switchLevel", "setLevel", [75, 2])
    assert result == True

Devices with the switch capability have the following coroutines:

    result = await device.switch_on()
    assert result == True

    result = await device.switch_off()
    assert result == True

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

    result = await device.set_level(75, 2)
    assert result == True

Project details


Download files

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

Files for pysmartthings, version 0.7.6
Filename, size File type Python version Upload date Hashes
Filename, size pysmartthings-0.7.6-py3-none-any.whl (34.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pysmartthings-0.7.6.tar.gz (27.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page