Docs

Tuya BLE General Serial Port Protocol

Last Updated on : 2020-08-27 10:07:58download

Overview

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

Tuya BLE General Serial Port Protocol

Serial communication convention

TermDescription
Baud (bps)9600
Data bit8
Parity checkNone
Stop bit1
Data flow controlNone

Bluetooth parameter description

  • General firmware for locks
TermDescription
Broadcast intervalFixed at 100 ms in the non-low power mode.
1000 ms in the low power mode, which can be set to 0 – 2000 ms by MCU. 0 means that the broadcast is turned off.
Connection parameterThe module is bound and connected (min_conn,max_conn,latency,timeout):(180ms,200ms,0,5000ms).
OTA process, (min_conn,max_conn,latency,timeout):(20ms,25ms,0,5000ms).
  • General firmware for healthy product
TermDescription
Broadcast intervalFixed at 100 ms in the non-low power mode.
1000 ms in the low power mode, which can be set to 0–2000 ms by MCU. 0 means that the broadcast is turned off.
Connection parameterThe module is bound and connected (min_conn,max_conn,latency,timeout):(180ms,200ms,0,5000ms).
OTA process, (min_conn,max_conn,latency,timeout):(20ms,25ms,0,5000ms).

Terms and definitions

TermDescription
Data point (DP)One data point (DP) refers to one function or one pair of command.
PIDProduct ID. It describes the collection of one type of product function (DP). Every product that is created on Tuya IoT Console will have a unique product ID (PID). PID is associated with all information related with this product, including specific DP, app control panel, and delivery information.

Frame data packet structure

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.It is used for upgrade and extension
31CommandSpecific frame type
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenData
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Note: All data greater than one byte shall be transmitted with big-endian mode.

DP format description

FieldLength (byte)Description
dp_id1DP command
dp_type1DP data type
dp_data_len2DP data length
dp_data_valuedp_data_lenDP data (refer to DP protocol for details)

Dp_type value range and meaning (cloud definition)

dp_typeValueLength (byte)Description
raw0x001–255Raw type, HEX array
bool0x011Boolean value
value0x024Value type (integer)
string0x030–255String (it might be null)
enum0x041Enumeration

Categories of general firmware

Note:

  • Universal 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, supplemental protocol for general firmwares of locks, and supplemental protocol for general firmwares of healthy products.
  • All general firmwares support general connection protocol, and some of general firmwares support the supplemental protocol for low power function. The supplemental protocols for general firmwares of locks and healthy products are supported by general firmwares in the corresponding categories respectively.

List of modules supported by general connection categories:

General connection categoryChip/module
LockTYBN1 and BK3431Q
Healthy productBK3432 and TYBT3L
OthersTYBT3L, TYBT4L, and other Telink modules

Some modules have general firmwares of many categories.

Supported protocol interface

Note:

  • General firmwares of different categories support different protocols, and different versions of the same category support different protocol interfaces.

Protocol interface supported by general firmwares of all categories is shown in the following figure:

Tuya BLE General Serial Port Protocol

General connection protocol

Heartbeat packet (CMD-0x00)

Note:

  • After a module is powered on, a heartbeat packet is sent every 3 seconds. After receiving the response from MCU, the module considers that MCU is working normally. MCU responds to the heartbeat packet for the first time after power-on or reboot, and then the module queries the product information from MCU.
  • According to the heartbeat packet, MCU regularly checks whether the module is working normally. If no heartbeat packet is sent by the module, MCU can reset the module through the hardware reset pin of the module.
  • After the module receives messages from MCU, there is no heartbeat in the low power mode, and the heartbeat packet is sent every 10 seconds in the normal power mode.

Specially, Telink module does not have heartbeat in low power mode, and heartbeat packets are not sent after MCU information (PID) is obtained. Therefore, Telink module cannot check whether MCU is rebooted or not.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x00
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

MCU returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x00
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: the returned value only after MCU is powered on and receives the heartbeat packet from the module for the first time. Thus, the module can check whether MCU is rebooted during work.
0x01: the returned value in other cases, except the 0x00 returned by MCU for the first time after MCU is rebooted.

Obtain MCU information (CMD-0x01)

Note:

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

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x01
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

MCU returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x01
4
5
2Data length0x00
0x0d
6–180x0dDataRefer to the following table
191CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1–89–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,mcu ver=1.0.0)
PID is a 8-bit string, such as “ftb8x2x0”.
Reserved field: The field was filled with MCU software version number in the past. At present, the module does not analyze this field, so the field is reserved. MCU version number is transmitted by CMD E8\E9.

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

Note:

  • The working mode of the module mainly includes how to indicate working status and how to reset the module. There are two cases:
    • Coordinated processing by the MCU and the module: The module notifies MCU of the current working status of the module through serial port, and MCU displays the working status of the module. MCU detects the reset requirement of the module, and through the serial port, notifies the module to reset.
    • Self-processing by the module: It is not supported.
  • At present, only the coordinated processing by the MCU and the module is supported.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x02
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

For example, 55 aa 00 02 00 00 01

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x02
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

For example, 55 aa 00 02 00 00 01

Send the working status of the module (CMD-0x03)

Note:

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

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x03
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
StatusWorking status descriptionHealthy/shared general firmwares
0x00
0x01
Unbound
bound but not connected
The concept of "binding" goes through fuzzy processing in the healthy and shared products.
When the healthy/shared products are in the unbound status and bound but not connected status, network can be configured.
0x02Bound and connectedWhen the healthy/shared products are in the bound and connected status, network has been configured and connected.

Reset the module (CMD-0x04)

Note:

  • Disconnect Bluetooth, unbind the Bluetooth, clear offline cache information of the module, clear virtual ID, and then reboot.
  • In the past, this interface is frequently used as an unbinding interface on th Telink platform. In order not to affect their functions, virtual ID will not be cleared after Telink platform is reset.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x04
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

For example, 55 aa 00 04 00 00 03

The module returns:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x04
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

For example, 55 AA 00 04 00 00 03

Send command (CMD-0x06)

Note:

  • For the data points, refer to DP format description.
  • "Send command" can contain "command data units" of multiple data points.
  • "Send command" is an asynchronous processing protocol, corresponding to data point "transmit status" of MCU.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x06
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDatapointRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Datapoint format:

123–45–nn+1n+1 to n+2n+3–
dp_iddp1_typedp1_lendp1_datadpN_iddpN_typedpN_lendpN_data

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

MCU returns the following command: None

Transmit status (CMD-0x07)

Note:

  • For the data points, refer to DP format description.
  • "Transmit status" can contain "command data units" of multiple data points.
  • "Transmit status" is an asynchronous processing protocol. Its trigger mechanism has three types:
    1. After receiving "send command" processing frame, MCU executes the command of the corresponding data point, and then send the changed status to the module through "transmit status" frame.
    2. MCU detects that the data point has changed, and sends the changed status to the module.
    3. After MCU receives a status query frame, MCU sends the status of all data points to the module.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x07
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDatapointRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Datapoint format:

123–45–nn+1n+1\ to n+2n+3–
dp_iddp1_typedp1_lendp1_datadpN_iddpN_typedpN_lendpN_data

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

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x07
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: succeeded
0x01: failed.

Status query (CMD-0x08)

Note:

  • “Status query” is an asynchronous processing command that is mainly used by the module to query the status of all "obj" type data points of MCU. When MCU receives this frame, MCU transmits the status of data points through CMD 0x07 status transmitting frame.
  • "Status query" is sent at two time points:

    • When the module is bound and connected, and detects that MCU is rebooted according to heartbeat(CMD-0x00) response, the "status query" frame is sent.

      Note: Telink general firmwares do not support to detect MCU rebooting.

    • When the module Bluetooth is offline and then goes online (it changed from bound but not connected status to bound and connected status), the "status query" frame is sent.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x08
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

For example, 55 aa 00 08 00 00 07

MCU returns the following command: None

