Data Point Reference

Last Updated on : 2024-06-13 07:51:53download

This topic describes the features, formats, and usages of data points (DPs) that apply to Bluetooth smart locks.

Background

Terms

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

Terms Explanation
Data point (DP) A DP is an abstract representation of a feature you want to apply to a physical device, which can be defined by various data types.
Product ID (PID) A 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 20-character universally unique identifier of a device, also known as a license.
Authkey A 32-character authkey used to register a device with cloud services. One UUID corresponds to one AuthKey uniquely.
Firmware key The unique identity of firmware assigned by the Tuya Developer Platform.
Member Also known as 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 and password) is valid during the specified time period.
Smart sticker lock A gadget that can be attached to a traditional door lock to make it smart.
Cloud-to-device messaging Data is sent from a mobile phone or gateway to a Bluetooth device.
Device-to-cloud messaging Data is sent from a Bluetooth device to a mobile phone or gateway.

Role assignment

  • Central device: Refers to the Smart Life app, Bluetooth gateways, or lock accessories.

  • Peripheral device: Refers to Bluetooth locks.

    The central device can initiate a pairing request to an advertising peripheral device. After successful pairing, the peripheral device is bound to the central device.

    They communicate with each other over a secure channel in compliance with the Bluetooth standard.

Concepts in the process of establishing this secure channel.

Data Point Reference

  • Connection: Refers to the ordinary Bluetooth connection between a mobile app and a Bluetooth lock.
  • Pairing: Refers to a process when a range of keys are exchanged.
  • Bound: Refers to a kind of status. The status of a paired device is bound. Paired devices communicate with each other over a secure channel.
  • Reconnect: Refers to a process when a range of keys are exchanged, in other words, a simplified pairing process. To enter this process, the device should have been bound.
  • Remove: Refers to a process when the key is deleted and the binding status is cleared.

DP format

dp_data_len is one or two bytes, depending on the version of the Bluetooth communication protocol you use. For 3.x versions, the data length is one byte. For 4.x versions and later, the data length is two bytes. The following table details the DP format.

Field Length (byte) Description
dp_id 1 The ID of a DP.
dp_type 1 The data type of a DP.
dp_data_len 1/2 The data length of a DP.
dp_data_value dp_data_len The payload of a DP.

Manage unlocking methods

Add unlocking methods

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 1 Raw len Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Validity period
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n bytes)
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
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
Device-to-cloud 1 Raw len 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)
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0x00: Start enrollment. 0x00: Ordinary member
0x01: Admin
0x00 to 0x64 0xFF: Default value The number of times to finish enrollment
For example, six times for fingerprint enrollment.
Once for door card enrollment.
0x00: Default value
0xFC: Enrollment in progress 0x00: Ordinary member
0x01: Admin
0x00 to 0x64 0xFF: Default value The sequence number for enrollment times, starting from 1.
For example, fingerprint enrollment is generally six times.
This field is populated with the current times.
Reasons for failed enrollment:
0x00: Success.
0x01: Incomplete fingerprint.
0xFD: Enrollment failed 0x00: Ordinary member
0x01: Admin
0x00 to 0x64 0xFF: Default value 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 to 0x64 0xFF: Default value 0x00: Default value 0x00: Default value
0xFF: Enrollment is finished. 0x00: Ordinary member
0x01: Admin
0x00 to 0x64 0x00 to 0xFE 0x00: Default value 0x00: Default value

Interaction example

  • The following figure shows how the mobile app interacts with the lock during the enrollment of the password, door card, and face.

    AppLockStart EnrollmentStart EnrollmentComplete EnrollmentAppLock
  • The following figure shows how the mobile app interacts with the lock during fingerprint enrollment.

    AppLockStart EnrollmentStart Enrollment (6 times)Enrollment In Progress (Once)Enrollment In Progress (2, 3, 4, 5, 6 Times)Complete EnrollmentAppLock

Delete unlocking methods

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 2 Raw len Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Deletion method
(1 byte)
0x00: Delete a member. 0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0xFF: Default value 0x00: Delete all the unlock
methods granted to a member.
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0x00 to 0xFE 0x01: Delete a specified unlocking
method granted to a member.
Device-to-cloud 2 Raw len 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)
0x00: Delete a member. 0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0xFF: Default value 0x00: Delete all the unlock
methods granted to a member.
0x00: Deletion failed.
0xFF: Deletion succeeded.
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0x00 to 0xFE 0x01: Delete a specified unlocking
method granted to a member.
0x00: Deletion failed.
0x01: Unlocking method does not exist.
0xFF: Deletion succeeded.

