MCU 对接协议

更新时间：2024-06-20 08:48:17下载pdf

本文介绍 NB-IoT 通讯方式设备采用 MCU SDK 开发时使用的涂鸦串口协议。

串口通信要求

波特率：9600/115200
数据位：8
奇偶校验：无
停止位：1
数据流控：无
MCU：控制板控制芯片，与涂鸦模组通过串口对接。在涂鸦的协议设计上，所有包的交互均为全双工通信。

帧格式

大于 1 字节的数据均采用大端模式传输。
协议中举例数据为十六进制。
NB 模组主动发起的通信发送包超时时长为 1 秒，重发机制会重发三包。
通常采用同命令字一发一收同步机制，即一方发出命令，另一方应答。若发送方超时未收到正确的响应包，则视为超时传输。

说明：具体通信方式以协议详述章节为准。

MCU 状态上报则采用同步模式，MCU 状态上报命令字为 y，如下所示：

MCU 对接协议

字段	长度（Byte）	说明
帧头	2	固定为 0x55aa。
版本	1	升级扩展用。
命令字	1	具体帧类型。
数据长度	2	大端。
数据	N	数据部分包含网络层传下来的数据，例如 IP 数据包等。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

基础协议

查询产品信息

产品信息由 Product ID、MCU 软件版本构成。

Product ID：对应涂鸦开发者平台 PID（产品标识），由涂鸦云开发者平台生成，用于云端记录产品相关信息
MCU 软件版本：版本号格式采用点分十进制形式。例如x.x.x，其中 0<=x<=99，x 为十进制数。

模组发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x01
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组发送示例

55 aa 00 01 00 00 00

MCU 返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x01
数据长度	2	N
数据	N	{“p”:“gl9iswyeobu5s93j”, “v”:“1.0.0”, “s”:“psm”, “c”:“isp”}
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

数据

参数	说明
p	产品 ID，即在开发者平台所创建的产品的 PID。
v	MCU 版本。
s	设备的功耗模式。 psm：省电模式 drx：不连续接收模式 edrx：扩展不连续接收模式
c	设备连接云的方式。 isp：通过运营商平台转发到涂鸦云 tuya：直接连接涂鸦云

MCU 返回示例

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

报告设备联网状态

设备联网状态	描述	状态值
状态 1	搜索 NB 网络中。	0x01
状态 2	已搜索 NB 网络。	0x02
状态 3	已连接到电信平台，设备未绑定。	0x03
状态 4	设备已绑定，已连接到涂鸦云。	0x04

模组发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x02
数据长度	2	0x0001
数据	1	指示 NB-IoT 模组工作状态： 0x01 : 状态 1 0x02 : 状态2 0x03 : 状态 3 0x04 : 状态 4
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组发送示例

设备已绑定，已连接到涂鸦云。

55 aa 00 02 00 01 04 06

MCU 返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x02
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 返回示例

55 aa 00 02 00 00 01

重置 NB 模组

设备将会重置一切设置，并刷新模组到出厂状态，然后模组重新向云端请求激活。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x03
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 03 00 00 02

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x03
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回示例

55 aa 00 03 00 00 02

实时状态上报

注意：设备联网状态必须为已连接到云端，否则实时状态上报命令将执行失败。

MCU 可以通过实时状态上报命令，将数据的实时状态上报到模组。

采用同步命令机制，即 MCU 数据上报后需等待模组返回上报结果。在信号良好情况下，通常在 5 秒内可收到云端的上报应答结果。
命令支持单个或多个数据单元上报。用户根据需要选择发送组包的方式。具体数据包参见示例。

使用场景

要求实时推送状态的设备，类似报警器等。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x05
数据长度	2	取决于状态数据单元类型以及个数。
数据	N	一个或多个组合状态数据单元组。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x05
数据长度	2	0x0001
数据	1	0x00 成功 0x01 失败
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

单个状态数据单元上报样例

状态数据：DP 点 109，bool 型变量，数值为 1。

55 aa 00 05 00 05 6d 01 00 01 01 79

多个状态数据单元上报样例

状态数据 1：DP 点 109，bool 型变量，数值为 1。
状态数据 2：DP 点 102，string 型变量，数值为 “201804121507”（具体传输对应 ASCII 值）。

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

记录型状态上报

