Bot BLE open API

Bot Broadcast Message
Broadcast Message Format
- (Old) Broadcast Message
- (New) Broadcast Message
Broadcast Mode
BLE Communication Data Message Basic Format
0x01 Execute an Action
0x02 Get Device Basic Info
0x03 Set Device Basic Info
0x08 Get Device Time Management Info
0x09 Set Device Time Management Info
0x0f Extended Command
- 0x08 Set long press duration

Bot Broadcast Message

This broadcast message defines the Service data of Scan Rsp of the specific Device.

The length of the Service data is different based on Device Type. The Service data can be 8 bytes max. The Byte: 0, Byte: 1 and Byte: 2 are for every Device Type. The bytes start from Byte: 3 depends on different Device Type. Please refer to Device Type definition in the table below.
Broadcast modes are defined as:
- SwitchBot Mode (Default)
- Simple Mode
- iBeacon Mode

Device Types
Product Name	HEX	ASCII	Note
SwitchBot Bot (WoHand)	0x48	'H'
WoButton	0x42	'B'
SwitchBot Hub (WoLink)	0x4C	'L'	'Add Mode'
SwitchBot Hub (WoLink)	0x6C	'l'	'Normal Mode'
SwitchBot Hub Plus (WoLink Plus)	0x50	'P'	'Add Mode'
SwitchBot Hub Plus (WoLink Plus)	0x70	'p'	'Normal Mode'
SwitchBot Fan (WoFan)	0x46	'F'	'Add Mode'
SwitchBot Fan (WoFan)	0x66	'f'	'Normal Mode'
SwitchBot MeterTH (WoSensorTH)	0x74	't'	'Add Mode'
SwitchBot MeterTH (WoSensorTH)	0x54	'T'	'Normal Mode'
SwitchBot Mini (HubMini)	0x4D	'M'	'Add Mode'
SwitchBot Mini (HubMini)	0x6D	'm'	'Normal Mode'

Device Type

Broadcast Message Format

(Old) Broadcast Message

Use this for firmware version before Bot v30, Remote v20 and Hub v6.

Advertise:

Manufacturer data: includes device's company ID and MAC address (support WeChat protocol)

Scanrsp:

Device Name: "Bot", "Remote", "Hub", "WoSensorTH"
UUID: cba20d00-224d-11e6-9fb8-0002a5d5c51b and fee7

(New) Broadcast Message

The length of the Service data is different based on Device Type. The Service data can be 8 bytes max.

The bit[6:0] in Byte: 0 of the broadcast message is Device Type. The Byte: 0, Byte: 1 and Byte: 2 are for every Device Type. The bytes start from Byte: 3 depends on different Device Type, serving as general registers.

The backend also needs a mapping table of the Service data, so both the backend and app can parse the Service data.

Service data
Byte: 0	Enc Type Dev Type	Bit[7] - Reserved When Enc type - Byte: 1 Bit[5] = 0 0: no encryption 1: encryption algorithm 1 (the same as the Bot) When Enc type - Byte: 1 Bit[5] = 1 0: encryption algorithm 2 (TBD) 1: encryption algorithm 3 (TBD)
Byte: 0	Enc Type Dev Type	Bit[6:0] - Device Type Please refer to the Device Type table above.
Byte: 1	Status	Bit[7] - Switchbot Mode 0: one state mode 1: on/off state mode
		Bit[6] - State 0: on 1: off
		Bit[5] - Enc type 0: encryption algorithm (the same as the Bot) 1: encryption algorithm 2 or 3 (TBD) Please refer to Byte: 0 Bit[7]
		Bit[4] - Data Commit Flag 0: service data no data update 1: service data has data update The flag bit needs to be cleared by the Hub or App after the data is successfully updated, and the Device itself will not actively clear this flag.
		Bit[3] – Group D Bit[2] – Group C Bit[1] – Group B Bit[0] – Group A 0: the Device is not in this group 1: the Device is in this group