Unbind the module (CMD-0x09)

Note:

  • Unbind the module from mobile phone, and disconnect Bluetooth connection. The data and virtual ID will not be cleared.
  • Note: The concept of "binding" goes through fuzzy processing in the healthy (shared) general firmwares. Therefore, the module cannot unbind from the interface.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x09
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x09
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: succeeded
0x01: failed.

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

Note:

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

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x0A
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Transmit the record type data (CMD-0xE0)

Note:

  • This interface is mainly used to transmit important data. If the module is offline during transmission, the module will store the data in the module flash, and transmit the data to the app after the module goes online. After the module is online and the last piece of data is transmitted successfully continuously, the cache data will be transmitted to the app.
  • The module can store maximum N pieces of DP data, and the recorded data will be overwritten circularly:
    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 Bluetooth module has limited accuracy, and the error is less than 1 minute in 24 hours. The clock is recalibrated during each reconnection. If you have a high requirement on accuracy, you can use the built-in time of MCU.

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

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE0
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

12–xxn+1x+2\ to x+3x+4–nn+1n+1\ to n+2n+3–
TYPETime_Strdp_iddp1_typedp1_lendp1_datadpN_iddpN_typedpN_lendpN_data

Time_Str: 13-bit Unix time string

Note:

TYPEDescription
0x01Format 1—Transmit the built-in time of Bluetooth module
0x02Format 2—Transmit the raw data only, and the time refers to actual time during transmission
0x03Format 3—Transmit 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—Transmit 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—Transmit the raw data only, and the time refers to 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—Transmit the built-in time of 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:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE0
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: stored successfully
Others: failed to store

Obtain real-time time (CMD-0xE1)

Note:

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

MCU returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE1
4
5
2Data length0x00
0x01
61Time_TypeRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Time_type description:

Time_TypeDescription
0x00Format 0: Obtain 7-byte time type + 2-byte time zone information
0x01Format 1: Obtain 13-byte Unix time in milliseconds + 2-byte time zone information
0x02Format 2: Obtain 7-byte time type + 2-byte time zone information

Note: Different platforms might be incompatible if format 0 is used to obtain custom time, therefore it will be removed in the later versions. It is recommended to use format 0x02 to request the time in the YYMMDD format.
Telink general firmwares do not support format 0 now. If you request the time in format 0, the time in format 2 will be returned.

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE1
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenTime_DataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
  • Time_Data format 0:
Result codeTime formatYearMonthDayHourMinuteSecondWeekTime zone
12345678910–11
ResultTime_Type2018 + yearmondayhourminsecweektime_zone
  • Time_Data format 1:
Result codeTime formatUnix time in millisecondsTime zone
123-1516-17
ResultTime_Typeunix_time_stringtime_zone
  • Time_Data format 2:
Result codeTime formatYearMonthDayHourMinuteSecondWeekTime zone
12345678910–11
ResultTime_Type2000 + yearmondayhourminsecweektime_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, UTC+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, UTC+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, UTC+8

MCU-OTA interfaces

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

Note:

  • When the module sends a command to obtain MCU information, the module shall send a command to query the version number of MCU at the same time.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE8
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

MCU returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE8
4
5
2Data length0x00
0x06
6–116DataRefer to the following table
121CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1–34–6
Soft_VerHard_ver

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

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

MCU sends current version number (CMD-0xE9)

Note:

  • To ensure that the module obtains the version number of MCU timely, MCU sends the current version number to the module once after it is started (and often after the serial port is initialized). If no response is received from the module, the current version number shall be resent.

MCU returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE9
4
5
2Data length0x00
0x06
6–116DataRefer to the following table
121CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1–34–6
Soft_VerHard_ver

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

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

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE9
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: succeeded
Others: failed.

MCU-OTA flowchart

Tuya BLE General Serial Port Protocol

MCU-OTA upgrade request (CMD-0xEA)

Note:

  • At the start of upgrade, the module sends a request to MCU, and obtains the maximum single packet length that can be transferred through MCU serial port.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEA
4
5
2Data length0x00
0x02
6–72Maximum data length of single packet — len 1Refer to the note
81CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Note:

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

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

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEA
4
5
2Data length0x00
0x06
6–116DataRefer to the following table
121CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

12–45–6
FlagThe version number of current firmware of MCUMaximum acceptable data length — len 2
  • Flag: 0x00 indicatesupgrade confirmation, and 0x01 indicatesupgrade rejection.

  • 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 single packet limited by the module.

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

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

MCU-OTA upgrade file information (CMD-0xE8)

Note:

  • It describes MCU-OTA upgrade file information. MCU compares the upgrade information, and decides to upgrade or not.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEB
4
5
2Data length0x00
0x23
6–4035DataRefer to the following table
411CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

8 bytes3 bytes16 bytes4 bytes4 bytes
Product ID (PID)File versionFile MD5File lengthCRC32
  • PID: the PID of MCU.
  • File version: for example, 0x010002 means that the version is V1.0.2.
  • File MD5: the MD5 value of the upgrade firmware.
  • File length: total length of the upgrade firmware in bytes.
  • CRC32: the CRC32 value of the upgrade firmware.

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEB
4
5
2Data length0x00
0x19
6–3025DataRefer to the following table
311CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1 byte4 bytes4 bytes16 bytes
StatusLength of the stored fileCRC32 value of the stored fileMD5 value of the stored file (not used at present)

Status:

  • 0x00 — normal upgrade.
  • 0x01 — PID is inconsistent.
  • 0x02 — the file version is lower than or equal to the current version.
  • 0x03 — 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 OTA upgrade request according to the sequence of MCU OTA process. If MCU maintains the upgrade status, when MCU receives the information that the working mode of the module is other statuses except the bound and connected status, MCU resets the upgrade status, in order to start the next upgrade process.

MCU-OTA upgrade file offset request (CMD-0xEC)

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEC
4
5
2Data length0x00
0x04
6–94OffsetRefer to the following table
101CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

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.

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEC
4
5
2Data length0x00
0x04
6–94OffsetRefer to the following table
101CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

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

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

MCU-OTA upgrade data (CMD-0xED)

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xED
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

2 bytes2 bytes2 bytesn bytes
Packet numberThe current packet data length nThe current packet data CRC16The current packet data

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

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xED
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Note:

StatusDescription
0x00Success
0x01Packet number exception
0x02Length is inconsistent
0x03Cyclic redundancy check (CRC) failed
0x04Others

MCU-OTA upgrade is completed (CMD-0xEE)

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEE
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Response from the MCU:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xEE
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Note:

StatusDescription
0x00Success
0x01The total data length is incorrect
0x02Length is inconsistent
0x03Others

Production test interfaces

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

Note:

  • Received signal strength indication (RSSI) of the module shall be tested, in order to check whether RF of Bluetooth module works normally 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 meter away from the module. Then, send the RF test command through a serial port. The module will search for Bluetooth beacon and return the signal strength value. If the signal strength is greater than -70db, it is thought that the RF of the module works normally.

In this mode, pay attention to the following points:

  • Some special chips and modules, 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 meter away from the module. Then, send the RF test command to the module through a serial port. The dongle connects the module and returns the signal strength value. If the signal strength is greater than -70db, it is thought that the RF of the module works normally.
  • The module shall be in the non-low power mode, and unbound.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x0E
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0x0E
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

DataDescription
{"ret":true,"rssi":"-55"}The signal strength is -55db
{"ret":false}The signal is not found

Supplemental protocol for low power function

Different categories of general firmwares have different low power work designs.

Low power working description of locks — TYBN1 and BK3431Q

  • After the module obtains MCU information, the heartbeat packet will not be sent in low power status, and will be sent in the non-low power status.
  • Working mode includes low power mode and non-low power mode.
    • In the non-low power mode, 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, Bluetooth broadcast interval is set by MCU to 1 second by default. If the interval is 0, the Bluetooth broadcast is disabled. In this mode, data is sent downstream through serial port of the module, but upstream transfer is prohibited — it does not receive data from MCU serial port.
  • The low power working status of the module is determined by electrical level of low power control pin of the module — SCL. Through the SCL, MCU outputs different electrical levels to control the power consumption status of the module. For details, refer to the following table:
