🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
Book a DemoInstallSign in
Socket

switchbotpy

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

switchbotpy

An API for Switchbots that allows to control actions, settings and timers (also password protected)

0.1.8
PyPI
Maintainers
1

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

RequestNotification (Response)
NameHandleUnencryptedEncryptedRequiredHandleValue
press0x160x 57 010x 57 11 pw80x13stat2
turn on0x 57 01 010x 57 11 pw8 01
turn off0x 57 01 020x 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.

RequestNotification (Response)
NameHandleUnencryptedEncryptedRequiredHandleValue
get settings0x160x 57 020x 57 12 pw8x0x13 0x stat2 bat2 fw2 64 00 00 00 00 nt2 ds1 inv1 sec2
batterybat2: 1st byte of value
firmwarefw2: 2nd byte of value (div by 10)
number of timersnt2: 8th byte of value
dual state modeds1: first 4 bits of 9th byte of value
inverse directioninv1: last 4 bits of 9th byte of value
hold secondssec2: 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

RequestNotification (Response)
NameHandleUnencryptedEncryptedRequiredHandleValue
hold time0x160x 57 0f 08 sec20x 57 1f pw8 08 sec20x13stat2
mode0x 57 03 64 ds1inv10x 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

RequestNotification (Response)
NameHandleUnencryptedEncryptedRequiredHandleValue
get timer0x160x 57 08 tid130x 57 18 pw8 tid13x0x13
set timer0x 57 09 tid13 timer200x 57 19 pw8 tid13 timer20stat2
sync timer0x 57 09 01 t160x 57 19 pw8 01 t16stat2
  • 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

Keywords

Switchbot

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts