Accessory DP Reference

Last Updated on : 2024-06-21 03:36:08download

This topic describes the function definitions based on data points (DPs), frame format, and usage notes in the application of Bluetooth lock accessories. This topic applies to all-in-one Bluetooth lock accessory products or projects.

Background information

Terms

The following table lists the important terminologies that you may find helpful in understanding this topic. For more information, see Glossary.

Term Definition
DP A data point (DP) matches a smart device function. Each DP indicates a function or a pair of commands.
PID A product ID (PID) is an abstract representation of a collection of physical devices that have the same configurations and properties. Each product created on the Tuya Developer Platform is assigned a unique PID that is associated with the product information, including DPs, app control panel, and purchase information.
UUID A universally unique identifier (UUID) is the license and unique ID when you develop a smart product on the Tuya Developer Platform. A UUID is a 20-digit number.
Authkey An authkey is the authentication key that is used to register the device to the cloud. Each authkey corresponds to a UUID. An authkey is a 32-digit number.
Firmware key The unique identity of firmware assigned by the Tuya Developer Platform.
Member A member is also called a user.
Member ID The ID of a member or a user, which is a 1-byte unsigned integer assigned and managed by the cloud. The valid values range from 0x01 to 0x64. The rest are reserved.
Hardware ID The ID of the hardware specific to an unlocking method, which is a 1-byte unsigned integer assigned and managed by the local processor. The valid values range from 0x00 to 0xFE. 0xFF is reserved. For example, for fingerprint unlocking and password unlocking, the hardware ID is 0x01 and 0x02 respectively.
Validity period A specific unlocking method (such as fingerprint or password) is valid during the specified time period.
Smart stick lock A device that upgrades traditional locks to smart locks. For more information, see related documents.
Client to server The operation in which data is transmitted in a specific direction from a mobile phone or a gateway to a Bluetooth device.
Server to client The operation in which data is transmitted in a specific direction from a Bluetooth device to a mobile phone or a gateway.

How a smart lock works

To enable the smart lock functions, the following roles are required:

  • Central device: This role is assigned to the Smart Life app.

  • Peripheral device: This role is assigned to a Bluetooth lock.

    The central device recognizes the peripheral device by using Bluetooth broadcasting and sends a pairing request to the authorized peripheral device. The central device is associated with the peripheral device after the pairing operation.

    A secure channel that complies with Bluetooth specifications is established between the central device and peripheral device. All service data can be transmitted through this secure channel.

The secure channel supports the following steps in sequence: start in the disassociated state > connect > pair > associate > establish a secure communication > disconnect > reconnect > associate > establish a secure communication > … > remove > return to the disassociated state.

  • Connect: a common Bluetooth connection between the app and the smart lock.
  • Pair: a process of key exchanges.
  • Associate: A device is associated with another device after they are paired with each other. Then, secure communication is enabled between both devices.
  • Reconnect: a process of key exchanges. It can be regarded as a simplified pairing process. Devices can reconnect to each other only after they have been associated with each other.
  • Remove: A key or an associated relationship can be removed.

How Bluetooth lock accessories work

Each Bluetooth lock accessory can be assigned either of the following roles:

  • Peripheral device: An accessory gets the details of the associated smart lock after the accessory is paired with the app. This enables the accessory to reconnect to the smart lock.
  • Central device: An accessory is allowed for secure communication after the accessory is reconnected with the smart lock. This enables the accessory to control the smart lock.

Double identity verification in the service layer is implemented to protect the lock.

  • 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 device (lock) a unique code that includes the peripheral ID and a peripheral random number to identify the peripheral device.

  • After the cloud sends the unique code of the app and the peripheral ID of the lock 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 peripheral device, the lock is considered to be paired with the accessory.

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

DP formats

Field Length (number of bytes) Description
dp_id 1 The ID of a DP.
dp_type 1 The data type of a DP.
dp_data_len 1 The data length of a DP.
dp_data_value dp_data_len The payload of a DP.
Note: The size of dp_data_len is two bytes for Tuya Bluetooth modules and applies to all DPs.

Central ID and peripheral ID

