Wi-Fi Lock

Wi-Fi connection protocol for door lock

Version history

Serial communication convention

Baud: 9600/115200

Data bit: 8

Parity check: None

Stop bit: 1

Data flow control: None

MCU: Micro Controller Unit. MCU is connected to Tuya modules through serial ports. Regarding the protocol design, interaction of all packets is designed as full-duplex communication.

Frame format description

Note:

  • All data greater than one byte shall be transmitted with big-endian mode.

  • All examples in the protocol use hexadecimal data.

  • The packets sent by Wi-Fi module time out after 1s. The resend mechanism will resend three packets.

  • Generally, one command word is sent by one party and received by the other party in a synchronous way. That is, one party sends the command, and the other party responds. If the sender does not receive the correct response packet within 1 second, the transmission times out, as shown in the following figure.

Note: for specific communication mode, refer to the section Protocol Details.

MCU status is reported in a synchronous way. Command word of reporting MCU status is y, as shown in the following figure:

Status data unit

Note:

Datapoint command or the status data unit is shown as follows.

  • For 0datapoint command/status data unit, except raw type, all other types belong to obj type datapoint.

  • Status data can include multiple datapoint command data units.

Points for attention during development:

  • The whole protocol applies to devices that use Wi-Fi modules and cannot use external power supply. During development of MCU programs, power-off management is especially important. Under the precondition of completing the functions, try to reduce the power-on time period of Wi-Fi module, in order to reduce the power consumption of devices. Overall control flow chart of data uploading is provided here. Developers can choose the required functions depending on device features. During development, developers can adjust relevant control logics as needed in a real-time way.

  • In many cases, a device works normally when Wi-Fi function is not enabled. Due to various reasons, users might not be able to use Wi-Fi functions after they get the devices. To prevent electrical energy loss if Wi-Fi module is power on in this case, we can design a physical button or relevant options in the device. Only when the user presses this button or enables the options, the data changes, and MCU powers on the Wi-Fi module to transmit data.

Protocol details

Querying product information

  • Product ID: corresponding to product ID of Tuya IoT console. It is generated by Tuya IoT console to record product information in the cloud.

  • Product information consists of product ID and MCU software version number.

  • Define the format of MCU software version No.: dot-decimal notation, x.x.x (0<=x<=99), x is decimal digit.

For example, the module sends the following command:

55 aa 00 01 00 00 00

MCU returns the following command

For example, {"p": "vHXEcqntLpkA****", "v": "1.0.0"},

  • p represents product ID, vHXEcqntLpkA****, which is the product ID created by the user on the Tuya IoT console.

  • v represents MCU version number, which is 1.0.0.

MCU returns example information

55 aa 00 01 00 24 7b 22 70 22 3a 22 76 48 58 45 63 71 6e 74 4c 70 6b 41 6c 4f 73 79 22 2c 22 76 22 3a 22 31 2e 30 2e 30 22 7d bf

Reporting the network status of the device

  • When Wi-Fi status of the module changes, Wi-Fi status is sent to MCU.

  • Status packet here is used by MCU device to get current status of the module. For status 1 and status 2, MCU shall configure network and display.

  • In principle, users need to configure network in two ways. In the first network configuration way, a few routers have compatibility issues. The second network configuration way ensures that the device can be connected to the network.

  • Before network configuration, the power-on module is in the low power consumption status by default. After MCU sends Wi-Fi reset command, the module will enter the network configuration status.

  • After the device is removed from a mobile phone, the module enters the low power consumption status. After MCU sends Wi-Fi reset command, the module will enter the status of waiting for network configuration.

  • After the Wi-Fi module enters network configuration mode, if the module fails to connect the router within 10 seconds and the module is power-off, the module will be still in the previous network configuration status after it is powered on next time.

The module sends the following command

For example, the module sends the following command:

55 aa 00 02 00 01 04 06, the device is connected to the router and the cloud.

MCU returns the following command

MCU returns the following command

55 aa 00 02 00 00 01

Resetting Wi-Fi

Reset Wi-Fi status transfer is shown as follows.

MCU sends the following command

MCU sends the following command

55 aa 00 03 00 00 02

The module returns the following command

The module returns the following command:

55 aa 00 03 00 00 02

Resetting Wi-Fi and select configuration mode

Note:

  • Compared to Reset Wi-Fi, with this frame, MCU can select the required configuration mode after Wi-Fi is reset.

  • After connected to MCU, users can implement this protocol selectively.

MCU sends the following command

MCU sends the command to the control module and enters AP configuration mode:

55 aa 00 04 00 01 01 05

The module returns the following command

The module returns the following command:

55 aa 00 04 00 00 03

Reporting the real-time status

Scenario: If a device has an alert function and requires real-time notification, we can use this command to report the relevant status data.

Note: When MCU needs to report real-time status data, this protocol can be used to report the data.

  • Status data is directly reported to the cloud, so the device shall be connected to the cloud already. Otherwise, the device fails to report the data.

  • This command is a synchronous command. MCU reports the data, and then waits for the result returned by the module. The waiting timeout is 7 seconds.

  • The module sends a network status packet that the server is connected, and then sends the required statistical data packet. The data uploading here does not have storage function. If, after a period, MCU does not receive the network status packet that the server is connected, the MCU will still power off the device.

  • The waiting period in the preceding sentence is affected by network and whether it is the first network configuration. If it is the first network configuration, it takes much time to transfer from status 3 (Wi-Fi has been configured) to cloud connection status, because the device shall be activated and initialized. It takes a longer time if the network is poor, so it is suggested that the waiting period should be 120 seconds. If it is not the first network configuration, that is, the network has already been configured, it is suggested that the waiting period should be 30 seconds, considering that a longer waiting period is required in case of poor network.

  • Support the reporting of multiple data units and single data unit. users can select the packet sending mode as needed. For specific data packet, refer to the following example.

The general operation flow chart is shown as follows.

MCU sends the following command

The module returns the following command

Example of reporting single status data unit: Datapoint 109 has a boolean variable, and the value is 1 55 aa 00 05 00 05 6d 01 00 01 01 79.

Example of reporting multiple status data units: Datapoint 109 has a boolean variable, and the value is 1. Datapoint 102 has a string variable, and the value is 201804121507 (transmission corresponds to ASCII value): 55 aa 00 05 00 15 6d 01 00 01 01 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 5d.

Reporting the recorded status

Scenario: A door lock contains multiple datapoint data, which shall be processed by the server as one record. In case of transient network failure, the data that cannot be reported will be saved through this command. This command can report the status of record type devices. The report shall indicate the local time.

Note: When MCU requires whole data that combines multiple datapoint and that shall be reported as a whole, this command can be used to send the data to Wi-Fi module. If the device is disconnected from network when the data is being reported, the module will save the data. During the next data reporting, the module will upload the data, and report it together with previously saved data.

  • Each time when a previously saved record is reported successfully, the module will send a returned packet with 09 command word data, which is 01. According to the returned packet, MCU will determine it as timeout, and power off. When a record is sent, MCU will wait for 5 seconds. If no reply is received from the module, it is determined that an exception occurs, and the module will power off.

  • With normal network, after the module is powered on, it usually takes 4 seconds to connect the server. Each time when there is record and the device is powered on, wait Wi-Fi module to send the device network status packet as described in the protocol document.

  • The waiting period is affected by network and whether it is the first network configuration. If it is the first network configuration, it takes much time to transfer from status 3 (Wi-Fi has been configured) to status 5 (cloud connection status), because the device shall be activated and initialized. It takes a longer time if the network is poor, so it is suggested that the waiting period should be 120 seconds. If it is not the first network configuration, that is, the network has already been configured, it is suggested that the waiting period should be 30 seconds, considering that a longer waiting period is required in case of poor network. If the packet that the module has been connected to the server is not received when the waiting period expires, this command will be reported. After MCU reports the data, MCU will wait for the reporting results returned by the module.

  • Maximum length of data area reported in one record (multiple status data units) is 80. The finally combined and actually saved data length might change, depending on the actual datapoint data. When no network is available, in case of exceeding the stipulated length, Wi-Fi module will return the result that the record cannot be sent.

  • Maximum 20 historical records can be saved by the module. In case of exceeding the limit, the earliest records will be overwritten.

  • When the Wi-Fi module receives a piece of data and successfully transmits it, or when there is no network state, the record is stored in the flash successfully, which will also be regarded as the push success (00). When there is a successful push and a delay record, it will return 01. In other cases, it will return 02 to represent the push failure.

  • The use of time data is to guarantee that the recorded data is consistent with the actual events when the device is disconnected. If the time data is generated when the data transmission arrives at the server, the recorded data generated when the device is temporarily disconnected will be inconsistent with the actual event when the network is restored next time. Therefore, when the device is connected to the Wi-Fi module for the first time, and the network performance is guaranteed, the desired time data can be obtained through the protocol. Each time when a record with the current device time data is transmitted, the Tuya cloud platform recognizes the time that is given by the device.

  • Since the device is involved in events such as time zone and daylight saving time around the world, the recorded time processing also should consider the difference between two time format standard. When the device has no display screen, the device obtains the GMT through the protocol, and when the relevant data is generated, it will transmit the GMT data of the current device operation according to the protocol. Some devices, such as the door lock, need to display the local time, the lock can obtain the local time through the protocol. The time module has can calculate the value based on the time zone or daylight saving time to guarantee that the time and the local time can be matched. When the relevant data is generated, the local time data of the device is transmitted according to the protocol.

