switchbot#

class platypush.plugins.switchbot.SwitchbotPlugin(*_, **__)[source]#

Bases: RunnablePlugin, DimmerEntityManager, EnumSwitchEntityManager, LightEntityManager, SwitchEntityManager

Plugin to interact with the devices registered to a Switchbot account/hub.

In order to use this plugin:

  • Set up a Switchbot Hub and configure your devices through the Switchbot app.

  • Follow the steps on get started page to get an API token from the app.

__init__(api_token: str, **kwargs)[source]#
Parameters:

api_token – API token (see get started page).

back(device: str)[source]#

Send backward IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

channel_next(device: str)[source]#

Send next channel IR event to a device (for TV, IPTV/Streamer, and Set Top Box).

Parameters:

device – Device name or ID.

channel_prev(device: str)[source]#

Send previous channel IR event to a device (for TV, IPTV/Streamer, and Set Top Box).

Parameters:

device – Device name or ID.

devices() List[dict][source]#

Get the list of devices associated to the specified Switchbot API account.

Returns:

[
  {
    "cloud_service_enabled": "True if cloud access is enabled on this device,False otherwise. Only cloud-enabled devices can be controlled from the switchbot plugin.",
    "device_type": "Default types: [Hub, Hub Plus, Hub Mini, Bot, Curtain, Plug, Meter, Humidifier, Smart Fan, Air Conditioner, TV, Light, IPTV / Streamer, Set Top Box, DVD, Fan, Projector, Camera, Air Purifier, Speaker, Water Heater, Vacuum Cleaner, Remote, Others]",
    "hub_id": "Parent hub device unique ID",
    "id": "Device unique ID",
    "is_calibrated": "[Curtain devices only] Set to True if the device has been calibrated, False otherwise",
    "is_virtual": "True if this is a virtual device, i.e. a device with an IR remote configuration but not managed directly by the Switchbot bridge",
    "name": "Device name",
    "open_direction": "[Curtain devices only] Direction where the curtains will be opened (\"left\" or \"right\")",
    "remote_type": "Default types: [Air Conditioner, TV, Light, IPTV / Streamer, Set Top Box, DVD, Fan, Projector, Camera, Air Purifier, Speaker, Water Heater, Vacuum Cleaner, Others]"
  }
]

forward(device: str)[source]#

Send forward IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

ir_stop(device: str)[source]#

Send stop IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

lock(device: str, **_)[source]#

Lock a compatible lock device.

Parameters:

device – Device name or ID.

main()[source]#

Implementation of the main loop of the plugin.

mute(device: str)[source]#

Send mute/unmute IR event to a device (for TV, IPTV/Streamer, Set Top Box, DVD and Speaker).

Parameters:

device – Device name or ID.

next(device: str)[source]#

Send next IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

off(device: str, **_)[source]#

Send a turn-off command to a device

Parameters:

device – Device name or ID.

on(device: str, **_)[source]#

Send a turn-on command to a device

Parameters:

device – Device name or ID.

pause(device: str)[source]#

Send pause IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

play(device: str)[source]#

Send play IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

press(device: str)[source]#

Send a press-button command to a device.

Parameters:

device – Device name or ID.

previous(device: str)[source]#

Send previous IR event to a device (for DVD and Speaker).

Parameters:

device – Device name or ID.

run_scene(scene: str)[source]#

Execute a scene.

Parameters:

scene – Scene ID or name.

scenes() List[dict][source]#

Get the list of registered scenes.

Returns:

[
  {
    "id": "Scene ID",
    "name": "Scene name"
  }
]

set(entity: str, value: Any, attribute: str | None = None, **kwargs)[source]#

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_ac_fan_speed(device: str, fan_speed: int)[source]#

Set the fan speed for an air conditioner.

Parameters:
  • device – Device name or ID.

  • fan_speed

    Possible values:

    • 1: auto

    • 2: low

    • 3: medium

    • 4: high

set_ac_mode(device: str, mode: int)[source]#

Set the mode of an air conditioner.

Parameters:
  • device – Device name or ID.

  • mode

    Air conditioner mode. Supported values:

    • 1: auto

    • 2: cool

    • 3: dry

    • 4: fan

    • 5: heat

set_channel(device: str, channel: int)[source]#

Set the channel on a TV, IPTV/Streamer, Set Top Box device.

Parameters:
  • device – Device name or ID.

  • channel – Channel number.

set_curtain_position(device: str, position: int)[source]#

Set the position of a curtain device.

Parameters:
  • device – Device name or ID.

  • position – An integer between 0 (open) and 100 (closed).

set_fan_mode(device: str, mode: int)[source]#

Set the mode of a fan.

Parameters:
  • device – Device name or ID.

  • mode – Fan mode (1 or 2).

set_fan_speed(device: str, speed: int)[source]#

Set the speed of a fan.

Parameters:
  • device – Device name or ID.

  • speed – Speed between 1 and 4.

set_humidifier_efficiency(device: str, efficiency: int | str)[source]#

Set the nebulization efficiency of a humidifier device.

Parameters:
  • device – Device name or ID.

  • efficiency

    Possible values:

    • auto: Automatic mode.

    • A value between 0 and 100.

set_lights(*_, lights: Collection[str], on: bool | None = None, brightness: int | None = None, hex: str | None = None, temperature: int | None = None, **__)[source]#

Change the settings for compatible lights.

Parameters:
  • lights – Light names or IDs.

  • on – Turn on the lights.

  • brightness – Set the brightness of the lights.

  • hex – Set the color of the lights.

  • temperature – Set the temperature of the lights.

set_swing_range(device: str, swing_range: int)[source]#

Set the swing range of a fan.

Parameters:
  • device – Device name or ID.

  • swing_range – Swing range angle, between 0 and 120.

set_temperature(device: str, temperature: float)[source]#

Set the temperature of an air conditioner.

Parameters:
  • device – Device name or ID.

  • temperature – Temperature, in Celsius.

set_value(device: str, property: str | None = None, value: Any = None, **__)[source]#

Set the value of a property of a device.

Parameters:
  • device – Device name or ID, or entity (external) ID.

  • property – Property to set. It should be present if you are passing a root device ID to device and not an atomic entity in the format <device_id>:<property_name>.

  • value – Value to set.

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

Get the status of all the registered devices or of a specific device.

Parameters:

device – Filter by device ID or name.

Returns:

[
  {
    "active_time": "[Plug devices only] How long the device has been absorbing during a day, measured in minutes",
    "auto": "[Humidifier devices only] True if auto mode is on",
    "brightness": "[Light devices only] Light brightness, between 1 and 100",
    "child_lock": "[Humidifier devices only] True if safety lock is on",
    "cloud_service_enabled": "True if cloud access is enabled on this device,False otherwise. Only cloud-enabled devices can be controlled from the switchbot plugin.",
    "color": "[Light devices only] Color, expressed as a hex string (e.g. FF0000)",
    "color_temperature": "[Light devices only] Color temperature, between 2700 and 6500",
    "current": "[Plug devices only] Device current at the moment, measured in amperes",
    "device_type": "Default types: [Hub, Hub Plus, Hub Mini, Bot, Curtain, Plug, Meter, Humidifier, Smart Fan, Air Conditioner, TV, Light, IPTV / Streamer, Set Top Box, DVD, Fan, Projector, Camera, Air Purifier, Speaker, Water Heater, Vacuum Cleaner, Remote, Others]",
    "door_open": "[Lock devices only] True if the door is open, False otherwise",
    "fan_speed": "[Air conditioner devices only] Speed of the fan",
    "hub_id": "Parent hub device unique ID",
    "humidity": "[Meter/humidifier devices only] Humidity in %",
    "id": "Device unique ID",
    "is_calibrated": "[Curtain devices only] Set to True if the device has been calibrated, False otherwise",
    "is_virtual": "True if this is a virtual device, i.e. a device with an IR remote configuration but not managed directly by the Switchbot bridge",
    "locked": "[Lock devices only] True if the lock is on",
    "low_water": "[Humidifier devices only] True if the device is low on water",
    "mode": "[Fan/Air conditioner devices only] Fan mode",
    "moving": "[Curtain devices only] True if the device is moving, False otherwise",
    "name": "Device name",
    "nebulization_efficiency": "[Humidifier devices only] Nebulization efficiency in %",
    "on": "True if the device is on, False otherwise",
    "open_direction": "[Curtain devices only] Direction where the curtains will be opened (\"left\" or \"right\")",
    "position": "[Curtain devices only] Position of the device on the curtain rail, between 0% (open) and 100% (closed)",
    "power": "[Plug devices only] Consumed power, measured in watts",
    "remote_type": "Default types: [Air Conditioner, TV, Light, IPTV / Streamer, Set Top Box, DVD, Fan, Projector, Camera, Air Purifier, Speaker, Water Heater, Vacuum Cleaner, Others]",
    "sound": "[Humidifier devices only] True if sound is muted",
    "speed": "[Smart fan devices only] Fan speed, between 1 and 4",
    "swing_direction": "[Smart fan devices only] Swing direction",
    "swing_range": "[Smart fan devices only] Swing range angle, between 0 and 120",
    "swinging": "[Smart fan devices only] True if the device is swinging",
    "temperature": "[Meter/humidifier/Air conditioner devices only] Temperature in Celsius",
    "voltage": "[Plug devices only] Voltage of the device, measured in volts"
  }
]

toggle(device: str, **_)[source]#

Shortcut for press().

Parameters:

device – Device name or ID.

transform_entities(entities: Collection[dict]) Collection[Entity][source]#

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.

unlock(device: str, **_)[source]#

Unlock a compatible lock device.

Parameters:

device – Device name or ID.

voldown(device: str)[source]#

Send volume down IR event to a device (for TV, IPTV/Streamer, Set Top Box, DVD and Speaker).

Parameters:

device – Device name or ID.

volup(device: str)[source]#

Send volume up IR event to a device (for TV, IPTV/Streamer, Set Top Box, DVD and Speaker).

Parameters:

device – Device name or ID.