Each of the central ID and peripheral ID is assigned a unique ID by the Tuya Developer Platform. An ID starts from 1.

Central IDDescriptionPeripheral IDDescription
0Invalid0Invalid
1Accessory 11Lock 1
2Accessory 22Lock 2
10000Accessory 1000010000Lock 10000
65535
(0xFFFF)
Mobile phone (gateway)

Unlocking methods

Add unlocking methods

Data
transmission

dp_id
(1
byte)
dp
_type
(1
byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server
1 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member
ID
(1 byte)
Hardware
ID
(1 byte)
Validity
(17
bytes)
Number
of times
(1 byte)
Password
length
(1
byte)
Password
content
(n
byte)
0 to 10000 0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00: Start enrollment.
0xFE: Cancel enrollment
(initiated by app).
0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0xFF:
Default value
See
Appendix 1
Value
Range
Description Description
Server to client
1 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member
ID
(1 byte)
Hardware
ID
(1 byte)
Number of times
(1 byte)
Return value
(1 byte)
0 to 10000 0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00: Start enrollment. 0x00: Ordinary member
0x01: Admin
0x00
-0x64
0x00
-0xFE
The number of times to finish enrollment.
For example, six times for fingerprint enrollment,
one time for door card enrollment.
0x00: Default value
0xFC: Enrollment in progress 0x00: Ordinary member
0x01: Admin
0x00
-0x64
0x00
-0xFE
The sequence number for enrollment times,
starting from 1.
For example, fingerprint enrollment might be six times.
This field is populated with the current times.
Reasons for an enrollment exception:
0x00: no exception
0x01: incomplete fingerprint
0xFD: Enrollment failed 0x00: Ordinary member
0x01: Admin
0x00
-0x64
0x00
-0xFE
Current enrollment stage:
0x00: Start enrollment.
0xFC: Enrollment in progress.
0xFF: Finish enrollment.
Reasons for failed enrollment
0xFE: Cancel enrollment
(initiated by app).
0x00: Ordinary member
0x01: Admin
0x00
-0x64
0x00
-0xFE
0x00: Default value 0x00: Default value
0xFF: Enrollment is finished. 0x00: Ordinary member
0x01: Admin
0x00
-0x64
0x00
-0xFE
0x00: Default value 0x00: Default value

Delete unlocking methods

Data
transmission

dp_id
(1
byte)
dp
_type
(1
byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server
2 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Deletion method
(1 byte)
0 to 10000 0x00: Delete a member. 0x00:
Default
0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0xFF:
Default value
0x00: Delete all the unlocking methods
granted to a member.
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00:
Default
0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0x00
-0xFE
0x01: Delete a specified unlocking method
granted to a member.
Server to client
2 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Deletion method
(1 byte)
Return value
(1 byte)
0 to 10000 0x00: Delete a member. 0x00:
Default
0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0xFF:
Default value
0x00: Delete all the unlocking methods
granted to a member.
0x00: Failure
0xFF: Success
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00:
Default
0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0x00
-0xFE
0x01: Delete a specified unlocking method
granted to a member.
0x00: Failed to delete.
0x01: The unlocking method does not exist.
0xFF: Deleted successfully.

Modify unlocking methods

Data
transmission

dp_id
(1
byte)
dp_type
(1
byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server
3 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Validity
(17
bytes)
Number of times
(1 byte)
Password
length
(1
byte)
Password
content
(n
byte)
0 to 10000 0x00:
Modify the
validity period
for a specified member.
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0xFF:
Default value
See
Appendix 1
0x00:
Default value.
(Modification is
not allowed)
Descrption Descrption
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0x00
-0xFE
See
Appendix 1
Value
range
Description Description
Server to client
3 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Number of times
(1 byte)
Return value
(1 byte)
0 to 10000 0x00:
Modify the
validity period
for a specified member.
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0xFF:
Default value
0x00: Default value.
(Modification is not allowed)
0x00: Failure
0xFF: Success
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01
to 0x64
0x00
-0xFE
Value range 0x00: Failure
0xFF: Success

Add temporary passwords

The temporary password is different from the ordinary password in the following ways:

  1. A temporary password does not belong to any member.
  2. The validity period of a temporary password can be modified when the lock is connected.
  3. A temporary password is defined as 0xF0 for an unlocking method. 0x01 indicates password. 0x02 indicates door card. 0x03 indicates fingerprint.
Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 4 raw len Peripheral ID
(2 bytes)
Type
(1 byte)
Validity
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n byte)
0 to 10000 0x00: Type 0
00x01: Type 1
See Appendix 1 Value range The bytes of a password
(used for unlocking with password only)
Description
Server to client 4 raw len Peripheral ID
(2 bytes)
Hardware ID
(1 byte)
Return value
(1 byte)
0 to 10000 0x00-0xFE 0x00: Success
0x01: Failure
0x02: Hardware ID is assigned.

Delete temporary passwords

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 5 raw len Peripheral ID
(2 bytes)
Hardware ID
(1 byte)
0 to 10000 0x00-0xFE
Server to client 5 raw len Peripheral ID
(2 bytes)
Hardware ID
(1 byte)
Return value
(1 byte)
0 to 10000 0x00-0xFE 0x00: Success
0x01: Failure
0x02: The temporary password does not exist.

Modify temporary passwords

Data
transmission
dp_id
(1
byte)
dp
_type
(1
byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server 6 raw len Peripheral ID
(2 bytes)
Hardware ID
(1 byte)
Type
(1 byte)
Validity
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n byte)
0 to 10000 0x00-0xFE 0x00: Type 0
00x01: Type 1
See Appendix 1 Value range The bytes of a password
(used for unlocking with password only)
Description
Server to client 6 raw len Peripheral ID
(2 bytes)
Hardware ID
(1 byte)
Return value
(1 byte)
0 to 10000 0x00-0xFE 0x00: Success
0x01: Failure

Sync unlocking methods

To ensure the unlocking methods in the local device and the server are in sync, each time users open the app homepage or refresh the device list, all the added unlocking methods will be synced between them.

The field of hardware types is used to notify the lock of what unlocking methods it should report. For the in-sync stage, the data length of each packet is defined by you. The total length of one packet should not exceed 200 bytes.

For more information, see Bluetooth LE Lock FAQ.

Sync locally-added unlocking methods

When a lock syncs the locally-added unlocking methods with the cloud:

  • If the member ID is 0xFF, the cloud saves this ID and associates the reported unlocking method with the app account that is bound with this lock. The member ID 0xFF will be used when the cloud sends commands of this unlocking method. This scenario only applies to smart padlocks provided by BioLock and Hui-Li. The unlocking methods cannot be deleted from the cloud.
  • If the member ID is 0xFD, the cloud saves this ID and associates the reported unlocking method with the app account that is bound with this lock. The member ID 0xFD will be used when the cloud sends commands of this unlocking method. Note that this member ID is generic.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 7 raw len Hardware type enumeration
(bytes)
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
Server to client 7 raw len Stage
(1 byte)
Packet sequence
number (1 byte)
Data to be
synchronized (n bytes)
0x00: In-sync 0x00–0xFF Data 1, data 2, …, data n
Server to client 7 raw len Stage
(1 byte)
Total number of packets
(1 byte)
0x01: Sync finished Total number of packets

User guide

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 8 raw len Feature
(1 byte)
0x00: function 0
0x01: function 1
Server to client 8 raw len Feature
(1 byte)
Return value
(1 byte)
0x00: function 0
0x01: function 1
0x00: Success
0x01: Failure

Add a Bluetooth key

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 9 raw len Peripheral ID
(2 bytes)
Member ID
(1 byte)
Admin flag
(1 byte)
Validity
(17 bytes)
0 to 10000 0x01 to 0x64 0x00: Ordinary member
0x01: Admin
See Appendix 1
Server to client 9 raw len Peripheral ID
(2 bytes)
Member ID
(1 byte)
Admin flag
(1 byte)
Validity period
(17 bytes)
Return value
(1 byte)
0 to 10000 0x01 to 0x64 0x00: Ordinary member
0x01: Admin
See Appendix 1 0x00: Success
0x01: Failure
0x02: Hardware ID is assigned.

Delete a Bluetooth key

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 10 raw len Peripheral ID
(2 bytes)
0 to 10000
Server to client 10 raw len Peripheral ID
(2 bytes)
Return value
(1 byte)
0 to 10000 0x00: Success
0x01: Failure
0x02: The Bluetooth key does not exist.

Modify a Bluetooth key

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 11 raw len Peripheral ID
(2 bytes)
Member ID
(1 byte)
Admin flag
(1 byte)
Validity
(17 bytes)
0 to 10000 0x01 to 0x64 0x00: Ordinary member
0x01: Admin
See Appendix 1
Server to client 11 raw len Peripheral ID
(2 bytes)
Member ID
(1 byte)
Admin flag
(1 byte)
Validity period
(17 bytes)
Return value
(1 byte)
0 to 10000 0x01 to 0x64 0x00: Ordinary member
0x01: Admin
See Appendix 1 0x00: Success
0x01: Failure
0x02: Hardware ID is assigned.

Unlock with new combined methods

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data
_len
(1 byte)
dp_data_value
Server to client 59 raw len Peripheral ID
(2 bytes)
Combined unlocking methods
(1 byte)
Unlocking method 1
(1 byte)
Hardware ID 1
(1 byte)
Unlocking method 2
(1 byte)
Hardware ID 2
(1 byte)
0 to 10000 Value range Value range 0x01-0xFE Value range 0x01-0xFE

Accessory settings

Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Accessory ringtones Cloud-to-device/device-to-cloud 20 enum len Ringtones (1 byte)
0x00: Ringtone 0

0x0A: Ringtone 10
Accessory sound volume Cloud-to-device/device-to-cloud 21 enum len Volume (1 byte)
Value range
Volume on keypress Cloud-to-device/device-to-cloud 22 enum len Volume (1 byte)
Value range
Local navigation volume Cloud-to-device/device-to-cloud 23 enum len Volume (1 byte)
Value range
Accessory language Cloud-to-device/device-to-cloud 24 enum len Language (1 byte)
Value range
Welcome message on the display screen Cloud-to-device/device-to-cloud 25 String len Welcome message (1 byte)
0-50 bytes
Turn on/off locking check Cloud-to-device/device-to-cloud 27 Boolean len Switch (1 byte)
0x00: on
0x01: off
Single-cylinder (or lock) and multi-cylinder (or lock) settings Cloud-to-device/device-to-cloud 28 enum len Setting (1 byte)
0x00: single-cylinder (or lock),
0x01: multi-cylinder (or lock)
Special features Cloud-to-device/device-to-cloud 29 enum len Feature (1 byte)
0x00: function 0
0x01: function 1

Accessory real-time status

Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Battery percentage Cloud-to-device/device-to-cloud 40 Value len Percentage (4 bytes)
0x00-0x64
Battery level Cloud-to-device/device-to-cloud 41 enum len Level (1 byte)
Value range

Report accessory records

Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Unlock with button Server to client 50 raw len Fixed value (4 bytes) Peripheral ID (2 bytes)
0x00 0 to 10000
Unlock with password Server to client 51 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with card Server to client 52 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with fingerprint Server to client 53 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with face recognition Server to client 54 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with iris Server to client 55 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with palm print Server to client 56 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Unlock with finger vein Server to client 57 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Temporary password unlocking Server to client 58 raw len Hardware ID (4 bytes) Peripheral ID (2 bytes)
0x00-0xFE 0 to 10000
Combination unlocking Server to client 59 raw len Possible combinations of
unlocking methods (1 byte)
Peripheral ID (2 bytes)
Value range 0 to 10000
Alert reason Server to client 60 raw len Reasons for alerts (1 byte)
Value range
Locking records Server to client 106 raw len Locking methods (1 byte) Member ID (4 bytes)
0x05: Accessory locked 0x01–0x04
Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
General accessory
record report
Server to client 69 raw len Peripheral ID (2 bytes) Unlocking method (1 byte) Unlocking data (1 byte)
0 to 10000 0x00: mobile phone
0x01: button

dp_id of unlocking record
Mobile phone: 1 byte, member ID
button: 1 byte, fixed value 0x00

dp_data_value of unlocking record

Offline password

Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Offline password
Set T0 time
Cloud-to-device/device-to-cloud 70 String len T0 timestamp (10 bytes)
Unix timestamp
Offline password
Clear one password
Server to client 71 raw len The encrypted code for clearing passwords (16 bytes)
See the note.
Offline password
Clear all passwords
Server to client 72 raw len The encrypted code for clearing passwords (16 bytes)
See the note.
Unlock with offline password Server to client 73 raw len Encrypted password (16 bytes)
See the note.
Unlock with dynamic password Server to client 74 Value len Fixed value (4 bytes)
0: default

DPs of the Tuya Developer Platform

Function Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
SMS notification None 90 Boolean len None
Duress alarms None 91 Boolean len None

Pair devices or cancel pairing

Pairing commands are used to pair accessories with the smart lock. The commands are sent to accessories through the pass-through channel TUYA_BLE_CB_EVT_DATA_PASSTHROUGH on a mobile phone. The accessory SDK parses and processes the commands and outputs API operations for development.

Data
transmission
data_value
Client to server Operation
(1 byte)
Accessory ID
(2 bytes)
Accessory random number
(8 bytes)
Peripheral ID
(2 bytes)
Peripheral ID
(16 bytes)
Peripheral device
login_key (16 bytes)
0x00: Add
0x01: Delete
0 to 10000 Accessory random number 0 to 10000 device id login key
Server to client Operation
(1 byte)
Accessory ID
(2 bytes)
Accessory random
number (8 bytes)
Peripheral ID
(2 bytes)
Return value
(1 byte)
0x00: Add
0x01: Delete
0 to 10000 Accessory random number 0 to 10000 Value range

New DPs of smart lock

To protect smart locks that are designed based on the “Bluetooth Lock DP Reference” and enable functions of the lock accessories, you must modify the following DPs:

  • Use dp_id = 71 instead of dp_id = 6
  • Use dp_id = 73 instead of dp_id = 60

Pair devices or cancel pairing

Data is sent from the mobile phone to the smart lock.

Pairing commands are used to pair accessories with the smart lock. The mobile phone sends the commands to the smart lock by using DP 70 of the smart lock.

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Client to server 70 raw len Central ID
(2 bytes)
Peripheral ID
(2 bytes)
Random number
(8 bytes)
Operation
(1 byte)
Central ID to
be configured (2 bytes)
Random number
of central ID to be
configured (8 bytes)
0 to 10000 0 to 10000 Central random number 0x00: Add
0x01: Delete
0 to 10000 Description
Server to client 70 raw len Peripheral ID
(2 bytes)
Central ID
(2 bytes)
Random number
(8 bytes)
Operation
(1 byte)
Central ID to
be configured (2 bytes)
Return value
(1 byte)
0 to 10000 0 to 10000 Central random number 0x00: Add
0x01: Delete
0 to 10000 Value range

Locking and unlocking

Accessories can only use this DP to lock or unlock the door.

Data is sent from the mobile phone to the smart lock.
Data is also sent from the accessories to the smart lock.

If this DP is selected, the DP with dp_id = 6 cannot be used. Otherwise, lock operations cannot be safe.

The locking and unlocking command is the only lock DP that is available for accessories.
After the DP is sent, the smart lock verifies the central ID, peripheral ID, and random number to ensure security.
The timestamp, method, and details of locking and unlocking are sent by accessories and processed by the Tuya Developer Platform. The smart lock reports the data without modifications.

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server 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
(18 bytes)
0 to 10000 0 to 10000 Central random number 0x00: Lock.
0x01: Unlock.
Description Description Description
Server to client 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 Central random number 0x00: Lock.
0x01: Unlock.
Description Description Value range

Locking and unlocking records

Data is reported from the smart lock to the mobile phone.

The DP of locking and unlocking records is reported from the smart lock to the mobile phone.

After the DP is sent, the smart lock includes the peripheral ID, central ID, and random number in the report to ensure security.

The timestamp, method, and details of locking and unlocking are sent from accessories to the smart lock and processed by the Tuya Developer Platform in the locking and unlocking scenario. The smart lock reports the data without modifications.

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_
data_len
(1
byte)
dp_data_value
Server to client 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
(18 bytes)
0 to 10000 0 to 10000 Central random number 0x00: Lock.
0x01: Unlock.
Description Description Description

Configure remote unlocking

Data is sent from the mobile phone to the smart lock.

If this DP is selected, the DP with dp_id = 60 cannot be used. Otherwise, security cannot be ensured during lock operations.

Data
transmission

dp_id
(1
byte)
dp_type
(1
byte)
dp_
data_len
(1
byte)
dp_data_value
Client to server
73 raw len Central ID
(2
bytes)
Peripheral ID
(2
bytes)
Random number
(8
bytes)
Validity
(1 byte)
Member ID
(2
bytes)
Start time
(4
bytes)
End time
(4
bytes)
Access times
(2
bytes)
Key content
(8
bytes)
0
to 10000
0
to 10000
Central
random number
0x00: Invalid
0x01: Valid
0x01
to 0x64
Unix timestamp
(See Appendix 1)
Unix timestamp
(See Appendix 1)
0x0000
-0xFFFF
ASCII code
Server to client
73 raw len Peripheral ID
(2
bytes)
Central ID
(2
bytes)
Random number
(8
bytes)
Validity
(1 byte)
Member ID
(2
bytes)
Return value
(1 byte)
0
to 10000
0
to 10000
Central
random number
0x00: Invalid
0x01: Valid
0x01
to 0x64
Value range

Get offline records (pass-through channel)

Data is sent from the mobile phone to the smart lock.

For the smart lock that does not support accessories, offline records are reported in specific conditions. For example, this applies when a delay occurs after the BONDING_CONN event between the mobile phone and the smart lock.
For the smart lock that supports accessories, the BONDING_CONN event also occurs between the accessories and the smart lock. However, offline records are not reported to the accessories. In this case, the mobile phone uses the pass-through channel to send the command for retrieval of offline records. The smart lock reports the offline records after the command is received.

Data transmission dp_data_value
Client to server Central ID
(2 bytes)
Peripheral ID
(2 bytes)
Random number
(8 bytes)
Fixed value
(1 byte)
0
to 10000
0
to 10000
Central
random number
0x00
Server to client All offline records with timestamps are reported, such as the unlocking records and alerts.

Pair accessories with the smart lock

Accessory DP Reference

In the preceding figure, Steps 1, 3, and 5 are implemented with the DP dp_id=70 of the smart lock. Steps 2 and 4 are implemented through the pass-through channel of the accessories.

Step 1 indicates the second pairing between the mobile phone and the smart lock. When the mobile phone opens the smart lock panel for the first time, DP 70 is sent to the smart lock. The following fields are included in the command:

  • Central ID: 0xFFFF, the ID of the mobile phone
  • Peripheral ID: The smart lock ID that is assigned by the Tuya Developer Platform
  • Random number: All bits set to 0 for the initial number
  • Operation: Add
  • Central ID to be configured: The mobile phone ID that is assigned by the Tuya Developer Platform
  • Central random number to be configured: The mobile phone random number that is assigned by the Tuya Developer Platform

Step 2 indicates the pairing between the first accessory and the smart lock. When pairing is started, the mobile phone sends data to the accessory through the pass-through channel. The following fields are included in the command:

  • Operation: Add
  • Accessory ID: The central ID that is assigned by the Tuya Developer Platform to the accessory
  • Accessory random number: The central random number that is assigned by the Tuya Developer Platform to the accessory
  • Peripheral ID: The smart lock ID that is assigned by the Tuya Developer Platform
  • Peripheral device_id: See Tuya Bluetooth Low Energy Communication Protocol
  • Peripheral login_key: See Tuya Bluetooth Low Energy Communication Protocol

This step is implemented in the SDK and module. You only need to call required API operations or use serial commands to enable the pairing function.

Step 3 indicates the pairing between the first accessory and the smart lock. When pairing is started, the mobile phone sends data to the accessory by using DP 70. The following fields are included in the command:

  • Central ID: 0xFFFF, the ID of the mobile phone
  • Peripheral ID: The smart lock ID that is assigned by the Tuya Developer Platform
  • Random number: The central random number that is assigned by the Tuya Developer Platform to the mobile phone, already sent to the smart lock in Step 1
  • Operation: Add
  • Central ID to be configured: the accessory ID that is assigned by the Tuya Developer Platform
  • Central random number to be configured: the accessory random number that is assigned by the Tuya Developer Platform

Step 4 is the same as Step 2.

Step 5 is the same as Step 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 one or more accessories
  • The peripheral ID of the smart lock

An accessory stores the following information:

  • The central ID and central random number of the accessory

  • One or more smart lock peripheral IDs.


Important:

If either of Steps 2 and 3 is successful, the pairing operation between the first accessory and the smart lock is regarded as successful.

If Step 2 is successful but Step 3 failed, open the smart lock panel and perform Step 3 to synchronize data. Then, the accessory is paired with the smart lock.

If Step 2 failed but Step 3 is successful, open the accessory panel and perform Step 2 to synchronize data. Then, the accessory is paired with the smart lock.

These rules apply to Steps 4 and 5.

Appendix

Byte(s) Meaning Description Example
1 Start time Unsigned integer
Data is four bytes long, stored in big-endian format.
Example:
123-456-789 (Unix timestamp) = 0x‭075BCD15 (hex)‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬
If the validity is permanent, the start time is `0x386CD300`.
07
2 5B
3 CD
4 15
5 End time Unsigned integer
Data is four bytes long, stored in big-endian format.
Example:
999-999-999 (Unix timestamp) = 0x‭3B9AC9FF (hex)‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬
If the validity is permanent, the end time is `0x72BC9B7F`.
3B
6 9A
7 C9
8 FF
9 The recurring patterns: 0x00: One-time 0x01: Daily schedule 0x02: Weekly schedule 0x03: Monthly schedule
10 Recurring flag 1 For a one-time schedule,
bytes 10 to 17 are 0.
This field
defaults to `0x00`.
This field
defaults to `0x00`.
Bit 7: Default to 0
Bit 6: The 31st of a month

Bit 0: The 25th of a month
11 Recurring flag 2 This field
defaults to `0x00`.
This field
defaults to `0x00`.
Bit 7: The 24th of a month

Bit 0: The 17th of a month
12 Recurring flag 3 This field
defaults to `0x00`.
This field
defaults to `0x00`.
Bit 7: The 16th of a month

Bit 0: The 9th of a month
13 Recurring flag 4 This field
defaults to `0x00`.
Bit 7: Default to 0
Bit 6: Saturday

Bit 1: Monday
Bit 0: Sunday
Bit 7: The 8th of a month

Bit 0: The 1st of a month
14 The start time 1 (hour) in a day Start time: 08:30 08 (decimal)
15 The start time 2 (minute) in a day 30 (decimal)
16 The end time 1 (hour) in a day End time: 20:30 20 (decimal)
17 The end time 2 (minute) in a day 30 (decimal)

Important:
When users add or modify unlocking methods, the recurring validity period and the access times are both applied. There are two use cases:

  • When the access times are 0x00, this indicates permanent access. You only need to process the recurring pattern of the validity.
  • When the recurring pattern is 0x00, this indicates one-time access. You only need to process the access times.

For example, schedule a password to be valid every Monday to Friday from 08:00 to 08:30 from 2018-01-26 08:00:00 to 2018-08-08 09:56:32.

  • 2018-01-26 08:00:00 = 1516924800 (Unix timestamp) = 0x‭5A6A6F80‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬ (hex)
  • 2018-08-08 09:56:32 = 1533693392 (Unix timestamp) = 0x5B6A4DD0 (hex)
  • The recurring pattern: 0x02 indicates a weekly schedule.
  • Recurring flag 1 = Recurring flag 2 = Recurring flag 3 = 0x00
  • Recurring flag 4 = 0x3E (from Monday to Friday)
  • The start time 1 is 0x08. The start time 2 is 0x00.
  • The end time 1 is 0x08. The end time 2 is 0x1E.

Based on these rules, the validity is set to 0x ‭5A6A6F80 5B6A4DD0 02 0000003E 0800 081E‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬.