门禁协议

本文档主要为涂鸦 Wi-Fi 连接方案中串口协议描述，适用于门锁门禁产品。

串口通信约定

• 波特率：9600/115200/230400

  注意：为避免传图过慢，带传图功能的模组最低波特率需配置为115200。

• 数据位：8
• 奇偶校验：无
• 停止位：1
• 数据流控：无
• MCU：用户控制板控制芯片，与涂鸦模组通过串口对接，这里协议设计上，所有包的交互为全双工通信设计。

帧格式

字段	长度（byte）	说明
帧头	2	固定为0x55aa
版本	1	升级扩展用
命令字	1	具体命令字
数据长度	2	数据长度之后到校验和之前所包含数据的长度
数据	N
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

说明：

• 所有数据均采用大端模式传输。
• 协议中所有举例说明数据都是十六进制数据。
• Wi-Fi 模组主动发起的通信发送包超时时间为 500ms，重传次数为 2 次。

• 一般情况下，采用同命令字一发一收同步机制，即一方发出命令，另一方应答，若发送方超时未收到正确的响应包，则超时传输，如下图所示：

  

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

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

  MCU统计数据上报：

  

协议列表

查询产品信息

产品信息由 PID（Product ID）和 MCU 软件版本构成。

• Product ID：对应 涂鸦 IoT 平台 PID（产品标识），由涂鸦 IoT 平台生成，用于云端记录产品相关信息。
• 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”:“vHXEcqntLpkAlOsy”, “v”:“1.0.0”, “n”:0, “cap”:0}
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

示例：{"p":"vHXEcqntLpkAlOsy","v":"1.0.0","n":0,"cap":0}

• n 为可选字段，表示模式的配网模式，没有该字段保持传统两种配网方式互相切换的模式，配网方式的支持情况由模组确定：

  • Wi-Fi 快连配网&热点配网共存配网模式

    模组同时支持热点配网和 Wi-Fi 快连配网无需用户切换。

  • 仅仅只有热点配网模式

    这种模式下产品只能通过热点连接的方式进行设备配网。

• cap 字段表示设备能力：

  • bit0：表示设备是否需要支持图片上传功能。0 表示不支持，1 表示支持。
  • bit1：表示设备采用哪种通信方式上传图片。0 表示串口，1 表示SPI。
  • bit2：表示设备是否为运营商设备。0 表示不支持，1 表示支持。（暂不支持此功能）
  • bit3：表示设备是否支持模组重置状态通知。0 表示不支持，1 表示支持。
  • 其他位当前默认为 0。您需要为 MCU 做好状态管理，预留位请按照 0 填充。

MCU 返回示例信息：

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

报告设备联网状态

当模组的 Wi-Fi 状态发生变化，则会主动发送 Wi-Fi 状态至 MCU。

联网状态	说明	状态值
状态1	Wi-Fi 快连配网状态	0x00
状态2	热点配网状态	0x01
状态3	Wi-Fi 已配置但未连上路由器	0x02
状态4	Wi-Fi 已配置且连上路由器	0x03
状态5	已连上路由器且连接到云端	0x04
状态6	Wi-Fi 设备处于低功耗模式	0x05
状态7	Wi-Fi 设备处于Wi-Fi 快连配网和ap共存配置状态	0x06 （暂不支持）

说明：

• 状态 1 和状态 2 两种配置状态需要 MCU 做相关的配网显示。
• 原则上，您需要为设备配置两种配网方式。第一种配网方式存在少部分路由兼容性问题，第二种配网方式是确保设备可以联网成功的保障。
• 在未配网前，模组上电默认处于低功耗状态。需要 MCU 主动发 重置Wi-Fi 指令后，模组才会进入配网状态。
• 手机移除设备后，模组进入低功耗状态，需要 MCU 主动发 重置Wi-Fi 指令后，模组才会进入待配网状态。
• Wi-Fi 模组进入配网模式后，如果在 10 秒内未连接路由并且模组断电了，下次模组上电后依旧保持上一次的配网状态。

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x02
数据长度	2	0x0001
数据	1	指示 Wi-Fi 工作状态，状态值请参考 联网状态表
校验和	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

重置 Wi-Fi

重置 Wi-Fi 状态转化如下图所示：

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

重置 Wi-Fi 并选择配置模式

• 相对于 重置Wi-Fi 而言，此帧提供 MCU 根据自身需求选择重置 Wi-Fi 后的配置方式。
• 您可选择性地实现该协议。

