MCU Integration Protocol

This topic describes the serial port protocol in Tuya Bluetooth Low Energy pass-through solutions. It applies to a communication solution with the following architecture:

Serial communication convention

Term	Description
Baud (bps)	9600
Data bit	8
Parity	None
Stop bit	1
Data flow control	None

Terms

Term	Description
DP	A data point (DP) refers to one function or one pair of commands.
PID	Product ID. It describes the collection of one type of product function (DP). Every product that is created on the Tuya IoT Platform will have a unique product ID (PID). The PID is associated with all information related to this product, including specific DP, app control panel, and delivery information.

Frame data packet structure

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	It is used for update and extension
3	1	Command (CMD)	Specific frame type
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	–
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Note: All data greater than one byte shall be transmitted in big-endian format.

DP format

Field	Bytes	Description
dp_id	1	DP command
dp_type	1	DP data type
dp_data_len	2	DP data length
dp_data_value	dp_data_len	DP data (see DP protocol for details)

Dp_type value range and meaning (cloud definition):

dp_type	Value	Bytes	Description
raw	0x00	1–255	Raw type, hexadecimal array
bool	0x01	1	Boolean
value	0x02	4	Value type (integer)
string	0x03	0–255	String (it might be null)
enum	0x04	1	Enumeration

Categories of general firmware

• The general serial port protocol is extended to expand the functions of Bluetooth general firmware, and provide general firmware with features of one category. At present, the whole protocol consists of General connection protocol, Supplemental protocol for low power function, and Supplemental protocol for general firmware of locks.

• All general firmware supports general connection protocol, and some of them support the supplemental protocol for low power function. The supplemental protocol for the general firmware of locks is supported by general firmware in the corresponding categories.

List of modules supported by general connection categories:

Category	Chip/module
Lock	TYBN1 and BK3431Q
Healthy/shared categories	BK3432, BK3431Q, and TYBT3L
Basic categories	BK3432, TYBT3L, TYBT4L, and other Telink modules

Note: Some modules have general firmware of multiple categories.

Protocol API supported by general firmware of all categories

General firmware of different categories supports different protocols, and the protocol APIs vary depending on versions of the same category.

Protocol API supported by general firmware of all categories is shown in the following figure:

General connection protocol

Basic workflow diagram is shown as follows.

Heartbeat packet (CMD: 0x00)

• After a module is powered on, a heartbeat packet is sent every three seconds. After receiving a response from the MCU, the module considers that the MCU is working properly. The MCU responds to the heartbeat packet for the first time after power-on or reboot, and then the module queries the product information from the MCU.

• According to the heartbeat packet, the MCU regularly checks whether the module works properly. If the module does not send a heartbeat packet, the MCU can reset the module through the reset pin of the module.

• After the module receives messages from the MCU, there is no heartbeat in the low power mode, and the heartbeat packet is sent every 10 seconds in the normal power mode.
  

  Note: The Telink module has no heartbeat in low power mode, and no longer sends heartbeat packets after getting the PID from the MCU, so it cannot detect whether the MCU reboots.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x00
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x00
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state	Description
0x00	The MCU sends this value when it receives the first heartbeat packet after powered on. The module can determine whether the MCU reboots during operation according to this value.
0x01	The returned value in other cases, except the 0x00 returned by the MCU for the first time after reboot.

Get MCU information (CMD: 0x01)

• Product key: With 8 bytes, the product key is generated by the Tuya IoT Platform to record the product information in the cloud.
  
• Product information mainly refers to PID.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x01
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x01
4 5	2	Data length	0x00 0x0d
6–18	0x0d	Data	See the following table
19	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1–8	9–13
PID	Reserved field

For example, 55 AA 00 01 00 0D 66 74 62 38 78 32 78  30 31 2E 30 2E 30 C0 (PID=ftb8x2x0, and MCU version=1.0.0)

The PID is an 8-bit string, such as ftb8x2x0.

Note: Reserved field is filled with the MCU software version number. This field is not parsed by the module, so it is reserved. The MCU version number is reported by CMD E8\E9.

Request the working mode of the module (CMD: 0x02)

The working mode of the module includes how to indicate working status and how to reset the module. There are two cases:

1. Coordinated processing by the MCU and the module: The module notifies the MCU of the current working status of the module through a serial port, and the MCU displays the working status of the module. The MCU detects the reset requirement of the module, and through the serial port, notifies the module to reset.
   
2. Self-processing by the module: It is not supported now.
   

Note: At present, only the coordinated processing by the MCU and the module is supported.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x02
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, 55 aa 00 02 00 00 01

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x02
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, 55 AA 00 02 00 00 01

Send module working status (CMD: 0x03)

• Working status of the module: 0x00—unbound, 0x01— bound but not connected, and 0x02—bound and connected.
  
• After the module receives the MCU’s request for the working mode of the module and reply of CMD 0x02, the module sends its working mode to the MCU.
• When the module detects status changes of the module, the module sends the module status to the MCU.
  

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x03
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

State	Description	Healthy/shared general firmware
0x00 0x01	Unbound bound but not connected	The concept of binding in healthy and shared products is obfuscated. When the healthy/shared products are in the unbound status and bound but not connected status, the product can be paired.
0x02	Bound and connected	When the healthy/shared products are in the bound and connected status, the device is paired and connected to the network.

Reset the module (CMD: 0x04)

Disconnect Bluetooth, unbind the Bluetooth, clear offline cache of the module, clear virtual ID, and then reboot.

Note: In the past, this API is used to unbind devices on the Telink platform. In order not to affect their functions, virtual ID will not be cleared after reset on the Telink platform.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x04
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, 55 aa 00 04 00 00 03

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x04
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, 55 AA 00 04 00 00 03

