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

Serial Port Protocol

Last Updated on : 2022-03-29 03:55:13download

The serial protocol is used for serial communication between Tuya’s Cat.1 module and the third-party MCU.

Serial Port Protocol

Terms

  • Module: refers to Tuya’s Cat.1 module in this topic.
  • GNSS: stands for Global Navigation Satellite System.

Serial communication

  • Baud rate: 115200 or 9600. The baud rate will be automatically detected for two minutes. If not specified, the default baud rate of 115200 will be used.
  • Data bit: 8
  • Parity check: none
  • Stop bit: 1
  • Data flow control: none
  • MCU: microcontroller unit. Your MCU communicates with Tuya’s modules through the serial port.

Frame format

Field Bytes Description
Header 2 It is fixed to 0x55aa.
Version 1 It is used for updates and extensions.
Command 1 Frame type
Data length 2 Big-endian
Data N None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.
  • All data greater than one byte is transmitted in big-endian format.

  • Generally, one command is sent by one party and received by the other party synchronously. That is, one party sends a command and waits for a response from the other party. If the sender does not receive a correct response packet within a specified time period, the transmission times out, as shown in the following figure.

    Serial Port Protocol

    For more information about the serial communication, see the Protocol list.

  • The module sends control commands and the MCU reports data point (DP) status, which occurs asynchronously. Assume that the module sends a command X and the MCU reports a command Y. The data transmission is as follows.

    • The module sends a control command:

      Serial Port Protocol
    • The MCU reports status:

      Serial Port Protocol

Protocol list

Send heartbeats

  • The module sends heartbeats to the MCU every 15 seconds. If the MCU does not respond within the 90-second timeout period, the module considers a communication exception occurred and will restart the software.

  • The MCU can determine whether the module works properly according to the heartbeat. If the module fails to send a heartbeat, the MCU can use the reset pin to reset the module.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x00
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 00 0000 ff

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x00
Data length 2 0x0001
Data 1 0x00: The MCU returns this value only one time after a restart. The module uses this value to determine whether the MCU restarts during operation.
0x01: The MCU returns this value except for the first response after a restart.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

  • Returns 0x55aa 03 00 0001 00 03 after a restart.
  • Returns 0x55aa 03 00 0001 01 04 except for the first response after a restart.

Query product information

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

  • Product ID (PID): It is automatically generated for each product created on the Tuya IoT Platform for storing product information in the cloud.
  • MCU software version number: It is expressed in dot-decimal notation, x.x.x (0 ≤ x ≤ 99), and x is a decimal digit.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x01
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 01 0000 00

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x01
Data length 2 N
Data N {"p": "AIp08kLIftb8x2x0", "v":"1.0.0" ,"m":1, "apn":"cniot"}
The apn (access point name) is optional. If not specified, the system will configure the APN settings automatically.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

{"p":"AIp08kLIftb8x2x0","v":"1.0.0","m":1}

  • p indicates the PID is AIp08kLIftb8x2x0.
  • v indicates the MCU software version number is 1.0.0.
  • m indicates the power consumption of the module.
    • 0: standard power.
    • 1: low power. Note that the period of the TuyaOS timer is one second.

Query the MCU and set the working mode of the module

The working mode indicates how the network status is indicated and the way to trigger module reset. The module can work in the following two modes.

  • The module works with the MCU to process network events. Through serial communication, the module sends the network status to the MCU for LED indication. The MCU can send the command to reset the module when necessary.

  • The module processes network events itself. The NET_MODE pin on the module drives the LED indicator to indicate the network status. The GPIO input signal determines module reset.

    When the module detects a low level on the GPIO input pin for more than three seconds, it will trigger a reset action. The following command specifies the GPIO pins of the LED indicator and the reset button. This feature is not available in low power mode.

    In the module self-processing mode, the LED indicator can only be defined by NET_MODE.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x02
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 02 0000 01

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x02
Data length 2 0x0000: The module works with the MCU to process network events.
0x0002: The module processes network events itself.
Data 0/2 The data length is 2 bytes:
The first byte indicates the GPIO pin of the LED indicator. The fixed value is 0.
The second byte indicates the GPIO pin of the reset button.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

  • The module works with the MCU to process network events: 0x55aa 03 02 0000 04 is returned.

  • The module processes network events itself: 0x55aa 03 02 0002 0c0d 1f is returned.

    • 0x0c indicates the LED indicator is connected to GPIO12.
    • 0x0d indicates the reset button is connected to GPIO13.

Report network status

Network status Description Status value
Status 1 The SIM card is not connected. 0x00
Status 2 Search for cellular networks. 0x01
Status 3 The module is registered with the cellular network but not connected to the network. 0x02
Status 4 The module is connected to the network and gets an IP address. 0x03
Status 5 The module is connected to the cloud. 0x04
Status 6 SIM card registration is denied.
(The SIM card might not subscribe to a cellular service.)
0x05
  • Network status

    • The SIM card is not connected.
    • Search for cellular networks.
    • The module is registered with the cellular network but not connected to the network.
    • The module is connected to the network and gets an IP address.
    • The device has been connected to the cloud.
    • The cellular base station denies the registration. The SIM card might not subscribe to a cellular service.
  • When the module detects the MCU is restarted or disconnected and then goes online, the module actively sends the network status to the MCU.

  • When network status changes, the module actively sends the current status to the MCU.

  • In the module self-processing mode, the MCU does not need to implement this protocol.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x03
Data length 2 0x0001
Data 1 See the description of network status.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 03 0001 00 03

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x03
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 03 0000 05

Reset network connection

After the Cat.1 module receives the reset command, it will reset the SIM card and then reconnect to the cellular network.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x04
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 04 0000 06

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x04
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 04 0000 03

Set the cellular mode

The Cat.1 module can work in fully operational mode or airplane mode.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x05
Data length 2 0x0001
Data 1 1: fully-operational mode.
4: airplane mode.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 04 0000 06

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x05
Data length 2 0x0001
Data 1 0: Cellular mode is set successfully.
1: Failed to set cellular mode.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 04 0000 03

Send commands

  • The DP command and status data unit are defined as follows:

    Data segment Bytes Description
    dpid 1 The serial number of a DP.
    type 1 The data type of a DP is defined on the Tuya IoT Platform, which is represented by value. See the Data type table below.
    len 2 The length is the number of bytes of a value.
    value 1/2/4/N Represented in hexadecimal format. Data greater than one byte is transmitted in big-endian format.

    Data type

    Type Value Length (byte) Description
    Raw 0x00 N Represents DP of raw data type. The data is passed through the module to the cloud.
    Boolean 0x01 1 Represents DP of Boolean data type. Valid values include 0x00 and 0x01.
    Value 0x02 4 Represents DP of integer type. The data is represented in big-endian format.
    String 0x03 N Represents DP of string type.
    Enum 0x04 1 Represents DP of enum type, ranging from 0 to 255.
    Bitmap 0x05 1/2/4 Represents DP of fault type. Data greater than one byte is represented in big-endian format.
  • Except for the raw data type, all others belong to the object type.

  • A command can contain data units of multiple DPs.

  • The module sends control commands and the MCU reports DP status, which occurs asynchronously.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x06
Data length 2 Depends on the type and number of command data units.
Data N Command data units
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: The DP 3 of on/off control is a Boolean variable. The value is 1, which indicates switching on the device.

0x55aa 00 06 0005 03 01 0001 01 10

Report status

  • For more information about the DP data unit, see Status data unit.

  • The MCU asynchronously reports DP status, which can be triggered by three mechanisms.

    • After the MCU executes the command received from the module, it reports the changed DP status to the module.
    • When the MCU actively detects status changes of DPs, it reports the changed DP status to the module.
    • When the MCU receives the DP status query, it sends the status of all DPs to the module.
  • The MCU can report command data units of multiple DPs.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x07
Data length 2 It depends on types and the number of status data units.
Data N See Status data unit.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: The DP 5 of humidity adjustment is a value variable. The value is 30%.

0x55aa 03 07 0008 05 02 0004 0000001e 3a

Query DP status

  • The module asynchronously queries the status of all object DPs. When the MCU receives queries, it sends the status of DPs to the module. For more information, see Report status.
  • The module sends DP status queries when the following two events occur.
    • When powered on for the first time, the module builds communication with the MCU and then sends status queries.
    • When the module detects the MCU is restarted or disconnected and then goes online, the module sends status queries.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x08
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 08 0000 07

OTA firmware update

  • You can specify the update method for the OTA firmware update. The module only serves as the channel for OTA data transmission, without any data parsing operation.

  • The Tuya IoT Platform provides four update methods.

    • Update notification: Users receive a firmware update notification on the app and choose whether to install updates.

    • Automatic update: Users will not receive any update pop-up window. The module checks for firmware updates within one minute after power-on. If any new version is available, it will automatically pull the updates. The module checks for updates every 24 hours after the first-time power-on.

    • Forced update: Users receive a firmware update notification on the app and have no option but to update the firmware.

    • Check for updates: Users will not receive a firmware update notification on the app, but need to manually check for new updates.

  • After the module has sent all update packages, it will send the command 0x01 to query the product information. The MCU must reply with the new MCU firmware version number within one minute. The new version number should be consistent with that configured on the Tuya IoT Platform. The following block diagram shows how the OTA firmware update works.

    Serial Port Protocol

Start OTA update

The OTA update can be initiated automatically or manually. For automatic updates, when the module detects MCU firmware updates from the cloud, the transmission of the update package automatically starts. For manual updates, the module initiates updates only when updates are confirmed on the app.

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0a
Data length 2 0x0004
Data 4 The size of the update package. The data type is an unsigned integer, and the data is stored in big-endian format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 0a 0004 00006800 75: indicates the size of the update package is 26624 bytes, namely 26 KB.

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x0a
Data length 2 0x0001
Data 1 The update package size of a single packet:
0x00: 256 bytes by default, compatible with legacy firmware
0x01: 512 bytes
0x02: 1024 bytes
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 0a 0001 00 0d

Transmit update package

  • The data format of update package transmission: packet offset (unsigned short) + packet data.

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

The module sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0b
Data length 2 The sum of 0x0004 and the packet length.
Data N The first four bytes are fixed as packet offset, and the latter bytes are the packet data.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: The size of the updates is 530 bytes. The MCU can skip the response to the last packet.

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

    0x55aa 00 0b 0104 00000000 xx…xx XX

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

    0x55aa 00 0b 0104 00000100 xx…xx XX

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

    0x55aa 00 0b 0016 00000200 xx…xx XX

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

    0x55aa 00 0b 0004 00000212 xx…xx XX

The MCU returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x0b
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 0b 0000 0d