MCU 的记录型数据是由多个 DP 点组合的整条数据，因此需要整体上报。上报可通过向 NB 模组发送下方描述的命令。若数据上报时设备断网，这条数据则会暂时在模组端存储，在下次网络通畅、有数据上报时，模组会再次上传存储的数据。

滞留数据：当模组存在滞留的记录时，每上报成功一条内容，模组就会主动发送一条命令字为 08，数据为 01 的回复包，并告知 MCU。
设备联网：当网络状态正常时，模组首次上电需要大约 30 秒以连接服务器。此后每当记录产生时，可以先让 MCU 等待报告设备联网状态章节所描述的设备联网状态包。但是若等待 6 秒以上还没收到模组连接成功的状态报告，也可选择使用该条指令上报数据，且此后重复等待模组联网成功并返回上报结果。
数据长度限制：单次记录上报的数据区域（多个状态数据单元）最大长度为 100，根据实际的 DP 点的数据的不同，最后组合实际储存的长度可能会有所变化，因此当模组没有网络时，超过限制长度的数据上报会导致 NB 模组返回记录发送失败。
记录条数限制：模组可以储存历史记录的条数最长限制为 20 条。当超过 20 条后，模组会从最早储存的记录开始循环覆盖。
返回状态：NB 模组接收到一条数据并成功上报后会返回上报成功的状态报告。
- 00：推送成功
  - 推送成功且模组无滞留数据
  - 模组未连接网络，单记录成功存储进闪存
- 01：推送成功但模组存在滞留数据
- 02：推送失败。
时间标记：在数据上报时添加时间数据，是为了保证记录数据在设备没有网络的情况下，上报的时间和有网络时上报的时间一致。如果以到达服务端的时间为准，则当设备暂时处于没有网络的状态时，产生的记录数据会和在下次网络恢复正常后上传的记录时间不符合。所以每当设备第一次和 NB 模组配网的时候，在网络环境可以保证的情况下，MCU 最好可以通过协议获取一次准确的时间数据。之后上传记录的时候带上当前设备的时间数据。服务端的记录时间也以设备提供的时间为准。

使用场景

对于类似门锁等包含多个需要上报到服务端、当作整条信息处理的 DP 点数据的类记录型的设备，若设备短暂断网，本命令会要求设备暂存无法上报成功的数据，以满足记录型设备的上报需求。命令上报需要带上本地的时间。

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	取决于状态数据单元类型以及个数。
数据	7	需要使用 MCU 的时间戳时，按以下信息格式： Data[0] 为年份，0x00 表示 2000 年 Data[1] 为月份，从 1 开始到 12 结束 Data[2] 为日期，从 1 开始到 31 结束 Data[3] 为时钟，从 0 开始到 23 结束 Data[4] 为分钟，从 0 开始到 59 结束 Data[5] 为秒钟，从 0 开始到 59 结束 Data[6] 为星期，从 1 开始到 7 结束，1 代表星期一说明：需要使用模组的时间戳时，只需要将该字段填充 0。模组内部将自动将内部 RTC 时间填充到记录型数据上。
模组发送	N	一个或多个组合状态数据单元组
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

单个状态数据单元

DP 点 109，bool 型变量，数值为 1 。以模组内部 RTC 时间为准。
```
55 aa 00 08 00 0c 00 00 00 00 00 00 00 6d 01 00 01 01 d1
```
多个状态数据单元
- 状态数据 1：DP 点 109，bool 型变量，数值为 1。
- 状态数据 2：DP 点 102，string 型变量，“201804121507”（具体传输对应 ASCII 值）。以服务端时间为准。
```
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
```

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	0x0001
数据	1	0x00：上报成功。 0x01：当前记录上报成功，滞留记录待上报。 0x02：上报失败。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组命令下发

命令下发为异步处理协议，MCU 收到相关控制包，确认接收到回复下发包后，完成相关的控制动作。MCU 状态反馈通过 MCU 的状态上报实现。

模组发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x09
数据长度	2	取决于命令数据单元类型以及个数。
数据	N	命令数据单元组。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组发送信息示例

系统开关对应 3 号 DP，使用 bool 型变量，开机数值为 1。

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

MCU 返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x09
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 返回信息示例

55 aa 00 09 00 00 08

命令/状态数据单元

Datapoint 命令/状态数据单元如下所示。

数据字段属性	长度（字节）	说明
dpid	1	功能点序号
type	1	对应开放平台上功能点具体的数据类型： raw：raw 型功能点（模组输入）表示值：0x00 长度（字节）：N bool：布尔型，取值为 0x00 或 0x01 表示值：0x01 长度（字节）：1 value：对应 int 类型，大端表示表示值：0x02 长度（字节）：4 string：对应字符串表示值：0x03 长度（字节）：N enum：枚举类型，取值范围 0~255 表示值：0x04 长度（字节）：1 bitmap：故障型，长度大于 1 字节时，大端表示表示值：0x05 长度（字节）：1、2 或 4
len	2	长度对应 value 的字节数（大端）
value	1/2/4/N	hex 表示，大于 1字节采用大端传输

说明：Datapoint 命令/状态数据单元除 Raw 类型外，其他类型均属于 Obj 型。状态数据可含多个 Datapoint 命令数据单元。

获取本地时间

需要等待设备连接上网络（报告设备联网状态）后，开始发送获取本地时间的数据包。
在设备连接上服务器后，在网络情况非常差的情况下，有可能会获取时间数据失败。对于依赖时间的设备（例如门锁），当本地时间没有校准过的情况下获取失败时，需要完善间隔 3 秒的获取时间值的功能，确保时间数据获取成功。

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x06
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 06 00 00 05

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x06
数据长度	2	0x0008
数据	Data	数据长度为(1) 8字节: Data[0] 为是否获取时间成功标志，为 0 表示失败，为 1 表示成功 Data[1] 为年份, 0x00 表示 2000 年 Data[2] 为月份，从 1 开始到 12 结束 Data[3] 为日期，从 1 开始到 31 结束 Data[4] 为时钟，从 0 开始到 23 结束 Data[5] 为分钟，从 0 开始到 59 结束 Data[6] 为秒钟，从 0 开始到 59 结束 Data[7] 为星期，从 1 开始到 7 结束，1 代表星期一
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回示例

本地时间：18 年 9 月 17 日 16 时 9 分 5 秒星期一。

如设备在国内激活使用，则当地时间为北京时间 (东 8 区)。
如果设备在国外激活使用，则当地时间为设备所处时区时间。

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

获取格林威治时间

格林威治时间不带有时区和夏令时等相关因素，因此支持动态密码功能的设备（门锁等）不需要显示设备所在当地时间，本地只需要运行格林威治时间，在使用支持记录型上报的通道时也只需上报格林威治时间。
带动态密码功能的设备（门锁等）如需显示设备所在地的当前时间，在设备本地运行格林威治时间的同时，也需要在定时获取本地时间，并在本地储存格林威治时间和当地时间的时间差，每次显示本地时间时，只需在格林威治时间的基础上加上时间差算出当地时间即可

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x10
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 10 00 00 0F

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x10
数据长度	2	0x0008
数据	8	数据长度为 8 字节: Data[0] 为是否获取时间成功标志，为 0 表示失败，为 1 表示成功 Data[1] 为年份, 0x00 表示 2000 年 Data[2] 为月份，从 1 开始到 12 结束 Data[3] 为日期，从 1 开始到 31 结束 Data[4] 为时钟，从 0 开始到 23 结束 Data[5] 为分钟，从 0 开始到 59 结束 Data[6] 为秒钟，从 0 开始到 59 结束 Data[7] 为星期，从 1 开始到 7 结束，1 代表星期一
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回示例

格林威治时间：2018 年 9 月 17 日 8 时 21 分 3 秒星期一。

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

动态密码校验

协议中的时间数据用于运算当前的动态密码。动态密码运算时间都为当前的格林时间，设备需要给模组格林时间数据。
App 端可以设置动态密码校验权限，动态密码的生成算法会使用管理员密码，来参与结果混算。设备每次请求校验动态密码的时候，都需要给模组当前门锁所有的管理员密码（暂时不支持）。
发送包的数据长度至少为15字节，时间数据+密码+传输的管理员密码组数（不包含可选项管理员密码）

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x12
数据长度	2	0x0006+0x08+0x01+N
数据	6	数据长度为 6 字节: 设备当前格林时间： Data[0] 为年份, 0x00 表示 2000 年 Data[1] 为月份，从 1 开始到 12 结束。 Data[2] 为日期，从 1 开始到 31 结束。 Data[3] 为时钟，从 0 开始到 23 结束。 Data[4] 为分钟，从 0 开始到 59 结束。 Data[5] 为分钟，从 0 开始到 59 结束。
-	8	用户输入的密码数据:Data[6]~Data[13] 数据内容范围为 ‘0’~’9’数据传输使用ASCII码
-	1	管理员密码组数（0~10）有多少组管理员密码后面带上相应组数数据（暂时不支持）默认填0
校验和	1	从帧头开始按字节求和得出的结果对 256 求余

