串口协议接入

涂鸦云通用串口协议对接

1.串口通信约定

  • 波特率:9600
  • 数据位:8
  • 奇偶校验:无
  • 停止位:1
  • 数据流控:无
  • MCU:用户控制板控制芯片,与涂鸦模块通过串口对接

2.帧格式说明

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

说明:

  • 所有大于1个字节的数据均采用大端模式传输。
  • 一般情况下,采用同命令字一发一收同步机制,即一方发出命令,另一方应答,若发送方超时未收到正确的响应包,则超时传输.说明:具体通信方式以“协议详述”章节中为准
  • 模块控制命令下发及MCU状态上报则采用异步模式,假设模块控制命令下发“命令字”为x,MCU状态上报“命令字”为y.

3.协议详述

3.1 心跳检测

说明:

  • 模组上电后,以10s的间隔定期发送心跳,若在超时时间(3s)内,未收到MCU的回应,则认为MCU离线。
  • MCU侧也可依据此心跳定期检测模块是否正常工作,若模块无心跳下发,则MCU可通过模块提供的硬件复位引脚复位模块。

模块发送:

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

例:0x55aa 00 00 0000 ff

MCU返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x00
数据长度 2 0x0001
数据 0 0x00:MCU重启后第一次心跳返回值,
仅发送一次,用于模块判断工作过程中MCU是否重启
0x01:除MCU重启后第一次返回0外,其余均返回此值
校验和 1 从帧头开始按字节求和得出的结果对256求余

例:0x55aa 00 00 0001 00 00(MCU第一次返回)
0x55aa 00 00 0001 01 01(除第一次外,正常返回)

3.2 查询产品信息

说明:

  • prodect key:固定为16字节,由涂鸦云开发者平台生成,用于云端记录产品相关信息
  • 产品信息由prodect key、MCU软件版本构成

MCU软件版本号格式定义:采用点分十进制形式,”x.x.x”(0<=x<=99),同时支持“x.x”及“x”形式,模块会自动扩展成”0.x.x”或“0.0.x”格式处理

模块发送:

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

例:0x55aa 00 01 0000 00

MCU返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x01
数据长度 2 0x0010 ~ 0x0018
数据 0 prodect key+mcu version
校验和 1 从帧头开始按字节求和得出的结果对256求余

例:(key=AIp08kLIftb8x2x0,mcu ver=1.0.0)
0x55aa 00 01 15 41497030386b4c496674623878327830 312e302e30 2a

(说明:ASCLL码转十六进制,如“A”转为十六进制为“41”)

3.3 查询MCU,设定模块的工作模式

说明: 模块工作模式主要针对如何指示WIFI的工作状态以及如何重置WIFI而言,主要分两种情况:

1. MCU与模块配合处理: 即MCU上报重置配网(smartconfig模式或者AP模式)指令给模块,模块接收到后通过串口通知MCU WIFI当前的工作状态,然后MCU进行逻辑处理,提供不同模式,显示不同状态支持;MCU检测出WIFI的重置需求,通过串口通知模块重置WIFI。 2. 模块自处理: WIFI的工作状态通过WIFI模块本身的GPIO引脚驱动LED状态显示;WIFI重置通过检测模块本身GPIO输入需求处理。模块自处理WIFI重置方法为:WIFI模块检测到模块本身的GPIO入口低电平持续5s以上触发WIFI重置。指示灯与按钮所使用的GPIO管脚由以下命令配置。 模块自处理WIFI重置方法为:WIFI检测GPIO入口低电平持续5s以上触发WIFI重置。指示灯与按钮所使用的GPIO管脚由以下命令配置。

模块发送:

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

例:0x55aa 00 02 0000 01

MCU返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x02
数据长度 2 0x0000/0x0002
0x0000:指示模块工作为“MCU与模块配合处理”模式,MCU需实现上述“说明”中提及的功能。
0x0002:指示模块工作为“模块自处理”模式。
数据 0/2 数据长度为2:首字节为WIFI状态指示GPIO序号;次字节为WIFI重置按键GPIO序号
校验和 1 从帧头开始按字节求和得出的结果对256求余

例:0x55aa 00 02 0000 01(MCU与模块配合处理)
0x55aa 00 02 0002 0c0d 1a(指示灯:GPIO12,复位按钮:GPIO13)

3.4 报告WIFI工作状态

说明:

  1. WIFI工作状态:

    1. smartconfig配置状态;
    2. AP配置状态;
    3. WIFI配置成功但未连上路由器;
    4. WIFI配置成功且连上路由器。
    5. 如果是“模块自处理”工作模式相应的LED显示分别为:(1) 间隔闪烁250ms;(2)间隔闪烁1500ms;(3)长暗状态;(4)长亮状态
  2. 当模块检测到MCU重启或MCU断线再上线的过程,则主动上报WIFI状态至MCU

  3. 当模块检测到WIFI状态发生变化,则主动上报WIFI状态至MCU

  4. 如设置模块工作模式为“模块自处理”,则MCU无需实现该协议

模块发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x03
数据长度 2 0x0001
数据 1 指示WIFI工作状态:
0x00:状态1
0x01:状态2
0x02:状态3
0x03:状态4
校验和 1 从帧头开始按字节求和得出的结果对256求余