Modify unlocking methods

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 3 Raw len Type
(1 byte)
Stage
(1 byte)
Admin flag
(1 byte)
Member ID
(1 byte)
Hardware ID
(1 byte)
Validity period
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n bytes)
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)
Description Description
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0x00 to 0xFE See
Appendix 1
Value range
Description Description
Device-to-cloud 3 Raw len 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)
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
0x05: Palm print
0x06: Finger vein
0x00: Default 0x00: Ordinary member
0x01: Admin
0x01 to 0x64 0x00 to 0xFE Value range 0x00: Failure
0xFF: Success

Manage temporary passwords

Add temporary passwords

The types of temporary passwords include one-time and recurring. The temporary password is different from the ordinary password in the following ways:

  • A temporary password is not associated with any members.

  • The validity period of a temporary password can be modified when the lock is connected.

  • As an unlocking method, the type of the temporary password is defined as 0xF0. 0x01 indicates password. 0x02 indicates door card. 0x03 indicates fingerprint.

Take care of the following possible issue with temporary passwords:

  • If the lock fails to sync the internal clock with the server time due to a power failure, this can cause the schedule for recurring access to not work properly.
  • Solution:
    • Add a backup battery to the lock to ensure it can still be connected to the cloud even after a power failure.
    • You can accept the problems that might arise.
Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 51 Raw len Type
(1 byte)
Validity period
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n bytes)
0x00: Type 0
0x01: Type 1
See
Appendix 1
Value range The bytes of a password
(used for unlocking with password only)
Description
Device-to-cloud 51 Raw len Hardware ID
(1 byte)
Return value
(1 byte)
0x00 to 0xFE 0x00: Success.
0x01: Failure.
0x02: Hardware ID is assigned.
0x03: Repeated password.

Delete temporary passwords

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 52 Raw len Hardware ID
(1 byte)
0x00 to 0xFE
Device-to-cloud 52 Raw len Hardware ID
(1 byte)
Return value
(1 byte)
0x00 to 0xFE 0x00: Success.
0x01: Failure.
0x02: The temporary password does not exist.
(In this case, you can also return 0x00).

Modify temporary passwords

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 53 Raw len Hardware ID
(1 byte)
Type
(1 byte)
Validity period
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n bytes)
0x00 to 0xFE 0x00: Type 0
0x01: Type 1
See
Appendix 1
Value range The bytes of a password
(used for unlocking with password only)
Description
Device-to-cloud 53 Raw len Hardware ID
(1 byte)
Return value
(1 byte)
0x00 to 0xFE 0x00: Success.
0x01: Failure.

Sync unlocking methods

Full sync (new)

  • Purpose: To ensure the unlocking methods in the local device and the server are in sync, each time users open the lock member list or pull down to refresh the list, all the added unlocking methods will be synced between them.
  • Hardware types: 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.
  • Sync locally-added unlocking methods: A lock syncs the locally-added unlocking methods with the cloud in the following cases:
    • 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 is used when the cloud sends commands of this unlocking method. Note that this case only applies to Biolock and HuiLi padlocks, and the member ID 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 is 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/2 byte(s))
dp_data_value
Cloud-to-device 54 Raw len Hardware types
(len bytes)
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
Device-to-cloud 54 Raw len Stage
(1 byte)
Packet sequence number
(1 byte)
Data for sync
(n bytes)
0x00: In-sync 0x00 to 0xFF
The packet sequence number starts
from 0, incrementally in order.
Data 1, Data 2 … Data n
Data format definition
Device-to-cloud 54 Raw len Stage
(1 byte)
Total packets
(1 byte)
0x01: Sync finished Total packets
For example, if a packet for the in-sync stage
is delivered twice, the packets are two in total.

Differential sync (deprecated)

To minimize the amount of data to transfer, you sync only the data that has changed since the last sync.