Send command (CMD: 0x06)

• For more information about the data points, see DP format description.
  
• “Send the command” can contain “command data units” of multiple data points.
  
• “Send the command” is an asynchronous processing protocol, corresponding to “report DP status” of the MCU.
  

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x06
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	datapoint	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Datapoint format:

1	2	3–4	5–	…	n	n+1	n+1 to n+2	n+3–
dp1_id	dp1_type	dp1_len	dp1_data	…	dpN_id	dpN_type	dpN_len	dpN_data

For example, 55 aa 00 06 00 05 03 01 00 01 01 10

The MCU returns the following command:

None

Report the status (CMD: 0x07)

• For more information about the data points, see DP format description.
  
• “Report the status” can contain “command data units” of multiple data points.
  
• “Report the status” is an asynchronous processing protocol. Its trigger mechanism has three types:
  

1. After receiving the “send the command” processing frame, the MCU executes the command of the corresponding data point, and then sends the changed status to the module through the “report the status” frame.
   
2. The MCU detects that the data point has changed, and sends the changed status to the module.
   
3. After the MCU receives a status query frame, the MCU sends the status of all data points to the module.
   

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x07
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	datapoint	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Datapoint format:

1	2	3–4	5–	…	n	n+1	n+1 to n+2	n+3–
dp1_id	dp1_type	dp1_len	dp1_data	…	dpN_id	dpN_type	dpN_len	dpN_data

For example, 55 aa 00 06 00 05 03 01 00 01 01 10

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x07
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: succeeded
0x01: failed

Query the status (CMD: 0x08)

• “Query the status” is an asynchronous processing command that is used by the module to query the status of all “object” type data points of the MCU. When the MCU receives this frame, the MCU reports the status of data points through CMD 0x07 status reporting frame.
  
• “Query the status” is sent at two time points:
  
  1. When the module is bound and connected and detects that the MCU is rebooted (according to heartbeat response), the “query the status” frame is sent. Note: Telink general firmware does not support detecting the MCU rebooting.
     
  2. When the module Bluetooth is offline and then goes online (it changed from bound but not connected status to bound and connected status), the “query the status” frame is sent.
     

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x08
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

For example, 55 aa 00 08 00 00 07

The MCU returns the following command:
None

Unbind the module (CMD: 0x09)

• Unbind the module from the mobile phone, and disconnect the Bluetooth connection. The data and virtual ID will not be cleared.
  
• The concept of “binding” in the healthy (shared) general firmware is obfuscated. Therefore, the module cannot unbind from the API.**
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x09
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x09
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: succeeded
0x01: failed

Query the connection status of the module (CMD: 0x0A)

• The MCU queries the connection status of the module. After the module receives the query, the module sends its working status through CMD 0x03.
• Working status of the module: 0x00—unbound, 0x01— bound but not connected, and 0x02—bound and connected.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x0A
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Report the record type data (CMD: 0xE0)

• This API is used to report important data. If the module is offline during reporting, the module will store the data in the module flash, and report the data to the app after the module goes online. After the module is online and the last piece of data is reported successfully continuously, the cache data will be transmitted to the app.
  
• The module can store maximum N pieces of DP data. In case of exceeding the limit, the earliest records will be overwritten:
  
  1. nrf52832/BK3431q can store maximum 80 pieces of data, and each piece of data has maximum 200 bytes.
     
  2. nrf52832/BK3431q can store maximum 80 pieces of data, and each piece of data has maximum 200 bytes.
     
  3. bk3432 can store maximum 32 pieces of data, and each piece of data has maximum 32 bytes.
     
• The clock inside the Bluetooth module has limited accuracy, and the error is less than one minute in 24 hours. The clock is recalibrated during each reconnection. If you have a high requirement on the accuracy, you can use the built-in time of the MCU.
  

Note: It is strongly recommended that the record type data should be reported with this API, no matter the device is online or offline.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE0
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1	2–x	x	x+1	x+2 to x+3	x+4–	…	n	n+1	n+1 to n+2	n+3–
TYPE	Time_Str	dp1_id	dp1_type	dp1_len	dp1_data	…	dpN_id	dpN_type	dpN_len	dpN_data

Time_Str: 13-bit Unix time string

TYPE	Description
0x01	Format 1: Report DP status by using the built-in time of Bluetooth module
0x02	Format 2: Report the raw data only, and the time refers to the actual time during transmission
0x03	Format 3: Report DP status by using the built-in time of MCU

unix_time_string: It is required only when TYPE is 0x02, and it can be empty when TYPE is in other formats.

For example,

• Format 1: Report DP status by using the built-in time of Bluetooth module:
  
  55 AA 00 E0 00 17 01 66 02 00 04 00 00 00 01 67 03 00 05 72 77 72 77 77 68 04 00 01 00 89
• Format 2: Report the raw data only, and the time refers to the actual time during transmission:
  
  55 AA 00 E0 00 1B 02 66 02 00 04 00 00 00 01 67 03 00 09 72 77 72 77 77 61 66 61 66 68 04 00 01 00 20
• Format 3: Report DP status by using the built-in time of the MCU:
  
  55 AA 00 E0 00 28 03 31 35 38 39 31 36 38 33 32 37 30 30 30 66 02 00 04 00 00 00 01 67 03 00 09 72 77 72 77 77 61 66 61 66 68 04 00 01 00 D0

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE0
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: stored successfully
Others: failed to store

Get the real time (CMD: 0xE1)

• It is recommended to use the format 0x02 to request the time in the YYMMDD format.
  