PlatformLow power control pin of module — SCLSCL electrical level corresponding to low powerSCL electrical level corresponding to non-low power
NORDICIO11HighLow
BKP03LowHigh

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

  • The module uses SDL to wake up external MCU. When the module needs to send data to external MCU, the module changes SDL electrical level for 200 milliseconds, sends the data, and then restores to default electrical level after the data is sent completely.
PlatformSDL — the pin that is used by the module to wake up MCUSDL electrical level when data is being sentSDL electrical level during idle time
NORDICIO14LowHigh
BKP10HighLow
  • The low power interface cannot be enabled. It is determined by electrical 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 the platforms. The MCU pin that connects to SCL shall not float.


Low power working description of healthy module — BK3432 and BT3L

  • After the module obtains MCU information, the heartbeat packet will not be sent in low power status, and will be sent every 10 seconds in the non-low power status. Note: Telink platform has heartbeats only in the non-low power mode.
  • After every connection event, the module will obtain the app time automatically to calibrate the internal time of Bluetooth module. Internal real time clock (RTC) accuracy of the module depends on the quality of the crystal oscillator. If you have a high requirement on time accuracy, you must measure the internal RTC accuracy or mount an external high-accuracy RTC. You can obtain the test program from R&D through an FAE or a product manager.
  • Working mode includes low power mode and non-low power mode.
    • In the non-low power mode, 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, Bluetooth broadcast is disabled, and Bluetooth connection can be kept. In this mode, data is sent downstream through serial port of the module, but upstream transfer is prohibited — it does not receive data from MCU serial port.
  • The low power working status of the module is determined by electrical level of low power control pin of the module — SCL. Through the SCL, MCU outputs different electrical levels to control the power consumption status of the module. For details, refer to the following table:
PlatformLow power control pin of module — SCLSCL electrical level corresponding to low powerSCL electrical level corresponding to non-low power
BK3432P03 (configurable)LowHigh
BT3LTL_B5LowHigh

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

  • The low power mode is disabled by default. The lower power mode must be enabled before you use it.
  • You can disable the system timer in the low power mode to reduce power consumption. The system timer is disabled by default.
  • According to the heartbeat response, BK3432 automatically identifies which serial port is used by MCU, and stores it for ever. To replace the serial port, you must re-burn and authorize the module firmware.

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


Low power working description of other types — Telink platform

  • After the low power pin of the module is pulled down, the serial port of the module will not receive data. However, Bluetooth communication and downstream transfer of serial port are still working normally. After the pin is pulled up, the serial port of the module receives data normally.
  • When the module is bound and connected, the connecting status indication pin is pulled up to notify MCU. The pin is pulled down automatically after disconnection.
  • The serial port of the module can receive data from MCU 10 milliseconds after the module is woken up from the low power mode. When the module is woken up from deep sleep mode, the module will be rebooted. The serial port can receive data 600 milliseconds after the module is rebooted.
ModuleLow power control pin of the module — SCLSCL electrical level corresponding to low powerSCL electrical level corresponding to non-low power
BT3LModule silk screen TL_B5 pinLowHigh
  • After every connection, the module will obtain the app time automatically to calibrate the internal time of Bluetooth module. Telink module does not use external RTC, so clock accuracy is not very high. Error within 24 hours is less than 1 minute. If you have a high requirement on clock accuracy, you can connect an external clock.
  • When supply voltage is lower than normal working voltage, flash operation inside the chip might have an error, thus firmware or user data might be modified abnormally. You can avoid the error in two ways:

    1. When MCU detects that battery voltage is too low, cut off the working power supply of the module.
    2. When MCU detects that battery voltage is too low, disable the broadcast and system timer, and let the chip in deep sleep mode. Minimum working voltage of Telink module is 1.8V. MCU can set to disable the module at 2.0V, which shall be slightly higher than 1.8V.
  • The module uses SDL to wake up external MCU. When the module needs to send data to external MCU, the module changes SDL electrical level for 10 milliseconds, sends the data, and then restores to default electrical level after the data is sent completely.

