Smart Lock Service

Overview

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

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.
  • BK3633QN33 generic firmware v0.0.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:
  • As a door lock: Support being unlocked/locked by accessory devices (BK3633 supports this feature by default).
  • As an accessory: Support the control (unlock/lock) of door locks.
  • Configure 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	Disconnect duration in case of accessory pre-connection timeout (BK3633 only)

• FLAG:

  • Bit 0: Enable the lock accessory. 0 is for disabling, and 1 is for enabling. This feature is disabled by default, but enabled for BK3633 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 to 10 (that is, 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 4 to 10. 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.

• Accessory connection timeout: When an accessory initiates a pre-connection to a door lock, if no further lock/unlock command is received after successfully connecting to the lock, the accessory will proactively disconnect the Bluetooth connection with the door lock.

  • After the accessory successfully performs a lock/unlock operation, it will immediately disconnect the Bluetooth connection with the door lock.
  • This field’s configuration only takes effect for values between 5 to 30 seconds. Any other number will use the default setting (8 seconds).

Example

• 55 AA 00 A6 00 04 01 00 00 00 AA: Can be used as a door lock that can be locked/unlocked by accessories.
• 55 AA 00 A6 00 04 02 00 00 00 AB: Can be used as an accessory that can control door locks.
• 55 AA 00 A6 00 04 01 0A 00 00 B4: The number of password digits is 10, and the digits range from 0 to 9.

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 fieldibeacon_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:

• Configure whether to function as a door lock or an accessory. The default is as a door lock.
• Configure the positional notation of passwords.

If the module is intended to function as a door lock, configuration is not necessary as door lock functionality is the default. If the module needs to function as an accessory, 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 to 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?

DPs in Accessory DP Reference and 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 smart lock stores the following information:

   • The central ID and central random number of the app
   • The central ID and central random number of each accessory
   • The peripheral ID of the smart lock

   An accessory stores the following information:

   • The central ID and central random number of the accessory
   • The peripheral ID of the smart 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 module will transmit the obtained raw data to the MCU for processing.

How to integrate with the lock and unlock 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 connection request and forward the unlock/lock DP to the lock for command execution.

Description	Data transmission	dp_id (1 byte)	dp_type (1 byte)	dp_data _len (1 byte)	dp_data_value
Unlock and lock	Send	71	Raw	len	Central ID (2 bytes)	Peripheral ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Lock/unlock timestamp (4 bytes)	Lock/unlock method (1 byte)	Lock/unlock info (len-12 bytes)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock 0x01: Unlock 0xFF: Pre-connection (BK3633 only)	Description	Description	Description
	Report	71	Raw	len	Peripheral ID (2 bytes)	Central ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Lock/unlock timestamp (4 bytes)	Lock/unlock method (1 byte)	Return value (1 byte)
					0 to 10000	0 to 10000	Same as above	Same as above	Same as above	Same as above	Value range

• Central ID and random number: When the accessory’s MCU reports the unlock DP 71 to the accessory, the corresponding fields should be padded with zeros. The module does not process this. Based on the connected peripheral ID, the module will automatically fill in the central ID and random number.

• Peripheral ID: The MCU must populate this field. If it is set to 0xFFFF, the module will connect to the door lock that has already been bound. If multiple door locks are bound, it will only control the one it successfully connects to during that instance. The MCU can also specify a peripheral ID. When the app adds an unlocking method, it will send the peripheral ID corresponding to that unlocking method to be added.

• Operation type: 0xFF is only supported in module-based solutions. It is used to trigger the accessory to establish a Bluetooth connection with the door lock in advance. This facilitates faster lock/unlock control after the accessory completes permission verification. If no subsequent lock/unlock command is received within the pre-connection timeout period, the Bluetooth connection will be disconnected.

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

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

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_data _len (1 byte)	dp_data_value
Lock &unlock record	Report	72	Raw	len	Peripheral ID (2 bytes)	Central ID (2 bytes)	Random number (8 bytes)	Operation (1 byte)	Lock/unlock timestamp (4 bytes)	Lock/unlock method (1 byte)	Lock/unlock info (len-12 bytes)
					0 to 10000	0 to 10000	Random number for central device	0x00: Lock 0x01: Unlock	Description	Description	Description

The accessory’s MCU should store:

• Peripheral ID (the lock 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, but directly send the raw data to the MCU, except for the offline password T0 parameter and the single/multi-unlock settings. The MCU must reply with the corresponding DP command (including offline password T0 and single/multi-unlock settings).

• During door lock and accessory pairing, the door lock information sent via the pass-through channel will be directly handled by the module, requiring no operation from 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 30s, the Bluetooth connection will be disconnected. If the MCU returns a result, the module also disconnects from the Bluetooth accessory.