• After the device is online, the time in the cloud will be synchronized to the MCU once.
  

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE1
4 5	2	Data length	0x00 0x01
6	1	Time_Type	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Time_type description:

Time_Type	Description
0x00	Format 0 means to get 7-byte time type plus 2-byte time zone information
0x01	Format 1 means to get 13-bytes ms-level Unix time plus 2-byte time zone information
0x02	Format 2 means to get 7-byte time type plus 2-byte time zone information

Note:

• Format 0 to get custom time has compatibility issues with different platforms and will be deprecated in later versions. It is recommended to use the 0x02 format for the year, month, and day time format.
• Telink general firmware no longer supports format 0. If the time in format 0 is requested, the time in format 2 will be returned.
• Time zone: 100 times the actual time zone. For example, it is 8x100=800 in the GMT+8, and -750 in the GMT-7.5.

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE1
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Time_Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Time_Data format 0:

Result code	Time format	Year	Month	Day	Hour	Minute	Second	Week	Time Zone
1	2	3	4	5	6	7	8	9	10–11
Result	Time_Type	2018 + year	mon	day	hour	min	sec	week	time_zone

Time_Data format 1:

Result code	Time format	Unix time in milliseconds	Time Zone
1	2	3151617
Result	Time_Type	unix_time_string	time_zone

Time_Data format 2:

Result code	Time format	Year	Month	Day	Hour	Minute	Second	Week	Time Zone
1	2	3	4	5	6	7	8	9	10–11
Result	Time_Type	2000 + year	mon	day	hour	min	sec	week	time_zone

It succeeded when Result is 0x00, and it failed when Result has other values.

For example,

• Time_Data format 0:
  

  MCU—55 AA 00 E1 00 01 00 E1
  
  Module—55 AA 00 E1 00 0B 00 00 01 0C 1E 0F 34 1F 01 03 20 9C // 15:52:31, December 30, 2019, Monday, GMT+8
  

• Time_Data format 1:
  

  MCU—55 AA 00 E1 00 01 01 E2
  
  Module—55 AA 00 E1 00 11 00 01 31 35 37 37 36 39 32 33 39 35 30 30 30 03 20 BB// Timestamp 1577692395000, GMT+8

• Time_Data format 2:
  

  MCU—55 AA 00 E1 00 01 02 E3
  
  Module—55 AA 00 E1 00 0B 00 02 13 0C 1E 10 09 29 01 03 20 90 // 16:09:35, December 30, 2019, Monday, GMT+8
  

MCU-OTA APIs

Query the version number of MCU (CMD: 0xE8)

• The module sends a command to query the MCU version number every time it sends a command to get the MCU information.
• For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE8
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE8
4 5	2	Data length	0x00 0x06
6–11	6	DATA	See the following table
12	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1–3	4–6
Soft_Ver	Hard_ver

Soft_Ver: the version number of the current MCU firmware. For example, 0x01 00 02 means that the version number is v1.0.2.

Hard_ver: the version number of the current MCU hardware, also PCBA version number.

MCU sends current version number (CMD: 0xE9)

• In order to ensure that the module gets the MCU version information in time, the MCU needs to actively send the current version number to the module every time it is started (usually after the serial port is initialized). If it does not receive a response from the module, it needs to be sent again.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE9
4 5	2	Data length	0x00 0x06
6–11	6	DATA	See the following table
12	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1–3	4–6
Soft_Ver	Hard_ver

Soft_Ver: the version number of the current MCU firmware. For example, 0x01 00 02 means that the version number is v1.0.2.

Hard_ver: the version number of the current MCU hardware, also PCBA version number.

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE9
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: succeeded
Others: failed

MCU-OTA flowchart

MCU-OTA update request (CMD: 0xEA)

• When the update starts, the module sends a request to the MCU to get the maximum single packet length that the MCU serial port can transmit.
• For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEA
4 5	2	Data length	0x00 0x02
6–7	2	Maximum data length of single packet—len 1	See the note
8	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Len 1: Maximum data length of a single packet allowed by the device. Unit: byte.

For example, 55 AA 00 EA 00 02 00 C8 B3.

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEA
4 5	2	Data length	0x00 0x06
6–11	6	Data	See the following table
12	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1	2–4	5–6
Flag	The version number of current MCU firmware	Maximum acceptable data length—len 2

Flag: 0x00 indicates that the update is allowed, and 0x01 indicates that the update is refused.

Version: the version number of current firmware. For example, 0x01 00 02 means that the version number is v1.0.2.

Len1: Maximum data length of a single packet limited by the module.

Len2: Maximum acceptable packet length of the MCU. If len1 is less than len2, the len1 shall prevail during the update. Otherwise, len2 shall prevail.

For example, 55 AA 00 EA 00 06 00 01 00 00 00 C8 B8.

MCU-OTA update file information (CMD: 0xE8)

• This section describes MCU-OTA update file information. The MCU compares the update information, and decides to update or not.
• For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEB
4 5	2	Data length	0x00 0x23
6–40	35	Data	See the following table
41	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

8 bytes	3 bytes	16 bytes	4 bytes	4 bytes
Product ID (PID)	File version	File MD5	File length	CRC32

• PID: the PID of the MCU.
• File version: For example, 0x01 00 02 means that the version number is v1.0.2.
• File MD5: The MD5 value of the updated firmware.
• File length: The total length of the updated firmware, in bytes.
• CRC32: The CRC32 of the updated firmware.
  

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEB
4 5	2	Data length	0x00 0x19
6–30	25	Data	See the following table
31	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1 byte	4 bytes	4 bytes	16 bytes
STATE	Length of the stored file	CRC32 value of the stored file	MD5 value of the stored file (not used now)

