English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Access Control DP Reference

Last Updated on : 2022-06-17 09:32:58download

This topic describes the function definitions based on data points (DPs), frame format, and usage notes in the application of the Tuya Smart Wi-Fi access control locks. This topic applies to all-in-one Wi-Fi access control lock projects.

Background information

Terms

The following table lists specific terms and definitions that are used in 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) describes a collection of product functions or DPs that belong to the same type.
Every product that is created on the Tuya IoT Platform is assigned a unique PID.
The PID is associated with all information about this product, including specific DPs, app control panel, and delivery data.
UUID A universally unique identifier (UUID) is the SDK license and unique ID when you develop a smart product on the Tuya IoT Platform. A UUID is a 20-digit number.
AuthKey The authorization key that is used to register the device to the cloud. Each authorization key corresponds to a UUID and is a 32-digit number.
Firmware key The unique identifier of the firmware on the Tuya IoT Platform.
Member A member is also called a user.
Member ID A 2-byte unsigned integer. It is used as a member number that is also known as the user number. Each member ID is assigned by the server and does not need to be maintained on a local device. Valid values: 0x0001 to 0xFFFE. Other numbers are the reserved values.
Hardware ID A 2-byte unsigned integer. It is used as a hardware number for an unlocking method.
Each hardware ID is assigned and maintained on a local device. Each unlocking method corresponds to a hardware ID.
For example, the hardware ID 0x0001 indicates unlocking with a fingerprint, and the hardware ID 0x0002 indicates unlocking with a password. Valid values: 0x0000 to 0xFFFE. The value 0xFFFF is a reserved value.
Validity A specific unlocking method such as unlocking with a fingerprint or a password is valid within a specified period.
Smart stick lock A device that upgrades traditional locks to smart locks. For more information, see related documents.
Send The operation in which data is transmitted in a specific direction from a mobile phone to a Wi-Fi device.
Report The operation in which data is transmitted in a specific direction from a Wi-Fi device to a mobile phone.

DP format

When you use Tuya Bluetooth modules for development, the length of dp_data_len is 2 bytes. When you use Tuya Wi-Fi modules for development, the length of dp_data_len is 1 byte. The following table describes different DP formats.

Field Length (number of bytes) Description
dp_id 1 A DP ID
dp_type 1 DP data type
dp_data_len 1 DP data length
dp_data_value dp_data_len DP data content

Interaction examples

  • The following figure shows the interaction process when unlocking with passwords, cards, or faces is enabled.

    Access Control DP Reference

  • The following figure shows the interaction process when unlocking with fingerprints is enabled.

Access Control DP Reference

Unlocking methods

Unlocking methods depend on user information, such as fingerprints, unlocking passwords, dynamic passwords, and face ID.

Add an unlocking method

Send

  • Data direction: send
  • dp_id (1 byte): 1
  • dp_type (1 byte): raw
  • dp_data_len (1 byte): len
  • dp_value: see the following table
Type
(1 byte)
Phase
(1 byte)
Administrator tag
(1 byte)
Member ID
(2 bytes)
Hardware ID
(2 bytes)
Validity
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n byte)
Message UUID
(2 bytes)
0x01: password
0x02: card
0x03: fingerprint
0x04: face
0x07: remote control
0x00: start enrollment
0xFE: cancel enrollment
0x00: common member
0x01: administrator
0x0001–0xFFFE 0xFFFF: default value See Appendix 1 0x00: permanently valid
0x01: valid only once
0xyy: valid for yy times
0xFF: invalid
Number of password bytes: n
(only used for password type)
The password is sent in the numerical format.
For example, [0x01,0x02,0x03,0x04,0x05,0x06] represents the password: 123456.
The unique sequence number of the message. The value is associated with a message report and applies to all scenarios when DPs are sent from the cloud.