ModuleSDL — the pin used by the module to wake up MCUSDL electrical level when data is being sentSDL electrical level during idle time
BT3LModule silk screen TL_D2 pinHighLow

Enable the low power functions (CMD-0xE5)

Note:

  • General firmwares of locks do not support this operation, including TYBN1 general firmware and BK3431Q general firmware.
  • The module is not in the low power mode when leaving factory. You must enable the low power function through this command. Then, you can pull down the low power enabling pin, so the module enters low power status. The setting will be saved forever.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE5
4
5
2Data length0x00
0x01
61DataRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

DataDescription
0x00Disable low power function
0x01Enable low power function

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE5
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

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

Note:

  • General firmwares of BK3432 healthy module do not support this operation.
  • To reduce power consumption during hibernation, you can modify 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, broadcast interval is 1 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 example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE2
4
5
2Data length0x00
0x01
61Adv_intervalRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Adv_interval: The value ranges from 0 to 20, and the unit is 100 milliseconds. Actual broadcast interval range is 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:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE2
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Disable system timer (CMD-0xE4)

Note:

  • To reduce power consumption of Telink chips during hibernation, you can disable internal timing function of Bluetooth module through this command. If MCU does not need the time function, this function can be disabled. After the timing function and broadcast function are disabled, SDA is pulled down, the module enters deep sleep, and the power consumption is reduced to 3 ua. After wakeup, the module is rebooted and put into operation 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 1 minute to solve the RTC reset issue of the module after reboot. It is disabled by default.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE4
4
5
2Data length0x00
0x01
61DataRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

DataDescription
0x00Disable the system timer
0x01Enable the system timer

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE4
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Disconnect Bluetooth connection (CMD-0xE7)

Note:

  • To reduce power consumption during hibernation, when MCU does not need Bluetooth connection, Bluetooth connection of the module can be disconnected and the module can be put into low power mode to minimize the power consumption. Main function of this interface is to disconnect Bluetooth connection.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE7
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE7
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Configure the module wakeup pin (CMD-0xE3)

Note:

  • Applicable module: At present, it only applies to BK3432 general firmwares.
  • It is used when the chip is connected to low power wakeup pin of your custom modules. If you need to wake up the module with pins other than the default pin, immediately after MCU initializes UART, this command can be used to configure the low power wakeup pin of the module.
  • The setting will be saved forever.

Note: After the module enters low power mode, data cannot be transferred upstream through the serial port. MCU shall configure within 1 second after the module is powered on (the module does not enter low power mode within 1 second after power-on), or shall configure before low power is enabled (the low power mode is disabled by default).

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE3
4
5
2Data length0x00
0x06
6–116Data content CFGRefer to the following table
121CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Format of data content CFG:

4 bytes1 byte1 byte
PIN_NUMReservedReserved

Note: PIN_NUM adopts big-endian transmission. The reserved field is not parsed, and you can fill in 0xff/0x00. If you are unclear about PIN_NUM, you can confirm the configuration command with Tuya technical support.

For example,

  1. Set BK3432 P03 as low power wakeup pin of the module (PIN_NUM of P03 is 0x03) 55 AA 00 E3 00 06 00 00 00 03 00 00 EB
  2. Set BK3432 P11 as low power wakeup pin of the module (PIN_NUM of P11 is 0x11) 55 AA 00 E3 00 06 00 00 00 11 00 00 F9

Note: At present, BK3432 can configure P02, P03, P04, P05, P10, P11, P12, P13, P34, P14, P35, P32, and P31. PIN_NUM of BK Pxx is 0xxx.

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE3
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Configure low power wakeup of MCU (CMD-0xB0)