STATE:

• 0x00: Normal update.
• 0x01: The PID is inconsistent.
• 0x02: The file version is lower than or equal to the current version.
• 0x03: The file size exceeds the range.
• Others: Reserved.

Note: The file information that is stored in the device will be returned, in order to support resumable transfer. After the app receives the file information, the app calculates the CRC32 value of the corresponding length of the new file according to the stored file length returned by the device, and then compares it with the CRC32 value returned by the device. If both values are the same, in the following file start transfer request, the start transfer offset is changed to this length value. Otherwise, the start transfer offset is changed to 0, meaning to start transfer from the beginning.

Caution: Each resumable transfer starts with an OTA update request according to the sequence of the MCU OTA process. If the MCU maintains the update status, when the MCU receives the information that the working mode of the module is other statuses except for the bound and connected status, the MCU resets the update status, in order to start the next update process.

MCU-OTA update file offset request (CMD: 0xEC)

For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEC
4 5	2	Data length	0x00 0x04
6–9	4	OFFSET	See the following table
10	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Note: Offset refers to the offset value of file start transfer, with four bytes.

For example, 55 AA 00 EA 00 02 00 C8 B3.

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEC
4 5	2	Data length	0x00 0x04
6–9	4	OFFSET	See the following table
10	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Offset: the offset value of the start transfer file required by the MCU.

Note: The offset address of the actual file transfer shall meet the MCU requirements. The address required by the MCU is less than or equal to the offset provided by the app.

MCU-OTA update data (CMD: 0xED)

For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xED
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

2 bytes	2 bytes	2 bytes	n bytes
Packet number	The length (n) of current packet data	The CRC16 value of current packet data	The current packet data

Note: Packet number starts with 0. The current packet data length cannot exceed the maximum packet length designated by the OTA update request command.

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xED
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

State	Description
0x00	Success
0x01	Packet number exception
0x02	Length is inconsistent
0x03	Cyclic redundancy check (CRC) failed
0x04	Others

MCU-OTA update is completed (CMD: 0xEE)

For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEE
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xEE
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Description:

State	Description
0x00	Success
0x01	The total data length is incorrect
0x02	Length is inconsistent
0x03	Others

Production test API

Radio frequency (RF) test (CMD: 0x0E)

• Received signal strength indication (RSSI) of the module shall be tested, in order to check whether RF of the Bluetooth module works properly after leaving the factory.
  
• Test tool: Bluetooth beacon (provided by Tuya), which emits a broadcast signal with the name of ty_mdev.
  
• Test steps: Firstly, put the beacon about 0.5 meters away from the module. Then, send the RF test command through a serial port. The module will search for a Bluetooth beacon and return the signal strength value. If the signal strength is greater than -70 dB, it is thought that the RF of the module works properly.
  

Important:

• Some special chips and modules, such as BK3431Q and BK3432, do not support the scanning of the beacon. The following tools are needed to test the RSSI:
  
• Test tool: Bluetooth dongle (provided by Tuya), which connects the device under test and returns RSSI.
  
• Test steps: Firstly, put the dongle about 0.5 meters away from the module. Then, send the RF test command to the module through a serial port. The dongle connects to the module and returns the signal strength value. If the signal strength is greater than -70 dB, it is considered that the RF of the module works properly.
  
• The module shall not be in the low power mode, and shall be unbound.
  

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x0E
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0x0E
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

Data	Description
{“ret”:true,“rssi”:“-55”}	The signal strength is -55 dB
{“ret”:false}	The signal is not found

Supplemental protocol for low power function

Different categories of general firmware have different low power mode designs.

Low power working description of locks—TYBN1 and BK3431Q

• After the module gets the MCU information, the heartbeat packets will no longer be sent in the low power status, and the heartbeat packets are normal under non-low power status.
• The working mode includes low power mode and non-low power mode.
  • In the non-low power mode, the Bluetooth broadcast interval is fixed at 100 ms. Data can be sent upstream and downstream through the serial port of the module.
  • In the low power mode, the Bluetooth broadcast interval is set by the MCU to one second by default. If the interval is 0, the Bluetooth broadcast is disabled. In this mode, data is sent downstream through the serial port of the module, but the upstream transfer is prohibited—it does not receive data from the MCU serial port.
• The low power working status of the module is determined by the level of the low power control pin of the module—SCL. Through the SCL, the MCU outputs different levels to control the power consumption status of the module. For more information, see the following table:

Platform Description	Low power control pin of the module—SCL	SCL level corresponding to low power	SCL level corresponding to non-low power
NORDIC	I/O11	High	Low
BK	P03	Low	High

It is recommended to use the serial port 20 milliseconds after the module is woken up.

The module uses SDL to wake up the external MCU. When the module needs to send data to the external MCU, the module changes SDL level for 200 milliseconds, sends the data, and then restores to the default level after the data is sent completely.

Platform Description	SDL—the pin that is used by the module to wake up the MCU	SDL level when data is being sent	SDL level during idle time
NORDIC	I/O14	Low	High
BK	P10	High	Low

• The low power API cannot be enabled. It is determined by the level of SCL, the low power control pin of the module.
  
• System timer cannot be disabled.
  

Note: SCL pull-up and pull-down might differ on platforms. The MCU pin that connects to SCL shall not float.

Modify broadcast interval in the low power mode (CMD: 0xE2)

• The general firmware of BK3432 healthy module does not support this operation.
  