Get system time in GMT

  • As the international standard of civil time, GMT is independent of the time zone and DST.
  • Before connecting to the network, the module returns success and valid time data after the local timestamp is calibrated.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x0c
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 03 0c 0000 0e

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0c
Data length 2 0x0007
Data 7 The data length is 7 bytes.
Data[0]: indicates whether the system time is obtained successfully.
  • 0: failure.
  • 1: success.
Data[1]: indicates the year. For example, 0x00 indicates the year 2000.
Data[2]: indicates the month, ranging from 1 to 12.
Data[3]: indicates the day, ranging from 1 to 31.
Data[4]: indicates the hour, ranging from 0 to 23.
Data[5]: indicates the minute, ranging from 0 to 59.
Data[6]: indicates the second, ranging from 0 to 59.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

0x55aa 00 0c 0007 01 10 04 13 05 06 07 4c indicates the time 05:06:07 on April 19, 2016 in GMT.

Test module functionality

  • Insert the SIM card in the module to test whether the card can be detected.

  • Test whether the Cat.1 module is authorized.

  • Test whether the RF is calibrated.

  • Get the 4G network signal strength. A SIM card must be inserted. Signal strength ranges from 0 to 31. You can set a quality standard as needed.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x0e
Data length 2 0x0000
Data Data None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0e
Data length 2 0x0004
Data 4 The data length is 4 bytes.
Data[0]: 0 indicates the SIM card is not detected. 1 indicates the SIM card is detected.
Data[1]: 0 indicates the module is not authorized. 1 indicates the module is authorized.
Data[2]: 0 indicates RF is not calibrated. 1 indicates RF is calibrated.
Data[3]: gets the cellular network signal strength, ranging from 0 to 31.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Get local time

  • The local time is calculated by adding the time zone offset and DST to the GMT. The time zone is where the device is activated.
  • Before connecting to the network, the module returns success and valid time data after the local timestamp is calibrated.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x1c
Data length 2 0x0000
Data 0 None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1c
Data length 2 0x0008
Data Data The data length is 8 bytes.
Data[0]: indicates whether the local time is obtained successfully.
  • 0: failure.
  • 1: success.
Data[1]: indicates the year. For example, 0x00 indicates the year 2000.
Data[2]: indicates the month, ranging from 1 to 12.
Data[3]: indicates the day, ranging from 1 to 31.
Data[4]: indicates the hour, ranging from 0 to 23.
Data[5]: indicates the minute, ranging from 0 to 59.
Data[6]: indicates the second, ranging from 0 to 59.
Data[7]: indicates the week, ranging from 1 to 7. 1 indicates Monday.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example: A device deployed in mainland China is activated at 05:06:07 on April 19, 2016 (UTC+8).

0x55aa 00 1c 0008 01 10 04 13 05 06 07 02 5f

Get module’s memory

This command can be used to get the module’s remaining memory. If the module returns -1, getting the module’s remaining memory is not supported.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x0f
Data length 2 0x0000
Data Data None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0f
Data length 2 0x0004
Data 4 The data length is 4 bytes. The value is represented in big-endian format. For example, 0x00 0x00 0x28 0x00 represents 10240 bytes remaining memory.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Get offline dynamic passwords

A type of dynamic password that can be used even if a device is disconnected from the internet for long periods of time.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x16
Data length 2 N
Data Year(1) + mon(1) + day(1) + hour(1) + min(1) + sec(1) + code_len(1) + code(n) Year(1) + mon(1) + day(1) + hour(1) + min(1) + sec(1) indicates GMT.
code_len(1) indicates password length.
code(n) indicates the password.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

  • An offline password: 1849455172
  • GMT: 08:18:42 on January 11, 2021
  • Example: 55 AA 00 16 00 11 15 01 0B 08 12 2A 0A 01 08 04 09 04 05 05 01 07 02 C3

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x16
Data length 2 N
Data Result(1) + type(1) + decode_len(1) + decode(n) result:
  • 0: correct password.
  • All other values: incorrect password.
type:
  • 0: timed password.
  • 1: one-time password.
  • 2: clear password.
decode_len: data length after decoding.
decode: decoded data.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Get Unix timestamp (with time zone)

  • The MCU can get a Unix timestamp, time zone, and daylight saving time (DST).
  • The protocol described in this section only applies to door locks with the keep-alive feature.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x1B
Data length 2 0x0000
Data Data None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x1B
Data length 2 N
Data 2 Data[0]: indicates whether the time is obtained successfully.
  • 1: succeeded.
  • 0: failed.
Data[1] to Data[4]: Unix timestamp.
Data[5]: indicates whether time zone information is obtained successfully.
  • 1: succeeded.
  • 0: failed.
Data[6]: 0 indicates local time ahead of GMT. 1 indicates local time behind GMT.
Data[7]: indicates the time zone.
Data[8]: indicates whether DST is in use in a time zone.
  • 1: in use.
  • 0: not in use.
Data[9] to Data[12]: the timestamp when DST starts, in big-endian format.
Data[13] to Data[16]: the timestamp when DST ends, in big-endian format.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Currently, getting the DST is not supported.

Request temporary password from cloud (with schedule)

  • To maximize power saving, when detecting multiple temporary passwords, the MCU then calls this interface to get password data for updating locally stored data.

    The module sends the MCU time data in GMT format so the MCU needs to call the interface to get GMT for updating time.

  • The server sends full temporary passwords each time and the MCU updates locally stored data accordingly.

  • Users can set a weekly schedule based on the current validity period of a temporary password. Up to three schedules can be added.

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x14
Data length 2 0x0000
Data Data None
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

The door lock gets the currently valid temporary password:

55 aa 00 14 00 00 13

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x14
Data length 2 0x0001+N (temporary password)
Data 1+N The data length is 1+N bytes. The data is transferred in ASCII mode.
Data[0]: indicates whether the password is obtained successfully.
  • 0 indicates failure with a data length of one byte, and the data of password and valid time will not be transmitted in serial communication.
  • 1 indicates success.
Data[1]: indicates the number of passwords, ranging from 0 to 10. 0 indicates no password is created on the app. The data of password and valid time will not be transmitted in serial communication. The number of passwords indicates the password data contained in the current packet.
Data[2]: indicates password length. The length of each password is consistent.

Data[3]: bit7 indicates whether there is a subsequent packet. Bit6 to bit0 indicates the serial number of the current packet, starting with 0.

The following describes the data of the first password.

Data[4]: indicates password No., ranging from 1 to 50. To get the actual No., add 900 to the password No.
Data[5]: indicates the number of times a specified password can be used as expected.
  • 0: A password can be used as many times as needed before it expires.
  • 1: A password can only be used once before it expires.
Data[6]: indicates the current status of the password.
  • 0: The password is valid.
  • 1: The password is invalid because it has been deleted from the app.

The valid time of a password, in GMT.

Data[7]: indicates the year. For example, 0x00 indicates the year 2000.
Data[8]: indicates the month, ranging from 1 to 12.
Data[9]: indicates the day, ranging from 1 to 31.
Data[10]: indicates the hour, ranging from 0 to 23.
Data[11]: indicates the minute, ranging from 0 to 59.

Data[12]: indicates the second, ranging from 0 to 59.

The expiration time of a password, in GMT.

Data[13]: indicates the year. For example, 0x00 indicates the year 2000.
Data[14]: indicates the month, ranging from 1 to 12.
Data[15]: indicates the day, ranging from 1 to 31.
Data[16]: indicates the hour, ranging from 0 to 23.
Data[17]: indicates the minute, ranging from 0 to 59.
Data[18]: indicates the second, ranging from 0 to 59.

Data[19+N]: indicates the number of schedules.

The following describes the first schedule.

Data[20+N]:
0 indicates the password is valid for a specific time period in a day.
1: indicates the password is valid all day long. The data of start and end time is invalid.
Data[21+N]: indicates start time (hour).
Data[22+N]: indicates start time (minute).
Data[23+N]: indicates end time (hour).
Data[24+N]: indicates end time (minute).
Data[25+N]: indicates weekly schedule. Bit0: Sunday. Bit1: Monday. Bit2: Tuesday. Bit3: Wednesday. Bit4: Thursday. Bit5: Friday. Bit6: Saturday.

If a schedule is repeated on Sunday and Wednesday, use the command 0x09.

The following will be the second schedule

… (Omitted for brevity)

The following will be the second password.

… (Omitted for brevity)
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Positional notation

The positional notation uses a set of consecutive digits to represent any real number. The positional notation adopted by the password is determined by two factors:

  • The base: indicates the number of unique digits that a positional notation system uses to represent numbers. Base-4 through base-10 are supported.

  • The starting value: indicates a number starts with zero or one.

    The number of digits
    in a password
    A password starts
    with 0 or 1
    Dynamic password
    Offline password
    The min length of
    online password
    Safety rating
    Multilingual configuration
    of online password
    4 Optional Not supported Not supported 8 1 in 290,000 Password of 8 to 12 digits
    5 Optional Supported Not supported 8 1 in 390,000 Password of 8 to 12 digits
    6 Optional Supported Not supported 8 1 in 1,000,000 Password of 8 to 12 digits
    7 Optional Supported Supported 8 1 in 1,000,000 Password of 8 to 11 digits
    8 Optional Supported Supported 7 1 in 1,000,000 Password of 7 to 11 digits
    9 Optional Supported Supported 7 1 in 1,000,000 Password of 7 to 10 digits
    10 Non selectable Supported Supported 6 1 in 1,000,000 Password of 6 to 10 digits

Set positional notation

The MCU sends the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x03
Command 1 0x17
Data length 2 0x0002
Data 2 The data length is 2 bytes:
Data[0]: indicates the base number.
Data[1]: indicates the starting value.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example

  • To adopt a set of consecutive digits 1 through 5, the base number is set to 5 and the starting value is set to 1.

  • To adopt a set of consecutive digits 0 through 5, the base number is set to 6 and the starting value is set to 0.

    You must set the positional notation after the product information query and before any password-related operation.

The module returns the following command.

