简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

MCU对接协议

更新时间:2022-06-17 09:34:58下载pdf

串口通信约定

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

帧格式说明

字段 长度(byte) 说明
帧头 2 固定为0x55aa
版本 1 升级扩展用
命令字 1 具体帧类型
数据长度 2 大端
数据 N
校验和 1 从帧头开始按字节求和得出的结果对256求余
  • 所有大于1个字节的数据均采用大端模式传输。

  • 协议中所有举例说明数据都是十六进制数据。

  • Wi-Fi模组主动发起的通信发送包超时时间为1S,重发机制会重发三包。

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

    说明:具体通信方式以"协议详述”章节中为准

  • MCU状态上报则采用同步模式,MCU状态上报“命令字”为y,如下所示:

    MCU统计数据上报:

    MCU对接协议

协议详述

查询产品信息0x01

产品信息由product id、MCU软件版本构成:

  • product id:对应涂鸦 IoT 平台中一款产品的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”:”vHXEcqntLpkAlOsy”, "v”:”1.0.0”,”n”:0,”cap”:0}
校验和 1 从帧头开始按字节求和得出的结果对256求余

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

  • p表示产品ID为vHXEcqntLpkAlOsy,这里参数为用户在涂鸦官网创建的产品PID

  • v表示MCU版本为1.0.0

  • n字段(可选):表示模式的配网模式,没有该字段保持传统两种配网方式互相切换的模式:(暂不支持)

    • 0:smartconfig&AP共存配网模式。模组同时支持AP连接配网和EZ配网无需用户切换。
    • 1:仅仅只有AP配网模式。这种模式下产品只能通过AP连接的方式进行设备配网。
  • 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

报告设备联网状态0x02

设备联网状态 描述 状态值
状态1 smartconfig配置状态 0x00
状态2 AP配置状态 0x01
状态3 Wi-Fi已配置但未连上路由器 0x02
状态4 Wi-Fi已配置且连上路由器 0x03
状态5 已连上路由器且连接到云端 0x04
状态6 Wi-Fi设备处于低功耗模式 0x05
状态7 Wi-Fi设备处于smartconfig和ap共存配置状态 0x06 (暂不支持)
  • 设备联网状态:1 smartconfig配置状态 2 AP配置状态 3 Wi-Fi配置成功但未连上路由器 4 Wi-Fi配置成功且连上路由器 5 设备连接到路由器且连接到云端。

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

  • 这里的状态包用于MCU设备得知模组目前的状态,这里两种配置状态需要MCU做相关的配网显示。

  • 建议您同时实现两种配网方式,第一种配网方式存在少部分路由兼容性问题,第二种配网方式是确保设备可以联网成功的保障。

  • 在未配网前,模组上电默认处于低功耗状态。需要MCU主动发Wi-Fi重置指令(3.3或者3.4)后,模组才会进入配网状态。

  • 手机移除设备后,模组进入低功耗状态,需要MCU主动发Wi-Fi重置指令(3.3或者3.4)后,模组才会进入待配网状态。

  • wifi模组进入配网模式后,如果在10S内未连接路由并且模组断电了,下次模组上电后依旧保持上一次的配网状态。

模组发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x02
数据长度 2 0x0001
数据 1 指示Wi-Fi工作状态: 0x00:状态1 0x01:状态2 0x02:状态3 0x03:状态4 0x04:状态5 0x05:状态6 0x06:状态7
校验和 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 0x03

  • smartconfig&AP共存配网模式 :重置后仍然为共存配网状态。

  • 仅仅只有AP配网模式:重置后仍然为ap配网模式。

  • 传统两种配网模式互换配网模式:重置Wi-Fi状态转化如下图所示:
    MCU对接协议

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-选择配置模式0x04(保活门锁暂不支持)

  • 此重置指令只针对3.1节设置的wifi模式为传统的工作模式才有效。

  • 相对于“3.5”节“重置Wi-Fi而言”,此帧提供MCU根据自身需求选择性选择重置Wi-Fi后的配置方式

  • MCU接入用户可选择性的实现该协议

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x04
数据长度 2 0x0001
数据 1 0x00:进入smartconifg配置模式 0x01:进入AP配置模式
校验和 1 从帧头开始按字节求和得出的结果对256求余