• To reduce power consumption during sleep, you can modify the broadcast interval through this command. Broadcast parameters will be saved forever. When it is set to 0, the broadcast will be disabled. The setting will be saved forever.
  
• In the low power mode, the broadcast interval is one second by default. The greater the broadcast interval is, the longer time the connection requires. Some low-performance mobile phones might be hardly connected. Therefore, greater broadcast interval values are not recommended.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE2
4 5	2	Data length	0x00 0x01
6	1	Adv_interval	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Adv_interval: The value ranges from 0 to 20, and the unit is 100 milliseconds. The actual broadcast interval ranges from 100 milliseconds to 2 seconds. When the value is 0, the broadcast is disabled.

For example:
55 aa 00 E2 00 01 00 E2 (Disable the broadcast in the low power mode)
55 aa 00 E2 00 01 06 E8 (Set the broadcast interval to 600 milliseconds in the low power mode)

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE2
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Disable system timer (CMD: 0xE4)

• To reduce the power consumption of the Telink chip during sleep, the internal timing function of the Bluetooth module can be disabled through this command. If the MCU does not need the timing function, this function can be disabled. When the timing function and the broadcast function are both disabled, and SDA is pulled down, the module will enter deep sleep and the power consumption will be reduced to 3 μA. After waking up, the module will reboot and run again. The setting will be saved forever.
  
• In the BK3431Q and TYBN1 modules, the timing function has a relatively low power consumption, whereas flash storage consumes much power. Therefore, only the flash storage is disabled here. After the flash storage is enabled, the clock can store flash every minute to solve the RTC reset issue of the module after reboot. It is disabled by default.
  

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE4
4 5	2	Data length	0x00 0x01
6	1	Data	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

Data	Description
0x00	Disable the system timer
0x01	Enable the system timer

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE4
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Disconnect Bluetooth connection (CMD: 0xE7)

To reduce power consumption during sleep, when the MCU does not need Bluetooth connection, the Bluetooth connection of the module can be disconnected and the module can be put into low power mode to minimize the power consumption. The main function of this API is to disconnect the Bluetooth connection.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE7
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE7
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Configure low power wakeup of the MCU (CMD: 0xB0)

• Applicable modules: lock general firmware v6.2 and later versions support TYBN1, and lock general firmware v3.3 and later versions support BK3431Q.
  
• Considering that the previous wakeup time 200 milliseconds is too long, this value can be set by the MCU—the MCU can set the time period (t) required to wake up the MCU from low power mode. The value is 200 milliseconds by default. When the module sends serial port data to the MCU, the MCU wakeup pin will be pulled up or pulled down for about the time period (t).
  
• After the MCU is modified, test whether the MCU can be woken up within the wakeup time. If the answer is no, the wakeup time shall be increased. If you do not care much about the delay time, the default value can be used.
  
• Call time: After the MCU receives CMD 0x02 (55 aa 00 02 00 00 01), you can call this API to configure low power wakeup of the MCU. The setting is not saved forever. It is 200 milliseconds by default after the module is powered on or rebooted.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xB0
4 5	2	Data length	0x00 0x01
6	1	interval	See the note
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Note: Interval is in the unit of 10 milliseconds. Interval ranges from 1 to 20. At present, the minimum value is 10 milliseconds, and the maximum value is 200 milliseconds.

For example:
55 aa 00 E2 00 01 00 E2 (Disable the broadcast in the low power mode)
55 aa 00 E2 00 01 06 E8 (set the broadcast interval to 600 milliseconds in the low power mode)

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xB0
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Supplemental protocol for general firmware of locks

This section describes a supplemental protocol for the general firmware of locks. General firmware of other categories does not support this protocol. At present, the general firmware of locks includes BK3431Q general firmware and TYBN1 general firmware.

Dynamic password (CMD: 0xE6)

• The module calculates the dynamic password based on time. The calculated dynamic password is consistent only if the cloud time and device time are synchronous. Otherwise, a password error will occur. After the device is connected to an app, the time will be synchronized automatically.
  
• Input parameter of administrator password is not supported at present. Fill in 0 for the current administrator password.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE6
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

8 bytes	1 byte	N bytes	N bytes	…
password	Administrator password length	The first administrator password	The second administrator password	…

Password: the password data Data[0]\–Data[7] entered by the user. The data content ranges from 0 to 9 and the data transfer adopts ASCII code.

Input parameter of administrator password is not supported at present. Fill in 0 for the current administrator password.

For example, the MCU sends a data packet without an administrator password:

55 aa 00 E6 00 09 30 31 32 33 34 35 36 37 00 8a

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xE6
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: Password verification passed
0x01: Password verification failed

For example,
55 AA 00 E6 00 01 01 E7 (Password verification failed)
55 AA 00 E6 00 01 00 E6 (Password verification passed)

New dynamic password verification (CMD: 0xA7)

• The time data in the protocol is used to operate the current dynamic password. The operation time is the current Greenwich Mean Time (GMT). Therefore, the device is required to send GMT data to the module.
  
• The function is exactly the same as CMD 0xE6, the parameter has been changed, and the MCU can transfer the time.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA7
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	N bytes
TimeSource	2000 + year	Mon	Day	Hour	Min	Sec	Code_len	Code

• Time source:

• 0x00—the time comes from the year/mon/day/hour/min/sec field that is uploaded by the MCU.
• 0x01—the internal time of the module is used, and year/mon/day/hour/min/sec is not parsed. Fill in 0x00.
  Note: The time reported by the MCU should be in the year, month, and day format of GMT, that is, the year, month, and day time in the time zone 0. For example, Beijing time is 12:00:00, June 20, 2020, so you can fill in 0x14 0x06 0x14 0x04 0x00 0x00 for GMT time.
  

