DP Reference

This topic describes the data point (DP) function, frame format, and usage method involved in the Tuya Smart Bluetooth door lock application. It applies to the public version of the Bluetooth door lock project.

Background information

Terms and definitions

The following table lists some terms and definitions involved in this topic. For more details, see Terms.

Role assignment

• Host: Tuya Smart app

• Slave: Bluetooth lock

  The host recognizes the slave through Bluetooth broadcasting and initiates a pairing request to the authorized slave. The master and slave that have completed the pairing are in the bound states.

  There is a secure channel conforming to the Bluetooth specification between the master and slave in the bound states. All business communications are carried out in this secure channel.

The process of establishing a secure channel can be briefly described as follows: Unbound > Connect > Pair > Bound > Secure communication > Disconnect > Reconnect > Bound > Secure communication > … > Remove > Unbound

• Connection: common Bluetooth connection. Here, it specifies the connection between the app and the lock.
• Pairing: regarded as a process, a series of key exchange processes.
• Bound: regarded as a status. The status after pairing is called “bound status”, and two devices in the bound status can communicate securely.
• Reconnect: regarded as a process, it is also a series of key exchange processes, which can be considered as a simplified “pairing”. The premise of this process is that it has entered a bound status before.
• Removal: regarded as a process, the key is deleted and the bound status is cleared.

DP format

When you use Tuya Bluetooth modules for development, the length of dp_data_len is 2 bytes. For information about other DP formats, see the table below:

Manage unlocking methods

Add unlocking methods

Interactive example

• When the unlocking method is password, card, or face, the interaction process is shown in the following figure:

  

• When the unlocking method is the fingerprint, the interaction process is shown in the following figure:

  

Delete unlocking methods

Modify an unlocking method

Add a temporary password

Temporary passwords include one-time passwords and periodic passwords. The difference between a temporary password and a normal password is as follows:

• Temporary password does not belong to any member.

• The valid time of the temporary password can be changed separately in the connected status.

• The temporary password is defined as 0xF0 as an unlocking method (0x01 is the password, 0x02 is a card, and 0x03 is fingerprint…)

• Risk:

  After the network is disconnected, if the device is powered off, the local clock will not work properly. If the network cannot be connected and the clock cannot be synchronized in time, the periodic repetition function of the periodic password will not be accurately judged locally.

  Solution:

  • Add a backup battery locally to ensure that the local clock is not abnormal due to power failure.
  • Accept the problem that occurs in the above-mentioned case.

Delete a temporary password

Modify a temporary password

Synchronize unlocking methods

In order to maintain the consistency between the server and the local unlocking methods of the device, each time you enter the hardware list on the app or pull down to refresh the hardware list interface on the app, you need to perform full synchronization of the unlocking methods (all the unlocking methods added on the phone and locally). The hardware type enumeration is used to notify the local of the hardware type that needs to be synchronized this time. The unsent hardware type does not need to be reported locally. The data length of each packet in synchronization is defined by the user, and the total length of each packet is not more than 200 bytes. For more information, see FAQ.

Old version of synchronizing unlocking methods (which will be deprecated soon)

In order to minimize the amount of data transferred during synchronization, only the differentiated parts are synchronized each time. When you start to synchronize unlocking methods, the app will send the CRC8 value of the hardware ID, hardware type, and properties bound to each hardware ID (such as member ID and frozen status) stored on the server-side to the local device. After receiving the data, the received data and the locally stored data is compared. Then, the differentiated hardware ID is selected, and its property value is uploaded again.

Note:

• Send hardware n = hardware IDn + hardware type + hardware CRC8
• Report hardware n = operation type + hardware IDn + hardware type + hardware properties

• Operation type: 1 byte. 0x00 indicates the hardware properties are updated when the properties are inconsistent between the server and the local. 0x01 indicates the hardware ID is deleted, and no record can be found locally. Hardware type: 1 byte. 0x01-password, 0x02-door card, 0x03-fingerprint, and 0x04-face. Hardware property: 2 bytes.
  • Member ID: 1 byte. Value range: 0x01-0x64.
  • Frozen status: 1 byte. 0x01-unfrozen, 0x00-frozen.

• CRC8 calculation method: CRC8 is the low byte of CRC16. The C language calculation method of CRC16 is as follows:

  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;
   }
  
  

Guide function

Freeze and unfreeze users

• The objects of freezing and unfreezing are other members, including sharing users.
• Both family owners and administrators can freeze and unfreeze other members.
• In order to maintain consistency with the local, the freeze/unfreeze command can only be operated on the panel when the device is connected.
• Once the user is frozen, all unlocking methods under the member will be frozen until the user is unfrozen.
• Once the user is frozen, members have no permission to add, delete, or modify the unlocking method until the user is unfrozen.
• Once the user is frozen, the only operation that family owners and administrators can perform on it is “unfreeze”.

Locking and unlocking with Bluetooth

When the app successfully connects to a Bluetooth lock and unlocks it through the panel, the device unlocks after receiving the request and reports the unlocking record through ID 19.

Configure remote unlocking

