smartthings

Description

Plugin to interact with devices and locations registered to a Samsung SmartThings account.

Configuration

smartthings:
  # [Required]
  # SmartThings API access token - you can get one at https://account.smartthings.com/tokens.
  access_token:   # type=str

  # [Optional]
  # How often the plugin should poll for changes, in seconds (default: 20).
  # poll_interval: 20.0  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies

pip

pip install pysmartthings

Actions

• smartthings.execute

• smartthings.get_device

• smartthings.get_location

• smartthings.info

• smartthings.off

• smartthings.on

• smartthings.set

• smartthings.set_level

• smartthings.set_lights

• smartthings.set_value

• smartthings.status

• smartthings.toggle

Module reference

class platypush.plugins.smartthings.SmartthingsPlugin(*_, **__)

Bases: RunnablePlugin, DimmerEntityManager, EnumSwitchEntityManager, LightEntityManager, SensorEntityManager, SwitchEntityManager

Plugin to interact with devices and locations registered to a Samsung SmartThings account.

__init__(access_token: str, poll_interval: float | None = 20.0, **kwargs)

Parameters:

• access_token – SmartThings API access token - you can get one at https://account.smartthings.com/tokens.

• poll_interval – How often the plugin should poll for changes, in seconds (default: 20).

execute(device: str, capability: str, command, component_id: str = 'main', args: list | None = None)

Execute a command on a device.

Example request to turn on a device with switch capability:

{
  "type": "request",
  "action": "smartthings.execute",
  "args": {
    "device": "My Switch",
    "capability": "switch",
    "command": "on"
  }
}

Parameters:

• device – Device ID or name.

• capability – Property to be read/written (see device capabilities returned from get_device()).

