Bluetooth Control Service

The Bluetooth Low Energy (LE) standard module can access and control Bluetooth features through commands, including advertising, connecting, and retrieving device information.

Features

The table below lists the commands the Bluetooth LE module can use to access and control Bluetooth features.

Command	Description
0xE7	Initiate disconnecting from Bluetooth.
0xA3	Turn on or off Bluetooth advertising.
0xBC	Set the pairing trigger and time window.
0xA5	Set a flag in the advertising packet to request the gateway to initiate a connection with the Bluetooth module.
0xE2	Modify the advertising interval of the Bluetooth module in low power mode.
0xB1	Modify the connection interval of the Bluetooth module while maintaining connection.
0xBA	HID-based automatic unlocking features.
0xBB	Set the Bluetooth advertising name.
0xBD	Modify the Bluetooth transmission power.
0xBE	Query the MAC address of the Bluetooth module.

Bluetooth-specific protocol

Disconnect Bluetooth proactively (0xE7)

The MCU instructs the module to disconnect from Bluetooth and enter advertising mode.

The MCU sends the following data.

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

No.	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	Return value
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The return value of State.

• 0x00: Success.
• Other values: Failure.

Enable Bluetooth advertising (0xA3)

• In pairing mode, the advertising interval is 100 ms in standard power mode. In low power mode, it can range from 0 to 2,000 ms, with a default of 1,000 ms. A value of 0 indicates that advertising is turned off.
  The mobile app must scan for advertising packets to identify devices before pairing or connecting. This command allows the MCU to enable or disable advertising so that the MCU can determine when to perform pairing.

• You need to invoke this command to set the advertising enablement after the UART initialization. The enablement state is stored in the flash memory. The MCU should enable advertising when allowing the device to be paired or connected and disable it in other cases.

• The advertising is enabled by default. After you disable advertising through this command, the module will not advertise both in standard and low power mode.

• Disabling advertising will stop ongoing advertising immediately.

• When advertising is enabled, the module will start advertising immediately.

  • Adjusting the Bluetooth advertising interval in low power mode only applies to advertising while in that mode. This command can modify advertising interval in standard power mode.

  • If the module supports triggered pairing (0xBC), it is recommended to use this command to set the pairing time window.

The MCU sends the following data.

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

The valid values for Data:

• 0x00: Disable advertising.
• 0x01: Enable advertising.

The module returns the following data.

No.	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	Return value
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The return value of State.

• 0x00: Success.
• Other values: Failure.

Triggered pairing mode (0xBC)

• The advertising state of an unbound Bluetooth device is the called pairing state. This command only applies to unbound Bluetooth devices.
• When you disable the triggered pairing mode, the device resumes the default pairing mode (advertising is always on).
• There are two scenarios for devices with the triggered pairing mode enabled.
  • If the device is not bound, it will not start Bluetooth advertising automatically when powered on.
  • If the device has been bound, it will not start Bluetooth advertising automatically after unbinding.
• The triggered pairing mode restricts Bluetooth advertising on unbound devices. However, this mode does not apply after a device is paired.
• The triggered pairing mode supports power-off memory, but the advertising duration is not retained after power off.

The MCU sends the following data.

No.	Bytes	Field	Description
01	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBC
45	2	Data length (Len)	Upper 8 bits Lower 8 bits
6 to 6+Len-1	Len	Data	See the description below.
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 description:

ENABLE	ON_OFF	TIME
1 byte	1 byte	2 bytes

• ENABLE:
  • 0x00: Disable the triggered pairing mode, using the default pairing mode. When you set this field to 0x00, the module does not parse the subsequent fields.
  • 0x01: Enable the triggered pairing mode.
• ON_OFF:
  • 0x00: Exit pairing mode immediately. When you set this field to 0x00, the module does not parse the subsequent fields.
  • 0x01: Enter pairing mode immediately.
• TIME: Timeout for triggered pairing mode, in seconds, ranging from 10 to 600.

The module returns the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBC
4 5	2	Data length (Len)	Upper 8 bits Lower 8 bits
6 to 6+Len-1	Len	Status	See the description below.
6+Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Status:

• 0x00: Success.
• 0x01: Parameter error.
• 0x02: Request failed.
• 0x03: Status error (The device is not in the unbound state.)

Request getting online (0xA5)