After differential sync is initiated, the mobile app sends the lock the CRC-8 values of the hardware ID, hardware type, and the properties associated with each hardware ID. The lock compares the local CRC-8 value with the received one and uploads the properties of the hardware ID that has changed since the last sync.

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data_value
Cloud-to-device 35 Raw len Number of hardware IDs
(1 byte)
Hardware 1
(3 bytes)
Hardware 2
(3 bytes)
Hardware n
(3 bytes)
Count See the description. See the description. See the description.
Device-to-cloud 35 Raw len Number of hardware IDs
(1 byte)
Hardware 1
(3 bytes)
Hardware 2
(3 bytes)
Hardware n
(3 bytes)
Count See the description. See the description. See the description.

Description:

  • Cloud-to-device: hardware n = hardware ID n + hardware type + hardware CRC-8 value
  • Device-to-cloud: hardware n = operation type + hardware ID n + hardware type + hardware property
  • Operation type: one byte. 0x00: Update the hardware property of the specified hardware ID. 0x01: Delete the specified hardware ID.
    Hardware type: one byte. 0x01: Password. 0x02: Door card. 0x03: Fingerprint. 0x04: Face.
    Hardware property: two bytes
    • Member ID: one byte. Valid values range from 0x01 to 0x64.
    • Validity status: one byte. 0x01: Valid. 0x00: Invalid.
  • CRC-8 calculation: The CRC-8 value is the lower byte of the CRC-16 value. The following code shows how to calculate in C language.

    uint16_t cpt_crc16_compute(uint8_t* buf, uint16_t size, uint16_t* p_crc)
    {
    	uint16_t poly[2] = {0, 0xa001}; //0x8005 <==> 0xa001
    	uint16_t crc = 0xffff;
    	int i, j;
    
    	for (j=size; j>0; j--)
        {
    		uint8_t ds = *buf++;
            for (i=0; i<8; i++)
            {
    			crc = (crc >> 1) ^ poly[(crc ^ ds) & 1];
    			ds = ds >> 1;
    		}
    	}
    
        return crc;
    }
    

Short-range unlocking

Unlocking

After the mobile app is connected to the Bluetooth lock, users can send an unlocking command to the lock using the panel. The lock then unlocks the door on receiving the command and reports an unlocking record through DP 19.

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 6 Raw len Feature
(1 byte)
Member ID
(1 byte)
0x00: Lock. 0x01: Unlock.
0x01 to 0x64
Device-to-cloud 6 Raw len Return value
(1 byte)
Member ID
(1 byte)
0x00: Failure
0x01: Success
0x01 to 0x64

Manual locking

Be sure to use DP 46 to manually lock the door, regardless of short-range or remote unlocking. After the app sends this command to the lock, the door is locked immediately.

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 46 Boolean len Fixed value (1 byte)
0x01: Lock
Device-to-cloud 46 Boolean len Return value
(1 byte)
0x00: Failure
0x01: Success

Manage remote unlocking

Configure keys

  • Important: If your product enables support for accessories, this DP will be replaced with DP 73. For more information, see Lock Accessories.

  • A key is required to use remote unlocking. The cloud sends the key to the lock after successful pairing.

  • The key for remote unlocking (DP 61) is configured through the command of setting keys for remote unlocking.

  • In this command, validity, member ID, start time, end time, and access times are reserved fields.

    To enhance security, the key for remote unlocking is updated occasionally. The cloud determines the update rule. After a key is used for n times, the cloud sends a new key to the lock through the DP of configuring keys.

Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 60 Raw len Validity
(1 byte)
Member ID
(2 bytes)
Start time
(4 bytes)
End time
(4 bytes)
Access times
(2 bytes)
Key
(8 bytes)
0x00: Invalid
0x01: Valid
0x01 to 0x64 Unix timestamp Unix timestamp 0x0000 to 0xFFFF
Defaults to 0, meaning the
key is valid permanently.
ASCII code
Device-to-cloud 60 Raw len Return value
(1 byte)
Member ID
(2 bytes)
0x00: Success.
0x01: Failure.
0x01 to 0x64

Remote unlocking

Remote unlocking indicates the door is unlocked through a gateway.

  • If the command is initiated by a mobile app, this is called remote unlocking by app with DP 61.
  • If the command is initiated by a smart speaker, this is called remote unlocking by voice with DP 61.
  • If the command is initiated by a mobile app over Bluetooth, this is called short-range unlocking with DP 6.
  • Both remote unlocking and short-range unlocking end up with the same action but with different data links.
  • In this DP protocol, the locking field is reserved and not used. Be sure to use DP 46 to manually lock the door, regardless of short-range or remote unlocking.