MCU 发送控制模组进入AP 配置模式:

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

实时状态上报0x05

使用场景:对于类似报警器要求实时推送的设备,您可以通过本条命令上报相关状态数据。

当MCU需要上报实时状态的数据时,可通过改条协议上报数据

  • 状态数据会直接上报到云端,故设备联网状态必须为已连接到云端,否则数据上报失败

  • 该条指令为同步指令,MCU数据上报后需等待模组返回上报结果,等待超时时间5秒

  • 需要等待模组发送连接上服务器的网络状态包,再发送需要发送的统计数据包,这里的数据上传没有储存功能,这强制等待8s还没收到连接上服务器的网络状态包,也强制给设备断电。

  • 这里可以支持多个数据单元上报,和单个数据单元上报,用户根据自己的需要来选择发送组包的方式。具体数据包可以下面的例子。

大致操作的流程图:
MCU对接协议

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x05
数据长度 2 取决于“状态数据单元”类型以及个数
数据 N 一个或多个组合“4.10状态数据单元”组
校验和 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

“ 多个状态数据单元” 上报例子:

DP 109 bool型变量,数值为1

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

记录型状态上报0x08(保活门锁暂不支持)

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

说明:当MCU需要记录型数据是由多个DP 组合的整条数据,需要整体上报,便可以通过这条命令往Wi-Fi模组发送,并且当由数据上报时此时设备断网了的时候这条数据储存下来当下次有数据上报的时候模组再上传这条数据之后,并把之前的储存数据上报成功。

  • 这里当有滞留记录每次上报成功一条,模组就会主动发送一条09命令字数据为01的回复包。这里MCU可以根据这个回复做超时断电处理!这里当发送一条记录这里强制等待5s当没有收到模组任何回复,认为模组异常也要断电模组.

  • 网络正常下模组上电后正常需要4S左右连接上服务器,这里每当有记录产生给设备上电后,可以等Wi-Fi模组发送协议文档中3.2所描述的的设备联网状态包,当强制等待6S以上还没收到模组连接上服务器的包,也将该条指令MCU数据上报后需等待模组返回上报结果。

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

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

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

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

  • 这里由于设备在全世界各地涉及到时区和夏令时等事件因素,这里记录的时间的处理也给与两个时间的协议区分。当设备没有显示屏的需求,这里设备通过协议获取格林时间在设备中运行,当有相关上报数据产生的时候便按照协议给与当前设备运行的格林时间的数据。这里有些设备,比如门锁需要显示当地的时间,这里门锁可以通过协议获取本地时间,这个时间模组有加上时区包括夏令时的因素,确保时间和当地的时间可以对上。当有相关上报数据产生的时候便按照协议给与当前设备运行的本地时间的数据。

上报大致操作流程图:
MCU对接协议

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x08
数据长度 2 取决于“状态数据单元4.10”类型以及个数
数据 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 一个或多个组合“4.9状态数据单元”组
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x08
数据长度 2 0x0001
数据 1 0x00 上报成功:只MCU上报数据到模组成功,模组上报到云端成功或者是本地记录成功,均认为此命令执行成功。 0x01 当前记录上报成功,并且还有滞留记录需要上报 0x02 上报失败
校验和 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

状态快速上报(保活门锁暂不支持)

此章节下wifi模组端采用的上报接口有所变动。Mcu可以在设备反馈已经连接路由成功后就可以通过此接口上报数据。

此章节内容当前只针对XR系列模组应用有效。

实时状态快速上报0x18

使用场景:对于类似报警器要求实时推送的设备,您可以通过本条命令上报相关状态数据。

说明:当MCU需要上报实时状态的数据时,可通过改条协议上报数据

(1)状态数据会直接上报到云端,故设备联网状态必须为已连接到云端,否则数据上报失败

(2)该条指令为同步指令,MCU数据上报后需等待模组返回上报结果,等待超时时间5秒

(3)需要等待模组发送连接上服务器的网络状态包,再发送需要发送的统计数据包,这里的数据上传没有储存功能,这强制等待8s还没收到连接上服务器的网络状态包,也强制给设备断电。

(4)这里可以支持多个数据单元上报,和单个数据单元上报,用户根据自己的需要来选择发送组包的方式。具体数据包可以下面的例子。

  • 此处上报是通过http上报,若遇到网络断开,会出现http上报堵塞情况,http堵塞时间大致为15s。

大致操作的流程图:
MCU对接协议

MCU发送:

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

模组返回:

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

“ 单个状态数据单元” 上报例子

DP 109 bool型变量,数值为1

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

“ 多个状态数据单元” 上报例子:

DP 109 bool型变量,数值为1

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

记录型状态快速上报0x19

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

说明:当MCU需要记录型数据是由多个DP 组合的整条数据,需要整体上报,便可以通过这条命令往Wi-Fi模组发送,并且当由数据上报时此时设备断网了的时候这条数据储存下来当下次有数据上报的时候模组再上传这条数据之后,并把之前的储存数据上报成功。

  • 这里当有滞留记录每次上报成功一条,模组就会主动发送一条09命令字数据为01的回复包。这里MCU可以根据这个回复做超时断电处理!这里当发送一条记录这里强制等待5s当没有收到模组任何回复,认为模组异常也要断电模组.

  • 网络正常下模组上电后正常需要4S左右连接上服务器,这里每当有记录产生给设备上电后,可以等Wi-Fi模组发送协议文档中3.2所描述的的设备联网状态包,当强制等待6S以上还没收到模组连接上服务器的包,也将该条指令MCU数据上报后需等待模组返回上报结果。

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

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

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

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

  • 这里由于设备在全世界各地涉及到时区和夏令时等事件因素,这里记录的时间的处理也给与两个时间的协议区分。当设备没有显示屏的需求,这里设备通过协议获取格林时间在设备中运行,当有相关上报数据产生的时候便按照协议给与当前设备运行的格林时间的数据。这里有些设备,比如门锁需要显示当地的时间,这里门锁可以通过协议获取本地时间,这个时间模组有加上时区包括夏令时的因素,确保时间和当地的时间可以对上。当有相关上报数据产生的时候便按照协议给与当前设备运行的本地时间的数据。

  • 此处上报是通过http上报,若遇到网络断开,会出现http上报堵塞情况,http堵塞时间大致为15s。

上报大致操作流程图:
MCU对接协议
MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x19
数据长度 2 取决于“状态数据单元4.10”类型以及个数
数据 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 一个或多个组合“4.9状态数据单元”组
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x19
数据长度 2 0x0001
数据 1 0x00 上报成功 0x01 当前记录上报成功,并且还有滞留记录需要上报 0x02 上报失败
校验和 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

模组命令下发0x09

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

模组发送:

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

模组下发控制命令:(系统开关对应3号DP,使用bool型变量,开机数值为1)

55 aa 00 09 0005 03 01 00 01 01 13

MCU回复:

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

MCU 确认回复:

55 aa 03 09 00 00 0b

获取本地时间0x06

  • 需要等待设备连接上网络(也就是收到设备3.2命令 状态5)后开始发送获取本地时间的数据包

  • 在设备连接上服务器后,在网络情况非常差的情况下,有可能会获取时间数据失败。这里对于依赖时间的设备(例如门锁)当本地时间没有校准过的请款下当获取失败,这里需要做一个间隔3S的获取时间值,确保时间数据获取成功。

  • 模组每次上电在未为联网成功之前无法获取时间,待模组入网校时完成后,可随时获取时间。

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区)

  • 如果设备在国外激活使用,则当地时间为设备所处时区时间。

获取格林时间0x07

  • 格林时间不带有时区和夏令时相关因素,这里带动态密码功能(门锁等)的但是不需要显示设备所在当地时间的设备,本地只需要跑格林时间,记录上传走带记录型上报的通道给的时间也需要是格林时间。

  • 这里带动态密码功能的设备,并且门锁也要显示设备所在当地的当前时间,本地在跑跑格林时间的同时,需要在定时获取本地时间,本地储存格林时间和当地时间的时间差,每次显示本地时间的时候在格林时间的基础上加上时间差。记录上传走带记录型上报的通道给的时间也需要是格林时间。

  • 模组每次上电在未为联网成功之前无法获取时间,待模组入网校时完成后,可随时获取时间。

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功能性测试0x07

  • 扫描指定的SSID: tuya_mdev_test返回扫描结果和信号强度百分比。

  • 产测指令需要在wifi上电工作完成初始化流程以后发送(回复3.1查询产品信息的数据包),否则导致产测失败或无结果。

  • 本条命令多用于设备量产时的产品整机测试使用。

  • 产测路由器密码设置不做要求(随意设置),这里路由需要为2.4G信号的路由器。

MCU发送:

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

MCU触发模组功能性测试:

55 aa 00 07 00 00 06

模组返回:

字段 长度(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 01 50 59

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

请求Wi-Fi模组固件升级0x0A

  • 这里Wi-Fi模组的电源通断是由MCU去控制的,当MCU需要升级Wi-Fi模组的固件便可以通过下面的命令去拉去最新固件。MCU主板根据Wi-Fi模组的回复包决定是否需要给Wi-Fi模组断电。这里MCU当发送0a命令等待5S没有收到相关回复便把Wi-Fi模组断电。当模组回复正在更新固件这里MCU也需要起一个定时当处于正在更新固件超过60S没有收到固件升级成功,也强制认为固件升级失败给Wi-Fi模组断电。

MCU发送:

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

MCU 请求Wi-Fi 固件升级:

55 aa 00 0a 00 00 09

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0a
数据长度 2 0x0001
数据 1 0x00(开始检测固件更新)不可断电 0x01(已经是最新固件) 断电 0x02(正在更新固件)不可断电 0x03(固件更新成功)断电 0x04(固件更新失败)断电
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组升级状态返回:

55 aa 00 0a 00 01 00 0a (收到升级请求包立马返回)

55 aa 00 0a 00 01 01 0b (拉取服务端信息返回没有固件需要更新)

请求MCU固件升级0x0C

  • 这里当MCU收到模组返回固件更新完成之后,说明服务端MCU的升级文件已经全部拉取完成并且完成了串口数据传输。这里注意MCU在收到完整升级文件后,确认拉取文件没有问题,这个时候模组会重新发送查询信息,MCU需要返回相关产品信息和在升级服务器后台填写一致的新的软件版本号。

  • 目前支持最大为480K的MCU文件的OTA。

  • 这里用户再涂鸦官网配置MCU升级时,配置MCU升级方式为app静默升级

MCU发送:

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

MCU 请求MCU 固件升级:

55 aa 00 0c 00 00 0b

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0c
数据长度 2 0x0001
数据 1 0x00(开始检测固件更新)不可断电 0x01(已是最新固件) 断电 0x02(正在更新固件)不可断电 0x03(固件更新完成)断电 0x04(固件更新失败)断电
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组升级状态返回:

55 aa 00 0c 00 01 00 0c (收到升级请求包立马返回)

55 aa 00 0c 00 01 01 0d (拉取服务端信息返回没有固件需要更新)

升级启动0x0D

  • 当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

升级包传输0x0E

  • 升级包传输数据格式:包偏移(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

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

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

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

请求云端临时密码(只支持单组)0x11(保活门锁暂不支持)

  • 这里需要在APP端创建当前时间的密码,设备才能拉取到当前生效的密码。

  • 这里这个接口只支持一组临时密码的拉取,此为早期门锁通用固件1.0.0的接口需要和对应的早期门锁面板对应结合使用,后面所有APP面板临时密码均用4.8的支持创建多组临时密码的接口获取相关密码数据。

MCU发送:

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

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

55 aa 00 11 00 00 10

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x11
数据长度 2 0x0007+N(临时密码)
数据 7+N 数据长度为7+N字节: Data[0]为是否获取密码成功标志,为0表示失败,后面不会带上相关密码和有效时间数据,数据内容长度为1,为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结束 临时密码(N) 密码数据传输字符的ASLL码
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组返回当前密码:

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

格林时间2016年4月19日5时6分7秒

密码 “123456”,这里密码部分传输的字符的ASLL码

动态密码校验0x12(保活门锁暂不支持)

  • 协议中的时间数据用于运算当前的动态密码,这里的动态密码运算时间都为当前的格林时间,设备需要给模组格林时间数据。

  • 这里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’ 数据传输使用ASCLL码
1 管理员密码组数(0~10) 有多少组管理员密码后面 带上相应组数数据
1 管理员密码长度 (长度最长不超过8个字节)
N 第一组管理员密码部分 (密码部分由数字组成) 数据内容范围为 ‘0’~’9’ 数据传输使用ASCLL码
N 第二组管理员密码部分 ( 密码部分由数字组成) 数据内容范围为 ‘0’~’9’ 数据传输使用ASCLL码
校验和 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
数据长度 1 0x0001
数据 1 0x00 (密码核对通过) 0x01 (密码核对失败) //通信操作错误码 0x02 (设备未激活) 0x03 (数据长度错误)
校验和 1 从帧头开始按字节求和得出的结果对256求余

模组返回密码校验失败

55 aa 00 12 00 01 01 13

请求云端临时密码(支持多组)0x13(保活门锁暂不支持)

  • 临时密码,在 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]) (密码数据传输字符的ASLL码) //第二组密码数据 …
