switchbot

Description

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.

Configuration

switchbot:
  # [Required]
  # API token (see `get started page`_).
  api_token:   # type=str

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # 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

Actions

• switchbot.back

• switchbot.channel_next

• switchbot.channel_prev

• switchbot.devices

• switchbot.forward

• switchbot.ir_stop

• switchbot.lock

• switchbot.mute

• switchbot.next

• switchbot.off

• switchbot.on

• switchbot.pause

• switchbot.play

• switchbot.press

• switchbot.previous

• switchbot.run_scene

• switchbot.scenes

• switchbot.set

• switchbot.set_ac_fan_speed

• switchbot.set_ac_mode

• switchbot.set_channel

• switchbot.set_curtain_position

• switchbot.set_fan_mode

• switchbot.set_fan_speed

• switchbot.set_humidifier_efficiency

• switchbot.set_lights

• switchbot.set_swing_range

• switchbot.set_temperature

• switchbot.set_value

• switchbot.status

• switchbot.toggle

• switchbot.unlock

• switchbot.voldown

• switchbot.volup

Module reference

class platypush.plugins.switchbot.SwitchbotPlugin(*_, **__)

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)

Parameters:

api_token – API token (see get started page).

back(device: str)

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

Parameters:

device – Device name or ID.

channel_next(device: str)

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)

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]

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)

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

Parameters:

device – Device name or ID.

ir_stop(device: str)

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

Parameters:

device – Device name or ID.

lock(device: str, **_)

Lock a compatible lock device.

Parameters:

device – Device name or ID.

main()

Implementation of the main loop of the plugin.

mute(device: str)

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)

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

Parameters:

device – Device name or ID.

off(device: str, **_)

Send a turn-off command to a device

Parameters:

device – Device name or ID.

on(device: str, **_)

Send a turn-on command to a device

Parameters:

device – Device name or ID.

pause(device: str)

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

Parameters:

device – Device name or ID.

play(device: str)

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

Parameters:

device – Device name or ID.

press(device: str)

Send a press-button command to a device.

Parameters:

device – Device name or ID.

previous(device: str)

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

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

run_scene(scene: str)

Execute a scene.

Parameters:

scene – Scene ID or name.

scenes() → List[dict]

Get the list of registered scenes.

Returns:

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

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

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)

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)

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)

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)

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)

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)

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, **__)

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)

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)

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, **__)

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.

start()

Start the plugin.

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

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

stop()

Stop the plugin.

toggle(device: str, **_)

Shortcut for press().

Parameters:

device – Device name or ID.

transform_entities(entities: Collection[dict]) → Collection[Entity]

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, **_)

Unlock a compatible lock device.

Parameters:

device – Device name or ID.

voldown(device: str)

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)

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

Parameters:

device – Device name or ID.

wait_stop(timeout=None)

Wait until a stop event is received.