Data
transmission
dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 61 Raw len Feature
(1 byte)
Member ID
(2 bytes)
Key
(8 bytes)
Unlocking methods
(2 bytes)
0x00: Lock.
0x01: Unlock.
0x01 to 0x64 ASCII code 0x0000: Remote unlocking by unknown methods.
0x0001: Remote unlocking by app.
0x0002: Remote unlocking by voice.
Device-to-cloud 61 Raw len Return value
(1 byte)
Member ID
(2 bytes)
0x00: Success.
0x01: Failure.
0x02: The key is invalid.
0x03: The access times run out.
0x04: The current time is not in the validity period.
0x05: Key comparison does not pass.
0x01 to 0x64

Lock settings


Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Doorbell ringtones Cloud-to-device/device-to-cloud 26 enum len Ringtones (1 byte)
0x00: Ringtone 0

0x0A: Ringtone 10
Volume Cloud-to-device/device-to-cloud 31 enum len Volume (1 byte)
Doorbell volume (DP 27) and key volume (DP 30)
are replaced with this DP.
Value range
System language
(for display and play)
Cloud-to-device/device-to-cloud 28 enum len Languages (1 byte)
Value range
Display welcome message Cloud-to-device/device-to-cloud 29 String len Welcome message (len bytes)
0 to 50 bytes
Auto-locking Cloud-to-device/device-to-cloud 33 Boolean len On/off (1 byte)
0x00: Turn off.
0x01: Turn on.
Auto-locking timer Cloud-to-device/device-to-cloud 36 Value len The delay time in seconds (4 bytes)
0x00000001 to 0xFFFFFFFF
Unlock with a single
or combined methods
Cloud-to-device/device-to-cloud 34 enum len Possible unlocking
methods (1 byte)
Value range
Motor rotation Cloud-to-device/device-to-cloud 48 enum len Rotation direction (1 byte)
0x00: Clockwise.
0x01: Counterclockwise.
Motor torque Cloud-to-device/device-to-cloud 56 enum len Motor torque (1 byte)
0x00: Low.
0x01: Medium.
0x02: High.
Arm away Cloud-to-device/device-to-cloud 58 Boolean len On/off (1 byte)
0x00: Turn off.
0x01: Turn on.
Turn on/off locking check Cloud-to-device/device-to-cloud 75 Boolean len On/off (1 byte)
0x00: Turn off.
0x01: Turn on.
Do not disturb (DND) Cloud-to-device/device-to-cloud 76 Boolean len On/off (1 byte)
0x00: Turn off.
0x01: Turn on.
DND period Cloud-to-device/device-to-cloud 77 Raw len Time period (4 bytes)
HH:MM-HH:MM
Repeated daily

Report real-time status

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Battery level Device-to-cloud 8 Value len Battery level (4 bytes)
0x00 to 0x64
Battery level or remaining battery Device-to-cloud 9 enum len Battery level (1 byte)
0x00: High.
0x01: Medium.
0x02: Low.
0x03: Exhausted.
Child lock Device-to-cloud 10 Boolean len Status (1 byte)
0x00: Child lock is off.
0x01: Child lock is on.
Lift-up double locking Device-to-cloud 11 Boolean len Status (1 byte)
0x00: Not double locked by lifting up the handle
0x01: Double locked by lifting up the handle
Double locking state Cloud-to-device/device-to-cloud 32 Boolean len Status (1 byte)
0x00: Not double locked
0x01: Double locked
Doorbell notification Device-to-cloud 24 Boolean len Fixed value (1 byte)
0x00
Door open/closed state Device-to-cloud 40 enum len Status (1 byte)
0x00: Unknown
0x01: Door is open.
0x02: Door is closed.
Locking/unlocking state Device-to-cloud 47 Boolean len Status (1 byte)
0x00: Locked
0x01: Unlocked

Report records

