English
English
简体中文
Contact Us
Register
Log In
Language
English
English
简体中文
Contact Us
Log In
Register
Go to main website
App Develop

App Development Platform

App development platform provides multiple development methods such as no-code or IoT App SDK development to maximize the monetization of IoT apps.
layoutIndex

Serial Port Protocol

Last Updated on : 2021-06-07 06:30:25download

This topic describes Tuya serial protocols used for developing NB-IoT devices with MCU SDK.

Serial communication convention

  • Baud: 9600/115200
  • Data bit: 8
  • Parity check: None
  • Stop bit: 1
  • Data flow control: None
  • MCU: The microcontroller on the control board. It connects to the Tuya module through the serial port. Tuya serial protocol provides full-duplex communication.

Frame format

  • Data greater than one byte shall be transmitted in big-endian mode.

  • The sample data in the protocol is in hexadecimal.

  • When the packet sent by the NB-IoT module times out after one second, the resend mechanism will resend three packets.

  • One command 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 fails to receive the correct response packet within the stipulated period, the transmission times out.

    Note: For specific communication modes, see the section protocol details.

  • The MCU reports the status in a synchronous way. Assume that the MCU reports command y. The data transmission is as follows.

    Serial Port Protocol
    Field Length (byte) Description
    Header 2 It is fixed as 0x55aa.
    Version 1 It is used for update and extension.
    Command 1 Specific frame type.
    Data length 2 Big-endian.
    Data N The data packet contains the data passed down from the network layer, such as IP data packet.
    Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Basic protocol

Query product information

Product information consists of product ID (PID) and the MCU software version.

  • PID: It is automatically generated for each product created on the Tuya IoT Platform to record product information in the cloud.
  • MCU software version number: Defined as dot-decimal notation in the format of x.x.x (0<= x <=99), and x is a decimal digit.

The module sends the following command:

Field Length (byte) 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:

55 aa 00 01 00 00 00

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x01
Data length 2 N
Data N {“p”:“gl9iswyeobu5s93j”, “v”:“1.0.0”, “s”:“psm”, “c”:“isp”}
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Data

Parameter Description
p Product ID. It is the PID of a product created on the Tuya IoT Platform.
v The MCU version.
s The power consumption mode of a device.
  • psm: Power saving mode.
  • drx: Discontinuous reception mode.
  • edrx: Extended discontinuous reception mode.
c How the device is connected to the cloud.
  • isp: Forwarded to Tuya Cloud through the carrier.
  • tuya: Directly connected to Tuya Cloud.

Example:

55 AA 00 01 00 38 7B 22 70 22 3A 22 67 6C 39 69 73 77 79 65 6F 62 75 35 73 39 33 6A 22 2C 22 76 22 3A 22 31 2E 30 2E 30 22 2C 22 73 22 3A 22 70 73 6D 22 2C 22 63 22 3A 22 69 73 70 22 7D 02

Report device network status

Device network status Description Status value
Status 1 Searching for NB-IoT network. 0x01
Status 2 NB-IoT network is found. 0x02
Status 3 The device is connected to the telecom platform and is not bound yet. 0x03
Status 4 The device is bound and connected to Tuya Cloud. 0x04

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x02
Data length 2 0x0001
Data 1 Indicate the working status of the NB-IoT module:
0x01: Status 1
0x02: Status 2
0x03: Status 3
0x04: Status 4
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

The device is bound and connected to Tuya Cloud.

55 aa 00 02 00 01 04 06

The MCU returns the following command:

Field Length (byte) 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:

55 aa 00 02 00 00 01

Reset NB-IoT module

The device is reset. The module is restored to factory settings and sends an activation request to the cloud.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
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:

55 aa 00 03 00 00 02

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
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:

55 aa 00 03 00 00 02

Report real-time status

Note: The device must be connected to the cloud. Otherwise, reporting real-time status will fail.

The MCU can report real-time data status to the module through the real-time status reporting command.

  • This command works in a synchronous way. After reporting data, the MCU waits for the result returned by the module. With a good signal, the MCU can receive the result from the cloud within five seconds.
  • Support reporting single or multiple data units. You can select the packet sending mode as needed. For more information about the data packet, see the following example.

Scenario

Devices that require live status, such as alarms.

The MCU sends the following command command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x05
Data length 2 It depends on types and the number of status data units.
Data N One or multiple status data unit groups.
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 Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x05
Data length 2 0x0001
Data 1 0x00: Success. 0x01: Failure.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example of reporting a single status data unit

Status data: DP 109, 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

Status data 1: DP 109, Boolean variable, and the value is 1.
Status data 2: DP 102, string variable, and the value is an ASCII code of 201804121507.

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

Report record type data

Since the record type data combines the data of multiple DPs. The MCU shall reported them as a whole. Send the following command to the NB-IoT module for reporting. If the device is offline during data reporting, this piece of data will be temporarily stored on the module. When the device is online and data is reported, the module will report the stored data again.

  • Retained data: If the module stores the retained data, each time it successfully reports a piece of the retained data the module will send a response packet including command (0x08) and data (0x01), and notify the MCU.
  • Device networking: If the network works properly, it takes about 30 seconds for the module to connect to the server after the first power-on. After that, whenever a record is generated, the MCU can wait for the device network status packet. If the MCU does not receive the report that the module is successfully connected to the server after waiting for six seconds, it can use this command to report data.
  • Data length limit: The maximum length of a data area in one reported record (multiple status data units) is 100. The finally combined and actually stored data length might change, depending on the actual data point. When no network is available, in case of exceeding the stipulated length, the NB-IoT module will return the result that the record cannot be sent.
  • Limits on the number of records: The maximum number of historical records that the module can store is 20. In case of exceeding the limit, the earliest records will be overwritten.
  • Return status: After the NB-IoT module receives a piece of data and successfully reports it, it will return a status report on successful data reporting.
    • 00: Pushed successfully.
      • The NB-IoT module successfully reports all data without any retained data.
      • The module is not connected to the network, and records are successfully stored in the flash.
    • 01: Pushed successfully with retained data.
    • 02: Failed to push.
  • Timestamp: Include time data when data is reported to ensure that the reporting time without network access is consistent with that with network access. If the time data is generated when the data 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. When the device is paired with the NB-IoT module for the first time, if the network is connected, it is recommended to get accurate time data through the protocol. Each time when a record with the current device time data is transmitted, the server recognizes the time that is given by the device.

Scenario

Smart locks report record type data of multiple DPs to the server, which is processed as one message. In the 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.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x08
Data length 2 It depends on types and the number of status data units.
Data 7


MCU timestamp is required, in the following format:
Data[0] is the year, and 0x00 represents the year of 2000.
Data[1] is the month, ranging from 1 to 12.
Data[2] is the day, ranging from 1 to 31.
Data[3] is the hour, ranging from 0 to 23.
Data[4] is the minute, ranging from 0 to 59.
Data[5] is the second, ranging from 0 to 59.
Data[6] is the week, ranging from 1 to 7, and 1 represents Monday.
Note: If the module’s timestamp is used, the value for this field is 0. The module will automatically populate the internal RTC time to the record type data.
Data transmitted N One or multiple status data unit groups.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

  • Single status data unit

    The DP of 109 is a Boolean type variable, and the value is 1. The time is based on the internal RTC time of the module.

    55 aa 00 08 00 0c 00 00 00 00 00 00 00 6d 01 00 01 01 d1
    
  • Multiple status data units

    • Status data 1: DP 109, Boolean variable, and the value is 1.
    • Status data 2: The DP of 102 is a string type variable, and the value is an ASCII code of 201804121507. The time is based on the server’s time.
    55 aa 00 08 00 1c 00 00 00 00 00 00 00 6d 01 00 01 01 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 a7
    

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x08
Data length 2 0x0001
Data 1
  • 0X00: Reported successfully.
  • 0x01: The current record is reported successfully, and the retained record is to be reported.
  • 0x02: Failed to report.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Module sends commands

Sending command is an asynchronous processing protocol. When the MCU receives the control packet, it responds to the module about the reception and controls the device accordingly. Then, the MCU reports relevant DP status.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x09
Data length 2 It depends on the type and number of the command data unit.
Data N See the section of command 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 system switch corresponds to DP 3, uses boolean variable, and the value of 1 indicates power-on.

55 aa 00 09 00 05 03 01 00 01 01 13

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x09
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:

55 aa 00 09 00 00 08

Command/status data unit

The data unit of DP command and status is shown as follows:

Field property Length (byte) Description
dpid 1 DP number
type 1 Correspond to the data type specified in the Tuya IoT Platform:
  • raw: raw type. The module sends raw data.
    • Value: 0x00
    • Length (byte): N
  • bool: boolean type. The value is 0x00 or 0x01.
    • Value: 0x01
    • Length (byte): 1
  • value: integer type. Use a big-endian representation.
    • Value: 0x02
    • Length (byte): 4
  • string: string type.
    • Value: 0x03
    • Length (byte): N
  • enum: enumeration type. Range from 0 to 255.
    • Value: 0x04
    • Length (byte): 1
  • bitmap: fault type. Use a big-endian representation when there is more than one byte.
    • Value: 0x05
    • Length (byte): 1, 2, or 4
len 2 The length is the bytes of the value (big-endian).
value 1/2/4/N Expressed in hexadecimal format. Use a big-endian representation when there is more than one byte.

Note: For data unit of DP command and status, except raw type, all other types belong to obj type. Status data can contain command data units of multiple DPs.

Get local time

  • After the device is connected, the module can query the local time of the device.
  • If the network performance is poor, the query of the local time might fail even if the device is connected to the cloud. For time-dependent devices such as door locks, if the local time is failed to be obtained in the case of local time not being calibrated, a three-second interval to get the time value is required to ensure that the time is successfully obtained.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x06
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:

55 aa 00 06 00 00 05

The module returns the following command:

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

Example:

Local time of Monday, September 17, 2018, 16:09:05.

  • If the device is activated in mainland China, the local time is Beijing time (GMT+08:00).
  • If the device is activated in other countries or regions, the local time is the time zone in which the device is located.
55 aa 00 06 00 08 01 12 09 11 10 09 05 01 59

Get GMT time

  • Greenwich Mean Time (GMT) is independent of time zone and daylight saving time. Devices such as door locks with dynamic password functions do not need to display the local time. When record type data is reported, only the GMT is required.
  • If devices such as door locks with dynamic password functions need to display the local time, both local time and GMT are required, and the time difference between the local time and GMT is saved locally. GMT plus the time difference is the local time to be displayed.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x10
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:

55 aa 00 10 00 00 0F

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x10
Data length 2 0x0008
Data 8 The data length is eight bytes:
Data[0] is the flag indicating whether the data is successfully obtained.
0 means failure.
1 means success.
Data[1] is the year, and 0x00 represents the year 2000.
Data[2] is the month, ranging from 1 to 12.
Data[3] is the day, ranging from 1 to 31.
Data[4] is the hour, ranging from 0 to 23.
Data[5] is the minute, ranging from 0 to 59.
Data[6] is the second, ranging from 0 to 59.
Data[7] is the week, ranging from 1 to 7, and 1 represents Monday.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

Local time of Monday, September 17, 2018, 08:21:03.

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

Query NB-IoT signal strength

Query NB-IoT signal strength of the device.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
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:

55 aa 00 0b 00 00 0a

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x0b
Data length 2 0x0002
Data 2 Data[0] value:
  • 0x00: Failure
  • 0x01: Success

When Data[0] is 0x01, Data[0] means RSSI:
  • 0: -140 dBm or less
  • 1: -140 dBm ≤ RSRP < -139 dBm
  • 2: -139 dBm ≤ RSRP <-138 dBm
  • 95: -46 dBm ≤ RSRP < -45 dBm
  • 96: -45 dBm ≤ RSRP < -44 dBm
  • 97: -44 dBm ≤ RSRP
  • 255: Unknown
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 0b 00 02 01 50 5D

Query binding status

Check whether the device has been bound.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbb
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:

55 aa 00 bb 00 00 0a

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbb
Data length 2 0x0001
Data 1 The data length is one byte.
  • 0x00: Not bound.
  • 0x01: Bound.
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 bb 00 01 01 bc

Set sleep lock of NB-IoT module

When the MCU sets the sleep lock to 1, the module cannot enter the sleep mode. When the sleep lock is set to 0, the module will automatically enter power saving mode (PSM) during idle time. In PSM, you can pull down the PSM input pin to wake up the module.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb2
Data length 2 0x0001
Data 1 The data length is one byte.
  • 0x00: Unlock the sleep lock.
  • 0x01: Lock the sleep lock, and disable automatic sleep.
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 b2 00 01 01 00

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb2
Data length 2 0x0000
Data 0 0
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 b2 00 00 b1

Set NB-IoT network heartbeat interval

You can set the NB-IoT network heartbeat interval as needed. The default interval is eight hours.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb3
Data length 2 0x0004
Data 4 uint32_t type is in seconds and big-endian mode.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

Set the heartbeat interval to one hour.

55 aa 00 b3 00 04 00 00 0e 10 da

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb3
Data length 2 0x0001
Data 1
  • 0x01: Set successfully.
  • 0x00: Failed to set.
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 b3 00 01 01 b4

Set wake-up interval for NB-IoT record type data

  • When the record data stored in the flash is not sent successfully, this interval can be used to wake up next time. After the retained data is successfully sent, the default wake-up heartbeat interval will be restored.
  • The minimum wake-up interval is 120 seconds. If the interval is less than 120 seconds, wake-up will be executed at 120 seconds intervals.
  • You can use the wake-up interval to execute fast wake-up for retransmission of emergency record type data.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xc1
Data length 2 0x0004
Data 4 uint32_t type is in seconds and big-endian mode.
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

Set the next wake-up interval to three minutes.

55 aa 00 c1 00 04 00 00 00 b4 78

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xc1
Data length 2 0x0001
Data 1
  • 0x01: Set successfully.
  • 0x00: Failed to set.
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 c1 00 01 01 c2

Send heartbeat packets automatically

With the network heartbeat interval, the module can periodically send heartbeat packets. The MCU can send a heartbeat packet for data synchronization through this command. Generally, this command can be replaced by real-time status reporting, such as reporting battery level.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb1
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:

55 AA 00 B1 00 00 B0

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb1
Data length 2 0x0001
Data 1
  • 0x00: Failed to set.
  • 0x01: Set successfully.
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 B1 00 01 01 B2

Get device network status

Device network status Description Status value
Status 1 Searching for NB-IoT network. 0x01
Status 2 NB-IoT network is found. 0x02
Status 3 The telecom platform is connected, and the device is not bound. 0x03
Status 4 The device is bound and connected to Tuya Cloud. 0x04

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2b
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:

55 aa 00 2b 00 00 2c

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0x2b
Data length 2 0x0001
Data 1 Indicate the working status of the NB-IoT module:
  • 0x01: Status 1
  • 0x02: Status 2
  • 0x03: Status 3
  • 0x04: Status 4
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

The device is bound and connected to Tuya Cloud.

55 aa 00 2b 00 01 04 2f

Get international mobile subscriber identity (IMSI)

The MCU can send a command to the module for the IMSI.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb5
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:

55 AA 00 B5 00 00 B4

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb5
Data length 2 0x000F
Data 15 For example, 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 B5 00 0F 34 36 30 31 31 33 30 31 32 34 36 37 33 34 30 BD

Get SIM card number (ICCID)

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

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb6
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:

55 AA 00 B6 00 00 B5

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb6
Data length 2 0x0014
Data 20 For example, 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 B6 00 14 38 39 38 36 31 31 31 38 32 34 39 30 30 30 33 36 33 34 39 30 DB

Get extended signal quality (CESQ)

The MCU can send a command to the module for the CESQ.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb7
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:

55 AA 00 B7 00 00 B6

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb7
Data length 2 0x0006
Data 6 It consists of RxLev, BER, RSCP, Ec/No, RSRQ, and RSRP.
BYTE[0] 1 RxLev: Represent the received signal level measured in dBm units.
  • 0: -100 dBm or less
  • 1: -110 dBm ≤ RSSI < -109 dBm
  • 2: -109 dBm ≤ RSSI <-108 dBm
  • 61: -50 dBm ≤ RSSI < -49 dBm
  • 62: -49 dBm ≤ RSSI < -48 dBm
  • 63: -48 dBm ≤ RSSI
  • 99: Unknown