Report

  • Data direction: report

  • dp_id(1byte): 1

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Type
    (1 byte)
    Phase
    (1 byte)
    Administrator tag
    (1 byte)
    Member ID
    (2 bytes)
    Hardware ID
    (2 bytes)
    Number of times
    (1 byte)
    Return status
    (1 byte)
    Message UUID (2 bytes)
    0x01: password

    0x02: card

    0x03: fingerprint

    0x04: face

    0x07: remote control
    0x00: start enrollment 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE The total number of required enrollments. For example, a fingerprint might need to be enrolled eight times, and once for card enrollment. 0x00: default value Same as the process when data is sent
    0xFC: enrolling 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE The current number of enrollments. For example, a fingerprint might be enrolled eight times. Enter the sequence number (starting from `1`) for each enrollment. Reasons for an enrollment exception:
    0x00: no exception
    0x01: incomplete fingerprint or wet fingerprint
    0xFD: enrollment failed 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE Current enrollment phase:
    0x00: start enrollment
    0xFC: enrolling
    0xFF: enrollment completed
    Reasons for an enrollment failure:
    0x00: enrollment timeout
    0x01: enrollment failed
    0x02: repeated enrollment
    0x03: no available hardware ID
    0x04: password input error, invalid non-numeric value (reserved)
    0x05: password length error
    0x06: invalid unlocking method
    0x07: enrolling a fingerprint
    0x08: binding a card
    0x09: binding a face
    0x0A: too simple password
    0xFE: invalid hardware ID
    0xFE: cancel enrollment
    (initiated by the app)
    0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE 0x00: default value 0x00: default value
    0xFF: enrollment completed 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE 0x00: default value 0x00: default value

Delete unlocking methods

Send

  • Data direction: send

  • dp_id(1byte): 2

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Type
    (1 byte)
    Phase
    (1 byte)
    Administrator tag
    (1 byte)
    Member ID
    (2 bytes)
    Hardware ID
    (2 bytes)
    Deletion mode
    (1 byte)
    0x00: delete a member 0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0xFFFF: default value 0x00: delete all unlocking methods of a member
    0x01: password
    0x02: card
    0x03: fingerprint
    0x04: face
    0x07: remote control
    0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE 0x01: delete one of the unlocking methods of the member

Report

  • Data direction: report

  • dp_id (1 byte): 2

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Type
    (1 byte)
    Phase
    (1 byte)
    Administrator tag
    (1 byte)
    Member ID
    (2 bytes)
    Hardware ID
    (2 bytes)
    Deletion mode
    (1 byte)
    Return status
    (1 byte)
    0x00: delete a member 0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0xFFFF: default value 0x00: delete all unlocking methods of a member 0x00: failed to delete
    0xFF: deleted successfully

    0x01: the hardware ID does not exist
    0x02: the ID cannot be deleted by an administrator
    0x01: password
    0x02: card
    0x03: fingerprint
    0x04: face
    0x07: remote control
    0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE 0x01: delete one of the unlocking methods of the member 0x00: failed to delete
    0xFF: deleted successfully

    0x01: the hardware ID does not exist
    0x02: the ID cannot be deleted by an administrator

Modify an unlocking method

Send

  • Data direction: send
  • dp_id (1 byte): 3
  • dp_type (1 byte): raw
  • dp_data_len (1 byte): len
  • dp_value: see the following table
Type
(1 byte)
Phase
(1 byte)
Administrator tag
(1 byte)
Member ID
(2 bytes)
Hardware ID
(2 bytes)
Validity
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n byte)
0x00: only modify the validity period of a member 0x00: default 0x00: common member
0x01: administrator
0x0001–0xFFFE 0xFFFF: default value See Appendix 1 0x00: default
(cannot be modified)
Number of password bytes: n
(only used for password type)
The password is sent in the numerical format.
For example, [0x01,0x02,0x03,0x04,0x05,0x06] represents the password: 123456.
0xF1: only modify the role of a member 0x00: default 0x00: common member
0x01: administrator
0x0001–0xFFFE 0xFFFF: default value No subsequent fields
0x01: password
0x02: card
0x03: fingerprint
0x04: face
0x07: remote control
0x00: default 0x00: common member
0x01: administrator
0x0001–0xFFFE 0x0000–0xFFFE See Appendix 1 0x00: permanently valid
0x01: valid only once
0xyy: valid for yy times
0xFF: invalid
Number of password bytes: n
(only used for password type)
The password is sent in the numerical format.
For example, [0x01,0x02,0x03,0x04,0x05,0x06] represents the password: 123456.

Report

  • Data direction: report

  • dp_id (1 byte): 3

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Type
    (1 byte)
    Phase
    (1 byte)
    Administrator tag
    (1 byte)
    Member ID
    (2 bytes)
    Hardware ID
    (2 bytes)
    Number of times
    (1 byte)
    Return status
    (1 byte)
    0x00: only modify the validity period of a member 0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0xFFFF: default value 0x00: default 0x00: failed to modify
    0xFF: modified successfully
    0xF1: only modify the role of a member 0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0xFFFF: default value 0x00: default 0x00: failed to modify
    0xFF: modified successfully
    0x01: password
    0x02: card
    0x03: fingerprint
    0x04: face
    0x07: remote control
    0x00: default 0x00: common member
    0x01: administrator
    0x0001–0xFFFE 0x0000–0xFFFE 0x00: permanently valid
    0x01: valid only once
    0xyy: valid for yy times
    0xFF: invalid
    0x00: failed to modify
    0xFF: modified successfully

Synchronize unlocking methods

Each time users open the hardware list or pull down to refresh the hardware list on the app, all unlocking methods are synchronized between the app and the lock. This ensures consistent unlocking methods between the app and the lock.

  • The required hardware types are enumerated and sent to the smart lock to indicate the hardware types to be synchronized. The smart lock does not need to report the hardware types that are not enumerated.
  • The data length of each packet in the synchronizing state can be customized. The total length of each packet cannot be more than 200 bytes.

The following fields are used:

  • Phase: the progress of the current synchronization. 0x00: synchronizing. 0x01: synchronization ended.
  • Packet sequence number: the sequence number of each packet to be synchronized, starting from 0 and sequentially increased.
  • Total number of packets: the total number of packets that are sent in synchronization. For example, if a packet is sent in each of two synchronization phases, the total number of packets is 2.

The fields to be synchronized include the hardware ID, hardware type, and hardware property. These fields are configured based on the following rules:

  • Hardware ID: 2 bytes. Value range: 0x0000–0xFFFE

  • Hardware property: 1 byte

    • 0x01: password
    • 0x02: card
    • 0x03: fingerprint
    • 0x04: face
    • 0x07: remote control
    • 0xF0: temporary password
  • Hardware property: 3 bytes, including the member ID and frozen status:

    • Member ID: 2 bytes. Value range: 0x0001–0xFFFE.
    • Frozen status: 1 byte. 0x01—unfrozen, 0x00—frozen.

The unlocking methods that are added to the smart lock are synchronously reported to the cloud. The unlocking methods can be synchronized in the following scenarios:

  • The user ID 0xFF is reported. The cloud associates the unlocking methods that are added to the smart lock with the app account that is paired with the smart lock. The cloud also stores the user ID. Then, when the cloud sends these unlocking methods, the user ID 0xFF is included in the commands. This scenario only applies to smart padlocks provided by BioLock and Hui-Li. The unlocking methods cannot be deleted from the cloud.
  • The user ID 0xFD is reported. The cloud associates the unlocking methods that are added to the smart lock with the app account that is paired with the smart lock. The cloud also stores the user ID. Then, when the cloud sends these unlocking methods, the user ID 0xFD is included in the commands. This scenario applies to all types of smart locks.
Data direction dp_id (1 byte) dp_type (1 byte) dp_data_len (1 byte) dp_value
Send 4 raw len Hardware type enumeration
(len)
0x00:
0x01: password
0x02: card
0x03: fingerprint
0x04: face
0x07: remote control
0xF0: temporary password
Report 4 raw len Phase
(1 byte)
Packet S.N.
(1 byte)
Data to be synchronized
(n bytes)
0x00: synchronizing 0x00–0xFF G1, G2, ..., Gn
Report 4 raw len Phase
(1 byte)
Total number of packets
(1 byte)
0x01: end of synchronization Total number of packets

