Smart Lock Service

The generic Bluetooth Low Energy (LE) module can integrate with Tuya’s door lock technology to support features for standard locks.

Overview

Application scenarios

Applies to products using Tuya’s standard door lock technology solution.

Features

The following table lists the commands used in the generic Bluetooth LE module.

Command	Description
0xA7	Verify dynamic passwords
0xA2	Verify offline passwords
0xA6	Configure lock features
0xA8	Configure automatic unlocking in standard lock solutions

Lock protocol

Verify dynamic password (0xA7)

• The dynamic password is time-dependent. The module time must be in sync with the server time to ensure that the calculated dynamic password is consistent. After the device is connected to an app, the time will be synchronized automatically.
• The data of Greenwich Mean Time (GMT) is used to compute the current dynamic password. Therefore, GMT must be provided to the 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)	0xA7
4 5	2	Data length (Len)	Upper 8 bits Lower 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 byte(s)
TimeSource	2000+Year	Mon	Day	Hour	Min	Sec	Code_len	Code

• TimeSource: Set it to 0x00.

  • 0x00: Use the time data Year, Mon, Day, Hour, Min, and Sec uploaded by the MCU.

  • 0x01: Use the internal time of the module. The Year, Mon, Day, Hour, Min, and Sec uploaded by the MCU are not parsed.

    The MCU uploads the date and time in GMT. For example, 12:00:00 on June 20, 2020 is represented by 0x14 0x06 0x14 0x04 0x00 0x00 in GMT.

• Code_len: The length of the password.

• Code: The password. The command 0xE6 requires that the password be transferred in ASCII while with this command 0xA7, the MCU can send the digit directly. For example, 1 is 0x01, and 9 is 0x09. See the following example.

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

No.	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)	Upper 8 bits Lower 8 bits
6 to 6+Len-1	Len	State	Return value
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 succeeded.
• 0x01: Password verification failed.

Example:

• 55 AA 00 A7 00 01 01 A8, indicating password verification failed.
• 55 AA 00 A7 00 01 00 A7, indicating password verified.

Verify offline password (0xA2)

• Offline dynamic passwords can be used to unlock the door if a device is disconnected for long periods of time.
• The time drift of the internal clock of the module is less than one minute in 24 hours. The internal clock is reset after power off. The module syncs its clock with the server each time it is connected to the cloud.
  If your MCU is connected to an external clock, we recommend you choose 0x00 for the clock source to use the time data from the MCU. If you use the internal clock of the module as the clock source, consult the R&D for a test program to measure the clock error.

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)	0xA2
4 5	2	Data length (Len)	Upper 8 bits Lower 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 byte(s)
TimeSource	2000+Year	Mon	Day	Hour	Min	Sec	Code_len	Code

• TimeSource: Set it to 0x00.

  • 0x00: Use the time data Year, Mon, Day, Hour, Min, and Sec uploaded by the MCU.

  • 0x01: Use the internal time of the module. The Year, Mon, Day, Hour, Min, and Sec uploaded by the MCU are not parsed.

    The MCU uploads the date and time in GMT. For example, 12:00:00 on June 20, 2020 is represented by 0x14 0x06 0x14 0x04 0x00 0x00 in GMT.

• Code_len: The length of the password.

• Code: The password. The dynamic password is transferred in ASCII while for the offline password, the MCU can send the digit directly. For example, 1 is 0x01, and 9 is 0x09. See the following example.

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)	0xA2
4 5	2	Data length (Len)	Upper 8 bits Lower 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 byte(s)
Result	Type	Decode_len	Decode

• Result:

  • 0x00: Correct
  • Other values: Error. The return data is insignificant.

• Type:

  • 0x00: The password is verified.
  • 0x01: A single password is cleared.
  • 0x02: All passwords are cleared.

• Code_len: The length of the encrypted data.

• code: The encrypted clear code and unlocking password.

  Type and code are used to report DP status. The DPs related to the offline password feature are DP ID 65, 66, and 67.

For example, use the internal time of the module plus 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

Configure lock features (0xA6)

• Apply to:
  • TYBN1 generic firmware v6.2 and later for smart locks.
  • BK3431Q generic firmware v3.3 and later for smart locks.
• Some features that require specific fields of the DP are turned off by default. You can turn on them as needed. The configuration is stored in the nonvolatile memory.
• You can use this command to configure:
  • The lock accessory.
  • Accessory-triggered locking and unlocking.
  • Positional notation.

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)	0xA6
4 5	2	Data length	0x00 0x04
6 to 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:

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

• FLAG:

  • Bit 0: Enable the lock accessory. 0 is for disabling and 1 is for enabling. This feature is disabled by default.

  • Bit 1: Enable accessory-triggered locking and unlocking. 0 is for disabling and 1 is for enabling. This feature is disabled by default.

    Bit 0 and bit 1 are mutually exclusive. When you enable either of them, the other is disabled automatically.

  • Bit 2 to bit 7: reserved.

• PWD_NUM: The number of digits on the keypad, defaulting 10 (0 to 9). If a keypad only has 4 to 9 consecutive digits, the MCU can use this field to configure the keypad. PWD_BEGIN_NUM is used to set the starting digit, which can be 0 or 1.

  The valid values of PWD_NUM range from 0x04 to 0x09. Invalid values will apply the default setting of 10 digits.

• PWD_BEGIN_NUM: the starting digit, which can be 0 or 1. If the keypad starts from 0, set it to 0x00. If the keypad starts from 1, set it to 0x01.

  The valid values of PWD_BEGIN_NUM are 0x00 and 0x01. Invalid values will apply the default 0x00.

Example:

• 55 AA 00 A6 00 04 01 00 00 00 AA: Enable the lock accessory.
• 55 AA 00 A6 00 04 00 00 00 00 A9: Disable the lock accessory.

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)	0xA6
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.

Return value of state:

• 0x00: Success
• Other values: Failure

Configure iBeacon (0xA8)

• Apply to the generic firmware for smart locks.
• The principle of the anti-lost or auto-unlocking feature is that the Bluetooth device sends iBeacon-complied advertising packets within a time period. After the mobile phone receives the packet, it will execute the specified command.
• The anti-lost or auto-unlocking requires the corresponding DP and the mobile app.
• The anti-lost configuration is stored in the volatile memory so it will reset to default when the module is turned off or restarted. The auto-unlocking configuration is stored in the nonvolatile memory so the device will resume the last state after power on.
• After the device is unbound or reset, iBeacon configuration will be reset.

The MCU sends the following data.

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

CFG format:

1 byte	1 byte	2 bytes	2 bytes
1	2	3 to 4	4 to 5
operation	config_type	ibeacon_interval	timeout

• operation:

  • 0x00: Turn off anti-lost iBeacon.
  • 0x01: Turn on anti-lost iBeacon.
  • 0x02: Turn off auto-unlocking iBeacon.
  • 0x03: Turn on auto-unlocking iBeacon.

• config_type:

  • 0x00: Use the default configuration. Set ibeacon_interval and timeout to 0x00.
  • 0x01: Use the custom configuration. See the fields ibeacon_interval and timeout.

• ibeacon_interval: The iBeacon advertising interval in low power mode in the unit of 100 ms, ranging from 100 ms to 2,000 ms. The actual advertising interval is ibeacon_interval × 100 ms. It is fixed to 100 ms in standard power mode.

  With iBeacon turned on, the advertising interval is as follows:

  • The advertising interval in standard power mode is 100 ms.
  • The advertising interval in low power mode is 500 ms by default. The iBeacon interval is independent of the advertising interval set by the command 0xE2. With iBeacon turned on, the device advertises with the ibeacon_interval in low power mode.
  • With the anti-lost enabled, the device advertises the iBeacon content with the ibeacon_interval.
  • With the auto-unlocking enabled, the device advertises the iBeacon content and Tuya-specific content in turn with the ibeacon_interval. The interval for switching between advertising contents is one second, which is not configurable. Make sure ibeacon_interval is less than one second.

• timeout: iBeacon timeout in the unit of 5s. That is, iBeacon times out in 5 × timeout seconds. The valid values range from 5s to 2 min. The auto-unlocking feature has no timeout and needs to be configured to be turned off.

Example:

• Anti-lost iBeacon: 55 AA 00 A8 00 06 01 00 00 00 00 00 AE
• Auto-unlocking iBeacon: 55 AA 00 A8 00 06 03 00 00 00 00 00 B0

The module returns the following data.

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

Return value of state:

• 0x00: Success
• Other values: Failure

FAQs

What is the function of the interface 0xA6? When does it need to be configured?

This interface is used to configure the DP-specific features. It applies to three features:

• The lock accessory.
• Accessory-triggered locking and unlocking. These two features work for the Bluetooth lock accessory, one for the lock and the other for the accessory.
• Positional notation.

If the lock accessory features are not required for your product, you do not need to configure them. They are disabled by default. To set these features, the MCU should send the configuration to the module after the UART initialization. The configuration is stored in the nonvolatile memory.

What about a non-decimal keypad? How to configure the multi-digit password function?

• PWD_NUM: The number of digits on the keypad, defaulting 10 (0 to 9). If a keypad only has 4 to 9 consecutive digits, the MCU can use this field to configure the keypad. PWD_BEGIN_NUM is used to set the starting digit, which can be 0 or 1.

  The valid values of PWD_NUM range from 0x04 to 0x09. Invalid values will apply the default setting of 10 digits.

• PWD_BEGIN_NUM: the starting digit, which can be 0 or 1. If the keypad starts from 0, set it to 0x00. If the keypad starts from 1, set it to 0x01.

  The valid values of PWD_BEGIN_NUM are 0x00 and 0x01. Invalid values will apply the default 0x00.

Example

• Example 1: If the keypad has digits 1 through 6, set the PWD_NUM to 6 and PWD_BEGIN_NUM to 1.

• Example 2: If the keypad has digits 0 through 8, set the PWD_NUM to 9 and PWD_BEGIN_NUM to 0.

How to implement the accessory feature on the lock?

Four DPs and one command 0xA6 together implement the lock accessory feature. You do not need to take care of the Bluetooth pairing and reconnection, which has been implemented in the generic firmware.