MCU发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x04
数据长度	2	0x0001
数据	1	0x00：进入 Wi-Fi 快连配网配置模式 0x01：进入热点配网模式
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

MCU 发送控制模组进入热点配网模式：

55 aa 00 04 00 01 01 05

模组返回：

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

模组返回：

55 aa 00 04 00 00 03

实时状态上报

对于有告警功能，要求实时推送的设备，您可以通过本协议更新状态数据。实现 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 求余

单个状态数据单元上报示例：

55 aa 00 05 00 05 6d 01 00 01 01 79 （DP 109，Boolean 型变量，数值为1）

多个状态数据单元上报示例：

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 （DP 109，Boolean 型变量，数值为1；DP 102，String 型变量，数值为 201804121507，具体传输对应ASCII。）

上报记录型状态

使用场景：

对于门锁设备，包含多个DP数据需要服务端作为整条记录处理，在短暂断网的情况下，本条命令会保存下无法上报成功的数据，本条命令可以满足记录型设备的上报需求。这里的上报需要带上时间为本地时间。

使用说明：

当MCU需要记录型数据是由多个DP组合的整条数据，需要整体上报，可通过该命令往Wi-Fi模组发送。

并且当有数据上报时，如果设备断网，模组会将这条数据储存下来，当下次有数据上报的时候模组再上传这条数据，并把之前的储存数据一并上报。

• 当有滞留记录每次上报成功一条，模组就会主动发送一条08命令字数据为01的回复包。

• 单次记录上报的数据区域(多个状态数据单元)最大长度为80，根据实际的DP的数据最后组合实际储存的长度会有所变化，当无网络的状态下，超过限制长度Wi-Fi模组会返回记录发送失败。

• 模组可以储存历史记录的条数最长限制到400条，当超过400条从最早储存的记录开始覆盖，如此循环覆盖。

• 当Wi-Fi模组接收到一条数据成功推送，或者当没有网络状态下，记录成功存储进flash中也会当做推送成功（00）。当有网络推送成功一条，还有滞留记录的话会返回01，其他的情况均返回推送失败02。

• 协议中时间数据是为了保证记录型数据在设备没有网络的情况下和实际发生的事件一致。如果以记录到达服务端的时间为准，当设备暂时处于没有网络的状态下产生的记录数据，当下次使用网络恢复正常时，这个时候上传的记录时间便和实际发生的事件不符合。所以当WiFi模组配网的时候，网络环境可以保证的情况下，可以通过协议获取当前正确的时间数据。每次上传记录的时候带上当前设备的时间数据，服务端的记录时间便会以设备给的时间为准。

• 由于设备在各地涉及到时区和夏令时等因素，对时间也进行区分处理。当设备没有显示屏的需求时，可根据协议获取格林时间在设备中运行，当有相关数据上报时按照协议填充当前设备运行的格林时间。当某些设备需要显示当地时间时，可以通过协议向模组获取本地时间（该时间会综合计算时区、夏令时的因素确保时间符合当地时间）。当有相关上报数据产生的时候可按照协议填充当前设备运行的本地时间。

MCU发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	取决于 状态数据单元 类型以及个数
数据	7	数据长度为7字节： Data[0]为这条数据传输是否带本地时间标志位： 0：这条数据不带门禁给的时间，后面的时间数据，模组认为数据无效不处理 1：后面的时间数据有效，时间数据为设备所在的当地时间。 2：后面的时间数据有效，时间数据为格林时间。 Data[1]为年份，0x00表示2000年。 Data[2]为月份，从1开始到12结束。 Data[3]为日期，从1开始到31结束。 Data[4]为时钟，从0开始到23结束。 Data[5]为分钟，从0开始到59结束。 Data[6]为秒钟，从0开始到59结束
-	N	一个或多个组合 参考本文 状态数据单元 组
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组返回：

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

具体上报数据包举例：

单个状态数据单元上报示例：

DP 109 bool型变量，数值为1

• 服务端当前时间为准：

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

• 设备本地时间（2018/04/19/ 13点3分29秒）为准

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

• 设备当前格林时间（2018/04/19/ 5点3分29秒）为准

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

多个状态数据单元上报示例：

DP 109 bool型变量，数值为1

DP 102 string型变量，“201804121507”（具体传输对应ASCII值）

• 服务端时间为准

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

• 设备本地时间（2018/04/19/ 13点3分29秒）为准

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

• 设备格林时间（2018/04/19/ 5点3分29秒）为准

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