Note:

  • Applicable module: lock general firmware V6.2 and later versions support TYBN1, and lock general firmware 3.3 and later versions support BK3431Q.
  • Considering that previous wakeup time 200 milliseconds is too long, this value can be set by MCU — MCU can set the time period (t) required to wake up MCU from low power mode. The value is 200 milliseconds by default. When the module sends serial port data to MCU, MCU wakeup pin will be pulled up or pulled down for about the time period (t).
  • After MCU is modified, test whether 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 MCU receives CMD 0x02 (55 aa 00 02 00 00 01), you can call this interface to configure low power wakeup of MCU. The setting is not saved forever. It is 200 milliseconds by default after the module is powered on or rebooted.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xB0
4
5
2Data length0x00
0x01
61IntervalRefer to the note
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Note: Interval is a unit, representing 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:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xB0
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Supplemental protocol for general firmwares of locks

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

Dynamic password (CMD-0xE6)

Note:

  • The module calculates 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 current administrator password.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE6
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

8 bytes1 byteN bytesN bytes
PasswordAdministrator password lengthThe first administrator passwordThe second administrator password

Password: the password data Data[0]–Data[7] entered by the user. Data content range is ‘0’–’9’ and the data transfer adopts ASCII code.

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

For example, 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:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xE6
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
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)

Request for going online (CMD-0xA5)

Note:

  • This interface is mainly used by the gateway to connect as needed. After MCU calls this interface, 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 the module. After the module goes online, MCU can report DP normally.
  • Generally, record type data is transmitted by calling 0xE0. If MCU detects that the module is bound but not connected, MCU calls this interface to request for going online. After the module goes online, the data that is transmitted by 0xE0 will be released automatically.
  • Real-time data does not conform to general scenario of active transmission. However, MCU can transmit the real-time data in two ways:
  • After this interface is called, wait until the working status of the module becomes bound and connected. The working status is sent after the module goes online.
  • The real-time data can be transmitted 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 example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA5
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA5
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: succeeded
0x01: failed

Offline password (CMD-0xA2)

Note:

  • If the device is not connected to the Internet for long, dynamic password is also available.
  • Accuracy of the clock inside the module is not very high, and the error is less than 1 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 clock source should select 0x00 — 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 example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA2
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1 byte1 byte1 byte1 byte1 byte1 byte1 byte1 byteN bytes
Time source2000 + yearMonthDayHourMinuteSecondCode_lenCode
  • Time source: 0x00 — the time comes from the year/mon/day/hort/min/sec field that is uploaded by MCU. 0x01 — the internal time of the module is used, and year/mon/day/hort/min/sec is not parsed. Fill in 0x00. The time uploaded by MCU must be in the year, month and day format of Greenwich Mean Time (GMT). That is, the year, month and day of 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. Dynamic password transfers ‘1’–‘9’ format of ASCII, whereas offline password transfers numbers directly. 1 is 0x01...9 is 0x09. Refer to the following example.

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA2
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1 byte1 byte1 byteN bytes
ResultTypeDecode_lenDecode
  • Result: 0x00 — correct, and others — wrong (further data is of no significance)
  • Type: 0x00 — verified successfully, 0x01— cleared one piece of data successfully, and 0x02 — cleared all data successfully
  • Code_len: encrypted data length
  • code: encrypted clear code and unlock password.

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

For example, use internal time of the module + password (2279084005)
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
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)

Note:

  1. 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. MCU can set the value as 0 to 2,000, while 0 represents broadcast. When the app scans and finds the broadcast, network configuration can start. If you want to control the network configuration time with MCU, you can call this interface.
  2. The module records the broadcast status in the flash. If you want to control the network configuration time with MCU, you must call this interface after the serial port is initialized, and adjust to the default enabled status as required by MCU. MCU must enable it when network configuration is required, and disable it when network configuration is not required.
  3. The module enables broadcast by default. If module broadcast is disabled by this interface, the module will not have broadcast in both the low power mode and non-low power mode.
  4. If the module is in the broadcast status before the broadcast is disabled, the broadcast will be stopped immediately after disabled.
  5. After the broadcast is enabled, the module will start broadcast immediately. For details, refer to (1).