MCU发送带两组长度为 6 的管理员密码的数据包：

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

第一组密码数据：521314
第二组密码数据：521313

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x12
数据长度	2	0x0001
数据	1	0x00 (密码核对通过) 0x01 (密码核对失败)//通信操作错误码 0x02 (设备未激活) 0x03 (数据长度错误)
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回密码校验失败：

55 aa 00 12 00 01 01 13

请求云端临时密码（支持多组）

为将临时密码和其他密码作区分，App 设计上使用 7 位临时密码，门锁主板当检测到用户使用的是多组临时密码才去调用此接口去云端拉取相关数据，更新本地的密码数据和状态，这样可以最大程度节约功耗。
注意模组给门锁给的相关时间数据都是基于格林时间，请门锁本地通过获取格林时间的接口同步自己的时钟数据。
密码每次服务端都是全量下发，门锁需要每次根据服务端返回的所有密码和状态进行更新。

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x13
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

门锁获取当前生效临时密码：

55 aa 00 13 00 00 12

模组返回

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x13
数据长度	2	0x0001+N（临时密码）
数据	1+N	数据长度为1+N字节: Data[0] 为是否获取密码成功标志，为0表示失败，后面不会带上相关密码和有效时间数据，数据内容长度为1，为1表示成功 Data[1] 密码组数（0 ~10）当密码组数为0的时候表示面板没有创建密码。串口传输不会带上相关密码和有效时间数据 Data[2] 密码长度（后面每组的密码长度保持一致） //第一组密码相关数据 Data[3] 密码编号（实际编号需要在密码编号的数据上加900）（1 ~ 50） Data[4] 密码有效次数为 0：表示不限制次数密码-有效期内可以不限次数开门。为 1：表示一次性密码-有效期内只能开一次门 Data[5] 密码当前状态 0：表示密码有效 1：表示面板已经进行了删除操作此密码无效密码生效日期（格林时间） Data[6] 为年份, 0x00 表示 2000年 Data[7] 为月份，从 1 开始到 12 结束 Data[8] 为日期，从 1 开始到 31 结束 Data[9] 为时钟，从 0 开始到 23 结束 Data[10] 为分钟，从 0 开始到 59 结束 Data[11] 为秒钟，从 0 开始到 59 结束密码截至日期（格林时间） Data[12] 为年份, 0x00 表示 2000 年 Data[13] 为月份，从 1 开始到 12 结束 Data[14] 为日期，从 1 开始到 31 结束 Data[15] 为时钟，从 0 开始到 23 结束 Data[16] 为分钟，从 0 开始到 59 结束。 Data[17] 为秒钟，从 0 开始到 59 结束。临时密码（具体字节数N=data[2]）(密码数据传输字符的 ASCII 码) //第二组密码数据…
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

Wi-Fi模组返回当前10组密码数据密码：

55 AA 00 13 00 DF 01 0A 07 0A 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 09 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 08 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 07 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 06 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 05 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 04 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 03 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 02 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 01 00 00 12 06 1C 08 15 07 14 05 16 13 01 07 31 32 33 34 35 36 37 C6

离线动态密码

设备长时间不联网也可使用的动态密码。
MCU发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x16
数据长度	2	N
数据	Year(1)+mon(1)+day(1)+hour(1)+min(1)+sec(1)+code_len(1)+code(n)	格林时间+密码长度+密码
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

例：离线密码：1849455172 格林时间：2021/01/11 08:18:42
55 AA 00 16 00 11 15 01 0B 08 12 2A 0A 01 08 04 09 04 05 05 01 07 02 C3
模组返回

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x16
数据长度	2	N
数据	Result（1）+type（1）+decode_len(1)+decode(n)	Result： 0 正确非0 错误（无后续数据） Type： 0 限时开门密码 1 单次开门密码 2 清除密码 decode_len：解密后数据长度 decode：解密数据
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