组合开门方式上报说明：

组合开门方式根据相关的开门方式的DP，一个完整包上传相关组合DP的数据，完成组合开门方式的数据上报。

密码+指纹开锁数据上报：

55 aa 00 08 00 17 00 13 02 0D 06 33 03 02 02 00 04 00 00 00 01 01 02 00 04 00 00 00 05 91

• 密码开锁：02 02 00 04 00 00 00 01
• 指纹开锁：01 02 00 04 00 00 00 05

发送模组命令给 MCU

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

模组发送：

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

模组发送控制命令：

55 aa 00 09 0005 03 01 00 01 01 13 （系统开关对应 3 号DP，使用了 Boolean 型变量，开机数值为1。）

MCU回复：

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

MCU 确认回复：

55 aa 03 09 00 00 0b

获取本地时间

在设备连接上服务器后，但网络情况非常差时，有可能会获取时间数据失败。对于依赖时间的设备，例如门禁类，当本地时间没有校准过的情况下，需要对该协议进行间隔 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	数据长度为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 求余

模组返回本地时间数据：

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

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

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

获取格林时间

格林时间不带有时区和夏令时相关因素。

• 如果设备具有动态密码功能（例如门锁设备），但是不需要显示设备所在的当地时间，本地只需要实现格林时间，记录上传走带记录型上报的通道，上报的时间也需要是格林时间。
• 如果带动态密码功能的设备（如门锁等）需要显示设备所在地的当前时间，除定时获取本地时间外，还需本地储存格林时间和当地时间的时间差。则每次显示本地时间，是在格林时间的基础上加上时间差。

记录上传走带记录型上报的通道，上报的时间也需要是格林时间。

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 求余

模组返回设备格林时间：

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

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

Wi-Fi 功能性测试

• 本条命令多用于设备量产时的产品整机测试使用，产测指令需要在模组上电完成初始化流程以后（回复查询产品信息的数据包）发送。

• 模组在收到该指令后，可根据协议内容进行指定的测试

  • 模组收到0x00扫描指定路由器后，开始扫描指定SSID的路由器，并返回扫描结果。

  • 模组收到0x01扫描指定路由器后，开始连接指定SSID的路由器，并返回结果。

  • 模组收到0x02命令后，进行SPI传图测试，会在5s内等待接收SPI发送的0x61命令，若未收到，则返回失败，若收到61指令则返回成功。

• 扫描指定的SSID，返回的数据中表示扫描结果和信号强度百分比。

• 原则上若扫描成功，才可选择连接指定的路由器。

• 指定的SSID固定为：tuya_mdev_test，密码为：test1234，要求路由器为2.4G信号。

MCU发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x07
数据长度	2	0x0002
数据	2	Data[0]产测功能点 0x00：扫描指定路由器 0x01：连接指定路由器 0x02：SPI传图测试
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

MCU触发模组功能性测试：

55 aa 00 07 00 02 00 00 08（扫描指定路由器）

具体产测步骤及结果回复：

1. 扫描指定路由器

   • Data[0] = 0x00 时表示扫描成功

     • Data[1]表示扫描到的路由器信号强度百分比（0-100）

   • Data[0] = 0x01 时表示扫描失败

     • Data[1] = 0x00 表示未扫描到指定SSID

     • Data[1] = 0x01 表示模组未授权

2. 连接指定路由器

   • Data[0] = 0x00 时表示连接成功

     • Data[1] = 0x00 默认为0x00

   • Data[0] = 0x01 时表示连接失败

     • Data[1] = 0x00 默认为0x00 连接超时

     • Data[1] = 0x01 其他原因失败

3. SPI传图测试

   • Data[0] = 0x00 时表示接收成功

     • Data[1] = 0x00 默认为0x00

   • Data[0] = 0x01 时表示接收失败

     • Data[1] = 0x00 表示超时未收到SPI数据

     • Data[1] = 0x01 表示收到数据包长度错误

模组返回：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x07
数据长度	2	0x0002
数据	2	数据长度为2字节： Data[0]：0x00失败, 0x01成功 当Data[0]为0x01，即成功时：Data[1]表示信号强度 (0-100, 0信号最差，100信号最强) 当Data[0]为0x00，即失败时：Data[1]表示失败原因0x00表示未扫描到指定的ssid。 Data[1]为0x01表示模组未烧录授权key
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组返回测试结果：

55 aa 00 07 00 02 00 50 58

Wi-Fi功能性测试成功信号强度为80

固件升级通知

