Switchbot API

A Python API for SwitchBots that allows to control actions, settings and timers.

The setup is tested on a RaspberryPi 3 with the Raspbian Buster OS in combination with Switchbots running firmware 4.4 and 4.5

FAQ

Note that if you observe the following error: Can't init device hci0: Connection timed out (110) while running either of the APIs. Update all packages see these steps.

Usage

The examples folder contains demonstrations how to scan for switchbots, press the switchbot, read and set settings (battery, firmware, hold time, etc.), read and set timers.

Use the scanner to find all switchbots in the area:

from switchbotpy import Scanner

scanner = Scanner()
mac_addresses = scanner.scan()

Use the mac address to create a bot instance providing methods to control the switchbots:

from switchbotpy import Bot

bot = Bot(id=bot_id, mac=mac, name=name)
bot.encrypted(password) # optional (only required in case the bot has a password)

bot.press() # press the switchbot
settings = bot.get_settings() # get a dict with the current bot settings

# all other options can be found in the example folder

Switchbot BLE API

For people interested in building an application controlling their switchbots, I provide a list with the results of my reverse engineering. I do not guarantee correctness nor completeness but with the BLE commands as described below I managed to control switchbots with firmware 4.4 and 4.5. The official switchbot app was used to set the password of the bots.

Actions

	Request			Notification (Response)
Name	Handle	Unencrypted	Encrypted	Required	Handle	Value
press	0x16	0x 57 01	0x 57 11 pw8		0x13	stat2
turn on		0x 57 01 01	0x 57 11 pw8 01
turn off		0x 57 01 02	0x 57 11 pw8 02

• pw8: crc32 checksum of the password in 4 bytes
• stat2: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

Settings

GET Settings

The bot settings are all retrieved by triggering one notification which consists of the concatenated settings.

	Request			Notification (Response)
Name	Handle	Unencrypted	Encrypted	Required	Handle	Value
get settings	0x16	0x 57 02	0x 57 12 pw8	x	0x13	0x stat2 bat2 fw2 64 00 00 00 00 nt2 ds1 inv1 sec2
battery						bat2: 1st byte of value
firmware						fw2: 2nd byte of value (div by 10)
number of timers						nt2: 8th byte of value
dual state mode						ds1: first 4 bits of 9th byte of value
inverse direction						inv1: last 4 bits of 9th byte of value
hold seconds						sec2: 10th byte of value

• pw8: crc32 checksum of the password in 4 bytes
• stat2: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

SET Settings

	Request			Notification (Response)
Name	Handle	Unencrypted	Encrypted	Required	Handle	Value
hold time	0x16	0x 57 0f 08 sec2	0x 57 1f pw8 08 sec2		0x13	stat2
mode		0x 57 03 64 ds1inv1	0x 57 13 64 pw8 ds1inv1

• pw8: crc32 checksum of the password in 4 bytes
• sec2: seconds as one byte unsigned int
• ds1: if dual state mode: 1 else 0
• inv1: if inverse mode: 1 else 0
• stat2: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

Timers

	Request			Notification (Response)
Name	Handle	Unencrypted	Encrypted	Required	Handle	Value
get timer	0x16	0x 57 08 tid13	0x 57 18 pw8 tid13	x	0x13
set timer		0x 57 09 tid13 timer20	0x 57 19 pw8 tid13 timer20			stat2
sync timer		0x 57 09 01 t16	0x 57 19 pw8 01 t16			stat2

• pw8: crc32 checksum of the password in 4 bytes
• tid1: timer id between 0 and 4
• timer20: nt2 00 rep2 hh2 mm2 rep11md1 rep21act1 its2 ihh2 imm2
• nt2: number of timers as one byte (e.g. 0x03 if there are 3 timers set)
• rep2: repeating pattern as one byte. Is 0x00 if timer is disabled. Is 0x80==b10000000 if there is no repetition. Otherwise, the last seven bits of the byte indicate the weekday on which the timer should be repeated (e.g. b01100000 means that the timer counts for Sunday and Saturday).
• hh2: timer hour between 0 and 23
• mm2: timer minute between 0 and 59
• rep11: in case the timer is disabled (rep2=0), the first 4 bits of the repeating byte are stored here
• md1: timer mode (standard=0, interval=1) as a byte,
• rep21: in case the timer is disabled (rep2=0), the last 4 bits of the repeating byte are stored here
• act1: timer action (press=0, turn_on=1, turn_off=2) as a byte
• its2: interval timer sum
• ihh2: interval timer hour
• imm2: interval timer minutes
• stat2: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

Authors

• Nicolas Küchler - Initial work - nicolas-kuechler