Temporary passwords

Temporary passwords include one-time passwords and periodic passwords. A temporary password and a normal password have the following differences:

  • A temporary password does not belong to any member.

  • The validity period of a temporary password can be separately changed during a connection.

  • A temporary password is defined as 0xF0 for an unlocking method. 0x01 indicates unlocking with a password, 0x02 indicates unlocking with a card, and 0x03 indicates unlocking with a fingerprint.

  • Disadvantages:

    After the network is disconnected, if the device is powered off, the local clock cannot work as expected. If the network cannot be reconnected and the clock cannot be synchronized in time, the periodic password cannot be periodically repeated as expected on the local device.

    Solution:

    • Add a backup battery to the local device to ensure a normal local clock in case of power failure.
    • Accept the problems that might occur in the preceding conditions.

Add a temporary password

  • Password types:

    • Type 0: The number of times is valid within the range of the start time and end time, and the cycle mode is invalid. The default cycle mode is 0x00.
    • Type 1: The number of times is invalid within the range of the start time and end time, and the cycle mode is valid. The default number of times is 0x00.
  • Features:

    • A temporary password does not belong to any member.
    • The validity period of a temporary password can be separately changed during a connection.
    • A temporary password is defined as 0xF0 for an unlocking method. 0x01 indicates unlocking with a password, 0x02 indicates unlocking with a card, and 0x03 indicates unlocking with a fingerprint.

Send

  • Data direction: send
  • dp_id (1byte): 5
  • dp_type (1 byte): raw
  • dp_data_len (1 byte): len
  • dp_value: see the following table
Type
(1 byte)
Validity
(17 bytes)
Number of times
(1 byte)
Password length
(1 byte)
Password content
(n byte)
Message UUID
(2 bytes)
0x00: type 0
00x01: type 1
See Appendix 1 0x00: permanently valid
0x01: valid only once
0xyy: valid for yy times
0xFF: invalid
Number of password bytes: n
(only used for password type)
The password is sent in the numerical format.
For example, [0x01,0x02,0x03,0x04,0x05,0x06] represents the password: 123456.
The unique sequence number of the message. The value is associated with a message report and applies to all scenarios when DPs are sent from the cloud.

Report

  • Data direction: report

  • dp_id (1 byte): 5

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Hardware ID
    (2 bytes)
    Return Status Message UUID
    (2 bytes)
    0x0000–0xFFFE 0x00: added successfully
    0x01: failed to add
    0x02: no available hardware ID
    0x03: repeated enrollment
    0x0A: too simple password
    Same as the process when data is sent

Delete a temporary password

Data direction dp_id (1 byte) dp_type (1 byte) dp_data_len (1 byte) dp_data
Send 6 raw len Hardware ID
(2 bytes)
0x0000–0xFFFE
Report 6 raw len Hardware ID
(2 bytes)
Return status
(1 byte)
0x0000–0xFFFE 0x00: deleted successfully
0x01: failed to delete

Modify a temporary password

Send

  • Data direction: send

  • dp_id (1 byte): 7

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Hardware ID
    (2 bytes)
    Type
    (1 byte)
    Validity
    (17 bytes)
    Number of times
    (1 byte)
    Password length
    (1 byte)
    Password content
    (n byte)
    0x0000–0xFFFE Same as the process when a password is added. Same as the process when a password is added. Same as the process when a password is added. Same as the process when a password is added. If the password length is 0, the password is not modified. Same as the process when a password is added.

Report

  • Data direction: report

  • dp_id (1 byte): 7

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Hardware ID
    (2 bytes)
    Return status
    (1 byte)
    0x0000–0xFFFE 0x00: modified successfully
    0x01: failed to modify

Remote unlocking