• command – Command to execute on the capability (see https://smartthings.developer.samsung.com/docs/api-ref/capabilities.html).

• component_id – ID of the component to execute the command on (default: main, i.e. the device itself).

• args – Command extra arguments, as a list.

get_device(device: str) → dict

Get a device info by ID or name.

Parameters:

device – Device ID or name.

Returns:

"tv-switch-id": {
    "capabilities": [
        "switch",
        "refresh",
        "healthCheck"
    ],
    "device_id": "tv-switch-id",
    "device_type_id": null,
    "device_type_name": null,
    "device_type_network": null,
    "location_id": "location-id",
    "name": "TV Smart Switch",
    "room_id": "room-1"
}

get_location(location_id: str | None = None, name: str | None = None) → dict

Get the info of a location by ID or name.

{
    "name": "My home",
    "location_id": "location-id",
    "country_code": "us",
    "locale": "en-US",
    "latitude": "latitude",
    "longitude": "longitude",
    "temperature_scale": null,
    "region_radius": null,
    "timezone_id": null,
    "rooms": {
        "room-1": {
            "background_image": null,
            "location_id": "location-1",
            "name": "Living Room",
            "room_id": "room-1"
        },
        "room-2": {
            "background_image": null,
            "location_id": "location-1",
            "name": "Bedroom",
            "room_id": "room-2"
        }
    }
}

info() → Dict[str, Dict[str, dict]]

Return the objects registered to the account, including locations and devices.

{
    "devices": {
        "smart-tv-id": {
            "capabilities": [
                "ocf",
                "switch",
                "audioVolume",
                "audioMute",
                "tvChannel",
                "mediaInputSource",
                "mediaPlayback",
                "mediaTrackControl",
                "custom.error",
                "custom.picturemode",
                "custom.soundmode",
                "custom.accessibility",
                "custom.launchapp",
                "custom.recording",
                "custom.tvsearch",
                "custom.disabledCapabilities",
                "samsungvd.ambient",
                "samsungvd.ambientContent",
                "samsungvd.ambient18",
                "samsungvd.mediaInputSource",
                "refresh",
                "execute",
                "samsungvd.firmwareVersion",
                "samsungvd.supportsPowerOnByOcf"
            ],
            "device_id": "smart-tv-id",
            "device_type_id": null,
            "device_type_name": null,
            "device_type_network": null,
            "location_id": "location-id",
            "name": "Samsung Smart TV",
            "room_id": "room-1"
        },
        "tv-switch-id": {
            "capabilities": [
                "switch",
                "refresh",
                "healthCheck"
            ],
            "device_id": "tv-switch-id",
            "device_type_id": null,
            "device_type_name": null,
            "device_type_network": null,
            "location_id": "location-id",
            "name": "TV Smart Switch",
            "room_id": "room-1"
        },
        "lights-switch-id": {
            "capabilities": [
                "switch",
                "refresh",
                "healthCheck"
            ],
            "device_id": "lights-switch-id",
            "device_type_id": null,
            "device_type_name": null,
            "device_type_network": null,
            "location_id": "location-id",
            "name": "Lights Switch",
            "room_id": "room-2"
        }
    },
    "locations": {
        "location-id": {
            "name": "My home",
            "location_id": "location-id",
            "country_code": "us",
            "locale": "en-US",
            "latitude": "latitude",
            "longitude": "longitude",
            "temperature_scale": null,
            "region_radius": null,
            "timezone_id": null,
            "rooms": {
                "room-1": {
                    "background_image": null,
                    "location_id": "location-1",
                    "name": "Living Room",
                    "room_id": "room-1"
                },
                "room-2": {
                    "background_image": null,
                    "location_id": "location-1",
                    "name": "Bedroom",
                    "room_id": "room-2"
                }
            }
        }
    }
}

main()

Implementation of the main loop of the plugin.

off(device: str, *_, **__)

Turn off a device with switch capability.

Parameters:

device – Device name or ID.

on(device: str, *_, **__)

Turn on a device with switch capability.

Parameters:

device – Device name or ID.

publish_entities(entities: Collection[Any] | None, callback: Callable[[Entity], Any] | None = None, **kwargs) → Collection[Entity]

Publishes a list of entities. The downstream consumers include:

• The entity persistence manager

• The web server

• Any consumer subscribed to

  platypush.message.event.entities.EntityUpdateEvent events (e.g. web clients)

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

set(entity: str, value: Any, attribute: str | None = None, **kwargs)

Set the value of an entity.

Parameters:

• entity – The entity to set the value for. It’s usually the ID of the entity provided by the plugin.

• value – The value to set the entity to.

set_level(device: str, level: int, **kwargs)

Set the level of a device with switchLevel capabilities (e.g. the brightness of a lightbulb or the speed of a fan).

Parameters:

• device – Device ID or name.

• level – Level, usually a percentage value between 0 and 1.

• kwargs – Extra arguments that should be passed to execute().

set_lights(lights: Iterable[str], on: bool | None = None, brightness: int | None = None, hue: int | None = None, saturation: int | None = None, hex: str | None = None, temperature: int | None = None, **_)

Set a set of properties on a set of lights.

Parameters:

• light – List of lights to set. Each item can represent a light name or ID.

• kwargs – key-value list of the parameters to set.

set_value(device: str, property: str | None = None, value=None, **kwargs)

Set the value of a device. It is compatible with the generic set_value method required by entities.

Parameters:

• device – Device ID or device+property name string in the format device_id:property.

• property – Name of the property to be set. If not specified here then it should be specified on the device level.

• value – Value to set.

start()

Start the plugin.

status(device: str | List[str] | None = None, publish_entities=True, **_) → List[dict]

Refresh and return the status of one or more devices.

Parameters:

device – Device or list of devices to refresh (default: all)

Returns:

A list containing on entry per device, and each entry containing the current device state. Example:

[
  {
    "device_id": "switch-1",
    "name": "Fan",
    "switch": false
  },
  {
    "device_id": "tv-1",
    "name": "Samsung Smart TV",
    "switch": true
  }
]

stop()

Stop the plugin.

toggle(device: str, *_, **__)

Toggle a device with switch capability.

Parameters:

device – Device name or ID.

Returns:

Device status

transform_entities(entities)

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)

Wait until a stop event is received.