Double identity verification in the service layer is implemented to ensure the security of the lock.

1. The cloud assigns the central (app or accessory) a unique code that consists of the central ID and a central random number to identify the central device.
   The cloud assigns the peripheral (lock) a unique code that consists of the peripheral ID and a peripheral random number to identify the peripheral device.

2. After the cloud sends the app’s unique code and the lock’s peripheral ID to the lock, the lock is considered to be paired with the app.
   After the cloud sends the unique code of the accessory to the lock and sends the unique code of the accessory and the peripheral ID of the lock to the accessory, the lock is considered to be paired with the accessory.

3. The lock stores:
   The unique code of the app
   The unique code of the accessory (one/multiple)
   The peripheral ID of the lock

   The accessory stores:
   The unique code of the accessory
   The peripheral ID of the lock

So far, the accessory can unlock the door. Before unlocking, it tells the lock the unique code of itself and the peripheral ID of the lock for verification.

The implementation of the above logic is included in the generic firmware. The lock service configuration is disabled by default because it requires the data of specific DP and the generic firmware does not process DP data but transmits the raw data. To use this feature, the MCU should use the command 0xA6 to enable it. The module just gets and parses the central ID, peripheral ID, and random numbers without modifying them.

If you do not enable the lock service configuration, the module will transmit the obtained raw data to the MCU for processing.

Identity verification logic

The MCU enables the lock accessory feature through the command 0xA6(55 AA 00 A6 00 04 01 00 00 00 AA). Then, the module processes the DP ID 70 (configure random number) without transmitting the raw DP data to the MCU for processing.

For the DP ID 71 (unlock/lock) and 73 (set remote unlocking), the module collects the central ID, peripheral ID, and random number from the DP data for identity verification.

• If the identity is verified, the module will send the raw DP data to the MCU for processing the unlocking/locking operation and remote unlocking.
• If the identity is not verified, the module will return a failure without sending the raw DP data to the MCU.

The MCU processes the DP data

After the MCU enables the lock accessory feature, the module only verifies the accessory identity and determines whether to send the raw DP data to the MCU for processing. The MCU does not need to process the fields of central ID, peripheral ID, and random number but only adjusts the position of these fields. Take the DP ID 71 as an example:

Description	Data transmission	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Unlocking and locking	Send	71	raw	len	Central ID (2 bytes)	Peripheral ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking/unlocking timestamp (4 bytes)	Locking/unlocking method (1 byte)	Locking/unlocking info (len-12 bytes)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock. 0x01: Unlock.	Description	Description	Description
	Report	71	raw	len	Peripheral ID (2 bytes)	Central ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking/unlocking timestamp (4 bytes)	Locking/unlocking method (1 byte)	Return value (1 byte)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock. 0x01: Unlock.	Description	Description	Value range

The position of the central ID and the peripheral ID is exchanged.

• The module sends 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
• The MCU sends 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

DP ID 73 is processed the same way.

After the MCU receives data of DP ID 71, it stores the central ID, peripheral ID, and random number that will be used when the MCU reports the locking or unlocking record.

Description	Data transmission	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Locking & Unlocking Record	Report	72	raw	len	Peripheral ID (2 bytes)	Central ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking/unlocking timestamp (4 bytes)	Locking/unlocking method (1 byte)	Locking/unlocking info (len-12 bytes)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock. 0x01: Unlock.	Description	Description	Description

How to implement the accessory feature on the accessory?

The MCU enables the lock accessory feature through the command 0xA6.

After the module receives the unlock/lock command from the MCU, it will retrieve the accessory information according to the peripheral ID. If the accessory has been added, it can unlock or lock the door. Then, the module will initiate a reconnection request and forward the DP for unlock/lock to the lock for command execution.

Description	Data transmission	dp_id (1 byte)	dp_type (1 byte)	dp_da ta_len (1 byte)	dp_data_value
Unlocking and locking	Send	71	raw	len	Central ID (2 bytes)	Peripheral ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking/unlocking timestamp (4 bytes)	Locking/unlocking method (1 byte)	Locking/unlocking info (len-12 bytes)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock. 0x01: Unlock.	Description	Description	Description
	Report	71	raw	len	Peripheral ID (2 bytes)	Central ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Locking/unlocking timestamp (4 bytes)	Locking/unlocking method (1 byte)	Return value (1 byte)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock. 0x01: Unlock.	Description	Description	Value range

When the accessory’s MCU reports DP data, it only needs to populate the peripheral ID. If the accessory’s module has stored the information, it can automatically populate the corresponding central ID and random number.

The accessory’s MCU should store:

• Peripheral ID (the lock’s ID)

  The lock ID will be sent to the MCU when an unlocking method is added. For more information, see the DP protocol specification.

• For data from other DPs, the module will not process it and directly send the raw data to the MCU.

  After the connection is established, the accessory will forward the lock/unlock DP reported by the MCU to the lock and a 30s timer is started. If the lock does not respond with the result within 30 seconds, the Bluetooth connection will be disconnected. If the lock returns a result, the Bluetooth connection will be disconnected too.