Alert and unlocking records

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Fingerprint unlocking records Device-to-cloud 12 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Password unlocking records Device-to-cloud 13 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Door card unlocking records Device-to-cloud 15 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Mechanical key unlocking records Device-to-cloud 16 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Face unlocking records Device-to-cloud 39 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Iris unlocking records Device-to-cloud 41 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Palm print unlocking records Device-to-cloud 42 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Finger vein unlocking records Device-to-cloud 43 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Temporary password unlocking records Device-to-cloud 55 Value len Hardware ID (4 bytes)
0x00 to 0xFE
Combined unlocking records
(Deprecated, use DP 74 instead)
Device-to-cloud 57 enum len Possible unlocking
methods (1 byte)
Value range
Short-range unlocking records Device-to-cloud 19 Value len Member ID (4 bytes)
0x00 to 0x64
Remote unlocking by mobile app Device-to-cloud 62 Value len Member ID (4 bytes)
0x00 to 0x64
Remote unlocking by voice Device-to-cloud 63 Value len Member ID (4 bytes)
0x00 to 0x64
Unlocking from inside records Device-to-cloud 18 Boolean len Fixed value (1 byte)
0x00
Alert records Device-to-cloud 21 enum len Reasons for alerts (1 byte)
Value range

Locking records

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Device-to-cloud 20 Raw 0x05 Locking methods
(1 byte)
Member ID (4 bytes)
0x00: Locking by undefined methods
0x01: Remote locking by app
0x02: Remote locking by voice
0x03: Geofencing-based locking
0x04: Locking by app
0x05: Locking by using accessory
0x06: Auto-locking
0x07: Manual locking
0x01 to 0x64

Combined unlocking records (new)

Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Device-to-cloud 74 Raw len 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)
0x00: Single locking method.
0x01: Combined unlocking method.
0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0xF0: Temporary password
0x01 to 0xFE 0x01: Password
0x02: Door card
0x03: Fingerprint
0x04: Face
0x05: Palm print
0x06: Finger vein
0xF0: Temporary password
0x01 to 0xFE

Custom functions

Three DPs are available to be customized to your needs.

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
User guide Cloud-to-device 59 Raw len Feature
(1 byte)
0x00: Feature 0
0x01: Feature 1
Device-to-cloud 59 Raw len Feature
(1 byte)
Return value
(1 byte)
0x00: Feature 0
0x01: Feature 1
0x00: Success.
0x01: Failure.

Special features Cloud-to-device/device-to-cloud 68 enum len Feature (1 byte)
0x00: Feature 0
0x01: Feature 1
Special control Cloud-to-device/device-to-cloud 78 Boolean len On/off (1 byte)
0x00: Turn off.
0x01: Turn on.

Algorithm-generated passwords

This section describes the offline passwords and dynamic passwords that are generated based on algorithms. How it works: The cloud and the lock run the same algorithm to generate passwords and verify passwords. When users enter the generated password, the lock unlocks the door if the password is verified successfully.

Dynamic password

The local lock and the cloud have an identical set of algorithms stored to generate dynamic passwords, with the only difference in the Unix timestamp. If the Unix timestamp offset between the local clock and the cloud is less than 300 seconds (± 5 minutes), it is considered that the dynamic password generated by the lock and the cloud is identical, and the lock executes the unlocking command.

Offline password

  • Scenarios:

    The door lock user gets an offline password from the app and notifies the visitor of this password. The offline password can be the following types:

    • One-time password: It is valid for six hours and can be used only once. If the password is used within the validity period, an unlocking record is created.
    • Timed password: It must be used once within 24 hours for activation. Otherwise, it will expire. It can be used unlimited times within the specified validity period. Every unlocking operation is recorded.
  • The code to clear a single password: It has the same validity period as the corresponding password and takes effect only on the first-time usage. A record of clearing a single password is created after the code is used.

    • The code to clear all passwords: It is a one-time clear code and valid for 24 hours. A record of clearing all passwords is created after the code is used.
  • Limitations on clearing a single password or all passwords:

    • Only the activated and valid password can be cleared.
    • The one-time password cannot be cleared because it is invalid after use.
  • Usage: For more information, see Serial Communication Protocol. If you develop with the SDK, see the corresponding API reference.

Related protocols

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Offline password
Set T0 time
Cloud-to-device/device-to-cloud 64 String len T0 timestamp (10 bytes)
Unix timestamp
Offline password
unlocking records
Device-to-cloud 67 Raw len Encryption result (16 bytes)
See the description.
Offline password
Clear a single record
Device-to-cloud 65 Raw len Encryption result (16 bytes)
See the description.
Offline password
Clear all records
Device-to-cloud 66 Raw len Encryption result (16 bytes)
See the description.
Dynamic password
unlocking records
Device-to-cloud 14 Value len Hardware ID (4 bytes)
0xFF: Default value