The workflow is shown as follows.

MCU sends the following command

The module returns the following command.

Examples of data packet transmission is shown as follows.

For the transmission example of one status data unit:

The DP of 109 is a Boolean type variable, and the value is 1.

  • If the time complies with the server time.

    55 aa 00 08 00 0c 00 12 04 13 0d 04 14 ++*6d 01 00 01 01*++ d1

  • If the time complies with the local time of the device, for example, 2018/04/19 13:03:29 of Beijing time.

    55 aa 00 08 00 0c 01 12 04 13 0d 03 1d ++*6d 01 00 01 01*++ da

  • If the time complies with the local time of the device in the GMT format, for example, 2018/04/19 5:03:29 +0.

    55 aa 00 08 00 0c 02 12 04 13 05 03 1d ++*6d 01 00 01 01*++ d3

For the transmission examples of more status data units:

  • The DP of 109 is a Boolean type variable, and the value is 1.

  • The DP of 102 is a string type variable, and the value is an ASCII code of 201804121507.

  • If the time complies with the time of the Tuya cloud platform.

    55 aa 00 08 00 1c 00 12 04 13 0d 06 04 *6d 01 00 01 01* *66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37* a7

  • If the time complies with the local time of the device, for example, 2018/04/19 13:03:29 of Beijing time.

    55 aa 00 08 00 1c 01 12 04 13 0d 08 2e ++*6d 01 00 01 01*++ 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 d4

  • If the time complies with the local time of the device in the GMT format, for example, 2018/04/19 5:03:29 +0.

    55 aa 00 08 00 1c 02 12 04 13 05 08 2e ++*6d 01 00 01 01*++ 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 cd

If more than one unlocking method is used, see the following description.

Note: according to the DP ID of the used unlocking method, the data packet transmits the data of the related DPs, so as to transmit to related data for all of the used unlocking methods.

If the password and fingerprint recognition is used, 55 aa 00 08 00 17 00 13 02 0D 06 33 03 02 02 00 04 00 00 00 01 will be transmitted for the password method, while 01 02 00 04 00 00 00 05 91 will be transmitted for the fingerprint recognition method.

Reception of module command

The reception of command complies with asynchronous processing protocol. When the MCU receives the data packet, it responds to the module about the reception and controls the device according to the command, and the MCU status response is transmitted in the status reporting of the MCU.

The module sends the following command

The command sent by module is shown as follows. The DP of 3 is a Boolean type variable, and the value for unlocking command is 1.

55 aa 00 09 0005 *03 01 00* *01 01* 13

Response from the MCU

ACK response from the MCU

55 aa 03 09 00 00 0b

Inquiry of the local time

  • After the device is connected, and the device status 5 is received by the cloud, the module and others can query the local time of the device.

  • If the network performance is poor, the inquiry of the local time may fail even the device is connected to the cloud. For time-dependent devices such as door locks, if the local time is not calibrated, the inquiry fails. It is necessary to query the time repeatedly every 3 seconds to guarantee the success of time data acquisition.

MCU sends the following command

Local time inquiry example by the MCU:

55 aa 00 06 00 00 05

The module returns the following command

Local time response example by the module

55 aa 00 06 00 08 01 12 09 11 10 09 05 01 59

The preceding example represents the local time of Monday, September 17, 2018, 16:09:05.

  • If the device is activated in mainland China, the local time is Beijing time (East 8 District).

  • If the device is activated in other countries or regions, the local time is the time zone in which the device is located.

Inquiry of the time in GMT format

  • The GMT does not have time zone and daylight saving time related factors. If the dynamic password function is enabled for a device such as a door lock but does not need to display the local time of the device, the device only uses GMT, the transmitted data is in record type and must be in the GMT format.

  • If the dynamic password function is enabled for a device such as a door lock and needs to display the local time of the device, when the device uses GMT, in addition to obtaining the local time regularly, the time difference between GMT and the local time must also be stored locally. When displaying the local time, the device adds the time difference on the basis of GMT. When the data is transmitted in the channel of record data, the time must be in the GMT format.

MCU sends the following command

GMT inquiry example by the MCU:

55 aa 00 10 00 00 0F

The module returns the following command

GMT response example by the module:

