smartthings

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.

Requires:

• pysmartthings (pip install pysmartthings)

__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.

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.

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
  }
]

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.