Lock accessories

The standard Bluetooth lock solution requires you to implement the new DPs. This is because when the lock connects to an accessory, such as a Bluetooth key or keypad, the mobile app functions as a special type of accessory.

New DPs

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Get records None 69 Raw len See sections below.
Pair central device with peripheral device None 70 Raw len
Unlock and lock None 71 Raw len
Locking/unlocking records None 72 Raw len
Configure keys for remote unlocking None 73 Raw len

Get records

Background: A lock automatically reports any cached records when connected. With the accessory capability enabled, the lock cannot identify whether it is being connected to a mobile app, a gateway, or an accessory. Theoretically, the lock should not report cached records to an accessory, because the accessory is not connected to the cloud. Therefore, this command is used to notify the lock to report cached records.

  • Once a lock is connected, if there are cached records to report, it will notify the other party through DP 69.
  • If the lock is connected to a mobile app or a Bluetooth gateway, when the control panel is opened, a response to DP 69 will be sent to the lock. If connected to an accessory, the lock will not receive a response.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Device-to-cloud 69 Raw len Peripheral device ID
(2 bytes)
Action
(1 byte)
0 to 10,000 0x01: Request to report records
Cloud-to-device 69 Raw len Central device ID
(2 bytes)
Peripheral device ID
(2 bytes)
Random number
(8 bytes)
Fixed value
(1 byte)
0 to 10,000 0 to 10,000 Random number for central device 0x00

Pair central device with peripheral device

Pair an accessory (central device) with a lock (peripheral device). Through DP 70, the mobile app notifies the lock of the information about the central device to be paired, including its central ID and random number.

  • Central ID: 0xFFFF represents the mobile phone that initiates pairing and unpairing commands.
  • Peripheral ID: An identity assigned to the lock.
  • Random number: Initially set to all 0 and then a random number assigned to the mobile app.
  • Action: 0x00: Add an accessory. 0x01: Remove an accessory.
  • Central ID to pair: An identity assigned to the mobile phone or accessory. The central device to pair is the mobile phone initially and then the accessory.
  • Random number for central device to pair: An identity assigned to the mobile phone or accessory. The central device to pair is the mobile phone initially and then the accessory.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 70 Raw len Central ID
(2 bytes)
Peripheral ID
(2 bytes)
Random number
(8 bytes)
Action
(1 byte)
Central ID to pair
(2 bytes)
Random number for central device to pair
(8 bytes)
0 to 10,000 0 to 10,000 Random number for central device 0x00: Add
0x01: Remove
0 to 10,000 Description
Device-to-cloud 70 Raw len Peripheral ID
(2 bytes)
Central ID
(2 bytes)
Random number
(8 bytes)
Action
(1 byte)
Central ID to pair
(2 bytes)
Return value
(1 byte)
0 to 10,000 0 to 10,000 Random number for central device 0x00: Add
0x01: Remove
0 to 10,000 Value range

Unlock and lock

  • If you choose this DP, do not use DP 6 as this may compromise the device’s safety.
  • Use this command to unlock or lock the door, whether through a mobile phone or an accessory.
  • Before unlocking or locking, the lock must verify the legitimacy of the central ID, peripheral ID, and random number to ensure security.
  • The accessory sends the timestamp, method, and information for locking/unlocking to the lock. The lock simply needs to report the received data as is through DP 72.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 71 Raw len Central ID
(2 bytes)
Peripheral ID
(2 bytes)
Random number
(8 bytes)
Action
(1 byte)
Locking/
unlocking timestamp
(4 bytes)
Locking/
unlocking method
(1 byte)
Locking/unlocking
information
(len minus 18 bytes)
0 to 10,000 0 to 10,000 Random number for central device 0x00: Lock.
0x01: Unlock.
Description Description Description
Device-to-cloud 71 Raw len Peripheral ID
(2 bytes)
Central ID
(2 bytes)
Random number
(8 bytes)
Action
(1 byte)
Locking/
unlocking timestamp
(4 bytes)
Locking/
unlocking method
(1 byte)
Return value
(1 byte)
0 to 10,000 0 to 10,000 Random number for central device 0x00: Lock.
0x01: Unlock.
Description Description Value range