• 当模组检测到新的固件升级时，会发送通知给MCU，同步升级状态。
• MCU可根据当前状态随时终止升级过程（暂不支持）。

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0f
数据长度	2	0x0002
数据	2	Data[0] 固件类型： 0x00：Wi-Fi固件 0x01：MCU固件 Data[1] 升级状态通知： 0x00：开始检测固件更新 0x01：已经是最新固件 0x02：正在更新固件 0x03：固件更新成功 0x04：固件更新失败
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

Wi-Fi升级状态通知：

55 aa 00 0f 00 02 00 02 12 （正在更新Wi-Fi固件）

MCU返回：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0f
数据长度	2	0x0001
数据	1	Data[0]通知结果： 0x00：收到通知默认返回0 0x01：取消升级（暂不支持）
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

MCU升级状态返回：

55 aa 00 0f 00 01 00 0f （收到升级通知后默认返回0）

升级启动

当MCU触发了模组去升级MCU固件，且服务端也配置了更高版本的MCU固件，且升级方式也符合时，模组便会返回给MCU相关需要升级的MCU固件包的文件大小。

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0d
数据长度	2	0x0004
数据	4	固件包字节数，unsigned int，大端
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组发送文件包大小：

55 aa 00 0d 00 04 00 00 68 00 78 (固件包长度26624，即26KB)

MCU返回：

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

MCU确认包回复：

55 aa 00 0d 00 00 0c

升级包传输

• 升级包传输数据格式：包偏移（unsigned short） + 包数据

• MCU若收到该帧数据长度为4且包偏移>=固件大小，则包传输结束

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0e
数据长度	2	0x0004+数据包长度
数据	N	前四字节，固定为包偏移，后面为数据包内容
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组发送文件数据：

若要升级的文件大小530Byte，(最后一包数据可不回复)

• 第一包数据，包偏移为0x00000000，数据包长度为256字节

  55aa 00 0e 0104 00000000 xx…xx XX

• 第二包数据，包偏移为0x00000100，数据包长度为256字节

  55aa 00 0e 0104 00000100 xx…xx XX

• 第三包数据，包偏移为0x00000200，数据包长度为18字节

  55aa 00 0e 0016 00000200 xx…xx XX

• 最后一包，包偏移为0x00000212，数据包长度为0字节

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

MCU返回：

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

MCU每包数据包确认：

55aa 00 0e 0000 0d

查询当前连接路由信号强度

当需要查询设备连接路由器当前的路由的信号强度时，前提是 MCU收到设备的网络状态包——得知设备已经成功连接上路由器，否则发送此命令将返回失败的结果。

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	数据长度为2字节： Data[0]：0x00失败, 0x01成功。 当Data[0]为0x01，即成功时Data[1]表示信号强度 (0-100, 0信号最差，100信号最强)。 当Data[0]为0x00，即失败时，Data[1]为0x00，表示设备未连接上路由
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组返回当前强度值(80)：

55 aa 00 0b 00 02 01 50 5D

状态数据单元

• datapoint命令/状态数据单元如下所示：

  数据段	长度（byte）	说明
  dpid	1	datapoint序号
  type	1	对应 涂鸦 IoT 平台 上 DP 具体的数据类型,通过如下“表示值”标识
  类型	表示值	长度（字节）	说明
  raw	0x00	N	对应于raw型datapoint（模组透传）
  bool	0x01	1	value范围：0x00/0x01
  value	0x02	4	对应int类型，大端表示
  string	0x03	N	对应于具体字符串
  enum	0x04	1	枚举类型，范围0-255
  bitmap	0x05	1/2/4	长度大于1字节时，大端表示
  len	2	长度对应value的字节数
  value	1/2/4/N	hex表示，大于1字节采用大端传输

• datapoint命令/状态数据单元除”raw”类型外，其他类型均属于“obj”型datapoint

• “状态数据”可含多个datapoint“命令数据单元”

实际开发中的注意事项：

• 整套协议针对使用Wi-Fi模组且没法使用外电的设备。这里我们开发MCU程序的时候，对于断电管理尤为重要，在我们可以完成功能的前提下尽量减少Wi-Fi模组的上电时间，是节约设备功耗的关键。这里对于数据上传部分我们有给出大体的控制流程图，您可以根据自己设备的特性来选择协议中自己需要用到的功能。实际的开发中您可以根据自己的需要实时调整相关控制逻辑。