• Code_len: password length
  

• Code: Password. Different from the format of the old dynamic password CMD 0xE6 where the password passes the ASCII code ‘1’ to ‘9’, the new dynamic password directly passes the number, 1 is 0x01…9 is 0x09. Refer to the following example.
  

  55 AA 00 A7 00 10 00 14 0A 09 0D 33 2C 08 01 08 05 08 06 04 04 05 7A
  

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA7
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	State	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: Password verification passed
0x01: Password verification failed

For example:
55 AA 00 A7 00 01 01 A8 (Password verification failed)
55 AA 00 A7 00 01 00 A7 (Password verification passed)

Request for going online (CMD: 0xA5)

• This interface is used by the gateway to connect as needed. After the MCU calls this API, the Bluetooth module starts a high frequency broadcast for 30 seconds, similar to a “hand-up” process. After a Bluetooth host scans the marked module broadcast, the Bluetooth host connects to the module. After the module goes online, the MCU can report DPs normally.
  
• Generally, the record type data is reported by calling 0xE0. If the MCU detects that the module is bound but not connected, the MCU calls this API to request for going online. After the module goes online, the data that is reported by 0xE0 will be released automatically.
  
• Real-time data does not conform to the general scenario of active transmission. However, the MCU can report the real-time data in two ways:
  
  1. After this API is called, wait until the working status of the module becomes bound and connected. The working status is sent after the module goes online.
     
  2. The real-time data can be reported in the 0x02 format of 0xE0. After the module goes online, the data will be released to the app. This method is not recommended.
     
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA5
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA5
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: succeeded
0x01: failed

Offline password (CMD: 0xA2)

• If the device is not connected to the internet for long, a dynamic password is also available.
  
• The accuracy of the clock inside the module is not very high, and the error is less than one minute within 24 hours. Every time when the module goes online, the module synchronizes with cloud time. The clock inside the module cannot work and will be reset in case of power failure. If MCU has an external clock, it is strongly recommended that the clock source should select 0x00—the MCU uploads Greenwich Mean Time (GMT). If the clock inside the module is used, consult the R&D for a test program to measure the clock error.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA2
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	1 byte	N bytes
TimeSource	2000 + year	Mon	Day	Hour	Min	Sec	Code_len	Code

• Time source:

• 0x00: The time comes from the year/mon/day/hour/min/sec field that is uploaded by the MCU.
• 0x01: The internal time of the module is used, and year/mon/day/hour/min/sec is not parsed. Fill in 0x00.
  Note: The time reported by the MCU should be in the year, month, and day format of GMT, that is, the year, month, and day time in the time zone 0. For example, Beijing time is 12:00:00, June 20, 2020, so you can fill in 0x14 0x06 0x14 0x04 0x00 0x00 for GMT time.

• Code_len: password length
  
• Code: Password. Different from the format of ASCII code ‘1’ to ‘9’ in the dynamic password, the offline password reports the number directly. 1 is 0x01…9 is 0x09. See the following example.
  

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA2
4 5	2	Data length (Len)	Len high-order 8 bits Len low-order 8 bits
6 to 6 + Len-1	Len	Data	See the following table
6 + Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1 byte	1 byte	1 byte	N bytes
Result	Type	Decode_len	Decode

• Result: 0x00 indicates correct, and others indicate an error (subsequent data is meaningless).
• Type: 0x00 indicates that verification successful, 0x01 indicates the successful clearing of a single entry, and 0x02 indicates clearing all entries successfully.
• Code_len: Encrypted data length.
• Code: The encrypted clear code or unlocking password.

Type and code are used when MCU reports DPs, and parsed by reference to the offline password function in the lock DP protocol. DP ID: 65, 66, and 67.

For example, use the internal time of the module plus password (2279084005)

• The MCU: 55 AA 00 A2 00 12 01 00 00 00 00 00 00 0A 02 02 07 09 00 08 04 00 00 05 E3
• The module: 55 AA 00 A2 00 13 00 00 10 F3 50 3C 8F FF 03 F5 E9 0D 54 99 2A 62 A1 DE 42 F9

Enable Bluetooth broadcast (CMD: 0xA3)

• The module broadcasts in the 100 milliseconds interval in the non-low power mode, and in the 1,000 milliseconds interval in the low power mode. The MCU can set the value as 0 to 2,000, while 0 represents broadcast. When the app finds the broadcast, pairing can start. If you want to control the pairing time with the MCU, you can call this API.
  
• The module records the broadcast status in the flash. If you want to control the pairing time with the MCU, you must call this API after the serial port is initialized, and adjust to the default enabled status as required by the MCU. The MCU must enable it when pairing is required, and disable it when pairing is not required.
  
• The module enables broadcast by default. If module broadcast is disabled by this API, the module will not have broadcast in both the low power mode and non-low power mode.
  
• If the module is in the broadcast status before the broadcast is disabled, the broadcast will be stopped immediately after disabled.
  
• After the broadcast is enabled, the module will start broadcast immediately. For more information, see (1).
  
• For more information, see Protocol API supported by general firmware of all categories.

Difference: This API can control the broadcast in the non-low power mode, whereas modifying the broadcast interval in the low power mode only works in the low power mode. Therefore, the broadcast enabling API must be used to control the pairing time.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA3
4 5	2	Data length	0x00 0x01
6	1	Data	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

Data	Description
0x00	Disable the broadcast
0x01	Enable the broadcast

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA3
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Notice of restoring factory defaults (CMD: 0xA1)