查询 NB-IoT 信号强度

查询设备 NB-IoT 的信号强度。

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0b
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 0b 00 00 0a

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0b
数据长度	2	0x0002
数据	2	Data[0] 取值： 0x00：失败 0x01：成功当 Data[0] 为 0x01 时，Data[0] 表示 RSSI 即： 0：-140 dBm 或以下 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：未知
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回示例

55 aa 00 0b 00 02 01 50 5D

查询绑定状态

查询设备是否已经被用户绑定。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbb
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 bb 00 00 0a

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbb
数据长度	2	0x0001
数据	1	数据长度为 1 字节。 0x00：未绑定 0x01：绑定
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

55 aa 00 bb 00 01 01 bc

设置 NB 模组睡眠锁

MCU 将睡眠锁设置为 1 后，模组将禁止进入睡眠。设置为 0 后，模组将自动在 IDLE 进入 PSM 模式低功耗待机。在 PSM 模式下，可以拉低 PSM-INT 引脚，唤醒模组。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb2
数据长度	2	0x0001
数据	1	数据长度为 1 字节。 0x00：解锁睡眠锁。 0x01：锁住睡眠锁，禁止自动进入睡眠。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 b2 00 01 01 00

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb2
数据长度	2	0x0000
数据	0	0
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

55 aa 00 b2 00 00 b1

设置 NB-IoT 网络心跳间隔时间

用户可以根据自己的业务需求，设置模组的 NB-IoT 网络心跳周期，默认心跳间隔是 8 小时。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb3
数据长度	2	0x0004
数据	4	uint32_t 类型，单位为秒，大端格式。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

设置心跳间隔为 1 小时。

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

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb3
数据长度	2	0x0001
数据	1	0x01：设置成功 0x00：设置失败
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

55 aa 00 b3 00 01 01 b4

设置 NB-IoT 记录型数据唤醒间隔时间

Flash 内记录型数据未成功发出时，使用该时间进行下一次唤醒。记录型数据成功发出后，恢复默认的唤醒心跳间隔。
最小唤醒间隔 120 秒。如果设置时间小于 120 秒，按照 120 秒执行。
用户可以设置记录型数据唤醒时间功能，进行紧急记录型数据发送的快速唤醒重发。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xc1
数据长度	2	0x0004
数据	4	uint32_t 类型，单位为秒，大端格式。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

设置下一次唤醒间隔为 3 分钟。

55 aa 00 c1 00 04 00 00 00 b4 78

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xc1
数据长度	2	0x0001
数据	1	0x01：设置成功 0x00：设置失败
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

55 aa 00 c1 00 01 01 c2

自动发送心跳包

通过设置网络心跳间隔时间，模组将周期性的自动发送心跳包，本命令可以由 MCU 控制主动发送一个心跳包，以用于主动同步下发数据。在通常情况下，可以由实时状态上报（例如上报电量）替代本命令的功能。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb1
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 B1 00 00 B0

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb1
数据长度	2	0x0001
数据	1	0x00：设置失败 0x01：设置成功
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息

55 AA 00 B1 00 01 01 B2

获取设备联网状态

设备联网状态	描述	状态值
状态 1	搜索 NB 网络中	0x01
状态 2	搜索到 NB 网络	0x02
状态 3	已连接到电信平台，设备未绑定	0x03
状态 4	设备已绑定，已连接到涂鸦云	0x04

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2b
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送示例

55 aa 00 2b 00 00 2c

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2b
数据长度	2	0x0001
数据	1	指示 NB 模组工作状态： 0x01：状态 1 0x02：状态 2 0x03：状态 3 0x04：状态 4
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

设备已绑定，已连接到涂鸦云。

55 aa 00 2b 00 01 04 2f

获取国际移动用户识别码 IMSI

本命令可以由 MCU 主动发送 IMSI 获取包，获取模组的国际移动用户识别码。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb5
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 B5 00 00 B4

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb5
数据长度	2	0x000F
数据	15	示例：`460113012467340`。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 B5 00 0F 34 36 30 31 31 33 30 31 32 34 36 37 33 34 30 BD

获取 SIM 卡识别码 ICCID

MCU 主动下发指令至模组，获取 ICCID 指令，模组将 ICCID（长度 20 的字串）返回给 MCU。本命令可以由 MCU 控制，主动发送 ICCID 获取包，以用于获取模组的 SIM 卡识别号码。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb6
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 B6 00 00 B5

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb6
数据长度	2	0x0014
数据	20	示例：`89861118249000363490`。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

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