校验和 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

状态数据单元

  • datapoint命令/状态数据单元如下所示:
数据段 长度(byte) 说明
dpid 1 datapoint序号
type 1 对应开放平台上某datapoint具体的数据类型,通过如下“表示值”标识
类型 表示值 长度(字节) 说明
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字节采用大端传输
  • 0datapoint命令/状态数据单元除”raw”类型外,其他类型均属于“obj”型datapoint

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

实际开发中注意点:

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

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

请求云端临时密码(带schedule列表)0x14(保活门锁暂不支持)

  • 临时密码在 App 设计上目前为了和其他密码区分开使用7位有效数据,门锁主板当检测到用户使用的是多组临时密码才去调用此接口去云端拉取相关数据,更新本地的密码数据和状态,这样可以最大程度节约功耗。

  • 注意这里模组给门锁给的相关时间数据都是基于格林时间,请门锁本地通过获取格林时间的接口同步自己的时钟数据。

  • 密码每次服务端都是全量下发,门锁需要每次根据服务端返回的所有密码和状态进行更新。

  • 保留原生效周期设置,在生效周期基础上可以按照每周重复的方式添加密码生效的计划。最多可以添加3个schedule

MCU发送:

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

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

55 aa 00 14 00 00 13

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x14
数据长度 2 0x0001+N(临时密码)
数据 1+N 数据长度为1+N字节: Data[0]为是否获取密码成功标志,为0表示失败,后面不会带上相关密码和有效时间数据,数据内容长度为1,为1表示成功 Data[1] 密码组数(0~10) 当密码组数为0 的时候表示面板没有创建密码。串口传输不会带上相关密码和有效时间数据. 此密码组数为本包数据含有的密码数据 Data[2] 密码长度(后面每组的密码长度保持一致) Data[3] bit7: 后续是否还有数据包。Bit6-bit0: 本包序号(从0开始) //第一组密码相关数据 Data[4]密码编号 (实际编号需要在密码编号的数据上加900)(1~50) Data[5]密码有效次数 0:表示不限制次数密码-有效期内可以不限次数开门 1:表示一次性密码-有效期内只能开一次门 Data[6]密码当前状态 0:表示密码有效 1:表示面板已经进行了删除操作此密码无效 密码生效日期(格林时间): Data[7]为年份, 0x00表示2000年 Data[8]为月份,从1开始到12结束 Data[9]为日期,从1开始到31结束 Data[10]为时钟,从0开始到23结束 Data[11]为分钟,从0开始到59结束 Data[12]为秒钟,从0开始到59结束 密码截至日期(格林时间): Data[13]为年份, 0x00表示2000年 Data[14]为月份,从1开始到12结束 Data[15]为日期,从1开始到31结束 Data[16]为时钟,从0开始到23结束 Data[17]为分钟,从0开始到59结束 Data[18]为秒钟,从0开始到59结束 临时密码(具体字节数N=data[2]) (密码数据传输字符的ASLL码) Data[19+N] 为schedule 条数 /第一条schedule数据/ Data[20+N] 0:非全天有效,分时间段有效。 1:全天有效。后面的起始时间和结束时间为无效数据。 Data[21+N] 开始时间(小时) Data[22+N] 开始时间(分钟) Data[23+N] 结束时间(小时) Data[24+N] 结束时间(分钟) Data[25+N] 周循环 Bit0:周日 Bit1:周一 Bit2:周二 Bit3:周三 Bit4:周四 Bit5:周五 Bit6:周六 若此条schedule周日,周三循环,则为0x09 /第二条schedule数据/ … //第二组密码数据 …
校验和 1 从帧头开始按字节求和得出的结果对256求余