Set the key

  • To remotely unlock a door, you must configure the remote unlocking function.
  • The key for remote unlocking is specified in the command for remote unlocking settings. The key must be synchronized at least once through the link from the app to the device.
  • The following fields are reserved and can be ignored: Validity, Member ID, Take effect at, Expire at, and Max number of times the key is used.

Send

  • Data direction: send

  • dp_id (1 byte): 8

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Validity (1 byte) Member ID (2 bytes) Take effect at (4 bytes) Expire at (4 bytes) Max number of times the key is used (2 bytes) Key content (8 bytes)
    0x00: invalid 0x01: valid 0x0001–0xFFFF Timestamp Timestamp Current value: 0000FFFF ASCII code

Report

  • Data direction: report

  • dp_id (1 byte): 8

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Status
    (1 byte)
    Member ID
    (2 bytes)
    0x00: success
    0x01: failure
    0x0001–0xFFFF

Set the password-free remote unlocking method

Remote unlocking allows you to unlock a door through either of the following communication links of the app:

  • Remote unlocking with a mobile phone
  • Remote unlocking with voice if a speaker is used for unlocking

Send

  • Data direction: send

  • dp_id (1 byte): 9

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Status
    (1 byte)
    Member ID
    (2 bytes)
    Key content
    (8 bytes)
    Unlocking method
    (2 bytes)
    Channel ID
    (2 bytes)
    0x00: lock
    0x01: unlock
    0x0001–0xFFFE ASCII code 0x00: unknown remote unlocking
    0x01: unlock on the app panel
    0x02: unlock with voice
    0x03: unlock with remote control
    0x0000–0xFFFE
    Default value: 0xFFFF

Report

  • Data direction: report

  • dp_id (1 byte): 9

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Return status
    (1 byte)
    Member ID
    (2 bytes)
    Channel ID
    (2 bytes)
    0x00: success
    0x01: failure
    0x02: invalid
    0x03: max number of times the key is used is reached
    0x04: expired key
    0x05: key comparison error
    0x0001–0xFFFE 0x0000–0xFFFE
    Default value: 0xFFFE

Lock settings

The setup DPs that are configured on the panel support the following default values:

  • dp_type = bool, dp_data_value = 0x00
  • dp_type = value, dp_data_value = 0x00000000
  • dp_type = string, dp_data_value = “”
  • dp_type = enum, dp_data_value = 0x00

Set basic functions

Functional setting Data direction dp_id
(1 byte)
dp_type
(1 byte)
dp_data_len
(1 byte)
dp_data
Switch between single unlocking and combination unlocking Send/report 25 enum 0x01 Combinaton unlocking methods (1 byte)
0x00: single unlocking
0x01: fingerprint+password
0x02: fingerprint+card
0x03: fingerprint+face
0x04: password+card
0x05: password+face
0x06: card+face
Alarm volume Send/report 26 enum 0x01 Volume (1 byte)
0x00: mute
0x01: low
0x02: medium
0x03: high
Lock language Send/report 27 enum 0x01 Language (1 byte)
0x00: Simplified Chinese
0x01: English
0x02: Japanese
...
0x09: Traditional Chinese
0x0A: Korean
Latency of automatic latch Send/report 31 value 0x04 Latency (4 bytes)
Unit: seconds
Switch of automatic latch Send/report 30 bool 0x01 Status (1 byte)
0x00: off
0x01: on
Unlocking speed Send/report 32 enum 0x01 Unlocking speed
0x00: low
0x01: medium
0x02: high
Opening percentage Send/report 33 value 0x01 Percentage (1 byte)
Incremented by %5
Alarm duration Send/report 34 value 0x01 Duration (1 byte)
Valid values: 0–30 min. Default value: 3 min

Set doorbell calls, photo taking, and alert notifications

  • Retake a photo: Tap on the panel to retake a photo. Then, the specified DP is sent.
  • Voice alerts: Support panel configuration of the reason why remote unlocking is denied. Multilingual options can be customized. When the remote unlocking request is denied, the specified DP is sent from the panel. The DP determines whether the device plays the voice alert.
  • Alert notifications: The device generates alerts and the panel receives the alert notifications. Users can tap the panel to keep or cancel the alerts. Then, the DP 39 is sent to the device.