55 aa 00 10 00 08 01 12 09 11 08 15 03 01 65

The preceding example represents the of Monday, September 17, 2018, 8:09:05.

Network performance test of Wi-Fi

Note:

  • tuya\_mdev\_test scans the specific SSID and returns the result and the signal strength percentage.

  • If you send the production testing command to the device, the device must be initialized and has responded to the product information query for the first time. Otherwise, the production testing will fail or have no result.

  • This command is mostly used for testing the finished product during mass production.

  • The production testing router has no restriction on password setting. But the band of the router must be 2.4G.

MCU sends the following command

MCU makes network performance test requests to module:

55 aa 00 07 00 00 06

The module returns the following command

Testing response example transmitted by module:

55 aa 00 07 00 02 01 50 59

The preceding example represents that the network stability scores 80.

Upgrading the Wi-Fi module firmware

The power-on and power-off of Wi-Fi module are controlled by MCU. To upgrade the Wi-Fi module firmware, MCU can send the following command to make requests for the latest firmware. * The MCU main board powers off the Wi-Fi module according to the returned packet from Wi-Fi module.

When the MCU transmits 0a but receives no response after waiting for 5 second, then the MCU powers off the Wi-Fi module. If the reply from the module indicates that firmware is being upgraded, the MCU must monitor the upgrading for a while. For example, if the MCU does not receive a response of successful firmware upgrading after 60 seconds, it is considered that the firmware upgrading fails and the Wi-Fi module needs to be powered off.

MCU sends the following command

Firmware upgrading request example sent by MCU:

55 aa 00 0a 00 00 09

The module returns the following command

Firmware upgrading response example from module:

  • 55 aa 00 0a 00 01 00 0a: it is responded immediately after receiving the upgrading request.

  • 55 aa 00 0a 00 01 01 0b: indicates that there is no firmware to upgrade after querying the server.

Upgrading the MCU firmware

  • When MCU receives the firmware update completion instruction returned by the module, it indicates that the upgrade files of the server MCU have been obtained completely and the serial data transmission has been completed. Note that after receiving the complete upgrade file, the MCU confirms that there is no problem about the file. At this time, the module re-sends the query information. MCU needs to return the relevant product information and update the new software version number to the Tuya cloud platform.

  • At present, the maximum MCU OTA size is 480 KB.

  • When you configure MCU upgrade on the Tuya IoT console, the MCU upgrade mode is app silent upgrade.

MCU sends the following command

Example of upgrading the MCU firmware by MCU

55 aa 00 0c 00 00 0b

The module returns the following command

Firmware upgrading response example from module:

  • 55 aa 00 0c 00 01 00 0c: it is responded immediately after receiving the upgrading request.

  • 55 aa 00 0c 00 01 01 0d: indicates that there is no firmware to upgrade after querying the server.

Starting to upgrade

When the MCU triggers the module to upgrade the MCU firmware, the Tuya cloud platform has also prepared a newer version of MCU firmware, and the upgrade method is applicable to the MCU, the module will return the file size of the MCU firmware package that needs to be upgraded.

For example, the module sends the following command

Example of a package size sent by module:

55 aa 00 0d 00 04 00 00 68 00 78: the size of firmware package is 26624 bytes, namely 26KB.

MCU returns the following command

ACK response form the MCU:

55 aa 00 0d 00 00 0c

Upgrade packet transmission

Note:

  • The data type of upgrade packet offset is unsigned short, and the packet data does not have specific type.

  • If the MCU receives the frame with data length less than 4 and the upgrade packet offset is equal to or greater than the size of firmware, the packet transmission ends.

For example, the module sends the following command

Example of a package sent by module

If the file to be upgraded has 530 bytes in size, under this circumstance, the MCU can skip the response for the last data packet.

  • For the first packet data, packet offset is 0x00000000, and data packet length is 256.

    55aa 00 0e 0104 00000000 xx…xx XX

  • For the second packet data, packet offset is 0x00000100, and data packet length is 256.

    55aa 00 0e 0104 00000100 xx…xx XX

  • For the third packet data, packet offset is 0x00000200, and data packet length is 18.

    55aa 00 0e 0016 00000200 xx…xx XX

  • For the last packet data, packet offset is 0x00000212, and data packet length is 0.

    55aa 00 0e 0004 00000212 xx...xx XX

MCU returns the following command

Confirm each MCU data packet:

55aa 00 0e 0000 0d

Checking the signal strength of the connected router

The precondition of checking the signal strength of the currently connected router is that MCU receives the network status packet of the device, indicating the device has successfully connected to the router. Otherwise, sending this command will return failed.

MCU sends the following command