获取dp缓存命令0x15(保活门锁暂不支持)

对于某些带设置性或控制功能的传感器,需要新增dp下发功能

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x15
数据长度 2 N
数据 dp_num(1byte) +dp_1(byte)+…+dp_n(1byte) 如果dp_num是0,则认为查询所有的dp
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

门锁获取dp115, dp114, dp113 的:

55 AA 00 15 00 04 03 73 72 71 71

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x15
数据长度 2 取决于“命令数据单元”类型以及个数
数据 result(1byte)+dp_num(1byte) +dp_1(byte)+…+dp_n(1byte) “命令数据单元”组, 返回有缓存命令的dp数据。 result: 获取指令成功标志,为0表示失败,后面不会带上相关dp数据,数据内容长度为1,result为1表示成功 dp_num: 若dp_num为0,则认为当前没有缓存命令.
1 从帧头开始按字节求和得出的结果对256 求余

模组返回 (dp115自动关门(布尔型,代表是否要执行自动关门)+dp114延时门锁选择(枚举型,立即锁门或继续计时)+dp113(数值型,单位s),下列返回数据代表 延时30s关门)

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

离线动态密码0x16(保活门锁暂不支持)

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

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号0x17(保活门锁暂不支持)

通过这个接口可将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 求余

模组重置状态通知0x25

设备重置状态 描述 状态值
状态1 模组本地重置 0x00
状态2 APP远程重置 0x01
状态3 APP恢复出厂重置 0x02
  • 重置状态的发送最多也会重发三次,重发间隔保持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 求余

获取Wi-Fi状态0x1A

MCU可根据此条命令获取Wi-Fi状态。具体Wi-Fi状态见3.2。

MCU发送:

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

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1A
数据长度 2 0x0002
数据 2 Data[0]指示Wi-Fi工作状态: 0x00:状态1 0x01:状态2 0x02:状态3 0x03:状态4 0x04:状态5 0x05:状态6 0xff: 无效状态(初始化未完成) Data[1]指示设备激活状态: 0x00:未激活 0x01:已激活
校验和 1 从帧头开始按字节求和得出的结果对256求余

获取Unix时间戳(带时区信息)0x1B

MCU可以获取当前Unix时间戳,时区信息以及夏令时范围

MCU发送:

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

模组返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1B
数据长度 2 N
数据 2 Data[0]:获取时间成功与否 1:成功 0:失败 Data[1]-Data[4]:Unix时间戳 Data[5]:获取时区信息是否成功 1表示成功 0表示失败 Data[6]: 0:表示东区 1:表示西区 Data[7]:表示时区 Data[8]:是否有夏令时 1:表示有夏令时 0:表示没有夏令时 Data[9]-Data[12]:进入夏令时时间戳(大端) Data[13]-Data[16]:退出夏令时时间戳(大端)
校验和 1 从帧头开始按字节求和得出的结果对256求余

拓展功能协议详述(保活门锁暂不支持)

图片上传相关

使用场景:主要应用于人脸识别锁的图片传输功能需求。上传图片后,可从app端查看开门者人脸信息。

当MCU有图片上传时,需要先通知模组启动图片上传服务相关功能。

  • 当相同的事件有触发需要携带多张图片的时候,MCU只触发一次即可。

  • MCU返回的图片数据让模组自己添加时间记录上传到云端的情况下,会存在图片数据实际拍摄时间与云端接收时间误差的情况。

  • 当模组返回图片上传失败后,MCU应当停止图片传输。

图片上传流程图:
MCU对接协议

事件状态通知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 64

模组回复:

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

示例:

55 AA 00 60 00 01 00 60

图片上传0x61

图片上传时支持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 求余

图片上传结果反馈0x62