Field Bytes Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x17
Data length 2 0x0001
Data result The result:
  • 0: Positional notation set successfully.
  • All other values: Failed to set positional notation.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Request temporary password from cloud (with schedule)

    • To maximize power saving, when detecting multiple temporary passwords, the MCU then calls this interface to get password data for updating locally stored data.

      The module sends the MCU time data in GMT format so the MCU needs to call the interface to get GMT for updating time.

    • The server sends full temporary passwords each time and the MCU updates locally stored data accordingly.
    • Users can set a weekly schedule based on the current validity period of a temporary password. Up to three schedules can be added.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x14
    Data length 2 0x0000
    Data Data None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The door lock gets the currently valid temporary password:

    55 aa 00 14 00 00 13

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x14
    Data length 2 0x0001+N (temporary password)
    Data 1+N The data length is 1+N bytes. The data is transferred in ASCII mode.
    Data[0]: indicates whether the password is obtained successfully.
    • 0 indicates failure with a data length of one byte, and the data of password and valid time will not be transmitted in serial communication.
    • 1 indicates success.
    Data[1]: indicates the number of passwords, ranging from 0 to 10. 0 indicates no password is created on the app. The data of password and valid time will not be transmitted in serial communication.

    Data[2]: bit7 indicates whether there is a subsequent packet. Bit6 to bit0 indicates the serial number of the current packet, starting with 0.

    The following describes the data of the first password.

    Data[3]: indicates password length.
    Data[4]: indicates password No., ranging from 1 to 50. To get the actual No., add 900 to the password No.
    Data[5]: indicates the number of times a specified password can be used as expected.
    • 0: A password can be used as many times as needed before it expires.
    • 1: A password can only be used once before it expires.
    Data[6]: indicates the current status of the password.
    • 0: The password is valid.
    • 1: The password is invalid because it has been deleted from the app.

    The valid time of a password, in GMT.

    Data[7]: indicates the year. For example, 0x00 indicates the year 2000.
    Data[8]: indicates the month, ranging from 1 to 12.
    Data[9]: indicates the day, ranging from 1 to 31.
    Data[10]: indicates the hour, ranging from 0 to 23.
    Data[11]: indicates the minute, ranging from 0 to 59.

    Data[12]: indicates the second, ranging from 0 to 59.

    The expiration time of a password, in GMT.

    Data[13]: indicates the year. For example, 0x00 indicates the year 2000.
    Data[14]: indicates the month, ranging from 1 to 12.
    Data[15]: indicates the day, ranging from 1 to 31.
    Data[16]: indicates the hour, ranging from 0 to 23.
    Data[17]: indicates the minute, ranging from 0 to 59.
    Data[18]: indicates the second, ranging from 0 to 59.

    Data[19+N]: indicates the number of schedules.

    The following describes the first schedule.

    Data[20+N]:
    • 0 indicates the password is valid for a specific time period in a day.
    • 1: indicates the password is valid all day long. The data of start and end time is invalid.
    Data[21+N]: indicates start time (hour).
    Data[22+N]: indicates start time (minute).
    Data[23+N]: indicates end time (hour).
    Data[24+N]: indicates end time (minute).
    Data[25+N]: indicates weekly schedule. Bit0: Sunday. Bit1: Monday. Bit2: Tuesday. Bit3: Wednesday. Bit4: Thursday. Bit5: Friday. Bit6: Saturday.

    If a schedule is repeated on Sunday and Wednesday, use the command 0x09.

    The following will be the second schedule

    … (Omitted for brevity)

    The following will be the second password.

    … (Omitted for brevity)
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Enable weather services (optional)

    This command can be used to enable weather services.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x20
    Data length 2 N((L+K)+(L+K)…)
    Data Data L: consumes 1 byte and indicates the length of K.
    K: indicates the name of the request parameter.
    Example:
    L: 0x06, K: w.temp.
    L: 0x06, K: w.pm25.
    L: 0x0a, K: w.humidity.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x20
    Data length 2 0x0002
    Data 2 0x00: indicates a failure.
    0x01: indicates invalid data format.
    0x02: indicates an exception.
    0x01: indicates a success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Send weather data (optional)

    After you enable weather services, the module regularly sends specified weather data.

    The module sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x21
    Data length 2 N((LKTLV)+(LKTLV)+…)
    Data Data 0x00: indicates a failure.
    0x01: indicates an unauthorized parameter service. Check whether you have subscribed to specific weather services.
    0x01: indicates a success.
  • L: the length of the parameter name.
  • K: the name of the parameter.
  • T: 0x00 indicates an integer and 0x01 indicates a string.
  • L: the length of the field name.
  • V: the value of the field.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The MCU returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x21
    Data length 2 0x0000
    Data 0 None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    If the request contains two request parameters such as w.temp and w.pm25, and only w.temp returns a value, you need to check whether the request parameter name is correct.

    Synchronize DP status

    • Using this synchronous command, the MCU reports DP status and waits for a response from the module.

    • The module will respond to every command that the MCU sends it. The MCU must not resend the command until the module responds.

    • If the data fails to be reported due to poor network quality, the module will return a failure code five seconds later after receiving the command.

    • For the description of the status data unit, see Send commands.

    • The MCU can report data units of multiple DPs.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x22
    Data length 2 It depends on types and the number of status data units.
    Data N See Status data unit.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x23
    Data length 2 0x01
    Data Data 0x00: failure.
    0x01: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get signal strength (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x24
    Data length 2 0x0000
    Data 0 None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x24
    Data length 2 0x0001
    Data Data The RSSI value ranges from 0 to 31. The larger the value, the better the signal quality.
    0 indicates -113 dBm or less.
    31 indicates -51dBm or above.
    If the return value is not within the range, the value is invalid and the operation fails.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Notify the module to disable heartbeat (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x25
    Data length 2 0x0000
    Data 0 None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x25
    Data length 2 0x0000
    Data 0 None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Before the MCU goes to sleep for reducing power consumption, it can send this command to notify the module to disable the heartbeat. Because heartbeats are required for building communication between the module and the MCU, this command must not be sent when the device is just powered on.

    Get module network status

    Network status Description Status value
    Status 1 The SIM card is not connected. 0x00
    Status 2 Search for cellular networks. 0x01
    Status 3 The module is registered with the cellular network but not connected to the network. 0x02
    Status 4 The module is connected to the network and gets an IP address. 0x03
    Status 5 The module is connected to the cloud. 0x04
    Status 6 SIM card registration is denied. 0x05

    The protocol must be consistent with that described in Report network status.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x2b
    Data length 2 0x0000
    Data Data None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x2b
    Data length 2 0x0001
    Data 1 See the description of network status.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get module’s MAC address

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x2d
    Data length 2 0x0000
    Data Data None
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x2d
    Data length 2 0x0007
    Data Data Data[0]: indicates whether the MAC address is obtained successfully.
    • 0x00 indicates success and the next 6 bytes denote a valid MAC address.
    • 0x01 indicates failure and the next 6 bytes denote an invalid MAC address.
    Data[1] to Data[6]: indicates the valid MAC address of the module on a success.

    Get cellular mode

    The Cat.1 module can work in fully operational mode or airplane mode.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data 1 Subcommand: 0x01
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 AA 03 71 00 01 01 75

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002
    Data 2 Subcommand: 0x01
    1: fully-operational mode.
    4: airplane mode.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get international mobile subscriber identity (IMSI)

    The MCU can send this command to the module to get the IMSI of the module.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x02
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0010
    Data 16 Subcommand: 0x02
    For example, a 15-digit IMSI code is 460113012467340.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 AA 00 71 00 10 02 34 36 30 31 31 33 30 31 32 34 36 37 33 34 30 7C

    Get SIM card number (ICCID)

    The MCU can send this command to the module to get the integrated circuit card identifier (ICCID). The module returns a 20-digit ICCID number to the MCU. The MCU can send this command to the module to get the ICCID of the module.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x03
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0015
    Data 21 Subcommand: 0x03
    For example, a 20-digit ICCID code is 89861118249000363490.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 AA 00 71 00 15 03 38 39 38 36 31 31 31 38 32 34 39 30 30 30 33 36 33 34 39 30 9A

    Get international mobile equipment identity (IMEI)

    The MCU can send this command to the module to get the IMEI. The module returns a 15-digit IMEI number to the MCU. The MCU can send this command to the module to get the IMEI of the module.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x04
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0010
    Data 16 Subcommand: 0x04
    For example, a 15-digit IMEI number is 864237040014733.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 AA 00 71 00 10 04 38 36 34 32 33 37 30 34 30 30 31 34 37 33 33 88

    Enable or disable GNSS positioning (optional)

    The MCU sends this command to the module to enable or disable the GNSS positioning function. Because the GNSS module performs many operations, the maximum timeout period for a response is three seconds.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0003
    Data Data Subcommand: 0x81
    Control command:
  • 0x01: Enable GNSS.
  • 0x00: Disable GNSS.
    When GNSS positioning is enabled, the module can work in the following modes:
  • 0x00: Global Positioning System (GPS) plus BeiDou Navigation Satellite System (BDS)
  • 0x01: GPS plus Global Navigation Satellite System (GLONASS)
  • 0x02: GPS
  • 0x03: BDS (depending on the functionality of GNSS modules)
  • 0x04: GLONASS (depending on the functionality of GNSS modules)
  • 0x05: Galileo satellite navigation (depending on the functionality of GNSS modules)
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0003
    Data 3 Subcommand: 0x81
    Enable or disable GNSS positioning.
    0: failure.
    1: success.


    Specify the status of GNSS positioning. Note that the return value is invalid when GNSS positioning is disabled.
    0: failure.
    1: success.

    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Report GNSS information automatically (optional)

    The MCU sends this command to the module to enable or disable the GNSS positioning function. Because the GNSS module performs many operations, the maximum timeout period for a response is three seconds. You must enable GNSS positioning before using this feature.

    The values of fields of positioning modes are valid only when the GNSS positioning is enabled.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0003
    Data Data Subcommand: 0x90
    The reporting period: 2-byte data in seconds, transmitted in big-endian format.
    The DP ID: 1-byte data.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x90
    The result:
    0: failure.
    1: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    If the reporting period is 0, it indicates automatic reporting is canceled. The reporting period must be at least five seconds. The data that is automatically reported is transmitted over the cellular network.

    Enable or disable Wi-Fi positioning (optional)

    The MCU sends this command to the module to enable or disable the Wi-Fi positioning. If Wi-Fi positioning is enabled, the module will search for an access point (AP) every 30 seconds.

    It takes about two seconds to complete AP scanning. After the MCU sends this command, the MCU will wait about two seconds before getting the information.

    When Wi-Fi positioning is enabled, Bluetooth will be disabled.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x82
    Control command:
    0x01: Enable Wi-Fi positioning.
    0x00: Disable Wi-Fi positioning.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data 2 Subcommand: 0x82
    0: failure.
    1: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Report Wi-Fi positioning automatically (optional)

    The MCU sends the DP ID and the reporting period to the module. The module automatically reports the positioning information to the cloud. You must enable Wi-Fi positioning before using this feature.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x91
    The reporting period: 2-byte data in seconds, transmitted in big-endian format.
    The DP ID: 1-byte data.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data 2 Subcommand: 0x91
    The result:
    0: failure.
    1: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Report LBS positioning automatically (optional)

    The MCU sends the DP ID and the reporting period to the module. The module automatically reports the positioning information to the cloud.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x92
    The reporting period: 2-byte data in seconds, transmitted in big-endian format.
    The DP ID: 1-byte data.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data 2 Subcommand: 0x92
    The result:
    0: failure.
    1: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    If the reporting period is 0, it indicates automatic reporting is canceled. The reporting period must be at least five seconds. The data that is automatically reported is transmitted over the cellular network.

    We recommend you choose only one of the positioning modes from Wi-Fi, GNSS, or LBS for automatic positioning reporting. Otherwise, there will be an error of one to two seconds between the actual reporting period and the preset period.

    Reset GNSS module (optional)

    The MCU sends this command to the module to reset the GNSS module.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0003
    Data Data Subcommand: 0x83
    GPIO reset pin: a value from 0 to 31, according to the actual hardware connection.
    The voltage level on the reset pin:
    0: low level.
    1: high level.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data 2 Subcommand: 0x83
    0: failure.
    1: success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get GNSS positioning in longitude and latitude (optional)

    The MCU sends this command to the module to get GNSS positioning information, in longitude and latitude format.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x10
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N
    Data 2+N Subcommand: 0x10
    1: success. The returned positioning information is a string of n bytes in the format longitude, latitude.
    0: failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.
    The module returns information in string type, so the MCU gets the information and directly reports it to the cloud.

    The module returns information in string type, so the MCU gets the information and reports it to the cloud. If the cloud requires DP data in latitude and longitude format, the MCU must convert the format of the received positioning information.

    Get GNSS positioning in latitude and longitude (optional)

    The MCU sends this command to the module to get GNSS positioning information, in latitude and longitude format.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x29
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N
    Data 2+N Subcommand: 0x29
    1: success. The returned positioning information is a string of n bytes in the format latitude, longitude.
    0: failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns information in string type, so the MCU gets the information and reports it to the cloud.

    Get signal-to-noise ratio (SNR) of GNSS signals (optional)

    The MCU sends this command to the module to get the SNR of GNSS signals.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data 1 Subcommand: 0x11
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data 3 Subcommand: 0x11
    1: success. The 1-byte SNR value ranges from 0 to 100.
    0: failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get GNSS positioning speed (optional)

    The MCU sends this command to the module to get GNSS instantaneous velocity.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 1 0x0001
    Data Data Subcommand: 0x12
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0004
    Data 4 Data[0] indicates Subcommand: 0x12.
    Data[1] indicates the result:
    • 1: success. The speed value returned has 2 bytes, in the unit of 100 m/h.
    • 0: failure.
    Data[2] indicates the speed of the high data bit.
    Data[3] indicates the speed of the low data bit.
    For example, Data[2] is SPEED>>8, and Data[3] is SPEED&0xFF.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get Wi-Fi positioning information (optional)

    The MCU sends this command to the module to get Wi-Fi positioning information.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 1 0x0001
    Data Data Subcommand: 0x20
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N
    Data 2+N Subcommand: 0x20.
    The value that indicates the number of the pieces of positioning information has 1 byte.
    The positioning information has N bytes, in string type, such as [“b27e525dc87d”,-64] and [“957e5b5d087d”,-64], or b27e525dc87d,-64, 957e5b5d087d,-64.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns information in string type, so the MCU gets the information and directly reports it to the cloud.

    Get location-based service (LBS) positioning information

    The MCU sends this command to the module to get LBS positioning information. LBS positioning information takes the format of carrier code (mobile country code (MCC) + mobile network code (MNC)) + location area code + base station number. For example, the LBS information for China Telecom is 46011, e615, 04bafc0a.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x21
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N
    Data Data Subcommand: 0x21
    1: success. The LBS positioning information is a string of n bytes, for example, 46011, e615, 04bafc0a.
    0: failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 AA 00 71 00 15 21 01 34 36 30 31 31 2C 65 36 31 35 2C 30 34 62 61 66 63 30 61 7D

    Control GNSS’s main power supply

    The MCU sends this command to the LZ211 module to turn on or off the GNSS’s power supply. The LZ211 module has a built-in GNSS chip. As long as the device is powered on, the backup power for GNSS works. The on/off control of GNSS’s main power supply is supported. The chip performs a warm boot when the main power is on.

    When the GNSS chip is powered on, it takes about four seconds for the chip to load GNSS firmware. The GNSS positioning function will be restarted when the main power is off and on again. For more information, see Enable or disable GNSS positioning (optional).

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x85
    Data[1] specifies whether to turn on or off the power:
    1: Turn on the power.
    0: Turn off the power.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0002
    Data Data Subcommand: 0x85
    1: success.
    0: failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Get the GNSS power status of LZ211

    The MCU sends this command to the LZ211 module to query GNSS’s power status.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x22
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x22
    0: Power is off.
    1: Firmware is loading.
    2: Power is on and firmware loading is completed.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Incoming call notification (optional)

    Given that the MCU and the module communicate in a query-and-response manner, the MCU should send a response within three seconds as receiving an incoming call. Otherwise, the call will be hanged up.

    The module sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N (phone number)
    Data Data Subcommand: 0x23
    Control command: 0x00
    Phone number: a string of n bytes.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 00 71 00 0D 23 00 31 35 38 39 30 39 38 36 37 36 37 F2

    The MCU returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x23
    Control command: 0x00
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 03 71 00 02 23 00 98

    Outgoing calls (optional)

    The return value can only indicate whether the command of an outgoing call is sent successfully. Whether the call is successfully received depends on the return value of a call status query.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002+N (phone number)
    Data Data Subcommand: 0x23
    Control command: 0x01
    Phone number: a string of n bytes
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 03 71 00 07 23 01 31 30 30 38 36 9D

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x23
    Control command: 0x01
    Result: 1 indicates success. 0 indicates failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 00 71 00 03 23 01 01 98

    Answer calls (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x23
    Control command: 0x02
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 03 71 00 02 23 02 9A

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x23
    Control command: 0x02
    Result: 0 indicates success. 1 indicates failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 00 71 00 03 23 02 00 9A

    Hang up calls (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x23
    Control command: 0x03
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 03 71 00 02 23 03 9B

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x23
    Control command: 0x03
    Result: 0 indicates success. 1 indicates failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 00 71 00 03 23 03 00 99

    Query call status (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x23
    Control command: 0x04
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 03 71 00 02 23 04 9C

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x23
    Control command: 0x04
    Result:
    0: dialing.
    1: idle.
    2: call failed.
    3: in-call.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example

    55 aa 00 71 00 03 23 04 01 9B

    Receive SMS messages (optional)

    The module sends the received SMS message to the MCU and deletes this message when it confirms that the MCU receives it. This way, there will be enough space for the module to receive a new message.

    The module sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002+N
    Data Data Subcommand: 0x24
    Control command: 0x00
    The message content of n bytes:
    {“n”:”10086”, “t”:”2021-3-29 16:58”“c”:”xxxdfasfd”}
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The MCU returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x24
    Control command: 0x00
    Result: 0 indicates failure. 1 indicates success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The SMS message reported to the cloud is in JSON format, in which n represents phone number, t represents time, and c represents the message content. The encoding format of GB2312 is adopted.

    Send SMS messages (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0002+N
    Data Data Subcommand: 0x24
    Control command: 0x01
    Message content: {“n”:”10086”,“c”:”xxxdfasfd”}
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example: Send a message with the content of Hello in Chinese.

    55aa0371002024017b226e223a223135383930393836373533222c2263223a22c4e3bac3227d A2

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x24
    Control command: 0x01
    Result: 0 indicates failure. 1 indicates success.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Example: Send a message with the content of Hello in Chinese.

    55aa00710003240101 99

    Query battery level (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x25
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x25
    The battery level ranges from 0 to 100.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Query battery charging status (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data Data Subcommand: 0x26
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0002
    Data Data Subcommand: 0x26
    Battery charging status:
    1: Battery charging starts.
    2: Battery charging ends.
    3: Battery is low.
    4: Battery runs out.
    5: Battery is removed.
    6: Charger is removed.
    7: Charging fault occurs.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Set volume (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x72
    Data length 2 0x0003
    Data Data Subcommand: 0x87
    Volume type of 1 byte:
  • 1: local volume.
  • 2: call volume.
    The volume ranges from 0 to 100. 0 indicates mute.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x72
    Data length 2 0x0003
    Data Data Subcommand: 0x87
    Volume type of 1 byte:
  • 1: local volume.
  • 2: call volume.
    Result: 0 indicates success. All other values indicate failure.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Audio playback from SD card (optional)

    An SD card support is required to implement this feature.

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0004+N
    Data Data Subcommand: 0x27
    Port of one byte
  • 0: Play with the local speaker.
  • 1: Play with the call uplink.
    Control command of one byte:
  • 0: stop
  • 1: play
  • 2: pause
  • 3: resume
    Audio file format
  • 1: PCM
  • 2: WAVPCM
  • 3: MP3
  • 4: AMR-NB
  • 5: AMR-WB
    The path where the audio files are stored, for example, /sdcard0/ice_8k_16bit.pcm. The path has n bytes and is required for playing audio files.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0005
    Data Data Subcommand: 0x27
    Port number of one byte
    Control command of one byte
    Audio file format
    Result: 0 indicates success. All other values indicate failure.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Query local audio playback status (optional)

    The MCU sends the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x03
    Command 1 0x71
    Data length 2 0x0001
    Data 1 Subcommand: 0x28
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    The module returns the following command.

    Field Bytes Description
    Header 2 0x55aa
    Version 1 0x00
    Command 1 0x71
    Data length 2 0x0003
    Data Data Subcommand: 0x28
    Audio playback status:
  • 0: idle
  • 1: playing
  • 2: pause
  • 3: finish
    Result: 0 indicates success. All other values indicate failure.
  • Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

    Protocol version

    Version Changes Date Description
    1.0.5 1. Added the GPS positioning query in latitude and longitude format.
    2. Added the return data in JSON for a Wi-Fi positioning mode query.
    3. Added automatic reporting of Wi-Fi positioning.
    4. Added automatic reporting of GPS positioning.
    5. Added getting Unix timestamp with the time zone.
    6. Added offline dynamic password.
    7. Added positional notation settings.
    8. Added cloud temporary password with schedules.
    9. Added automatic reporting of LBS positioning.
    June 2, 2021 None
    1.0.4 1. Added features of phone calls and SMS messages.
    2: Added status query for battery level and battery charging.
    3: Added local audio playback.
    March 18, 2021 None
    1.0.3 1. Added APN option.
    2. Added on/off control command for the GNSS power source.
    3: Added supports for the LZ211 module.
    4: Added LBS positioning.
    5: Added network status of cellular registration denied.
    March 5, 2021 1: Added APN setting in the MCU response to product information queries.
    2: Added GNSS Subcommand: 0x85, which only applies to the LZ211 module.
    1.02 1. Added GPS and Wi-Fi positioning function.
    2. Removed minimum mode.
    3. Added module function test.
    4. Added positioning mode selection.
    December 24, 2020 The minimum mode is not supported currently.
    1.0.1 Added the specific subcommands for Cat.1 protocol. December 17, 2020 Added commands 0x71 and 0x72 for the read and write operations respectively.
    1.0.0 The first release. January 31, 2020 Created Cat.1 general serial protocol.