Byte: 2	Update UTC Flag Battery	Bit[7] – Sync UTC 0: no need to synchronize 1: the Device has passed a time synchronization cycle (10 days by default) and requires a time synchronization The Device uses UTC time when synchronizing. The Device will actively clear this flag after the Hub or App synchronize successfully.
Byte: 2	Update UTC Flag Battery	Bit[6:0] - Remaining Battery 0~100%

Broadcast Mode

SwitchBot Mode (Default)

Advertise:

Manufacturer data: include device's company ID (0x0059 Nordic) and MAC address (support WeChat protocol)
BLE_ADVDATA_NO_NAME

Scanrsp:

UUID: cba20d00-224d-11e6-9fb8-0002a5d5c51b and fee7
BLE_ADVDATA_NO_NAME

Example:

Simple Mode

Advsertise:

BLE_ADVDATA_NO_NAME

Scanrsp:

UUID (cba20d00-224d-11e6-9fb8-0002a5d5c51b)
BLE_ADVDATA_NO_NAME

iBeacon Mode (if you need welcome function)

Advertise:

Standard iBeacon package

UUID:cba20d00-224d-11e6-9fb8-0002a5d5c51b
Major ID:
High Byte: bit 7:4 - beacon type
Bit[3:0] - beacon data
Low Byte: beacon data
Minor ID:beacon data
TX power: 0xc3
BLE_ADVDATA_NO_NAME

beacon data instruction
Beacon Type	Major ID High byte bit[3:0]	Major ID Low byte	Minor ID High byte	Minor ID Low byte
0	Alert	MAC [3]	MAC [4]	MAC [5]

Scanrsp:

UUID(cba20d00-224d-11e6-9fb8-0002a5d5c51b)
BLE_ADVDATA_NO_NAME

BLE Communication Data Message Basic Format

The controlling terminal (short as the Terminal below) and the configured device (short as the Device below) use BLE to communicate with each other wirelessly. During the communication, the Terminal acts as a central device, while the Device acts as peripheral device. The Terminal gets basic device info by reading the broadcast message of the Device. They exchange data by using read and write characteristic of communication service.

All bilateral communication is after the BLE connection established. The Terminal send a REQ message to the Device, and then the Device returns a RESP message.

All communication message data length is 1-20 bytes, i.e. MTU=20. There are 2 types of REQ messages sending from the Terminal to the Device, encrypted and unencrypted.

Communication service UUID:
- cba20d00-224d-11e6-9fb8-0002a5d5c51b
- UUID TYPE:Vendor UUID types start at this index (128-bit)

RX characteristic UUID of the message from the Terminal to the Device:
- UUID: cba20002-224d-11e6-9fb8-0002a5d5c51b
- UUID TYPE: Vendor UUID types start at this index (128-bit)
- Char Attribute: RW
- Char Properties: notify

TX characteristic UUID of the message from the Device to the Terminal:
- cba20003-224d-11e6-9fb8-0002a5d5c51b
- UUID TYPE: Vendor UUID types start at this index (128-bit)
- Char Attribute: RW

All communication message data length is 1-20 bytes, i.e. MTU=20.

The REQ data from the Terminal to the Device is as below:

REQ message
Byte: 0	Magic Number	0x57 - (fixed value)
Byte: 1	Header	Bit [7:6] - Version 0 - (fixed value)
		Bit [5:4] - Encryption Mode 0 - no encryption
		Bit [3:0] - Command 0x01 - Execute an Action 0x02 - Get Device Basic Info 0x03 - Set Device Basic Info 0x08 - Get Device Time Management Info 0x09 - Set Device Time Management Info 0x0f – Enable command_ext in Byte: 2
Byte: 2	Payload or command_ext depend on command	if command == 0x0f{ command_ext : 0x08 - Set long press duration } else{ Payload }
Byte: 3-16	Payload	Depends on Command