Locking/unlocking records

  • The lock reports the locking/unlocking records to the mobile app.
  • When the accessory unlocks or locks the door, it sends the timestamp, method, and information to the lock accordingly through DP 71. The lock then reports the received data as the record type in DP 72 format.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Device-to-cloud 72 Raw len Peripheral ID
(2 bytes)
Central ID
(2 bytes)
Random number
(8 bytes)
Action
(1 byte)
Locking/
unlocking timestamp
(4 bytes)
Locking/
unlocking method
(1 byte)
Locking/unlocking
information
(len minus 18 bytes)
0 to 10,000 0 to 10,000 Random number for central device 0x00: Lock.
0x01: Unlock.
Description Description Description

Configure keys for remote unlocking

  • If you choose this DP, do not use the DP with dp_id = 60 as this may compromise the device’s safety.
  • A key is required to use remote unlocking. The cloud sends the key to the lock after successful pairing.
  • The key for remote unlocking (DP 61) is configured through the command of setting keys for remote unlocking.
  • In this command, validity, member ID, start time, end time, and access times are reserved fields.
Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Cloud-to-device 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
(8 bytes)
0 to 10,000 0 to 10,000 Random number for central device
0x00: Invalid
0x01: Valid
0x01 to 0x64 Unix timestamp
(See Appendix 1)
Unix timestamp
(See Appendix 1)
0x0000 to
0xFFFF
ASCII code
Device-to-cloud 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 10,000 0 to 10,000 Random number for central device
0x00: Invalid
0x01: Valid
0x01 to 0x64 Value range

Auto-unlock via Bluetooth

Prerequisites: The mobile phone must support geofencing. Android devices should be integrated with Google Mobile Services (GMS) or Huawei Mobile Services (HMS).

Bluetooth lock: It regularly sends advertising packets.

Mobile app: With geofencing enabled, when users enter the geofence, the mobile app is invoked. When the distance between users and the lock falls within the specified range, the app receives the advertising packet, gets connected to the lock, and then sends the unlocking command to the lock. After the door is unlocked, the mobile app closes the connection to the lock.

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Auto-unlock records Device-to-cloud 86 Value len Member ID (4 bytes)
0x00 to 0x64
Scan timeout None 87 enum len This feature is for the mobile app,
without the lock taking care of it.
RSSI level None 88 enum len This feature is for the mobile app,
without the lock taking care of it.
Auto-lock time delay Cloud-to-device/device-to-cloud 89 enum len Time delay enum (1 byte)
0x00: Not enable auto-lock time delay.
Use the original auto-lock logic.
0x01: 4 seconds.
0x02: 6 seconds.
0x03: 8 seconds.
0x04: 10 seconds.
0x05: 12 seconds.
0x06: 15 seconds.
0x07: 20 seconds.
0x08: 30 seconds.
0x09: 60 seconds.
Enable auto-unlock Cloud-to-device/device-to-cloud 90 Boolean len State (1 byte)
0x00: Turn off.
0x01: Turn on.

Disable/enable lock members

  • Disable or enable a lock member, including users with which the lock is shared.

  • The home owner and administrator can disable or enable a lock member.

  • To ensure data is consistent between the lock device and the cloud, disabling or enabling a lock member can be performed only when the lock is connected.

  • Once a lock member is disabled, all the unlocking methods associated with this member become invalid unless this member is enabled again.

  • Once a lock member is disabled, actions on the associated unlocking methods (such as add or delete) are not allowed unless this member is enabled again.

  • Once a lock member is disabled, the only action that can be performed by the home owner and administrator on this member is enable.

    The generic solution does not support disabling or enabling a lock member and specific features.

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
Disable a lock member Cloud-to-device/device-to-cloud 49 Value len Member ID
(4 bytes)
0x01 to 0x64
Enable a lock member Cloud-to-device/device-to-cloud 50 Value len Member ID (4 bytes)
0x01 to 0x64

Cloud-based DPs

Feature Data transmission dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1/2 byte(s))
dp_data_value
SMS motification None 25 Boolean len None
Duress alarm None 22 Boolean len None
Hardware RTC None 44 Boolean len None

Appendix 1: Validity period

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,
10 to 17 bytes 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)

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. The validity is 0x ‭5A6A6F80 5B6A4DD0 02 0000003E 0800 081E‬‬‬‬‬‬.

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