• When the app sends a command of restoring factory defaults to the module, the module will send a notice to the MCU, and the MCU restores factory defaults according to the command.
• For more information, see Protocol API supported by general firmware of all categories.

The module sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA1
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The MCU returns the following command:

None

MCU queries version number of the module (CMD: 0xA0)

• The MCU can call this API to query the version number of the module. If the MCU does not need the version number of the module, implementation of this protocol is not required.
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA0
4 5	2	Data length	0x00 0x00
6	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA0
4 5	2	Data length	0x00 0x06
6–11	6	DATA	See the following table
12	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Data format:

1–3	4–6
Soft_Ver	Hard_ver

Soft_Ver: the version number of the current MCU firmware. For example, 0x01 00 02 means that the version number is v1.0.2.

Hard_ver: the version number of the current MCU hardware, also PCBA version number.

Configure lock functions (CMD: 0xA6)

• Applicable modules: lock general firmware v6.2 and later versions support TYBN1, and lock general firmware v3.3 and later versions support BK3431Q.
  
• Some lock functions require the module to package some fields of the DP. These functions have switches and they are disabled by default, in order not to affect customers who do not use these functions. The setting will be saved forever.
  
• At present, the following functions shall be configured by this API: lock accessory, accessory locking and unlocking, and lock password system configuration.
  
• For more information, see Protocol API supported by general firmware of all categories.

The MCU sends the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA6
4 5	2	Data length	0x00 0x04
6–9	4	DATA	See the following table
10	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

CFG format:

Item 0	Item 1	Item 2	Item 3
1	2	3	4
FLAG	PWD_NUM	PWD_BEGIN_NUM	Reserved (0x00)

Note to FLAG:

• bit0: Enable lock accessory function. 0 is disabled and 1 is enabled. It is disabled by default.
• bit1: Enable accessory locking and unlocking function. 0 is disabled and 1 is enabled. It is disabled by default.

  Note: bit0 and bit1 are mutually exclusive, that is, if one is enabled, the other will be disabled automatically.

• bit2–bit7: Reserved.
• PWD_NUM: Indicates the number of digits that make up the lock password. The default is 10 (number 0\–number 9). When there are only 4\–9 consecutive numbers on some password panels, this field can be used to configure. In addition, you can configure the password to start with the zero or one through PWD_BEGIN_NUM.

  Note: The PWD_NUM field will only take effect if you fill in 0x04 to 0x09, and the rest of the numbers use the default settings (10 digits).

• PWD_BEGIN_NUM: Indicates the smallest number on the password panel, starting with zero or one. If the password panel starts with zero, fill in 0x00. If it starts with one, fill in 0x01.

  Note: The PWD_BEGIN_NUM field will only take effect if you fill in 0x00 or 0x01, and the rest of the numbers use the default settings (starting with zero).

Example:

• 55 AA 00 A6 00 04 01 00 00 00 AA (Enable the door lock accessory function)
• 55 AA 00 A6 00 04 00 00 00 00 A9 (Disable the door lock accessory function)

The module returns the following command:

S.N.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xA6
4 5	2	Data length	0x00 0x01
6	1	State	See the following table
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder

Return value of state:
0x00: set successfully
Others: failed to set

Click to show the Integration Guide

Q: What is the function of this protocol API? When does it need to be configured?

A: This API serves as a switch used to configure the function logic of the module, mainly the DPs. Currently, there are three packages of business logic:

• Lock accessory function.
• Accessory locking and unlocking function. These two functions are used for Bluetooth lock accessory, with one for locks and the other for the accessory.
• Multi-digit password configuration.

If the lock does not use an accessory, the configuration is not required. It is disabled by default. If an accessory is required, you can send the configuration once after the MCU serial port is initialized, and the configuration will be stored permanently.

Q: What about non-decimal password panels? How to configure the multi-digit password function?

A: PWD_NUM: Indicates the number of digits that make up the lock password. The default is 10 (number 0–number 9). When there are only 4–9 consecutive numbers on some password panels, this field can be used to configure. In addition, you can configure the password to start with the zero or one through PWD_BEGIN_NUM.

Note: The PWD_NUM field will only take effect if you fill in 0x04 to 0x09, and the rest of the numbers use the default settings (10 digits).

PWD_BEGIN_NUM: Indicates the smallest number on the password panel, starting with zero or one. If the password panel starts with zero, fill in 0x00. If it starts with one, fill in 0x01.

Note: The PWD_BEGIN_NUM field will only take effect if you fill in 0x00 or 0x01, and the rest of the numbers use the default settings (starting with zero).

Example 1: There are only numbers 1, 2, 3, 4, 5, and 6 on the password panel, so PWD_NUM is set to 6, and PWD_BEGIN_NUM is set to 1.

Example 2: There are only numbers 0 to 8 on the password panel, so PWD_NUM is set to 9, and PWD_BEGIN_NUM is set to 0.

Q: How to integrate with the lock accessory function?

A: The MCU and lock accessory function integration is described as follows.

The lock accessory function involves four DPs links in the lock DP specification, and a general serial port protocol API CMD 0xA6 (lock function configuration).

The pairing and reconnection between the lock and the accessory are actually included in the general firmware of the lock. This part can be skipped.
In order to improve the security level and ensure the safety of the lock after the accessory appears, second identity verifications are carried out at the business layer as follows:

• The cloud assigns a host ID + host random number to the host (app/accessory) to identify the unique host. Also, the cloud assigns a slave ID + slave random number to the slave (lock) to identify the unique slave.
  