获取拓展信号质量 CESQ

本命令可以由 MCU 控制，主动发送 CESQ 获取包，以获取模组的拓展信号质量参数。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb7
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 B7 00 00 B6

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb7
数据长度	2	0x0006
数据	6	由 ReLev, BER, RSCP, ECNO, RSRQ, RSRP 组成。
BYTE[0]	1	RXLev：接收信号强度等级 0：-100 dBm 或以下 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：未知
BYTE[1]	1	BER：信道位错误百分率 0~7：RxQual valuses 99：未知
BYTE[2]	1	RSCP：接收信号码功率 0： -120dBm or less 1： -120dBm≤RSCP<-119dBm 2 ： -119dBm≤ RSCP<-118dBm … 94： -27dBm ≤RSCP<-26dBm 95： -26dBm ≤ RSCP<-25dBm 255：未知
BYTE[3]	1	Ecno：Ec/No 0： -24dBm or less 1： -24dBm ≤Ec/Lo<-23.5dBm 2： -23.5dBm ≤Ec/Lo<-23dBm … 47： -1dBm ≤ Ec/Lo<-0.5dBm 48： -0.5dBm ≤Ec/Lo<0dBm 49： 0 dBm ≤Ec/Lo 255：未知
BYTE[4]	1	RSRQ : 参考信号接收质量 0： -19.5dB or less 1： -19.5dB ≤RSRQ<-19dB 2： -19dB ≤RSRQ<-18.5dB … 32： -4dB ≤ RSRQ<-3.5dB 33： -3.5dB ≤RSRQ<-3dB 34： -3dB ≤rsrq 255：未知
BYTE[5]	1	RSRP : 参考信号接收功率 0： -140dBm or less 1： -140dBm≤RSRP<-139dBm 2： -139dBm≤RSRP<-138dBm … 95： -46dBm≤ RSRP<-45dBm 96： -45dBm≤RSRP<-44dBm 97： -44dBm≤RSRP 255：未知
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 B7 00 06 28 00 FF FF 22 44 48

设置活动定时器 T3324

说明：本指令需要 SIM 卡支持。

MCU 主动发送一个 T3324 活动定时器指令包。本指令可用于设置模组从空闲模式进入 PSM 模式的超时时间（单位：秒）。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb9
数据长度	2	0x0004

| 数据 | 4 | 活动时间，单位：秒。<br/>例如：活动时间为 120（0x78）秒，即 <ul><li>act_time[0]：0x00<li>ct_time[1]：0x00<li>act_time[2]：0x00<li>act_time[3]：00x78 |

| 校验和 | 1 | 从帧头开始按字节求和，得出的结果对 256 求余。 |

MCU 发送信息示例

55 AA 00 B9 00 04 00 00 00 78 34

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xb9
数据长度	2	0x0001
数据	1	0x00：失败 0x01：成功
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 B9 00 01 01 BA

固件升级电量检测

对于使用电池供电的设备，在模组进行固件升级时，固件升级过程意外断电将可能会导致模组无法正常工作，因此需要电池剩余足够的电量以完成升级整个过程。

当用户 App 触发升级模组且下载完固件后，App 会向 MCU 询问电池电量是否正常。厂商需要根据硬件设计，确定一个电池电量充足的阈值（通常为大于 50%）来应答模组。

说明：不使用电池供电的设备可以直接应答非低电量状态后开始升级。

模组发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbc
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组发送信息示例

55 AA 00 BC 00 00 BB

MCU 返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbc
数据长度	2	0x0001
数据	1	0x00：低电量 0x01：电量正常
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 返回信息示例

55 AA 00 BC 00 01 01 BD

获取设备 IMEI

MCU 主动下发给模组获取 IMEI 指令，模组将 IMEI（长度 15 的字串）返回给 MCU。本命令可以由 MCU 控制，主动发送 IMEI 获取包，以用于获取设备的 IMEI 码。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbd
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 BD 00 00 BC

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbd
数据长度	2	0x000f
数据	15	示例：`864237040014733`。
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 BD 00 0F 38 36 34 32 33 37 30 34 30 30 31 34 37 33 33 CF

报告设备运行状态

