English
English
简体中文
Contact Us
Register
Log In

MCU Integration Protocol

Last Updated on : 2022-03-02 02:05:43download

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:

MCU Integration Protocol

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

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:

MCU Integration Protocol

General connection protocol

Basic workflow diagram is shown as follows.

MCU Integration Protocol

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 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 Integration Protocol

MCU-OTA update request (CMD: 0xEA)

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)

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)

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 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.