• This command is used to connect to the gateway when needed.
  1. The module will advertise for 30 seconds after the MCU invokes this command.
  2. After receiving the flagged advertisement, the Bluetooth central device will connect to the module.
  3. After the module is online, the MCU can report the status to the module.
• Typically, the MCU uses the command 0xE0 to report record-type data. If the module is bound but not connected, the MCU will request to get the module online. Then, after getting online, the module will send the stranded data reported through 0xE0.
• To report the real-time data, try the following two methods:
  1. The MCU invokes this command (0xA5) and waits for an online notification. The module will notify the MCU of its status after getting online.
  2. The MCU can report real-time data in 0x02 format through the command 0xE0. After getting online, the module will send the stranded data to the app. This method is not recommended.

The MCU sends the following data.

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

No.	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	Return value
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The return value of State.

• 0x00: Success.
• Other values: Failure.

Modify advertising interval in low power mode (0xE2)

• This command does not apply to the BK3432 generic firmware for shared devices.

• To further reduce the power consumption in sleep mode, you can use this command to modify the advertising interval. The configuration is stored in the nonvolatile memory. If the interval is set to 0, advertising is turned off. The configuration is stored in the nonvolatile memory.

  The advertisement interval defaults to one second in the low power mode. A long interval means taking more time to connect to a mobile phone. If the phone has poor radio performance, the Bluetooth connection attempt might fail.

The MCU sends the following data.

No.	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 valid values range from 0 to 20 in units of 100 ms. If the interval is set to 0, advertising is turned off.

Example:

• 55 aa 00 E2 00 01 00 E2, indicating advertising is turned off in low power mode.
• 55 aa 00 E2 00 01 06 E8, indicating the advertising interval is 600 ms in low power mode.

The module returns the following data.

No.	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	Return value
7	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The return value of State.

• 0x00: Success.
• Other values: Failure.

Set the Bluetooth connection interval (0xB1)

• If the module is in the bound and connected state when receiving this command, it will send a request for updating the connection parameters to the central. Otherwise, it only saves the connection parameters for later connections. However, if the module is performing an OTA update, it will not request to update the connection parameters to the central but save it.
• After getting online, the module will release the stranded data if any, and then update the connection parameters.
• The configuration is stored in the nonvolatile memory.

The MCU sends the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xB1
4 5	2	Data length	0x00 0x0B
6 to 16	11	CFG	See the description below.
17	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

CFG format:

1 byte	1 byte	1 byte	2 bytes	2 bytes	2 bytes	2 bytes
cfg_type	cfg_ack	mode	min_interval	max_interval	latency	timeout

• cfg_type: The configuration method.

  • 0x00: Configuration by mode. Choose the connection parameters with the mode field. If min_interval, max_interval, latency, and timeout do not work, you can use this method.
  • 0x01: Custom configuration. Set the interval with the min_interval and timeout. This method applies to Bluetooth devices.

• cfg_ack: Acknowledgement (ACK) response.

  • 0x00: Not configure the ACK response.
  • 0x01: Configure the ACK response. The connection parameters are assigned by the central. If the parameters fail to be updated, the configuration should respond to the failure. After successful updating, the module will send the connection parameters for use to the MCU.

• mode:

  • 0x00: Fast-speed mode. Provide fast interaction but use more battery. This mode applies to products that prioritize fast response by compromising power consumption.
  • 0x01: Balanced mode. Provide moderate response time and power consumption.
  • 0x02: Low-speed mode. Provide slow response time but use less battery. This mode applies to products that prioritize power consumption with less interaction with the app, such as sensors.

• min_interval: The minimal connection interval, in the unit of 1.25 ms. For more information, see the connection interval specified in the Generic Access Profile (GAP).

• max_interval: The maximum connection interval, in the unit of 1.25 ms. For more information, see the connection interval specified in the Generic Access Profile (GAP).

• latency: Peripheral latency. This parameter gives the peripheral device the option of skipping a number of connection events. For more information, see the connection interval specified in the Generic Access Profile (GAP).

• timeout: The maximum amount of time between two successful connection events, in the unit of 10 ms. For more information, see the connection interval specified in the Generic Access Profile (GAP).

  The field greater than two bytes is transmitted in big-endian format. You can set cfg_type and cfg_ack to 0x00 if these two parameters are not required for you.

The module returns the following data.

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

State