例:0x55aa 00 03 0001 00 03

MCU返回:

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

例:0x55aa 00 03 0000 02

3.5 重置WIFI

说明: 模块自处理WIFI重置方法为:WIFI检测GPIO入口低电平持续5s以上触发WIFI重置。

如设置模块工作模式为“模块自处理”,则MCU无需实现该协议

MCU发送:

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

例:0x55aa 00 04 0000 03

模块返回:

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

例:0x55aa 00 04 0000 03

3.6 重置WIFI-选择模式

说明:

  1. 相对于“3.5”节“重置WIFI而言”,此帧提供MCU根据自身需求选择性选择重置WIFI后的配置方式
  2. MCU接入用户可选择性的实现该协议
  3. 如设置模块工作模式为“模块自处理”,则MCU无需实现该协议

MCU发送:

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

例:0x55aa 00 05 0001 00 05

模块返回:

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

例:0x55aa 00 05 0000 04

3.7 命令下发

说明:

  1. datapoint命令/状态数据单元如下所示:

  1. datapoint命令/状态数据单元除”raw”类型外,其他类型均属于“obj”型datapoint
  2. “命令下发”可含多个datapoint“命令数据单元”
  3. “命令下发”为异步处理协议,对应于MCU的datapoint“状态上报”

模块发送:

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

例:系统开关对应3号DP,使用bool型变量,开机数值为1
0x55aa 00 06 05 03 01 0001 01 10

3.8 状态上报

说明:

  1. datapoint状态数据单元说明详见“3.7节”
  2. “状态上报”为异步处理协议,“状态上报”触发机制有三类:
    MCU收到“命令下发处理帧时,正确执行相应datapoint命令,再通过“状态上报”,帧将变化后的datapoint状态发送至模块;
    MCU主动检测到datapoint有变化,将变化后的datapoint状态发送至模块;
    MCU收到“3.9”节的状态查询帧时,将所有的datapoint状态发送至模块。
  3. “状态上报”可含多个datapoint“命令数据单元”

MCU发送:

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

例:湿度对应5号DP,使用valve型变量,湿度为30℃
0x55aa 00 07 08 05 02 0004 0000001e 37

3.9 状态查询

说明:

  1. “状态查询”为异步处理协议,主要用于模块查询MCU所有的“obj”类型的datapoint状态,当MCU收到此帧时,通过“3.8”节状态上报帧上报datapoint状态
  2. “状态查询”发送时机主要有两种:
    • 模块首次上电,通过心跳与MCU建立连接后,查询发送;
    • 模块工作过程中检测到MCU重启或发生了离线再上线的过程,查询发送。

模块发送:

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

例:0x55aa 00 08 0000 07

3.10 MCU升级支持

说明:

  1. MCU可根据自身情况,选择性支持
  2. 何时升级由MCU触发,模块仅作为支持MCU升级的数据传输通道
  3. 升级支持强制升级以及手动升级模式,可通过涂鸦云开发平台上传升级固件时选择具体模式
  4. 升级仅支持高版本升级低版本

3.10.1 升级启动

说明: ​

  1. 升级启动方式含自动及手动升级。当处于自动升级时,模块检测云端MCU有更新版本固件,则自动启动与MCU升级包交互流程;当处于手动升级时,通过APP确定,模块才启发与MCU升级包交互流程

模块发送:

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

例:0x55aa 00 0a 00 04 00 00 68 00 75(固件包长度26624,即26KB)

MCU返回:

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

例:0x55aa 00 0a 0000 09
备注:当MCU返回版本号为0x00时表示升级包传输偏移为2字节,当版本号为0x01时表示升级包传输偏移为4字节。

3.10.2 升级包传输

说明: ​

  1. 升级包传输数据格式:包偏移(unsigned short) + 包数据
  2. MCU若收到该帧数据长度为2且包偏移>=固件大小,则包传输结束

模块发送:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0b
数据长度 2 0x0002/0x0004+包大小
数据 N 前两/四字节,固定为包偏移
校验和 1 从帧头开始按字节求和得出的结果对256求余

例:
(1)若升级启动返回的协议版本号为0x00,则数据包为
0x55 aa 00 0b 0402 0100 xx…xx XX(包大小256,包偏移0x800)
(2) 若升级启动返回的协议版本号为0x01,则数据包为
0x55aa 00 0b 0404 00000100 xx…xx XX(包大小256,包偏移0x00000800)

MCU返回:

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

例:0x55aa 00 0b 0000 0a

3.11 获取本地时间

MCU发送:

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

例:0x55aa 00 0c 0000 0b

模块返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1c
数据长度 2 0x0008
数据 7 数据长度为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开始到15结束
Data[7]为星期,从1开始到7结束,1代表星期一
校验和 1 从帧头开始按字节求和得出的结果对256求余

3.12 WIFI功能性测试

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

MCU发送:

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

模块返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0e
数据长度 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求余

3.13 获取模块内存

说明:获取 WIFI模块剩余内存

MCU发送:

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

模块返回:

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0f
数据长度 2 0x0004
数据 4 数据长度为4字节,大端格式:
如0x00 0x00 0x28 0x00代表剩余10240字节内存
校验和 1 从帧头开始按字节求和得出的结果对256求余
400-881-8611