设备运行状态	描述	状态值
状态 1	设备初始化中	0x00
状态 2	设备识别到 SIM 卡	0x01
状态 3	设备正常运行中	0x02
状态 4	设备被绑定	0x03
状态 5	设备被解绑	0x04
状态 6	设备成功下载 SCHEMA	0x05
状态 7	设备正准备进入睡眠	0x06
状态 8	设备正准备重启	0x07

模组发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbe
数据长度	2	0x0001
数据	1	指示 NB 模组工作状态： 0x00 : 状态 1 0x01 : 状态 2 0x02 : 状态 3 0x03 : 状态 4 0x04 : 状态 5 0x05 : 状态 6 0x06 : 状态 7 0x07 : 状态 8
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组发送信息

设备正常运行中。

55 aa 00 be 00 01 02 c0

获取设备运行状态

设备运行状态	描述	状态值
状态 1	设备初始化中	0x00
状态 2	设备识别到SIM卡	0x01
状态 3	设备正常运行中	0x02
状态 4	设备被绑定	0x03
状态 5	设备被解绑	0x04
状态 6	设备成功下载SCHEMA	0x05
状态 7	设备正准备进入睡眠	0x06
状态 8	设备正准备重启	0x07

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbf
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 aa 00 bf 00 00 be

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xbf
数据长度	2	0x0001
数据	1	指示NB模组运行状态： 0x00 : 状态 1 0x01 : 状态2 0x02 : 状态 3 0x03 : 状态 4 0x04 : 状态 5 0x05 : 状态 6 0x06 : 状态 7 0x07 : 状态 8
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

设备识别到 SIM 卡。

55 aa 00 bf 00 01 01 c0 ]

设置设备进入睡眠

本命令可以由 MCU 控制主动发送指令包，使模组立刻进入睡眠状态。

MCU 发送

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xc0
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

MCU 发送信息示例

55 AA 00 C0 00 00 BF

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xc0
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 C0 00 00 BF

设置设备访问的 APN

由于设备可能无法识别部分基站的 APN 接入点，所以可由用户从 MCU 端手动配置设备的 APN 名称。

MCU 发送信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC2
数据长度	2	无
数据	取决于具体数据	{“apn”:“ctnb”,“pdp_type”:“IP”}
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

数据

参数	说明
apn	设备访问的 APN 名称，根据当前 SIM 接入的运营商而定。如： ctnb：中国电信 cmnbiot：中国移动
pdp_type	分组数据协议的类型，默认使用 IP 。 IP：互联网协议（IETF STD 5） IPV6：互联网协议版本 6（IETF RFC 2460） IPV4V6：双栈 Non-IP：将非 IP 数据传输到外部分组网络

MCU 发送信息示例

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

模组返回信息

字段	长度（Byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC2
数据长度	2	0x0001
数据	1	0x00：成功 0x01：失败
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

模组返回信息示例

55 AA 00 C2 00 01 00 C2

更新记录

版本	日期	说明
0.6.12	2021.04.01	增加波特率9600/115200自适应说明。
0.6.11	2020.11.30	增加记录型数据使用MCU时间戳。
0.6.10	2020.11.19	新增设置设备APN命令。
0.6.9	2020.11.16	更新设置心跳时间间隔的返回状态。
0.6.8	2020.08.17	更新 MCU 获取查询模组 NB 网络强度中数据呈现形式。
0.6.7	2020.08.13	查询产品信息中，新增功耗模式及云连接方式返回。
0.6.6	2020.07.27	新增记录型数据唤醒时间功能。
0.6.5	2020.05.14	获取/发送设备运行状态信息命令中，新增 SIM 卡识别成功，设备绑定，解绑，schema下载完成等状态。
0.6.4	2020.04.28	新增获取/发送设备运行状态信息命令。新增发送强制设备进入睡眠命令。
0.6.3	2020.04.16	新增发送设备IMEI信息命令。
0.6.2	2019.11.09	新增发送心跳包命令。
0.6.1	2019.09.05	更新记录型上报协议中的时间字段规则。
0.6.0	2019.06.24	更新 Wi-Fi 相关信息。
0.5.2	2019.03.20	更新睡眠锁说明。
0.5.1	2019.03.08	继承 Wi-Fi 通用门锁对接文档。

上一篇NB-IoT 门锁

下一篇可视对讲门锁