• Before remote unlocking, you must configure remote unlocking first.
• The “key content” in the “remote unlocking” command is configured through the “remote unlocking configuration” command. Only one successful configuration is performed through the gateway → Bluetooth device link. After the cloud confirms that the configuration is successful, the second configuration will not be performed.
• The “validity”, “member ID”, “key valid time”, “key expiration time”, and “key usage times” in this command are all reserved fields and can be ignored.

Remote unlocking

Remote unlocking refers to unlocking through the communication link of the gateway:

• If you use a mobile phone to unlock through the gateway, it is called “remote unlocking through mobile phone”.
• If you use a speaker to unlock through the gateway, it is called “remote unlocking with voice”.
• If you connect a mobile phone to a Bluetooth device to unlock, it is called “unlocking with Bluetooth”.

Note: Either “remote unlocking” or “Bluetooth unlocking”, the unlocking operation must be made. The two unlocking methods are just different in the data link, and the actual business meaning is the same.

Obtain unlocking record

New combination unlock

Lock settings

The default value of the setting type DP on the panel is specified as follows:

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

Real-time status

The default value of the status type DP on the panel is specified as follows:

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

Record report

Other passwords

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

Offline password

• Scenario:

  The operator obtains the offline password through APP/SaaS and informs the user.

  • The user gets a one-time password: if it is used within 6 hours, the door is opened successfully. Then, the password is invalid, and an unlocking record is generated. It becomes invalid after six hours.

  • The user gets a time-limited password: if it is used once within 24 hours, the password is activated. It can be used within the time limit, and an unlocking record will be generated every time it is used. It becomes invalid if it is not used within 24 hours.

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

  • The user gets the notification to clear all passwords: if it is used within 24 hours, all passwords will be cleared. It can be used only once. A record of “clearing all passwords” is generated. It becomes invalid after 24 hours.

• Restrictions on clearing a one-time password/all passwords:

  • The user can only clear “a time-limited password that has been used at least once (the activated time-limited password)”.
  • “One-time password” cannot be cleared, because a one-time password becomes invalid after it is used once.

• For usage, see the example code.

  The example code is in lock_hard.c file of the SDK installation package.

Dynamic password

• Both the local lock and the cloud independently have the same set of dynamic password generation algorithms. The only connection between the two is the Unix timestamp. If the difference of Unix timestamp between the lock and the cloud is no more than 300 seconds, the dynamic passwords generated by the two are considered to be the same. Local unlocking is allowed.

• The actual implementation mechanism of the dynamic password is slightly different, but the generated result is as described above. The calling method is as follows:

  if(DYNAMIC_PWD_VERIFY_SUCCESS == lock_dynamic_pwd_verify(&data[0], 8)) {
   APP_DEBUG_PRINTF("lock_open_with_dynamic_pwd_success");
  } else{
   APP_DEBUG_PRINTF("lock_open_with_dynamic_pwd_fail");
  }
  

Protocols

Note: The encrypted clear code is output.

app_port_aes128_cbc_encrypt(login_key, iv, input, input_len, output);

• key: 16-byte unsigned integer. The default filling character is “0”, and “tuya_ble_current_para.sys_settings.login_key” (6 bytes) is filled at the end. For example, if the login_key is “8f7d54”, the key is “00000000008f7d54”.
• iv: 16-byte unsigned integer, and vector. The default value of sixteen 0x00.
• input: 16-byte unsigned integer. The default filling character is “0”, and the plain text (10 bytes) of the offline password is filled at the end. For example, the plain text of the offline password is “0123456789”, then input is “0000000123456789”.
• output: 16-byte unsigned integer, the result of AES encryption, which is dp_data_value of dp_id=65/66/67.

DP for the cloud only

DPs supporting the lock accessories

If your smart door lock needs to support lock accessories, you need to use these DPs. For more information, see the new DP section of DP Protocol of Lock Accessories.

Appendix

When you add or modify the unlocking method, the validity cycle method, and the number of times take effect at the same time. However, generally, only the following two situations are used:

• The number of times is 0x00. The number of times is permanently valid, and only the validity cycle can be processed.
• The validity cycle method is 0x00. It is not cycled, and only the number of times can be processed.

For example, if you set to take effect from 8:00 to 8:30 in the morning from Monday to Friday during the period from 01/26/2018 at 08:00:00 to 08/08/2018 at 09:56:32, the validity is 0x ‭5A6A6F80 5B6A4DD0 02 0000001F 0800 081E:

• 01/26/2018 at 08:00:00 is converted to Unix time 1516924800, that is, 0x‭5A6A6F80
• 08/08/2018 at 09:56:32 is converted to Unix time 1533693392, which is 0x5B6A4DD0‬
• The validity cycle method is: 0x02-weekly cycle
• Cycle day flag 1 = cycle day flag 2 = cycle day flag 3 = 0x00
• Cycle day flag 4 = 0x1F (Monday to Friday)
• Start time of the day 1 = 0x08, start time of the day 2 = 0x00
• End time of the day 1 = 0x08, end time of the day 2 = 0x1E