1 byte	2 bytes	2 bytes	2 bytes	2 bytes
result	min_interval	max_interval	latency	timeout

result:

• 0x00: The module receives the new connection parameters and will request a parameter update with the central. min_interval, max_interval, latency, and timeout indicate the parameters of the target connection.

• 0x01: The connection parameters are updated successfully. min_interval, max_interval, latency, and timeout indicate the parameters of the actual connection.

• 0x02: Updating the connection parameters failed. min_interval, max_interval, latency, and timeout indicate the parameters of the target connection.

• 0x03: Illegal state. Generally, the module is not in the bound and connected state.

• 0x06: Invalid parameter.

• Other values: Failure.

  If cfg_ack is set to 0x01, the module syncs the current connection parameters to the MCU only after receiving the successful ACK message. The result 0x01 or 0x02 can be returned only when cfg_ack is set to 0x01. Otherwise, the module will not return the operation result to the MCU.

Example:

• Set to low-speed mode:

  • The MCU sends: 55 AA 00 B1 00 0B 00 00 02 00 00 00 00 00 00 00 00 BD
  • The module returns: 55 AA 00 B1 00 09 00 01 90 01 A0 00 00 01 90 7C

• Set to balanced mode:

  • The MCU sends: 55 AA 00 B1 00 0B 00 00 01 00 00 00 00 00 00 00 00 BC
  • The module returns: 55 AA 00 B1 00 09 00 00 90 00 A0 00 00 01 90 7A

• Set to fast-speed mode:

  • The MCU sends: 55 AA 00 B1 00 0B 00 00 00 00 00 00 00 00 00 00 00 BB
  • The module returns: 55 AA 00 B1 00 09 00 00 32 00 3C 00 00 01 90 B8

• Set to custom parameters:

  • The MCU sends: 55 AA 00 B1 00 0B 01 00 00 01 90 01 A0 00 00 01 90 7F
  • The module returns: 55 AA 00 B1 00 09 00 01 90 01 A0 00 00 01 90 7C

Human interface device (HID) (0xBA)

• This command is used for products that require automatic reconnection.
• To use the HID feature, the MCU must upload the TLD field when responding to the MCU information query 0x01 to enable the SMP feature. Otherwise, the module will reject this HID command.
• If you use RSSI as the threshold, make sure to select multiple RSSI values to ensure accuracy.

The MCU sends the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBA
4 5	2	Data length (Len)	Upper 8 bits Lower 8 bits
6	1	Subcommand	See the description below.
7 to 7+Len-1	Len	Data	See the description below.
7+Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

SubCmd (Subcommand):

• 0x00: Enable SMP.

  Dynamic configuration of SMP is not supported so the MCU should report the SMP enablement when responding to the MCU information query 0x01. The SMP is disabled by default. After you enable or disable the SMP, the module will restart and clear the pairing information for initialization. The configuration can be retained after power off.

• 0x01: Request the HID pairing.

• 0x02: The RSSI of the HID pairing signal.

• 0x03: Query the HID pairing state.

  The format of the Data field varies depending on subcommands. The module parses data according to the SubCmd and the Data format.

Data (format)

• When SubCmd is 0x01 and 0x03, the Data field is empty.

  • Example: Request the HID pairing

    The MCU sends 55 aa 00 BA 00 01 01 BB.

  • Example: Query the HID pairing state

    The MCU sends 55 aa 00 BA 00 01 03 BD.

• When SubCmd is 0x02, the format of the Data field is as follows:

  1	2	3
  op	num	interval

  • op: Operation.

    • 0x00: Stop getting the RSSI value.
    • 0x01: Start getting the RSSI value.

  • num: The number of RSSI values to be obtained.

  • interval: The interval of sending RSSI values, ranging from 1 to 20 in the unit of 100 ms.

    • Example: Start getting 10 RSSI values of the HID pairing signal with an interval of 200 ms.
    • The MCU sends 55 AA 00 BA 00 04 02 01 0A 02 CC.

The module returns the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBA
4 5	2	Data length (Len)	Upper 8 bits Lower 8 bits
6	1	Subcommand	See the following table.
7 to 7+Len-1	Len	Data	See the description below.
7+Len	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

SubCmd (Subcommand):

• 0x00: Enable SMP.

• 0x01: Request the HID pairing.

• 0x02: The RSSI of the HID pairing signal.