MCU receives the signal strength percentage of the connected router:

55 aa 00 0b 00 00 0a

The module returns the following command

Module returns current value of strength (80):

55 aa 00 0b 00 02 01 50 5D

Requesting cloud temporary password (only support single password)

  • To obtain currently valid password, creating a password for current time on the App-end is required.

  • This interface only supports obtaining one temporary password. Since this interface is for the general firmware 1.0.0 contained in early door lock, using in combination with corresponding early door lock panel is necessary. For all module firmware of later version (later than 1.0.0), the temporary password of App panel uses interface that supports multiple temporary passwords. Obtain related password data.

MCU sends the following command

The lock obtains currently valid temporary password:

55 aa 00 11 00 00 10

The module returns the following command

Module returns current password:

55 aa 00 11 00 0d 01 10 04 13 05 06 07 31 32 33 34 35 36 8c

At 05:06:07 on April 19, 2016 (GMT)

Password: “123456”. ASCII character is used for password transmission.

Checking dynamic password

  • The time data in the protocol is used to operate current dynamic password. The operation time here is the current GMT. Therefore, the device is required to send GMT data to the module.

  • The permission to check the dynamic password can be set on the App-end. The generation algorithm of dynamic password uses admin password to contribute hybrid computation of result. Each time the device requests to check the dynamic password, it is required to send all the admin password of current door lock to the module.

  • The data length of the sent packet is at least 15 bytes, including time data + password + the number of transmitted admin password (excluding optional admin password)

MCU sends the following command

MCU sends two data packets of 6-byte admin password.

55 aa 00 12 00 1C 12 09 11 06 22 29 31 35 39 35 30 31 35 38 02 06 *35 32 31 33 31 34* 35 32 31 33 31 33 b3

Data of the first password: 521314.

Data of the second password: 521313.

The module returns the following command

Module returning password validation failed.

55 aa 00 12 00 01 01 13

Requesting cloud temporary password (supports multiple group)

  • To distinguish it from other passwords, the App panel of temporary password uses 7-digit significant figures. This interface is deployed only when the door lock MCU detects that multiple sets of temporary password are used. Then, related data will be obtain from the cloud to update the data and status of local password, which can reduce energy consumption to the greatest extent.

  • Note that the related time data sent from module to the door lock is GMT. It is necessary to sync time data of the door lock by getting the GMT interface locally.

  • The password is delivered in full by the server each time. Therefore, the lock needs to be updated accordingly based on all the passwords and status returned by the server.

MCU sends the following command

The lock obtains currently valid temporary password:

55 aa 00 13 00 00 12

The module returns the following command

Wi-Fi module returns current 10 passwords:

55 AA 00 13 00 DF 01 0A 07

0A 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

09 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

08 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

07 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

06 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

05 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

04 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

03 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

02 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

01 00 00  12 06 1C 08 15 07  14 05 16 13 01 07  31 32 33 34 35 36 37

C6

Requesting cloud temporary password (with schedule list)

  • To distinguish it from other passwords, the App panel of temporary password uses 7-digit significant figures. This interface is deployed only when the lock MCU detects that multiple sets of temporary password are used. Then, related data will be obtain from the cloud to update the data and status of local password, which can reduce energy consumption to the greatest extent.

  • Note that the related time data sent from module to the lock is GMT. It is necessary to sync time data of the lock by getting the GMT interface locally.

  • The password is delivered in full by the server each time. Therefore, the lock needs to be updated accordingly based on all the passwords and status returned by the server.

  • Keep the original effective period setting, on the basis of the effective period, you can set the password effective plan according to the weekly repeat method; up to 3 schedules can be added

MCU sends the following command

The lock obtains currently valid temporary password:

55 aa 00 14 00 00 13

The module returns the following command

Getting dp cache command

For these sensors with setting or control features, adding dp delivery function is required.

MCU sends the following command

The lock gets the cache command of dp115, dp114 and dp113:

55 AA 00 15 00 04 03 73 72 71 71

The module returns the following command

Module returns (dp115 auto close (Boolean, indicating whether to execute auto close) +dp114 delay lock selection (Enumeration, immediately lock or continue timing) +dp113 (Numeric, in seconds). Following return data indicates close after 30s delays.)

55 AA 00 15 00 14 01 03 73 01 00 01 01 72 04 00 01 01 71 02 00 04 00 00 00 1E AF

Offline dynamic password

If the device is not connected to the Internet for long, dynamic password is also available.

MCU sends the following command

MCU sends the following command

Reporting SN number of MCU

Report SN number of MCU via this interface.

MCU sends the following command

MCU sends the following command

Last updated