Function Data direction dp_id (1 byte) dp_type (1 byte) dp_data_len (1 byte) dp_data
Request remote unlocking Send/report 24 raw len Multi-channel calls
For more information about reported values, see Appendix 2.

Reported values:
00: request unlocking

Send values:
00: unlock
01: deny unlocking
Retake a photo Send/report 36 bool 0x01 Retake a photo (1 byte)
ture: yes
false: no
Voice alerts Send/report 37 enum 0x01 Type (1 byte)
0x00: message 1
0x01: message 2
0x02: message 3
0x03: message 4
0x04: message 5
0x05: message 6
Alert dialog box Report 38 raw len Multi-channel alerts
For more information, see Appendix 2.

Valid values:
00: cancel local alerts
01: alerts of device exceptions
Cancel alerts Send 39 raw len Multi-channel alerts
For more information, see Appendix 2.

Valid values:
0x00: keep alerts
0x01: cancel alerts
Report 39 raw len For more information, see Appendix 2.

Valid values:
0x00: failed to cancel alerts
0x01: canceled successfully
0x02: unknown (An invalid command might be sent. For example, a command is sent to cancel alerts when the device does not generate an alert.)

Set normally open parameters

Send

Function Data direction dp_id (1 byte) dp_type (1 byte) dp_data_len (1 byte) dp_data
Normally open switch Send/report 28 bool 0x01 Status (1 byte)
0x00: off
0x01: on

Report

  • Data direction: report

  • dp_id (1 byte):29

  • dp_type (1 byte): raw

  • dp_data_len (1 byte): len

  • dp_value: see the following table

    Validity
    (1 byte)
    Weekly cycle
    (1 byte)
    Number of periods
    (1 byte)
    Details of periods
    (n bytes)
    0x00: non-permanent
    0x01: permanent

    Default value: 0x01
    See the example of encoded weekly cycles in Appendix 1 Valid values: 0x00–0xFE. The details of multiple periods.
    For more information about each period, see Appendix 3.

Real-time status reporting

The status DPs that are configured on the panel support the following default values:

  • dp_type = bool, dp_data_value = 0x00
  • dp_type = value, dp_data_value = 0x00000000
  • dp_type = string, dp_data_value = “”
  • dp_type = enum, dp_data_value = 0x00
Function dp_id (1 byte) dp_type (1 byte) dp_data_len (1 byte) dp_data
Open and closed status of the door 35 raw 0x03 Multi-channel status
For more information, see Appendix 2.

Valid values:
0x01: open
0x02: closed

Record reporting

The following table lists the reported records and DPs:

  • Data direction: report
  • The value of dp_type for each DP is set to raw and 1 byte in length.
Type of reported records dp_id (1 byte) dp_data_len (2 bytes) dp_data
Unlock with fingerprints 10 0x06 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF
Unlock with passwords 11 0x06 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF
Unlock with cards 12 0x06 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF
Unlock with remote control 14 0x06 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE
Default value: 0xFF
0x0000–0xFFFE
Default value: 0xFFFF
Unlock with face recognition 13 0x06 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF
Report alert status 23 0x01 Alerts (1 byte) Channel ID (2 bytes)
0: fingerprint attempt alert
1: password attempt alert
2: card attempt alert
3: face recognition attempt alert
4: anti-pry alert
5: unlock without recognition
6: doorbell alert
0x0000–0xFFFE
Default value: 0xFFFF
Combination unlocking 15 0x02 Combination unlocking methods
(1 byte)
Member ID
(2 bytes)
Channel ID (2 bytes)
0x01: fingerprint+password
0x02: fingerprint+card
0x03: fingerprint+face
0x04: password+card
0x05: password+face
0x06: card+face
0x01–0x64 0x0000–0xFFFE
Default value: 0xFFFF
Unlock with offline passwords 17 0x10 Offline password records Channel ID (2 bytes)
See the "Offline password records" section. 0x0000–0xFFFE
Default value: 0xFFFF
Report the clearing of all offline passwords 19 0x10 Offline password records Channel ID (2 bytes)
See the "Offline password records" section. 0x0000–0xFFFE
Default value: 0xFFFF
Report the clearing of a single offline password 21 0x10 Offline password records Channel ID (2 bytes)
See the "Offline password records" section. 0x0000–0xFFFE
Default value: 0xFFFF
Unlock with temporary passwords 16 0x04 Hardware ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF
Remote control on the app 22 0x04 Member ID (4 bytes) Channel ID (2 bytes)
0x0000–0xFFFE 0x0000–0xFFFE
Default value: 0xFFFF