BYTE[1] 1 BER: Represent the bit error rate.
  • 0 to 7: RxQual values
  • 99: Unknown
BYTE[2] 1 RSCP: Represent the received signal code power.
  • 0: -120 dBm or less
  • 1: -120 dBm ≤ RSCP < -119 dBm
  • 2: -119 dBm ≤ RSCP <-118 dBm
  • 94: -27 dBm ≤ RSCP < -26 dBm
  • 95: -26 dBm ≤ RSCP < -25 dBm
  • 255: Unknown
BYTE[3] 1 Ec/No: Represent the ratio between the received energy from the pilot signal CPICH per chip (Ec) to the noise density (No).
  • 0: -24 dBm or less
  • 1: -24 dBm ≤ Ec/Lo < -23.5 dBm
  • 2: -23.5 dBm ≤ Ec/Lo < -23 dBm
  • 47: -1 dBm ≤ Ec/Lo < -0.5 dBm
  • 48: -0.5 dBm ≤ Ec/Lo < 0 dBm
  • 49: 0 dBm ≤ Ec/Lo
  • 255: Unknown
BYTE[4] 1 RSRQ: Represent reference signal receiving quality.
  • 0: -19.5 dB or less
  • 1: -19.5 dB ≤ RSRQ < -19 dB
  • 2: -19 dB ≤ RSRQ < -18.5 dB
  • 32: -4 dB ≤ RSRQ < -3.5 dB
  • 33: -3.5 dB ≤ RSRQ < -3 dB
  • 34: -3 dB ≤ RSRQ
  • 255: Unknown
BYTE[5] 1 RSRP: Reference signal received power
  • 0: -140 dBm or less
  • 1: -140 dBm ≤ RSRP < -139 dBm
  • 2: -139 dBm ≤ RSRP < -138 dBm
  • 95: -46 dBm ≤ RSRP < -45 dBm
  • 96: -45 dBm ≤ RSRP < -44 dBm
  • 97: -44 dBm ≤ RSRP
  • 255: Unknown
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 B7 00 06 28 00 FF FF 22 44 48

Set activity timer T3324

Note: This command requires a SIM card.

The MCU sends a T3324 active timer command packet. This command can be used to set the timeout (in seconds) for the module to enter PSM mode from idle mode.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb9
Data length 2 0x0004
Data 4
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 B9 00 04 00 00 00 78 34

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xb9
Data length 2 0x0001
Data 1
  • 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.

Example:

55 AA 00 B9 00 01 01 BA

Detect battery level during firmware update

For devices supplied by dry cell batteries, if the battery runs out during firmware update, the module might not work properly. Therefore, sufficient battery capacity is required for a firmware update.

When a firmware update is triggered on the app and the firmware is downloaded, the app will request the battery level. You shall set a threshold of sufficient battery capacity (usually greater than 50%) to respond to the module.

Note: Devices that are not supplied by dry cell batteries can respond that the firmware update starts with a sufficiently charged battery.

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbc
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:

55 AA 00 BC 00 00 BB

The MCU returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbc
Data length 2 0x0001
Data 1
  • 0x00: Battery is low.
  • 0x01: Battery is okay.
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 BC 00 01 01 BD

Get international mobile equipment identity (IMEI)

The MCU can send a command to the module for the IMEI. The module returns a 15-digit IMEI to the MCU.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbd
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:

55 AA 00 BD 00 00 BC

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbd
Data length 2 0x000f
Data 15 For example, 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 BD 00 0F 38 36 34 32 33 37 30 34 30 30 31 34 37 33 33 CF

Report device operating status

Operating status Description Status value
Status 1 Device is initializing. 0x00
Status 2 Device detects SIM card. 0x01
Status 3 Device works properly. 0x02
Status 4 Device is bound. 0x03
Status 5 Device is unbound. 0x04
Status 6 Device successfully downloads schema. 0x05
Status 7 Device is about to sleep. 0x06
Status 8 Device is about to reboot. 0x07