Difference: This interface 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 interface must be used to control the network configuration time.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA3
4
5
2Data length0x00
0x01
61DataRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

DataDescription
0x00Disable the broadcast
0x01Enable the broadcast

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA3
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Notice of restoring factory defaults (CMD-0xA1)

Note:

  • When the app sends a command of restoring factory defaults to the module, the module will send a notice to MCU, and MCU restores factory defaults according to the command.

For example, the module sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA1
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

MCU returns the following command: None

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

Note:

  • MCU can call the interface to query the version number of the module. If MCU does not need the version number of the module, implementation of this protocol is not required.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA0
4
5
2Data length0x00
0x00
61CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

The module returns:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA0
4
5
2Data length0x00
0x06
6–116DataRefer to the following table
121CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

1–34–6
Soft_VerHard_ver
  • Soft_Ver: the version number of current firmware of MCU. For example, 0x01 00 02 means that the version number is V1.0.2.

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

Configure lock business function (CMD-0xA6)

Note:

  • Applicable module: 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 encapsulate some fields of 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, lock accessories function shall be configured by this interface.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA6
4
5
2Data length0x00
0x04
6–94DataRefer to the following table
101CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

CFG format:

Item 0Item 1Item 2Item 3
1234
FlagReserved (0x00)Reserved (0x00)Reserved (0x00)

Note to flag:

  • Bit 0: enable lock accessories function. 0 is disabled and 1 is enabled. It is disabled by default.
  • Bit 1 to bit 7: reserved.

For example,
55 AA 00 A6 00 04 01 00 00 00 AA (enable lock accessories function)
55 AA 00 A6 00 04 00 00 00 00 A9 (disable lock accessories function)

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA6
4
5
2Data length0x00
0x01
61StatusRefer to the following table
71CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder
Values returned by status:
0x00: set successfully
Others: failed to set

Supplemental protocol for general firmwares of healthy products

This section only applies to general firmwares of healthy products.

Transmit DP with flag bit (CMD-0xA4)

Note:

  • Applicable firmware: BK3432 and TYBT3L shared protocol general firmwares.
  • Choose whether to transmit to the panel or cloud depending on the flags. It is generally used in dynamic data and real-time data.

For example, MCU sends the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA4
4
5
2Data length (Len)Len high-order 8 bits
Len low-order 8 bits
6 to 6 + Len-1LenDataRefer to the following table
6 + Len1CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

2 bytes1 byte1 byte(Optional) 13 bytesm bytes
S.N.FlagTime_flagTime_dateDatapoint
  • S.N. (2): two bytes. The high byte is in the front.
  • Flag (1): 0x00 — transmit to both the cloud and panel. 0x01 — transmit to the cloud, rather than the panel. 0x02 — transmit to the panel, rather than the cloud. 0x03 — no transmission.
  • Time_flag (1): 0x00 — transmit to both the cloud and panel. 0x01 — transmit to the cloud, rather than the panel. 0x02 — transmit to the panel, rather than the cloud. 0x03 — no transmission.
  • Time_date: It is required only when Time_flag is equal to 0x01. The field is a 13-bit UNIX time string.
  • DP data encapsulation (m): For the data points, refer to DP format description.
    For example, 55 aa 00 A4 00 16 00 01 01 00 66 02 00 04 00 00 00 01 28.

The module returns the following command:

No.Length (byte)FieldDescription
0
1
2Header0x55
0xAA
21Version No.0x00
31Command0xA4
4
5
2Data length0x00
0x04
6–94DataRefer to the following table
101CRC8Start from the header, add up all the bytes, and then divide the sum by 256 to get the reminder

Data format:

2 bytes1 byte1 byte
S.N.FlagStatus
  • S.N. (2): Obtain from the transmitted S.N.
  • Flag (1): Obtain from the transmitted flag
  • Status (1): 0x00 — succeeded, others — failed.
Click for services and help