用来反馈图片上传结果,当模组返回图片上传失败时,需要中止图片传输。

  • 当模组返回图片上传成功之后,MCU上报事件记录的时候需要将模组返回的图片id和时间一起上报。

模组发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x62
数据长度 2 9
数据 2 图片id号:图片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:失败时,时间数据无效 图片上传成功 网络断开无法上传成功
图片太大超出30k
超时未收到MCU的图片信息
其它原因失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

MCU 回复:

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

图片上传状态获取0x63

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

  • 当模组返回当前状态的状态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号:图片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 求余

Wi-Fi拍照门锁图片上传相关

  • 针对新的平台wifi模组上集成了拍照功能,简化了拍照流程。

  • 图片上传结果反馈以及图片上传状态获取复用4.1.3、4.1.4协议

    图片上传流程图:
    MCU对接协议

事件触发抓拍通知0x64

当有事件触发时,通过此指令通知模组,有事件触发抓拍,模组收到此指令后开启抓拍相关功能。

  • 事件编码表可参见附录1。

  • 当事件通知需要抓拍图片时,模组会抓拍并上传图片,若超时还未收到上传成功的应答,则会通过0x62指令返回失败给MCU。

  • 每次事件触发抓拍图片时,都需要发送此命令通知模组,模组开启图片传输功能。

  • 可通过抓拍类型决定抓拍方式。

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x60
数据长度 2 0x01+0x05+0x07
数据 子命令 0x00
2 事件信息编码: 0x0000:防撬告警 0x0001:远程开门请求
0x0002:指纹开门试错
0x0003:密码开门试错
0x0004:人脸开门试错
0x0005:掌纹开门试错
0x0006:指静脉开门试错
0x0007:指纹开门
…………
1 是否抓拍图片: 0x00:不抓拍图片(后面的数据内容无效)
0x01:抓拍图片
1 抓拍类型: 0x00:单张抓拍 0x01:连续抓拍 0x02:智能抓拍 ……
1 抓拍图片张数(<=16): 0x00:此字节内容无效
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结束
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

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

示例:

55 AA 00 60 00 01 00 60

图片下载相关 (暂不支持)

图片下载通知0x65

通知模组当前有图片数据需要下载传输给MCU。

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x64
数据长度 2 1
数据 1 单包图片下载的大小: 0x01:1024
0x02:2048
0x03:3072
0x04:4096
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x64
数据长度 2 1
数据 1 result: 0 信息接收成功,启动数据下载服务成功 非0 失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

图片下载数据传输0x66

模组发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 N
数据 2 图片id号:图片id号作为一张图片数据的归属标识
2 图片总包数: 当前传输的中张图片一共分多少包传输
2 当前包序号(从0开始): 当前数据是第几包图片数据
N 图片数据
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

MCU 回复:

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

运营商上报(不对外展示-不上iot前台)

此功能主要是为支持入运营商渠道设备做数据上报使用。

运营商设备在每次配网的时候重新到云端注册,在配网完成后计时24小时,MCU唤醒模组去做心跳上报。

上报信息通知0x70

此指令在每次模组配网完成后发送给模组,通知模组去完成首次数据上报功能

MCU发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x70
数据长度 2 N
数据 { "cxcc”:”cmcc”; "id”:”xxx”; "appkey”:”xxxx”; "aeskey”:”xxxx”; "type”:”xxxx” } Cxcc:表示运营商类型 cmcc:移动
ctcc:电信
cucc:联通
id:厂商编码(移动没有此项)
appkey:移动设备需要填写,若为以涂鸦公司的入库设备,此内容填空
aeskey:移动设备需要填写
若为以涂鸦公司的入库设备,此内容填空
type:设备型号:例mc009
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x70
数据长度 2 1
数据 1 result: 信息接收成功,数据设备成功 网络错误 设备运营商类型错误
(MCU上报类型与从云端获取到的设备类型不匹配) 数据接收成功,上报失败
数据接收失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

心跳上报通知0x71

此指令在首次上报后每隔24小时触发设备上报一次心跳。

MCU发送:

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

模组回复:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x70
数据长度 2 1
数据 1 result: 0信息接收成功,数据设备成功 1 网络错误 2 数据接收成功,上报失败
3 数据接收失败
校验和 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

附录二:SPI配置信息表

当前默认参数

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