Payload complement the data info to the Commands. The Payload format varies for different Commands.

The basic format of RESP message from the Terminal to the Device:

RESP message
Byte: 0	Response status	0x01 - OK Action executed 0x02 - ERROR Error while executing an Action 0x03 - BUSY Device is busy now, please try later 0x04 - Communication protocol version incompatible 0x05 - Device does not support this Command 0x06 - Device low battery 0x07 - Device is encrypted 0x08 - Device is unencrypted 0x09 - Password error 0x0A - Device does not support this encription method 0x0B - Failed to locate a nearby mesh Device 0x0C - Failed to connect to the network
Byte: 1-19	Payload	Depends on the Command to reply

Status returns the handling result of the Device to the earlier command, which is the 1st Byte of every RESP message, and also mandatory.

Payload complement the data info to the Commands. The data length is 0-19 bytes depends on different cases, and can also be omitted.

The format of the Payload is up to the Command type it is responding and the handling result.

0x01 Execute an Action

By sending this command, the Bot will complete a major action:
Bot: Execute an action of moving the arm to press down and then move it back.
If executed successfully, the Status Byte of the RESP message will be 1.

REQ message payload
Byte: 0	Action control	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 1-2	Byte: 1	Time Internal (second)
Byte: 1-2	Byte: 2	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 3-4	Byte: 3	Time Internal (second)
Byte: 3-4	Byte: 4	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 5-6	Byte: 5	Time Internal (second)
Byte: 5-6	Byte: 6	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 7-8	Byte: 7	Time Internal (second)
Byte: 7-8	Byte: 8	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte:9-10	Byte: 9	Time Internal (second)
Byte:9-10	Byte: 10	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte:11-12	Byte: 11	Time Internal (second)
Byte:11-12	Byte: 12	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte:13-14	Byte: 13	Time Internal (second)
Byte:13-14	Byte: 14	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 15	Encrypted Mode	payload last byte, reserved
Byte: 15	Unencrypted Mode	Time Internal (second)
Byte: 16 Not existed for Encrypted Mode	Unencrypted Mode	0x0 - push and pull back 0x1 - light switch on 0x2 - light switch off 0x3 - push stop 0x4 - back
Byte: 17	Not existed for Encrypted Mode	This is the last byte of payload in Unencrypted Mode

Note: Byte: every 2 bytes are the same group for byte 1-16. The odd byterepresents the time interval of the coming action to the previous one, the even byte means the action to be executed in the action list. The time internal should not be set as 0, because the first time interval of 0 means the end of the action list. Regardless the value of Byte 17, the action list never stop.

Example:

In current firmware version, Terminal send Device a message of "0x57 0x01 0x00" to control the Bot to move the arm.

The Status Byte of the RESP message will be 1 when executed successfully, and the Payload will be like:

RESP message payload
Byte: 0	Running Information	Return the running information to controller for analyzing

Use NRF Connect to issue command "0x570100" to the Device, the Bot arm moves.

Note:

When the Device is in the Add-on mode，the replied RESP message will be 0x0548C0, Status is 0x05 Device does not support this Command.

When the Device is not in the Add-on mode, i.e the normal press mode, the replied RESP message will be 0x01FF00, Status is 0x01 OK Action executed.

0x02 Get Device Basic Info

This command is used to get the basic info of a Device:
REQ message payload is 0.
If executed successfully, the Status Byte of the RESP message will be 1. The payload is the Device basic info:
- This command is used to get the basic info of a SwitchBot (the Bot), remaining battery, firmware version, number of timers, act mode, hold-and-press timer, etc.

REQ message payload is 0.


REQ message payload: 0

If executed successfully, the Status Byte of the RESP message will be 0, payload format is as below:

RESP message payload
Byte: 0	Bat Per	The battery percentage
Byte: 1	FW Ver	Firmware Version
Byte: 2	NC
Byte: 3-4	NC	NC
Byte: 5-6	NC	NC
Byte: 7	Timer Num	The number of Timer
Byte: 8	Act Mode	The act mode of Bot
Byte: 9	Hold Times
Byte: 10	Service data byte 0
Byte: 11	Service data byte 1

Example:

Use NRF Connect to issue command 0x5702 to the Device and get relevant info.

Replied RESP message is 01642C64000000A10000004800

Status Byte is 0x01 OK Action executed;

RESP message payload Byte 0 is 0x64: 100% remaining battery.

RESP message payload Byte 1 is 0x2C: 44*0.1=4.4 Firmware Version;

RESP message payload Byte 2 is 0x64: 100 The strength to push button;

RESP message payload Byte 3-4 is 0x00 0x00: The ADC value read from sensor;

RESP message payload Byte 5-6 is 0x00 0xA1: The motor calibration value;

RESP message payload Byte 7 is 0x00: The number of Timer is 0;

RESP message payload Byte 8 is 0x00: The act mode of Bot: Not Add-on Mode, i.e. normal press mode;

RESP message payload Byte 9 is 0x00: Hold-and-press Times;

RESP message Payload Byte 10 is 0x48: service data Byte 0;

RESP message Payload Byte 11 is 0x00: service data Byte 1;

0x03 Set Device Basic Info

This command is used to set basic info of a Device:
REQ message payload is 2.
- This command could be used to set SwitchBot act mode.
If executed successfully, the Status Byte of the RESP message will be 1. The payload is 2:

REQ message payload:
Byte: 0	NC	The App must always give a value of 100.
Byte: 1	act mode	The mode of Bot. Bit[7:4] Bot mode:0 - One Bot can only press one button. 1 - One Bot can control two state of switch. Bit[3:0] Bot inverse 0 - Act para 0x01 is push for turn on. Act para 0x02 is pull for turn off. 1 - Act para 0x01 is push for turn off. Act para 0x02 is pull for turn on. Inverse won’t affect act para 0x00. Eg. 0x10 is two state switch mode, and push for turn on, pull for turn off.

If executed successfully, the Status Byte of the RESP message will be 1. The payload is 2:

RESP message status: 1
Byte: 0	Status

RESP message payload:
Byte: 0	NC
Byte: 1	Bot: Act mode	The act mode of Bot

Example:

Use NRF Connect to issue command 0x57036310 to a Device, set the Device as Add-on mode. If the Device (i.e. the Bot) was not in Add-on mode, the Bot arm will moves accordingly once mode set.

Replied RESP message is 0x016300;

Status Byte is 0x01 OK Action executed

Then use NRF Connect to issue a command 0x5702 to the Device and get some basic setting info.

The replied RESP message is, let's say, 01642C64000000A10000004800;

Status Byte is 0x01 OK Action executed

RESP message payload Byte 2 is 0x63: 99 The strength to push button;

RESP message payload Byte 8 is 0x10: The act mode of Bot: Add-on Mode;

0x08 Get Device Time Management Info

Used to get time management info, including current time, the number of alarms, the time of the alarms.
REQ message payload is 1 (3 Subcmd: get current time, get the number of alarms, get the alarm time).
If executed successfully, the Status Byte of the RESP message will be1，payload is up to Subcmd type.

REQ message payload:

REQ message payload:
Byte: 0	Subcmd	Indicates what to obtain from the target Device 0x01: Device current time 0x02: the number of alarm tasks the Device has 0xn3(n=0..4): what is the Nth task

If executed successfully, the Status Byte of the RESP message will be 0. For different subcmd, the Payload will be:

Subcmd=1:

RESP message payload:
Byte: 0-7	Current system timestamp	The current Unix timestamp in big endian

Subcmd=2:

RESP message payload:
Byte: 0	Num	Total number of tasks

Subcmd=0xn3(n=0..4) what is the Nth task:

RESP message payload:
Byte: 0	Num	Total number of tasks
Byte: 1	Index	Task index number
Byte: 2	Repeat	Repeating method: Bit [7]: repeating mode setting 1 - execute 1 time 0 - execute repeatedly Bit [6:0]: Sun to Mon 1 - valid for this date 0 - invalid for this date
Byte: 3	Time of HH	HH
Byte: 4	Time of MM	MM
Byte: 5	Action mode	0 - Execute the job at HH:MM in a repeating method. 1 - Execute the job at HH:MM in a repeating method, and repeat Sum times at the interval of Interval. 2 - Execute the job at HH:MM in a repeating method, and repeat forever at the interval of Interval.
Byte: 6	Job	What to do when time is up. 0 - Action 1 - On 2 - Off
Byte: 7	Sum	The total times of the continuous actions executed by the timer
Byte: 8-10	Interval: the interval between the continuous actions for the timer	HH (Max. 5)
		MM
		SS (in step of 10)

Example:

Use NRF Connect to issue command 0x570802 to the Device, get the number of alarms.

The replied RESP message is 0x0103;

Status Byte is 0x01 OK Action executed

RESP message payload Byte 0 is 0x03: Total number of tasks;

0x09 Set Device Time Management Info

Used to set Device time management info, including current time, the number of alarms, the time of the alarms.
Always set all 5 build-in timers simultaneously when setting alarm time.
REQ message payload depends on different Subcmd (3 types of Subcmd: set current time, set the number of alarms, set time of the alarms).
If executed successfully, the Status Byte of the RESP message will be 1, payload will be 0.

There are 3 formats for REQ message payload:

1.

REQ message payload:
Byte: 0	Subcmd	0x01: device current times
Byte: 1-8	Current system timestamp	The current Unix timestamp in big endian

2.

REQ message payload:
Byte: 0	Subcmd	0x02: the number of alarm tasks the Device has
Byte: 1	Num	Total number of tasks

3.

Rev

REQ message payload:
Byte: 0	Subcmd	0xn3(n=0..4): set the Nth task
Byte: 1	Num	Total number of tasks
Byte: 2	Index	Rev
Byte: 3	Repeat	Repeating method: Bit [7]: repeating mode setting 1 - execute 1 time 0 - execute repeatedly Bit [6:0]: Sun to Mon 1 - valid for this date 0 - invalid for this date
Byte: 4	Time of HH	HH
Byte: 5	Time of MM	MM
Byte: 6	Action mode	0 - Execute the job at HH:MM in a repeating method. 1 - Execute the job at HH:MM in a repeating method, and repeat Sum times at the interval of Interval. 2 - Execute the job at HH:MM in a repeating method, and repeat forever at the interval of Interval.
Byte: 7	Job	What to do when time is up. 0 - Action 1 - On 2 - Off
Byte: 8	Sum	The total times of the continuous actions executed by the timer
Byte: 9-11	Sum	HH (Max. 5)
		MM
		SS (in step of 10)

If executed successfully, the Status Byte of the RESP message will be 1, payload will be 0.

RESP message status: 1
Byte: 0	Status

RESP message payload: 0

Example:

Use NRF Connect to issue command 0x57090203 to a Device, and set 3 alarms to the Device.

Replied RESP message is 0x01;

Status Byte is 0x01 OK Action executed

0x0f Extended Command

0x08 Set long press duration

To set the duration (in second) for SwitchBot arm to long press
REQ Packet payload: 1
If executed successfully, the Status Byte of the RESP message will be 1, payload will be 0.

REQ Packet payload: 1

REQ Packet payload:
Byte: 0	Time

If executed successfully, the Status Byte of the RESP message will be 1, payload will be 0.

RESP Packet status: 1
Byte: 0	Status	1 – OK

Example:

Use NRF Connect to send a command 0x570f0803 to a Device, and set the long press duration to 3 seconds.

If the received RESP packet is 0x01

Replied RESP message is 0x01, meaning a successful setting.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!