• 0x03: Get the HID pairing state.

  The format of the Data field varies depending on subcommands. The MCU parses data according to the SubCmd and the Data format.

• When SubCmd is 0x00, the Data field is populated with a 1-byte status code.

  Status:

  • 0x00: The SMP is enabled successfully.
  • 0x01: Enabling the SMP failed.

• When SubCmd is 0x01, the Data field is populated with a 1-byte status code.

  Status:

  • 0x00: HID pairing request is sent.
  • 0x01: HID pairing failed.
  • 0x02: HID pairing succeeded.
  • 0x03: Status error.
  • 0x04: HID pairing rejected.

• When SubCmd is 0x02, the format of the Data field is as follows:

  1	2
  Status	rssi_raw

  • rssi_raw: If the value of status is not 0, rssi_raw is 0xff.
  • rssi_real: The value is rssi_raw minus 110. Assume the value of rssi_raw is 50, and the rssi_real is -60 dB.

  Status:

  • 0x00: Success.
  • 0x02: Parameter error.
  • 0x03: Not in the HID pairing state.
  • 0x04: HID pairing rejected.

• When SubCmd is 0x03, the Data field is populated with a 1-byte status code.

  Status:

  • 0x00: Not connected.
  • 0x01: Connected.
  • 0x02: HID paired and connected.
  • 0x04: HID pairing rejected.
  • 0x05: HID paired, connected, and verified.

Set advertising name (0xBB)

The MCU can set the advertising name when the module is not bound. Otherwise, the module will reject the request.

The MCU sends the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBB
4 5	2	Data length (Len)	Upper 8 bits Lower 8 bits
6 to 6+Len-1	Len	Data	See the description below.
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 to 2+ADV_LOCAL_NAME_LEN-1
ADV_LOCAL_NAME_LEN	ADV_LOCAL_NAME

• ADV_LOCAL_NAME_LEN: The length of the advertising name. Firmware earlier than v2.1.2 allows up to 5 bytes. Firmware v2.1.2 and later allows up to 14 bytes.
• ADV_LOCAL_NAME: The advertising name in ASCII.

The module returns the following data.

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

The return value of State.

• 0x00: Success.
• 0x01: Exceed the length limit.
• 0x02: Rejected.

Modify Bluetooth transmitter power (0xBD)

• If the default transmitter power cannot meet your needs, you can use this command to adjust it.
• Consult Tuya’s technical support to determine an appropriate transmitter power.

The MCU sends the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBD
4 5	2	Data length	0x00 0x02
6	1	OP	See the description below.
7	1	TX_POWER	See the description below.
8	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

OP:

• 0x00: Get
• 0x01: Set

TX_POWER:

• When OP is 0x00, this field only acts as a placeholder.

• When OP is 0x01, set the transmitter power register. Consult Tuya’s technical support to determine an appropriate value.

The module returns the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBD
4 5	2	Data length	0x00 0x02
6	1	OP	See the description below.
7	1	Value	See the description below.
8	1	CRC8	Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

OP: Its format is the same as that of the data the MCU sends to the module.

Value:

• When OP is 0x00, Value indicates TX_POWER.
• When OP is others, Value indicates the setting result. 0x00 indicates success, while any other value indicates failure.

Query module’s MAC address (0xBE)

The MCU can use this command to query the MAC address of the Bluetooth module.

The MCU sends the following data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBE
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 data.

No.	Bytes	Field	Description
0 1	2	Header	0x55 0xAA
2	1	Version number	0x00
3	1	Command (CMD)	0xBE
4 5	2	Data length	0x00 0x06
6 to 11	6	MAC	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.

Suppose that the MAC address of the module is DC:23:66:11:22:33.

• The MCU sends 55 AA 00 BE 00 00 BD to the module.

• The module returns 55 AA 00 BE 00 06 DC 23 66 11 22 33 8E.

FAQs

What is the difference between Bluetooth advertising enablement (0xA3) and triggered pairing (0xBC)?

• Bluetooth advertising enablement (0xA3) serves as the main switch for Bluetooth advertising, and all features that rely on advertising depend on its status.
• Triggered pairing (0xBC) is an advanced feature that integrates a Bluetooth advertising switch, designed to manage the pairing time window. It is a specific application of Bluetooth advertising enablement.

Reference

For more information, see Serial Communication Protocol.

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.