Other passwords

This section describes other passwords as unlocking methods, including offline passwords and dynamic passwords.

Offline passwords

  • Scenarios

    The operator gets an offline password from the app or software as a service (SaaS) and informs the user of the password.

    • The user gets a one-time password: If the password is used within six hours, the door is opened. Then, the password is invalid and an unlocking record is generated.

    • The user gets a time-limited password: If the password is used once within 24 hours, the password is activated. Then, it can be used within the time limit and an unlocking record is generated each time it is used.

    • The user gets the code to clear a one-time password: The validity of the code is the same as the password to be cleared. For multiple clearing operations, only the first clearing operation takes effect. A record of clearing a one-time password is generated.

    • The user gets the code to clear all passwords: If the code is used within 24 hours, all passwords are cleared. It can be used only once. A record of clearing all passwords is generated.

  • Restrictions on clearing a one-time password and all passwords

    • The user can only clear a time-limited password that has been used at least once. This is the activated time-limited password.
    • A one-time password cannot be cleared, because the password becomes invalid after it is used once.
  • Sample code

    For more information about the sample code, see the lock_hard.c file in the SDK installation package.

Set T0 time for offline passwords

The T0 timestamp string is set in the HexStr format. For example, if the current timestamp is 1586845269, the T0 timestamp string to be sent is 5E955655.

Data direction dp_id (1 byte) dp_type (1 byte) dp_data_len (2 bytes) dp_data
Send 18 string len T0 timestamp
(8 bytes)
T0 timestamp string
Report 18 string len T0 timestamp
(8 bytes)
T0 timestamp string

Offline password records

The user enters the decrypted string of the unlocking password. Then, the string is encrypted with the Advanced Encryption Standard (AES) algorithm and specified as output. The following code block shows the algorithm:

app_port_aes128_cbc_encrypt(login_key, iv, input, input_len, output);
  • key: a 16-byte unsigned integer. The default padding character is 0 and the value of tuya_ble_current_para.sys_settings.login_key (6 bytes) is added to the end. For example, if the login_key field value is 8f7d54, the key is 00000000008f7d54.
  • iv: a 16-byte unsigned integer and vector. The default value of sixteen 0x00.
  • input: a 16-byte unsigned integer. The default padding character is 0 and the plain text (10 bytes) of the offline password is added to the end. For example, if the plain text of the offline password is 0123456789, the value of input is 0000000123456789.
  • output: a 16-byte unsigned integer. The value is the result of AES encryption. It is the dp_data_value field value when dp_id is set to 65, 66, or 67.

Appendix

Appendix 1: Validity

Byte Meaning Description Example
1
Start time of validity
Unsigned integer

4 bytes (big endian)
For example, the Unix time is:

123-456-789 = 0x075BCD15.‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬ ‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬‬
If it is permanently valid, the start time is 0x00000000.
7
2 5B
3 CD
4 15
5 End time of
validity
Unsigned integer

4 bytes (big endian)
For example, the unix time is:

