switchbot-client

An unofficial Python client implementation of the SwitchBot API.

Table of Contents

• Authentication
• Usage
• License

Authentication

Before you start using this client, you need to get an open token and a secret key. Please follow the instructions in the official documentation below.

https://github.com/OpenWonderLabs/SwitchBotAPI#authentication

Once you have the token and secret key, use one of the following methods to pass the information to the client.

Environment variables

If the environment variable SWITCHBOT_OPEN_TOKEN and SWITCHBOT_SECRET_KEY is present, this client will automatically use this value.

export SWITCHBOT_OPEN_TOKEN=your_switchbot_open_token
export SWITCHBOT_SECRET_KEY=your_switchbot_secret_key
python your_script.py

# your_script.pyfromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
print(client.devices())

Constructor Arguments

It is also possible to initialize the client by passing a token and a secret key directly as an argument.

fromswitchbot_clientimportSwitchBotClientyour_token="your_switchbot_open_token"your_secret_key="your_switchbot_secret_key"client=SwitchBotClient(token=your_token, secret_key=your_secret_key)
print(client.devices())

Config file

If ~/.config/switchbot-client/config.yml exists and has a token and a secret_key entry, this client will automatically use the value.

mkdir -p ~/.config/switchbot-client
echo"token: your_switchbot_open_token">>~/.config/switchbot-client/config.yml
echo"secret_key: your_switchbot_secret_key">>~/.config/switchbot-client/config.yml
python your_script.py

# your_script.pyfromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
print(client.devices())

Usage

Get Device List

fromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
result=client.devices()
print(result)

[Meter({'device_id': 'ABCDEFG', 'device_type': 'Meter', 'device_name': 'Meter 0A', 'hub_device_id': 'ABCDE', 'is_virtual_infrared': False}), HubMini({'device_id': 'ABCDEFG', 'device_type': 'Hub Mini', 'device_name': 'Hub Mini 0', 'hub_device_id': None, 'is_virtual_infrared': False}), Light({'device_id': '12345', 'device_type': 'Light', 'device_name': 'My Light', 'hub_device_id': 'ABCDE', 'is_virtual_infrared': True}), AirConditioner({'device_id': '12345', 'device_type': 'Air Conditioner', 'device_name': 'My Air Conditioner', 'hub_device_id': 'ABCDE', 'is_virtual_infrared': True})]

If you run the above code, you will get a list of all the devices associated with your SwitchBot account. You can perform operations on the acquired device_id, such as manipulating it or getting its status.

Get Device Status

fromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
device_id="YOUR_DEVICE_ID"print(client.device(device_id).status())

DeviceStatus(device_id='ABCDE', device_type='Meter', device_name='Meter 0', hub_device_id='ABCDE', data={'deviceId': 'ABCDE', 'deviceType': 'Meter', 'hubDeviceId': 'ABCDE', 'humidity': 50, 'temperature': 25.0})

This function allows you to get the status of a device. Note that only the physical device returns accurate results, while the virtual infrared remote device is inaccurate, storing the results of the most recent operation.

Please refer to the following official document to know what kind of information can be obtained from each device.

https://github.com/OpenWonderLabs/SwitchBotAPI#get-device-status

Control Device

fromswitchbot_clientimportSwitchBotClientfromswitchbot_client.devicesimportLightclient=SwitchBotClient()
device_id="12345"# My Light(virtual infrared remote devices)device=Light.create_by_id(client, device_id)
print(device.turn_on())

SwitchBotCommandResult(status_code=100, message='success', response_body={})

It allows you to control the specified device. The following documents define the commands that can be executed.

https://github.com/OpenWonderLabs/SwitchBotAPI#send-device-control-commands

Get Scene List

fromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
print(client.scenes())

[SwitchBotScene({'scene_id': '12345', 'scene_name': 'My Scene1'}), SwitchBotScene({'scene_id': '23456', 'scene_name': 'My Scene2'})]

You can get a list of all the scenes associated with your SwitchBot account. Note that only manual scenes are returned from this api.

Execute Scene

fromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
print(client.scene("12345").execute())

SwitchBotCommandResult(status_code=100, message='success', response_body={})

The specified scene can be executed immediately.

Webhooks

fromswitchbot_clientimportSwitchBotClientclient=SwitchBotClient()
client.set_webhook(url="https://example.com/foo", enable=True)
print(client.webhooks())

[SwitchBotWebhook(url='https://example.com/foo', enable=True, device_list='ALL', create_time=datetime.datetime(2022, 1, 1, 12, 0, 0, 123456), last_update_time=datetime.datetime(2022, 1, 1, 12, 0, 0, 123456))]

You can handle webhook configurations via SwitchBotClient.

Raw API interface

Devices and scenes also can be manipulated via the low-level raw API client. The SwitchBotAPIClient class has methods for each endpoints of SwitchBot API.

For example the /v1.0/devices endpoint is implemented as SwitchBotAPIClient.devices(), the /v1.0/devices/{device_id}/status" endpoint is implemented as SwitchBotAPIClient.devices_status(device_id: str).

Examples

fromswitchbot_clientimportdevicesfromswitchbot_clientimportSwitchBotClientdefcall_this_function_when_i_go_out():
client=SwitchBotClient()
print("turn off all lights and air conditioners...")
fordinclient.devices():
ifisinstance(d, devices.Light):
d.turn_off()
ifisinstance(d, devices.ColorBulb):
d.turn_off()
ifisinstance(d, devices.AirConditioner):
d.turn_off()
print("done")
defcontrol_devices_by_temperature():
client=SwitchBotClient()
all_devices=client.devices()
temperatures= [d.temperature() fordinall_devicesifisinstance(d, devices.Meter)]
temperature=min(temperatures)
color_bulbs= [dfordinall_devicesifisinstance(d, devices.ColorBulb)]
air_conditioners= [dfordinall_devicesifisinstance(d, devices.AirConditioner)]
iftemperature>25.0:
print("hot!")
fordincolor_bulbs:
d.set_color("#FF0000")
fordinair_conditioners:
d.set_all(
temperature=20.0,
mode=devices.AirConditioner.Parameters.MODE_COOL,
fan_speed=devices.AirConditioner.Parameters.FAN_SPEED_HIGH,
power=devices.AirConditioner.Parameters.POWER_ON
)
eliftemperature<15.0:
print("cold!")
fordincolor_bulbs:
d.set_color("#0000FF")
fordinair_conditioners:
d.set_all(
temperature=20.0,
mode=devices.AirConditioner.Parameters.MODE_HEAT,
fan_speed=devices.AirConditioner.Parameters.FAN_SPEED_HIGH,
power=devices.AirConditioner.Parameters.POWER_ON
)

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.