• 实际产品很多情况下，设备不开启Wi-Fi功能也可以正常使用，或者不排除用户在拿到设备的同时由于种种原因不使用Wi-Fi功能。 为了防止这种情况下给Wi-Fi模组上电造成不必要的电能损耗，我们在设备端可以设计一个物理按键或者相关选项，只有当用户主动打开这个按键或则选项时，我们MCU才在每次数据变动的时候才去给Wi-Fi模组上电传输相关数据。

离线动态密码

设备长时间不联网也可使用的动态密码，目前可存储的离线密码的最大数量为200条。

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 求余

模组回复：

字段	长度（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 求余

上报MCU的SN号

通过这个接口可将MCU的SN号上报至平台。

MCU发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x17
数据长度	2	N
数据	sn_len(1) + sn(n)	Sn长度（长度不得超过32byte）+SN
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组回复：

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

模组重置状态通知

设备重置状态	描述	状态值
状态1	模组本地重置	0x00
状态2	App远程重置	0x01
状态3	App恢复出厂重置	0x02
状态4	本地数据清除，但设备不离网	0x03

说明：重置状态的发送最多也会重发三次,重发间隔保持1S

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x25
数据长度	2	0x0001
数据	1	重置状态： 0x00：模组本地重置 0x01：App远程重置 0x02：App恢复出厂重置 0x03：本地数据清除，但设备不离网
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

MCU回复：

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

拓展功能协议

图片上传相关

主要应用于人脸识别锁的图片传输功能需求。上传图片后，可从App端查看开门者人脸信息。当MCU有图片上传时，需要先通知模组启动图片上传服务相关功能。

• MCU上报0x60命令时，可以选择是否携带时间。如果不携带时间，则模组在回复0x62命令时，会将模组自己的时间回复给MCU，如果携带时间，则模组在回复0x62命令时会将该时间回复给MCU。MCU在上报事件时，事件所携带的时间应与0x62返回的时间保持一致。
• 当模组返回图片上传失败后，MCU应当停止图片传输。
• 模组需要在收到WiFi发送的0x02、0x03、0x04网络状态时，开始发送0x60图片上传请求。

事件状态通知

当有事件触发时，通过此指令通知模组，若需要携带图片信息，模组收到指令后开启图片传输相关功能服务。

• 事件编码表，请参考 附录1。
• 当事件通知是携带图片的事件时，模组会定时20s等待MCU上传图片，若超过20s还未收到图片信息，则会退出图片接收状态，通过0x62指令返回失败给MCU。
• 每次有图片传输时，都需要先发送此命令通知模组，模组开启图片传输功能。
• 单次事件通知只触发一张图片的传输，若需要传输多张图片，需要重复图片上传流程。

MCU发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x60
数据长度	2	0x04
数据	2	事件信息编码： 0x0000：防撬告警 0x0001：远程开门请求 0x0002：指纹开门试错 0x0003：密码开门试错 0x0004：人脸开门试错 0x0005：掌纹开门试错 0x0006：指静脉开门试错 0x0007：指纹开门
-	1	是否携带图片信息：0x00：不携带图片（后面的数据内容无效） 0x01：携带图片
-	1	上传图片张数（<=10）：0x00：此字节内容无效
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

示例：55 AA 00 60 00 04 00 00 01 01 18

模组回复：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x60
数据长度	2	1
数据	1	result： 0 信息接收成功 非0 失败
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

示例：55 AA 00 60 00 01 00 93

图片上传

图片上传时支持 SPI 和 UART 两种数据传输方式。

• UART传输时单包图片大小限制为15K。
• SPI传输时单包图片大小限制为30K。
• 开启图片传输时，模组会开启超时接收定时器，一张图片数据每包之间超时等待间隔为5s，若5s未收到下包内容，则会退出接收，通过0x62指令返回失败。
• 若要重传则需要从0x60指令开始重新启动图片传输功能
• SPI传输时，模组做为从机，MCU作为主机，模组仅用于接收MCU发送的图片数据，ACK仍由串口通知返回MCU。

MCU 发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x61
数据长度	2	N
数据	7	Data[0]为这条数据传输是否带本地时间标志位： 0：这条数据不带门锁给的时间后面的时间模组认为数据无效不处理 1：后面的时间数据有效，时间数据为设备所在的 当地时间。 2：后面的时间数据有效，时间数据为格林时间。 Data[1]为年份，0x00表示2000年 Data[2]为月份，从1开始到12结束 Data[3]为日期，从1开始到31结束 Data[4]为时钟，从0开始到23结束 Data[5]为分钟，从0开始到59结束 Data[6]为秒钟，从0开始到59结束
-	2	图片id号：图片id号作为一张图片数据的归属标识
-	2	图片总包数：当前传输中的图片一共分多少包传输
-	2	当前包序号（从0开始）：当前数据是第几包图片数据
-	N	图片数据
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