The module sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbe
Data length 2 0x0001
Data 1 Indicate the working status of the NB-IoT module:
  • 0x00: Status 1
  • 0x01: Status 2
  • 0x02: Status 3
  • 0x03: Status 4
  • 0x04: Status 5
  • 0x05: Status 6
  • 0x06: Status 7
  • 0x07: Status 8
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

Device works properly.

55 aa 00 be 00 01 02 c0

Get device operating status

Operating status Description Status value
Status 1 Device is initializing. 0x00
Status 2 The device detects the SIM card. 0x01
Status 3 Device works properly. 0x02
Status 4 Device is bound. 0x03
Status 5 Device is unbound. 0x04
Status 6 Device successfully downloads schema. 0x05
Status 7 Device is about to sleep. 0x06
Status 8 Device is about to reboot. 0x07

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbf
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:

55 aa 00 bf 00 00 be

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xbf
Data length 2 0x0001
Data 1 Indicates operating status of the NB-IoT module:
0x00: Status 1
0x01: Status 2
0x02: Status 3
0x03: Status 4
0x04: Status 5
0x05: Status 6
0x06: Status 7
0x07: Status 8
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Example:

Device detects a SIM card.

55 aa 00 bf 00 01 01 c0

Set device sleeping

The MCU can send a command packet to the module to make it sleep.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xc0
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:

55 AA 00 C0 00 00 BF

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xc0
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:

55 AA 00 C0 00 00 BF

Set access point name (APN)

If devices cannot recognize the base station APN, you need to manually set the APN for a device through the MCU.

The MCU sends the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xC2
Data length 2 None
Data Depend on specific data {“apn”:“ctnb”,“pdp_type”:“IP”}
Checksum 1 Start from the header, add up all the bytes, and then divide the sum by 256 to get the remainder.

Data

Parameter Description
apn It represents the APN that the device accesses, depending on the carrier of the SIM card. For example,
  • ctnb: China Telecom
  • cmnbiot: China Mobile
pdp_type It represents the type of the packet data protocol, and IP is used by default.
  • IP: Internet Protocol (IETF STD 5)
  • IPv6: Internet Protocol version 6 (IETF RFC 2460)
  • IPv4v6: Dual stack
  • Non-IP: Used to transmit non-IP data to the external packet network.

Example:

55 AA 00 C2 00 1E 7B 22 61 70 6E 22 3A 22 63 74 6E 62 22 2C 22 70 64 70 5F 74 79 70 65 22 3A 22 49 50 22 7D 6B

The module returns the following command:

Field Length (byte) Description
Header 2 0x55aa
Version 1 0x00
Command 1 0xC2
Data length 2 0x0001
Data 1
  • 0x00: Succeeded.
  • 0x01: Failed.
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 C2 00 01 00 C2

Update history

Version Date Description
0.6.11 November 30, 2020 Added the use of MCU timestamp for record type data.
0.6.10 November 19, 2020 Added the command to set device APN.
0.6.9 November 16, 2020 Updated the return status of the heartbeat interval.
0.6.8 August 17, 2020 Updated display styles of the NB-IoT network signal strength.
0.6.7 August 13, 2020 Added power consumption mode and cloud connection method in the product information query.
0.6.6 July 27, 2020 Added wake-up time function of record type data.
0.6.5 May 14, 2020 Added SIM card detection, device binding, unbinding, and schema download in the command of querying and sending device status.
0.6.4 April 28, 2020 Added a command to query and send device status. Added a command to force the device to enter sleep.
0.6.3 April 16, 2020 Added the command to send device IMEI information.
0.6.2 November 9, 2019 Added the command to send heartbeat packets.
0.6.1 September 5, 2019 Updated the time field rules in the record type reporting protocol.
0.6.0 June 24, 2019 Updated Wi-Fi information.
0.5.2 March 20, 2019 Updated sleeping lock description.
0.5.1 March 8, 2019 Inherited from the documentation of Wi-Fi lock general connection.