# 串口通讯协议

# 1. 串口默认配置

  • 波特率:115200
  • 数据位:8
  • 奇偶校验:无
  • 停止位:1
  • 数据流控:无

# 2. 串口指令

  1. 上行指令↑

    指MCU发送至模组的指令

  2. 下行指令↓

    指模组发送给MCU的指令

上行指令由MCU实现,通过串口发送给模组的请求或命令

  • 格式:ez+cmd [param1] [param2]...[paramn]'\r\n'
  • 分隔符:采用空格分隔方式,非字符串中的空格需要转义为\u0020
  • 结束符:'\r\n'
  • 长度:数据区的长度,可选项,表示从首个空格符开始至'\r\n'之间的数据长度。采用固定8字符的16进制表示,如长度32换算后为00000020。如命令"ez+set_properties,00000003,CRC ...,abc\r\n",00000020表示abc的长度。
  • CRC校验:可选项,表示从首个空格符开始至'\r\n'之间的数据摘要值。CRC8标准(多项式x8+x5+x4+1,初始值0x00),采用固定2字符的16进制表示。格式为ez+cmd,[length],71 [param1] [param2]...[paramn]'\r\n'。若无此参数,则不进行CRC校验。
  • 命令和参数由合法字符构成,包括字母、数字、下划线

# 3. 数据类型

布尔值:true\false

整型:取值范围-2147483647至2147483647

字符串:字符串类型两端需要加双引号"",中间不能有0x00的值

json:json类型两端需要加双引号"",中间不能有0x00的值

# 4. 应答方式

采用"一应一答"模式,若发送方超时未收到正确的响应,则传输超时,命令响应超时时间500ms。

wifi模组->MCU:下发命令M
MCU-->wifi模组:响应命令M
MCU-->wifi模组:下发命令N
wifi模组->MCU:响应命令N
MCU-->wifi模组:上报

# 5. 错误码

code 描述
1 不支持的命令
2 命令过长,超过最大缓冲区
3 参数缺失
4 参数错误
5 crc校验失败
6 属性、事件不匹配/不存在
7 属性value错误
8 属性不可写
9 该命令正在执行中,不可重入(例如配网)
10 内部错误
11 响应超时,找不到对应的上下文

# 6. 上行

# 设置串口波特率

  • 命令:ez+set_baud
  • 参数:115200 N N N N
  • 返回:ok/error 1/error 2/error 3/error 4
  • 说明:参数依次为波特率(300至1500000)、数据位(暂不支持)、停止位(暂不支持)、奇偶校验(暂不支持)、数据流控(暂不支持)。每次启动波特率为默认值,需要更改的话要重新设置。

↑ez+set_baud 460800 N N N N

↓ok

# 设置日志等级

  • 命令:ez+set_loglvl
  • 参数:0-5
  • 返回:ok/error 1/error 2/error 3
  • 说明:0/ASSERT,1/ERROR,2/WARN,3/INFO,4/DEBUG,5/VERBOSE,

↑ez+set_loglvl 1

↓ok

# 获取串口协议版本号

  • 命令:ez+uart_version
  • 参数:MCU串口协议版本号
  • 返回:模组串口协议版本号
  • 说明:若校验不通过,则不再进行通讯

↑ez+uart_version 1.0

↓1.0

# 固件版本号交换

  • 命令:ez+fw_version
  • 参数:MCU固件版本号
  • 返回:模组固件版本号
  • 说明:与模组交换固件版本号

↑ez+fw_version V2.3.5 build200501

↓V1.1.0 build 200505

# 获取模组网络状态

  • 命令:ez+net_stat
  • 参数:无
  • 返回:distribution/offline/local/cloud/ota
  • 说明:查询网络状态。distribution-设备正在配网;offline-连线中或掉线;local-连上路由器但未连上服务器;cloud-上平台;ota-设备正在升级中

↑ez+net_stat

↓offline

# 获取网络参数

  • 命令:ez+net_param
  • 参数:ip/mac/ssid
  • 返回:ip地址/mac地址/wifi ssid
  • 说明:

↑ez+net_param ip

↓192.168.1.1

↑ez+net_param mac

↓EE:EE:EE:EE:EE

↑ez+net_param ssid

↓wifi_ssid

# 重启

  • 命令:ez+reboot
  • 返回:ok
  • 说明:模组在接收到命令并响应之后,进行重启

↑ez+reboot

↓ok

# 重置wifi

  • 命令:ez+wifi_reset
  • 参数:无
  • 返回:ok/error 1/error 2/error 9/error 10
  • 说明:模块进入配网模式之后,返回ok,若进入配网模式失败,则返回error

↑ez+wifi_reset

↓ok

# 属性变化

  • 命令:ez+properties_changed,[length],[CRC] <pkey> ... <pkey>
  • 参数:
  • 返回:ok/error 1/error 2/error 3/error 5/error 10
  • 说明:用于属性上报。参数至少有一个pkey,当本地有相应的property改变时调用此命令。最多30个参数。

↑ez+properties_changed,, switch

↓ok

# 执行结果

  • 命令:response,[length],[CRC]
  • 参数:与下行命令对应
  • 返回:ok/error 1/error 2/error 3/error 4/error 5/error 6/error 7/error 10/error 11
  • 说明:发送下行指令的执行结果,按下行指令的不同返回。code 为对应的key的执行结果,0为成功,其他为失败

↓ez+get_properties switch

↑response,, switch 0 true

↓ok

# 心跳检测

  • 命令:ez+check_alive
  • 参数:无
  • 返回:alive
  • 说明:心跳检测,15s发送一次,超过3s未回应则认为卡死或串口通讯异常。

↑ez+check_alive

↓alive

# 7. 下行

# 模组状态更变通知

  • 命令:ez+sta_changed
  • 参数:boot/net
  • 应答格式:ok/error
  • 说明:模组状态更变通知。boot-模块开机启动;net-网络状态发生更变

# 读属性

  • 命令:ez+get_properties,[length],[CRC] <pkey>
  • 应答格式:response,[length],[CRC] <pkey> <code> [value]
  • 说明:参数只能有一个pkey;响应必须有一组对应的pkey和code,若code不为0,则无value值。

↓ez+get_properties switch

↑response,, switch 0 true

↓ez+get_properties version

↑response,, version 0 "v1.0.0"

# 写属性

  • 命令:ez+set_properties,[length],[CRC] <pkey> <value>
  • 应答格式:response,[length],[CRC] <pkey> <code>
  • 说明:参数只能有一对pkey和value;响应必须有一组对应的pkey和code。

↓ez+set_properties switch true

↑response,, switch 0

↓ez+set_properties serial "123456789"

↑response,, serial 0