模组回复：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x61
数据长度	2	1
数据	1	result： 0 信息接收成功 非0 失败
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

图片上传结果反馈

• 用来反馈图片上传结果，当模组返回图片上传失败时，需要中止图片传输。
• 当模组返回图片上传成功之后，MCU上报事件记录的时候需要将模组返回的图片id和时间一起上报。
• 若从收到0x60命令开始20s内图片仍未上传成功，则认为上传超时，返回失败。

模组发送：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x62
数据长度	2	9
数据	2	图片 ID，图片数据的归属标识
-	6	当前图片上传的时间： Data[1]为年份，0x00表示2000年 Data[2]为月份，从1开始到12结束 Data[3]为日期，从1开始到31结束 Data[4]为时钟，从0开始到23结束 Data[5]为分钟，从0开始到59结束 Data[6]为秒钟，从0开始到59结束
-	1	Result：失败时，时间数据无效 0 图片上传成功 1 网络断开无法上传成功 2 图片太大超出30k 3 超时未收到MCU的图片信息 4 其它原因失败
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

MCU回复：

字段	长度（byte）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x62
数据长度	2	1
数据	1	result： 0 无后续图片上传 非0 还有图片上传
校验和	1	从帧头开始，按字节求和，得出的结果对 256 求余

图片上传状态获取（门禁品类暂不支持）

用来反馈图片上传状态的，若模组反馈图片上传失败，需要停止图片传输。

• 当模组返回当前状态的状态0：无图片上传时，事件id和图片编码数据无效，

• 模组返回的时间只支持本地时间。

• 此命令通过串口发送获取到的为模组此刻的处理状态。spi获取到的是前一次spi数据交互时刻的状态。

MCU发送：

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

模组返回：

| 字段 | 长度（byte） | 说明 |
| ---- | ---- | ---- | ---- |
| 帧头 | 2 | 0x55aa |
| 版本 | 1 | 0x00 |
| 命令字 | 1 | 0x63 |
| 数据长度 | 2 | 11 |
| 数据 | 1 | （图片上传相关数据）状态：

• 0：无图片传输触发
• 1：接收图片中；
• 2：图片上传中
• 3：图片上传成功
• 4：图片上传获取url失败
• 5：图片数据上传云端失败
• 6：图片接收超时失败
• 7：图片大小超出限制失败

|
| | 2 | 事件信息编码：0x0000：防撬告警 |
| | 2 | 图片ID，图片数据的归属标识 |
| | 6 | （时间数据）当前图片上传的本地时间：

• Data[1]为年份，0x00表示2000年
• Data[2]为月份，从1开始到12结束
• Data[3]为日期，从1开始到31结束
• Data[4]为时钟，从0开始到23结束
• Data[5]为分钟，从0开始到59结束
• Data[6]为秒钟，从0开始到59结束

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

附录一：图片上传事件编码

事件状态	描述	状态值
状态1	防撬告警	0x0000
状态2	远程开门请求	0x0001
状态3	指纹开门试错	0x0002
状态4	密码开门试错	0x0003
状态5	卡片开门试错	0x0004
状态6	人脸开门试错	0x0005
状态7	掌纹开门试错	0x0006
状态8	指静脉开门试错	0x0007
状态9	指纹开门	0x0008
状态10	密码开门	0x0009
状态11	卡片开锁	0x000A
状态12	人脸开锁	0x000B
状态13	掌静脉开锁	0x000C
状态14	指静脉开锁	0x000D
状态15	临时密码解锁	0x000E
状态16	动态密码解锁	0x000F
状态17	远程解锁	0x0010
状态18	离线密码解锁上报	0x0011
状态19	门铃请求上报	0x0012
状态20	劫持告警	0x0013
状态21	低电量告警	0x0014
状态20	钥匙插入告警	0x0015
状态21	高温告警	0x0016

附录二：SPI 配置信息

当前默认参数：

参数名称	描述	状态值
时钟	时钟频率	6000000
时钟模式	-	SPI_SCLK_Mode0
首字节电平	-	SPI_TCTRL_FBS_MSB
Cs	片选信号	低电平
字节对齐	-	8位