999-999-999 = 0x3B9AC9FF.
If it is permanently valid, the end time is 0x7FFFFFFF.
3B
6 9A
7 C9
8 FF
9 Validity cycle mode 0x00: no cycle 0x01: daily cycle 0x02: weekly cycle 0x03: monthly cycle
10 Cycle flag 1 The bytes No. 10 to 17 set to 0 Default value: 0x00 Default value: 0x00 bit7: 0 by default
bit6: No. 31
...
bit0: No. 25
11 Cycle flag 2 Default value: 0x00 Default value: 0x00 bit7: No. 24
...
bit0: No. 17
12 Cycle flag 3 Default value: 0x00 Default value: 0x00 bit7: No. 16
...
bit0: No. 9
13 Cycle flag 4 Default value: 0x00 bit7: 0 by default
bit6: Saturday
...
bit1: Monday
bit0: Sunday

See the example of encoded weekly cycles in Appendix 1
bit7: No. 8
...
bit0: No. 1
14 Start time 1 of the day (hour) Start time: 08:30 08 (decimal)
15 Start time 2 of the day (minute) 30 (decimal)
16 End time 1 of the day (hour) End time: 20:30 20 (decimal)
17 End time 2 of the day (minute) 30 (decimal)

Example of encoded weekly cycles

bit7 reserved bit6 Saturday bit5 Friday bit4 Thursday bit3 Wednesday bit2 Tuesday bit1 Monday bit0 Sunday Value
0 0 1 0 1 0 1 0 0x2A
0 0 1 1 0 1 0 1 0x35
0 1 1 1 0 0 1 0 0x72
0 1 1 1 1 1 1 1 0x7F

After you add or modify an unlocking method, the cycle method and the number of cycle times take effect at the same time. However, the settings only apply to the following conditions:

  • The number of cycle times is set to 0x00 to specify permanent validity. In this case, only the cycle method is required.
  • The validity cycle method is set to 0x00 to specify that no cycle is used. In this case, only the number of cycle times is required.

For example, you can set the following validity cycle: 8:00 (UTC+8) to 8:30 (UTC+8) from Monday to Friday during the period from 2018-01-26 08:00:00 (UTC+8) to 2018-08-08 09:56:32 (UTC+8). Then, the validity is set to 0x ‭5A6A6F80 5B6A4DD0 02 0000003E 0800 081E. The following rules apply to this example:

  • 2018-01-26 08:00:00 is converted to the Unix time 1516924800 or 0x‭5A6A6F80.
  • 2018-08-08 09:56:32 is converted to the Unix time 1533693392 or 0x5B6A4DD0.
  • The validity cycle method is set to 0x02 that specifies a weekly cycle.
  • Cycle day flag 1 = Cycle day flag 2 = Cycle day flag 3 = 0x00
  • Cycle day flag 4 = 0x3E (Monday to Friday)
  • Start time 1 of the day = 0x08, Start time 2 of the day = 0x00
  • End time 1 of the day = 0x08, End time 2 of the day = 0x1E

Appendix 2: Channel protocol

The following table shows the multi-channel data definition.

Number of channels (1 byte) Channel information
0x00–0xFE See the following channel bit field description

Channel bit fields: Each channel is represented by two bytes:

  • The first byte represents the serial number of the current channel (starting from 0).
  • The following n-1 bytes represent the value of the current channel.

The following table shows a scenario that supports up to four channels. In this scenario, a DP value is one byte in length.

Scenario Value of channel 1 (1 byte) Value of channel 2 (1 byte) Value of channel 3 (1 byte) Value of channel 4 (1 byte) Reported/sent data
The values of three channels are sent. 0x21 No data sent 0x5B 0x0B Data to be sent: 0x03 0x00 0x21 0x02 0x5B 0x03 0x0B

Appendix 3: Normally open periods

Each period is described with 4 bytes:

  • The first byte represents the hour of the start time.
  • The second byte represents the minute of the start time.
  • The third byte represents the hour of the end time.
  • The fourth byte represents the minute of the end time.

For example, if the start time is 08:30 (UTC) and the end time is 20:30 (UTC), the normally open period is:

0x08 0x1E 0x14 0x1E