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

<table> <tr> <th></th> <th colspan="3">Request</th> <th colspan="3">Notification (Response)</th> </tr> <tr> <th>Name</th> <th>Handle</th> <th>Unencrypted</th> <th>Encrypted</th> <th>Required</th> <th>Handle</th> <th>Value</th> </tr> <tr> <td>press</td> <td rowspan="3">0x16</td> <td>0x 57 01</td> <td>0x 57 11 <code>pw₈</code></td> <td></td> <td rowspan="3">0x13</td> <td rowspan="3"><code>stat₂</code></td> </tr> <tr> <td>turn on</td> <td>0x 57 01 01</td> <td>0x 57 11 <code>pw₈</code> 01</td> <td></td> </tr> <tr> <td>turn off</td> <td>0x 57 01 02</td> <td>0x 57 11 <code>pw₈</code> 02</td> <td></td> </tr> </table>

• <code>pw₈</code>: crc32 checksum of the password in 4 bytes
• <code>stat₂</code>: 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.

<table> <tr> <th></th> <th colspan="3">Request</th> <th colspan="3">Notification (Response)</th> </tr> <tr> <th>Name</th> <th>Handle</th> <th>Unencrypted</th> <th>Encrypted</th> <th>Required</th> <th>Handle</th> <th>Value</th> </tr> <tr> <td>get settings</td> <td rowspan="7">0x16</td> <td rowspan="7">0x 57 02</td> <td rowspan="7">0x 57 12 <code>pw₈</code></td> <td rowspan="7">x</td> <td rowspan="7">0x13</td> <td> 0x <code>stat₂</code> <code>bat₂</code> <code>fw₂</code> 64 00 00 00 00 <code>nt₂</code> <code>ds₁</code> <code>inv₁</code> <code>sec₂</code> </td> </tr> <tr> <td>battery</td> <td><code>bat₂</code>: 1st byte of value</td> </tr> <tr> <td>firmware</td> <td><code>fw₂</code>: 2nd byte of value (div by 10)</td> </tr> <tr> <td>number of timers</td> <td><code>nt₂</code>: 8th byte of value</td> </tr> <tr> <td>dual state mode</td> <td><code>ds₁</code>: first 4 bits of 9th byte of value</td> </tr> <tr> <td>inverse direction</td> <td><code>inv₁</code>: last 4 bits of 9th byte of value</td> </tr> <tr> <td>hold seconds</td> <td><code>sec₂</code>: 10th byte of value</td> </tr> </table>

• <code>pw₈</code>: crc32 checksum of the password in 4 bytes
• <code>stat₂</code>: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

SET Settings

<table> <tr> <th></th> <th colspan="3">Request</th> <th colspan="3">Notification (Response)</th> </tr> <tr> <th>Name</th> <th>Handle</th> <th>Unencrypted</th> <th>Encrypted</th> <th>Required</th> <th>Handle</th> <th>Value</th> </tr> <tr> <td>hold time</td> <td rowspan="2">0x16</td> <td>0x 57 0f 08 <code>sec₂</code></td> <td>0x 57 1f <code>pw₈</code> 08 <code>sec₂</code></td> <td></td> <td rowspan="2">0x13</td> <td rowspan="2"><code>stat₂</code></td> </tr> <tr> <td>mode</td> <td>0x 57 03 64 <code>ds₁</code><code>inv₁</code></td> <td>0x 57 13 64 <code>pw₈</code> <code>ds₁</code><code>inv₁</code></td> <td></td> </tr> </table>

• <code>pw₈</code>: crc32 checksum of the password in 4 bytes
• <code>sec₂</code>: seconds as one byte unsigned int
• <code>ds₁</code>: if dual state mode: 1 else 0
• <code>inv₁</code>: if inverse mode: 1 else 0
• <code>stat₂</code>: 1 = action complete, 3 = bot busy, 11 = bot unreachable, 7 = bot encrypted, 8 = bot unencrypted, 9 = wrong password

Timers

<table> <tr> <th></th> <th colspan="3">Request</th> <th colspan="3">Notification (Response)</th> </tr> <tr> <th>Name</th> <th>Handle</th> <th>Unencrypted</th> <th>Encrypted</th> <th>Required</th> <th>Handle</th> <th>Value</th> </tr> <tr> <td>get timer</td> <td rowspan="3">0x16</td> <td>0x 57 08 <code>tid₁</code>3</td> <td>0x 57 18 <code>pw₈</code> <code>tid₁</code>3</td> <td>x</td> <td rowspan="3">0x13</td> <td></td> </tr> <tr> <td>set timer</td> <td>0x 57 09 <code>tid₁</code>3 <code>timer₂₀</code></td> <td>0x 57 19 <code>pw₈</code> <code>tid₁</code>3 <code>timer₂₀</code></td> <td></td> <td><code>stat₂</code></td> </tr> <tr> <td>sync timer</td> <td>0x 57 09 01 <code>t₁₆</code></td> <td>0x 57 19 <code>pw₈</code> 01 <code>t₁₆</code></code></td> <td></td> <td><code>stat₂</code></td> </tr> </table>

• <code>pw₈</code>: crc32 checksum of the password in 4 bytes
• <code>tid₁</code>: timer id between 0 and 4
• <code>timer₂₀</code>: <code>nt₂</code> 00 <code>rep₂</code> <code>hh₂</code> <code>mm₂</code> <code>rep1₁</code><code>md₁</code> <code>rep2₁</code><code>act₁</code> <code>its₂</code> <code>ihh₂</code> <code>imm₂</code>
• <code>nt₂</code>: number of timers as one byte (e.g. 0x03 if there are 3 timers set)
• <code>rep₂</code>: 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).
• <code>hh₂</code>: timer hour between 0 and 23
• <code>mm₂</code>: timer minute between 0 and 59
• <code>rep1₁</code>: in case the timer is disabled (<code>rep₂</code>=0), the first 4 bits of the repeating byte are stored here
• <code>md₁</code>: timer mode (standard=0, interval=1) as a byte,
• <code>rep2₁</code>: in case the timer is disabled (<code>rep₂</code>=0), the last 4 bits of the repeating byte are stored here
• <code>act₁</code>: timer action (press=0, turn_on=1, turn_off=2) as a byte
• <code>its₂</code>: interval timer sum
• <code>ihh₂</code>: interval timer hour
• <code>imm₂</code>: interval timer minutes
• <code>stat₂</code>: 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