• First, the cloud sends the host ID + host random number of the app and the slave ID of the lock to the lock. At this time, it is considered that the app and the lock have completed pairing. And then, the host ID + host random number of the accessory is sent to the lock. The host ID + host random number of the accessory and the slave ID of the lock are sent to the accessory. It is considered that the accessory and the lock have completed pairing.
• At this time, the lock stores:
  • Host ID + host random number of the app.
  • Host ID + host random number (one/multiple) of the accessory.
  • And the slave ID of the lock.
• The accessory store:
  • Host ID + host random number of the accessory.
  • And the slave ID of the lock.

The only operation that the accessory can do on the lock is to unlock. The accessory needs to tell the lock its own identity (the accessory’s host ID + host random number) and the identity of the lock (the lock’s slave ID) to ensure the security of communication.

The above logic is packaged in the general firmware of the lock. But this business logic needs to get and parse the DP content. In principle, the general firmware does not process the DP content but only transparently reports it. Therefore, in order to be general-purpose, the lock general firmware has disabled the logic by default. Only customers who need to integrate with this function can configure and enable this function through the CMD 0xA6, and then the module will process it. The module just gets the content and parses the host ID, slave ID, and random number, and does not change the data content.

Otherwise, the module will transparently report the data, and the MCU will complete the relevant logic.

Accessory authentication logic package

After the lock accessory function is enabled through CMD 0xA6 (55 AA 00 A6 00 04 01 00 00 00 AA), the module will fully process, whereas the dpid=70 Configure host random number will not be transparently transmitted to the MCU.

For the dpid=71 Locking and unlocking and dpid=73 Configure remote unlocking, the module will get the host ID, slave ID, and random number fields in the DP content for identity verification.

• If the authentication is successful, the module will completely transparently transmit the DP data to the MCU, the MCU needs to process the lock business logic of Locking and unlocking and Configure remote unlocking except for the host ID, slave ID, and random number.
  
• If the authentication fails, the module will not pass it to the MCU but will return a failure message.
  

DP processing by the MCU

After the lock accessory business capability of the module is enabled, the module only authenticates the accessories according to the host ID, slave ID, and random number, and then decides whether to pass it to the MCU for processing. Although the MCU does not need to make logical judgments and processing on the fields (host ID, slave ID, and random number) after receiving it, the MCU needs to adjust the position of the fields according to the protocol. For example, dpid=71:

Function	Data direction	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Locking and unlocking	Send	71	raw	len	Host ID (2 bytes)	Slave ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking and unlocking timestamp (4 bytes)	Locking and unlocking method (1 byte)	Locking and unlocking info (len-12 bytes)
					0–10000	0–10000	Random number of the host	0x00: lock 0x01: unlock	Note	Note	Note
	Report	71	raw	len	Slave ID (2 bytes)	Host ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking and unlocking timestamp (4 bytes)	Locking and unlocking method (1 byte)	Return status (1 byte)
					0–10000	0–10000	Random number of the host	0x00: lock 0x01: unlock	Note	Note	Value range

In the MCU, the host ID and slave ID must be exchanged.

Module > MCU: 55 AA 00 06 00 17 47 00 00 13 00 02 00 01 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 ED

MCU > module: 55 AA 00 07 00 17 47 00 00 13 00 01 00 02 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 EE

The same is true for dpid=73.

After the MCU receives the dpid=71 locking and unlocking, the MCU must record the host ID, slave ID, and random number, and then report through the locking and unlocking record on success. The host ID, slave ID, and the random number come from the previous dpid-71.

Function	Data direction	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Record	Report	72	raw	len	Slave ID (2 bytes)	Host ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking and unlocking timestamp (4 bytes)	Locking and unlocking method (1 byte)	Locking and unlocking info (len-12 bytes)
					0–10000	0–10000	Random number of the host	0x00: lock 0x01: unlock	Note	Note	Note

Q: How to integrate with the locking and unlocking function on the accessory?

A: For the Bluetooth accessory and MCU integration solution, you need to use the lock service function configuration (CMD: 0xA6) API to enable the locking and unlocking function on the accessory, in order to enable relevant business functions of the accessory.

After the module receives the locking and unlocking command from the MCU, the module will query the flash according to the slave ID in the locking and unlocking DP, to see if there is relevant information. If yes, it means that the lock has added the accessory and the accessory can control the lock. Then the module will initiate reconnection of the lock and forward the locking and unlocking DP. The lock will perform the operations after receiving the DP.

Function	Data direction	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Locking and unlocking	Send	71	raw	len	Host ID (2 bytes)	Slave ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking and unlocking timestamp (4 bytes)	Locking and unlocking method (1 byte)	Locking and unlocking info (len-12 bytes)
					0–10000	0–10000	Random number of the host	0x00: lock 0x01: unlock	Note	Note	Note
	Report	71	raw	len	Slave ID (2 bytes)	Host ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking and unlocking timestamp (4 bytes)	Locking and unlocking method (1 byte)	Return status (1 byte)
					0–10000	0–10000	Random number of the host	0x00: lock 0x01: unlock	Note	Note	Value range

The host ID and random number are not required when the accessory MCU reports the DP. You only need to fill in the slave ID. If there is information about the slave ID stored in the accessory Bluetooth module, the accessory will automatically fill in the host ID and random number.

The accessory MCU needs to store:

• The slave ID (the ID of the lock). The lock ID will be sent when the unlocking method is added. For more information, see the DP protocol specification.

• Other DPs will not be processed by the module and will be reported directly.

After connection, the accessory will forward the locking and unlocking DP from the MCU to the lock, and start the 30s timer. If the lock does not return the unlocking result for more than 30s, the Bluetooth connection will be disconnected. If the unlocking result is received, the Bluetooth connection will also be disconnected.