串口协议

更新时间:2024-06-24 06:01:39下载pdf

涂鸦 Wi-Fi 串口通用协议为涂鸦定制的 Wi-Fi 或 Wi-Fi & 蓝牙 LE 模组串口通用协议,主要用于涂鸦 Wi-Fi 或 Wi-Fi & 蓝牙 LE 模组与其它 MCU 串口直连做串口通信,其架构如下图所示。

涂鸦联网模组用户 MCUWi-Fi 模组或 Wi-Fi & 蓝牙模组TX->RXRX<-TX涂鸦联网模组用户 MCU

串口通信约定

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

帧格式

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

  • 一般情况下,采用同命令字一发一收同步机制。

    即一方发出命令,另一方应答,若发送方超时未收到正确的响应包,则超时传输,如下图所示:

    MCU模组发送命令字 N命令字 N 应答MCU模组

    具体通信方式以 协议列表 章节中为准。

  • 模组控制命令下发及 MCU 状态上报则采用异步模式,假设模组控制命令下发的命令字为 X,MCU 状态上报的命令字为 Y,如下所示:

  • 模组控制命令下发:

    模组MCU模组控制命令字 X 下发MCU 状态命令字 Y 上报模组MCU
  • MCU 状态上报:

    MCU模组MCU 状态命令字 Y 上报MCU模组
  • 版本字段

    版本用于拓展功能使用,为兼容新老版本协议,模组发送版本号均为 0x00,根据 MCU 回复版本号确定使用协议的版本。新用户默认使用协议版本为 0x03 即可。

联网模组串口缓冲区大小

芯片平台 接收缓冲区大小 发送缓冲区大小 备注
esp8266 256 字节 256 字节 固定大小,后续不会增加和迭代。
其他 最小为 1024 字节 最小为 1024 字节 若固件版本支持文件传输类功能,则缓冲区大小最大值参考文件传输时单包文件数据的最大长度。

MCU 完整数据大小(即从帧头开始计算到校验和结束计算)不可超出模组接收缓冲区大小值。如果数据包长度超出,则会出现数据通信异常情况。

状态数据单元

命令和状态数据单元(datapoint)如下所示:

数据段 字节数 说明
dpid 1 datapoint 序号
type 1 对应 涂鸦开发者平台 上一个 DP 具体的数据类型,参考下表中 type 字段说明
len 2 长度对应 value 的字节数,参考下表中 type 字段说明
value 1/2/4/N 用 16 进制表示,大于 1 字节采用大端传输

datapoint 中的 type 字段说明:

type 数据类型 字节数 说明
0x00 Raw N 对应于 raw 型 datapoint,采用模组透传的方式传输
0x01 Bool 1 范围:0x00/0x01
0x02 Value 4 又称 Integer 类型,采用大端表示
0x03 String N 对应于具体字符串
0x04 Enum 1 枚举类型,范围 0-255
0x05 Bitmap 1/2/4 长度大于 1 字节时,大端表示
  • datapoint 命令/状态数据单元中,除 Raw 类型外,其他类型均属于 Object 数据类型。
  • 状态数据可含多个 datapoint 命令数据单元。

协议列表

心跳检测

  • Wi-Fi 模组上电后,将会以 1 秒/次的频率持续发送心跳包,等待 MCU 回复。模组若收正确的心跳包回复,心跳包发送间隔变为 15 秒/次,继续执行其余初始化指令。模组若未收到正确回复,将保持 1 秒/次心跳包发送频率,直到收到正确回复。

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

模组发送

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

发送示例:55 aa 00 00 00 00 ff

MCU 返回

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

查询产品信息

产品信息由产品 ID 和 MCU 软件版本构成:

  • 产品 ID:即 PID(product ID),对应 涂鸦开发者平台 上产品的 PID,由涂鸦开发者平台生成,用于云端记录产品相关信息。
  • MCU 软件版本:采用点分十进制形式,格式为 x.x.x,其中 x 为十进制数,取值范围为 0-99。

模组发送

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

示例55 aa 00 01 00 00 00

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x01
数据长度 2 N
数据 N {“p”:“AIp08kLIftb8x***”, “v”:“1.0.0”, “m”:1, “mt”:10, “n”:0, “ir”:“5.12”, “low”:0}
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例{"p":"AIp08kLIftb8x***", "v":"1.0.0", "m":1,"mt":10,"n":0,"ir":"5.12", "low":0}

产品信息示例字段说明:

字段 说明
p 表示产品 ID 为 AIp08kLIftb8x***,即您在涂鸦开发者平台上创建的产品的 PID。
v 表示 MCU 版本为 1.0.0,MCU 版本号格式必须按照 x.x.x 的格式定义。
m 表示模组工作方式:
  • 0 表示常配网工作模式。模组出厂上电后一直处于待配网状态并一直保持。
  • 1 表示超时配网工作模式。模组出厂上电后处于非配网状态需要 MCU 发送重置命令才会进入相应的配网模式,当设备处于配网状态三分钟后未被用户配走模组便会重新进入非配网状态,需要重新收到重置命令才会重新进入配网模式。
  • 2 表示防误触工作模式。模组被用户配上后本地(MCU 发送重置命令)重置后,设备处于待配网状态三分钟没有被配走会会自动恢复重置前的用户网络连接。本地重置后设备中途异常断电上电也会自动恢复重置前的用户网络连接。这种模式下只有当设备被用户从 App 端移除设备便不会记录上次用户的网路连接并重连。这种模式用于需要有本地防误重置的用户场景的需求。
mt 设置安全模式和防误触模式的状态切换时间,没有上传这个字段统一按老的机制(三分钟)处理,可以支持的设置时间范围:3 分钟—10 分钟。
n 表示模组的配网模式,没有该字段保持传统(两种配网方式互相切换)的模式:
  • 0 表示 Wi-Fi 快连配网和热点联网共存配网模式。模组同时支持热点联网连接配网和快连配网无需用户切换,对应的配网状态包见 报告设备联网状态
  • 1 表示仅仅只有热点联网配网模式: 这种模式下产品只能通过热点联网连接的方式进行设备配网。
ir 启用模组的红外功能并告知模组红外的收发脚使用哪些 IO 口,没有这个字段红外能力默认关闭。 5.12:红外发送脚为 IO5,红外接收脚为 IO12。
注意:如果工作模式中使用模组自处理模式,请勿与按键和 Wi-Fi 指示灯设置的 IO 口重复。部分模组跨组 IO 设置,需要在设置组 IO 脚基础上加 32,PB20 设置序号为 20+32。红外发送脚需要用到 PWM 资源,接收需要使用 IO 中断,具体模组支持的 IO 口请参考模组资料。
若需要模组自处理工作状态指示红外工作状态指示灯,可通过命令字 设备新功能设置通知命令(可选) 设置。
low 模组是否开启保持长连接的低功耗模式,没有该字段低功耗模式默认关闭。对于有些产品对于没有网络控制的情况下,在模组保持和路由的连接下需要让模组的平均功耗低于 15mA,通过这个字段我们可以打开模组这个能力。双模模组打开这个功能后,模组只有蓝牙配网功能,蓝牙控制将会关闭。产品对于功耗没有要求的不需要关心这个字段。
  • 0:关闭低功耗模式
  • 1:打开模组低功耗模式
vt 表示 MCU 的固件类型,默认 MCU 固件类型为 9(为 9 时无需设置此字段),此字段数据可选值为 10—19。使用此字段则表示 MCU 固件类型为设置的值,且此数据与涂鸦开发者平台下的固件类型匹配。

vt 字段内容一定要与涂鸦开发者平台创建的固件类型数据匹配,否则会出现无法接收 OTA 信息或接收到错误的 OTA 升级信息,导致 OTA 升级异常。

查询工作模式

模组的配网触发及指示方式,由 MCU 选择设定。模组工作模式主要针对如何指示 Wi-Fi 的工作状态以及如何重置配网 Wi-Fi 而言,主要分两种情况:

  • MCU 与模组配合处理模式:

    MCU 检测配网触发信号,通过串口指令让 Wi-Fi 模组重置配网。模组通过串口通知 MCU,Wi-Fi 当前的工作状态,由 MCU 提供显示支持,家电类产品通常建议选择此模式。

  • 模组自处理模式:

    Wi-Fi 模组的工作状态通过 Wi-Fi 的 GPIO 引脚驱动 LED 状态显示。Wi-Fi 重置配网通过检测 GPIO 输入需求处理。

    模组自处理 Wi-Fi 重置方法为:Wi-Fi 检测 GPIO 入口低电平持续 5s 以上触发 Wi-Fi 重置。指示灯与按钮所使用的 GPIO 管脚由以下命令配置。

模组发送

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

示例55 aa 00 02 00 00 01

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x02
数据长度 2 0x0000/0x0002/0x0003
  • 0x0000:指示模组工作为 MCU 与模组配合处理 模式,MCU 需实现上述说明中提及的功能。
  • 0x0002/0x0003:指示模组工作为模组自处理模式。
数据 0/2/3 数据长度为 2
  • Data[0]:Wi-Fi 状态指示 GPIO 序号。
  • Data[1]:Wi-Fi 重置按键 GPIO 序号。
数据长度为 3
  • Data[0]:Wi-Fi 状态指示 GPIO 序号。
  • Data[1]:Wi-Fi 重置按键 GPIO 序号。
  • Data[3]:Bluetooth LE 状态指示 GPIO 序号。
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • MCU 与模组配合处理:

    55 aa 03 02 00 00 04

  • 模组自处理,指示灯 0x0c:GPIO12,复位按钮 0x0d:GPIO13:

    55 aa 03 02 00 02 0c 0d 1f

设备新功能设置通知命令(可选)

  • 此命令在设备上电后,在0x01 命令之后 0x02 命令字之前发送执行,用于相关功能设置通知。
  • 若无所需要的新增功能,此命令字不需要执行
  • 此命令每次上电或者是模组启动之后均需要发送,即 MCU 可按照逻辑,在收模组的 0x01 命令字后就发送此命令,设置所需要的功能。
  • 此命令会根据业务的拓展,功能字段也会扩充增加

  • ir:红外工作状态指示灯,红外状态指示灯使能即有效,可复用 Wi-Fi 网络状态指示灯,但注意不可与 02 命令字的其它功能 GPIO 冲突。红外工作指示灯,工作时指示规则如下:
    • 复用 Wi-Fi 状态指示灯 GPIO :非红外工作时 LED 为亮灯状态,则红外工作时灭灯。
    • 其它 GPIO :非红外工作时 LED 为灭灯状态,则红外工作时亮灯。
  • buf:MCU 串口资源 BUF 可承受的最大数据量。RF 遥控器功能在下发多键值的情况下以此字段数据参考是否分包发送键值。
  • RF 遥控器:指 433 小无线射频遥控器,涂鸦标准 RF 方案。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0001
数据 1 子命令:0x00
{ “mcu_ota”:xx, “abv”:x, “ir”:xx, “buf”:xx }
  • mcu_ota MCU OTA 执行方式设置:
    • 0x00:MCU 有程序暂存区
    • 0x01:MCU 无程序暂存区
  • abv:功能使能字段,按位设置
    • Bit0:蓝牙连接状态通知(双模设备支持):1:开启通知。0:关闭。
    • Bit1:RF 遥控器功能使能: 1:开启功能。0:关闭功能。
    • Bit2:蓝牙遥控器功能使能:1:开启功能。0:关闭功能
    • Bit3:状态查询(CMD:0x08)功能使能:1:开启功能。0:关闭功能
    • Bit4-bit7:0,预留,默认填充 0。
  • ir: 红外工作状态指示灯,设置模组自处理时红外工作状态指示灯的 GPIO。 数据内容规则与 0x02 命令字相同,指示规则请看 红外工作指示
  • buf:MCU 串口接收 BUF 大小,最小值为 256(字节),模组默认 MCU 可支持任何长度数据。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:MCU 有程序暂存区,abv 使能 RF 遥控器功能,BUF 为 1024。{“mcu_ota”:0,“abv”:3,“buf”:1024}

55 aa 03 37 00 21 00 7b 22 6d 63 75 5f 6f 74 61 22 3a 30 2c 22 61 62 76 22 3a 33 2c 22 62 75 66 22 3a 31 30 32 34 7d ac

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0002
数据 1 子命令:0x00
1 Ret: 0x00:成功。 0x01:数据字段内容不合法。 0x02:设置执行失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 37 00 02 00 00 3b

产品信息示例字段说明:

字段 是否必选 说明
mcu_ota 可选 设置 MCU 无程序暂存区 OTA,暂时只有 HomeKit 通用对接支持这个功能
abv 可选 新增功能使能字段,1 个字节 8 个 bit,按位表示不同的功能
  • Bit0:蓝牙连接状态通知(双模设备支持),功能暂不支持:1:开启通知。0:关闭。
  • Bit1:RF 遥控器功能使能: 1:开启功能。0:关闭功能
  • Bit2-bit7:0,预留,默认填充 0
ir 可选 红外工作状态指示灯,设置模组自处理时红外工作状态指示灯的 GPIO,GPIO 引脚编码规则同 02 命令字。示例: 5:表示红外工作状态指示灯引脚为 IO5
buf 可选 MCU 串口接收 BUF 大小,最小值为 256(字节)

报告设备联网状态

设备联网状态 描述 状态值
状态 1 Wi-Fi 快连配网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x00
状态 2 热点联网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x01
状态 3 Wi-Fi 已配置但未连上路由器 0x02
状态 4 Wi-Fi 已配置且连上路由器 0x03
状态 5 设备成功连接到云端 0x04
状态 6 主联网设备处于低功耗模式 0x05
状态 7 Wi-Fi 设备处于 Wi-Fi 快连配网和热点联网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x06
  • 设备联网状态:

    • Wi-Fi 快连配网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态)
    • 热点联网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态)
    • Wi-Fi 配置成功但未连上路由器
    • Wi-Fi 配置成功且连上路由器
    • 设备成功连接到云端。
  • 模组自处理工作模式相应的 LED 显示分别为:

    • 状态 1:间隔闪烁 250ms。
    • 状态 2:间隔闪烁 1500ms。
    • 状态 3 或 6:长暗状态。
    • 状态 4 或 5:长亮状态。
  • 当模组检测到 MCU 重启或 MCU 断线再上线的过程,则主动下发 Wi-Fi 状态至 MCU。

  • 当模组的联网状态发生变化,则主动下发设备联网状态至 MCU。

  • 如设置模组工作模式为模组自处理,则 MCU 无需实现该协议。

  • Wi-Fi & 蓝牙 LE 模组接入的设备,当设备同步联网状态为 0x000x010x06 时,蓝牙也处于可配网状态中。
  • 当设备同步联网状态为 0x04 时,则表示设备已经成功接入涂鸦 IoT 云,不论是通过 Wi-Fi 还是通过蓝牙方式接入涂鸦 IoT 云。当通过蓝牙方式接入涂鸦 IoT 云时需结合蓝牙连接状态来判断是否 App 可控。
  • 建议 MCU 订阅 报告设备蓝牙连接状态,来通知用户当前设备蓝牙网络状态的变化。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x03
数据长度 2 0x0001
数据 1 指示 Wi-Fi 工作状态:
  • 0x00:状态 1
  • 0x01:状态 2
  • 0x02:状态 3
  • 0x03:状态 4
  • 0x04:状态 5
  • 0x05:状态 6
  • 0x06:状态 7
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 03 00 01 00 03

MCU 返回

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

示例55 aa 03 03 00 00 05

重置 Wi-Fi

配网相关命令,模组收到该指令后会重启,初始化相关命令交互完成后模组进入配网模式,可以使用 App 进行配网。

  • 重置 Wi-Fi 后模组工作状态转化如下图所示:

    串口协议
    • 发送重置指令时,请在模组初始化完成后发送,否则可能无效。更多详情,请参考 Wi-Fi 模组初始化流程
    • Wi-Fi & 蓝牙 LE 双模模组发送重置指令后,Wi-Fi & 蓝牙 LE 均会处于待配网状态下。
  • 如设置模组工作模式为模组自处理,则 MCU 无需实现该协议。

    模组自处理 Wi-Fi 重置方法为:Wi-Fi 检测 GPIO 入口低电平持续 5s 以上触发 Wi-Fi 重置。

MCU 发送

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

示例55 aa 03 04 00 00 06

模组返回

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

示例55 aa 00 04 00 00 03

重置 Wi-Fi 选择配置模式

配网相关命令,与重制 Wi-Fi 命令功能类似。

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

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

  • 如设置模组工作模式为模组自处理,则 MCU 无需实现该协议。

    • 发送重置指令,请在模组初始化完成后发送,否则可能无效。初始化流程可参考 Wi-Fi 模组初始化流程
    • 当 MCU 在查询产品信息中字段 n 设置后,则此命令的指定切换功能无效。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x05
数据长度 2 0x0001
数据 1
  • 0x00:进入 smartconifg 配置模式
  • 0x01:进入热点联网配置模式
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:进入 Wi-Fi 快连配网配置模式

55 aa 03 05 00 01 00 08

模组返回

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

示例55 aa 00 05 00 00 04

命令下发

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

  • “命令下发为异步处理协议,通常下发数据解析完成后,MCU 会根据 datapoint 数据执行对应功能,若 datapoint 状态发生改变,MCU 还需使用状态上报命令

模组发送

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

示例:系统开关对应 3 号 DP,使用 bool 型变量,开机数值为 1

55 aa 00 06 00 05 03 01 00 01 01 10

状态上报(异步)

  • datapoint 状态数据单元说明,请参考 状态数据单元

  • 该协议为异步处理协议,状态上报触发机制有三类:

    • MCU 收到命令下发处理帧时,正确执行相应 datapoint 命令。再通过状态上报帧,将变化后的 datapoint 状态发送至模组。
    • MCU 主动检测到 datapoint 有变化,将变化后的 datapoint 状态发送至模组。
    • MCU 收到 状态查询 帧时,将所有的 datapoint 状态发送至模组。
  • 状态上报可含多个 datapoint 状态数据单元”。

  • 建议在 datapoint 状态改变时上报即可,有利于保证数据传输稳定性。请避免在短时间内,持续循环进行数据上报。
  • 在设备待机或者工作稳定状态下,请尽量控制重复 datapoint 的循环上报频率。建议最小上报间隔为 1 分钟。
  • MCU 上报的数据请注意数据的合法性,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致,不多报任何不存在的 DP。
  • MCU 上报的数据请注意数据的合法性,确保 DP ID 与数据类型以及内容,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致。

MCU 发送

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

示例

  • 湿度对应 5 号 DP,使用 value 型变量,湿度为 30℃

    55 aa 03 07 00 08 05 02 00 04 00 00 00 1e 3a

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

    • DP 点 109 bool 型变量,数值为 1

    • DP 点 102 string 型变量,201804121507(具体传输对应 ASCII 值)

      55 aa 03 07 00 15 6d 01 00 01 01 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 62

状态上报(同步)

  • 此命令为同步指令,MCU 数据状态上报后,需要等待模组返回结果。

  • 每次状态上报,模组都会有响应。模组未响应前,不可多次上报。

  • 网络环境差、数据难以及时上报时,模组会在 5 秒后返回失败。此时,MCU 需要等待 5 秒以上。

  • datapoint 状态数据单元说明,请参考 状态数据单元

  • 状态上报可含多个 datapoint 命令数据单元。

  • 建议在 datapoint 状态改变时上报即可,有利于保证数据传输稳定性。请避免在短时间内,持续循环进行数据上报。
  • 建议存在多个 DP 需要上报时,使用组合 DP 上报方式。若是单 DP 上报的方式,建议将每个 DP 数据上报间隔至少为 250 毫秒,有利于保证数据传输稳定性。
  • 在设备待机或者工作稳定状态下,请尽量控制重复 datapoint 的循环上报频率。建议最小上报间隔为 1 分钟。
  • MCU 上报的数据请注意数据的合法性,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致,不多报任何不存在的 DP。
  • MCU 上报的数据请注意数据的合法性,确保 DP ID 与数据类型以及内容,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致。

MCU 发送

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

示例:上报 bool 型 dp1,状态为 true

55 aa 03 22 00 05 02 01 00 01 01 2e

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x23
数据长度 2 0x0001
数据 Data
  • 0x00:表示失败
  • 0x01:表示成功
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 23 00 01 01 24

状态上报(记录型 DP)

  • 此协议为同步指令。MCU 数据状态上报后,需要等待模组返回结果。

  • 每次状态上报,模组都会有响应。模组未响应前,不可多次上报。

  • 网络环境差、数据难以及时上报时,模组会在 5 秒后返回失败。此时,MCU 需要等待 5 秒以上。

  • datapoint 状态数据单元说明,请参考 状态数据单元

  • 状态上报可含多个 datapoint 命令数据单元。

  • 对于类似门锁、电量统计插座等有记录或数据统计功能的设备,包含部分 DP 数据需要服务端统计记录的,可使用本条命令上报。当 MCU 需要记录数据是由多个 DP 组合的整条数据,MCU 则需要整体上报。

  • 目前此功能在使用 Wi-Fi 通信方式时支持,蓝牙通信方式暂未迭代支持。但支持蓝牙通信方式后,您无需修改 MCU 代码,更新模组固件即可。

  • 使用此功能时,请核对模组固件版本是否支持。

  • 此协议暂时不支持让模组保存上报失败的数据。
  • 建议在 datapoint 状态改变时上报即可,有利于保证数据传输稳定性。请避免在短时间内,持续循环进行数据上报。
  • 建议存在多个 DP 需要上报时,使用组合 DP 上报方式。若是单 DP 上报的方式,建议将每个 DP 数据上报间隔至少为 250 毫秒,有利于保证数据传输稳定性。
  • 在设备待机或者工作稳定状态下,请尽量控制重复 datapoint 的循环上报频率。建议最小上报间隔为 1 分钟。
  • MCU 上报的数据请注意数据的合法性,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致,不多报任何不存在的 DP。
  • MCU 上报的数据请注意数据的合法性,确保 DP ID 与数据类型以及内容,与 查询产品信息 p 字段同步的 PID 在 涂鸦开发者平台 下设置的 DP 内容信息一致。

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x34
数据长度 2 取决于 状态数据单元类型以及个数
数据 1 0x0b(子命令)
1 0x01(默认填充此数据)
1 上报时间类型:
  • 0x00:不上报 MCU 时间,模组侧填充,需要在模组获取时间后使用
  • 0x01:上报时间为设备所在的当地时间
  • 0x02:上报时间为格林时间
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 结束
N 状态数据单元
校验和 1 从帧头开始按字节求和得出的 结果 N 对 256 求余

例 1:上报 bool 型 dp,dpid 为 1,状态为 true,格林时间 2022.02.18.16:27:06 :55 aa 03 34 00 0e 0b 01 02 16 02 12 10 1b 06 01 01 00 01 01 b1
例 2:上报 Value 型 dp,dpid 为 2,状态为 100 和 Enum 型 dp,dpid 为 3,状态为 3,本地时间 2022.02.22.11:22:33:55 aa 03 34 00 16 0b 01 01 16 02 16 0b 16 21 02 02 04 00 00 00 64 03 04 01 03 40

模组返回

字段 长度 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x0b(子命令)
1 上报状态:
  • 0x00:MCU 上报数据到模组且模组上报到云端成功
  • 0x02:上报失败
  • 0x03:数据内容非法
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 00 34 00 02 0b 00 40

状态查询

  • 状态查询为异步处理协议,主要用于模组查询 MCU 所有的 obj 类型的 datapoint 状态,当 MCU 收到此帧时,通过 状态上报 帧上报 datapoint 状态。

  • 状态查询发送时机主要有三种:

    • 模组首次上电,通过心跳与 MCU 建立连接后,查询发送。
    • 模组工作过程中检测到 MCU 重启或发生了离线再上线的过程,查询发送,需要配合 0x3700 命令字的 abv 字段 bit3 使能
    • 当设备 Wi-Fi 连接情况下,每次进入面板(面板需要支持功能),触发查询发送,需要配合 0x3700 命令字的 abv 字段 bit3 使能
  • 使用此功能时,请确认固件版本功能支持情况,建议更新使用最新发布版本。
  • 老版本固件仅支持模组首次上电查询发送场景。

模组发送

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

示例55 aa 00 08 00 00 07

MCU 升级服务

  • 何时升级由客户在涂鸦开发者平台自己的产品页面配置相关升级选项触发,模组仅作为支持 MCU 升级的数据传输通道,也不对数据内容做任何解析。

  • 目前涂鸦平台的 MCU 升级支持下面四种升级方式的配置:

    • App 提醒升级:用户每次进入设备控制面板都会收到升级提醒的弹窗,是否确认升级由用户自己在 App 确认。
    • App 静默升级:App 不会有任何提醒弹窗,模组上电后一分钟内会去自动去检测升级发现有高版本的升级包会自动开始拉取相关升级包,第一次上电后模组会间隔 24 小时去云端检测一次是否有升级包配置。
    • App 强制升级:App 会有升级提醒弹窗,如果用户不确认升级用户就没法正常使用这个产品的控制面板。
    • App 检测升级:App 不会有任何升级提醒的弹窗,必须要用户自己在 App 上点击相关固件版本检测,如果有高版本的固件配置才会显示升级提示信息。
  • MCU 升级相关流程图:
    Wi-Fi 模组发送完所有的升级包,重新发送 01 命令字(查询产品信息),MCU 需要在一分钟回复产品信息中的 MCU 软件版本号(升级后的版本号),版本号需要和在涂鸦后台配置升级的版本号保持一致。

串口协议

升级启动(升级包大小通知)

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

模组发送

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

示例55 aa 00 0a 00 04 00 00 68 00 75

表示固件包长度 26624,即 26KB。

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x0a
数据长度 2 0x0001
数据 1 升级包分包传输大小:
  • 0x00:默认 256byte(兼容旧固件)
  • 0x01:512byte
  • 0x02:1024byte
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 03 0a 00 01 00 0d

升级包传输

  • 升级包传输数据格式:包偏移 + 包数据。

  • MCU 若收到该帧数据长度为 4 字节,并且包偏移 ≥ 固件大小,则包传输结束。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0b
数据长度 2 0x0004+N
数据 4+N
  • data[0]–data[3]:固定为包偏移
  • data[4]–data[n]:数据包内容
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

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

  • 第一包数据,包偏移为 0x00000000,数据包长度为 256
    55 aa 00 0b 01 04 00000000 xx…xx XX
  • 第二包数据,包偏移为 0x00000100,数据包长度为 256
    55 aa 00 0b 01 04 00000100 xx…xx XX
  • 倒数第 2 包数据,包偏移为 0x00000200,数据包长度为 18
    55 aa 00 0b 00 16 00000200 xx…xx XX
  • 最后一包,包偏移为 0x00000212,数据包长度为 0
    55 aa 00 0b 00 04 00000212 xx...xx XX

MCU 返回

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

示例55 aa 03 0b 00 00 0d

获取系统时间(格林时间)

  • 格林时间不带有时区和夏令时的因素,是一个国际标准的时间基准。

  • 当模组连接上网络后,本地的时间戳校准完成才会返回成功,并携带有效的时间数据。

  • Wi-Fi + 蓝牙 LE 的模组,当接收模组的 报告设备蓝牙连接状态 状态值为 0x03 后,也可以实现时间戳校准功能。设备与 App 连接建立时,App 需要连接外网。
  • 当接收到模组的 报告设备联网连接状态 状态值为 0x04 后,模组会执行时间戳校准功能。
  • 设备上电后 MCU 若不想主动获取时间,可通过 打开模组时间服务通知,等待模组时间戳校准完成后主动通知 MCU 时间信息。
  • 模组时间戳校准的功能,需要一定的时间消耗,MCU 在收到模组对应状态通知后立刻获取时间,可能会出现获取失败情况,此时请重试。
  • 关于 Wi-Fi + 蓝牙 LE 的模组,注意固件需更新到最新版本后,才可支持蓝牙 LE 连接后的时间校准功能。
  • 若固件更新后,依然无法实现蓝牙 LE 连接后的时间校准功能,可联系涂鸦工作人员帮忙排查问题。

MCU 发送

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

示例55 aa 03 0c 00 00 0e

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0c
数据长度 2 0x0007
数据 7 数据长度为 7 字节:
  • 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 结束
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

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

55 aa 00 0c 00 07 01 10 04 13 05 06 07 4c

获取本地时间

  • 本地时间是在格林时间的基础上加上当地(设备激活所在地)时区和夏令时的时间。

  • 当模组连接上网络后,本地的时间戳校准完成才会返回成功,并带有有效的时间数据。

  • Wi-Fi + 蓝牙 LE 的模组,当接收模组的 报告设备蓝牙连接状态 状态值为 0x03 后,也可以实现时间戳校准功能。设备与 App 连接建立时,App 需要连接外网。
  • 当接收到模组的 报告设备联网连接状态 状态值为 0x04 后,模组会执行时间戳校准功能。
  • 设备上电后 MCU 若不想主动获取时间,可通过 打开模组时间服务通知,等待模组时间戳校准完成后主动通知 MCU 时间信息。
  • 模组时间戳校准的功能,需要一定的时间消耗,MCU 在收到模组对应状态通知后立刻获取时间,可能会出现获取失败情况,此时请重试。
  • 关于 Wi-Fi + 蓝牙 LE 的模组,注意固件需更新到最新版本后,才可支持蓝牙 LE 连接后的时间校准功能。
  • 若固件更新后,依然无法实现蓝牙 LE 连接后的时间校准功能,可联系涂鸦工作人员帮忙排查问题。

MCU 发送

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

示例55 aa 03 1c 00 00 1e

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1c
数据长度 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 求余
  • 如设备在国内激活使用,则当地时间为北京时间(东 8 区)。
    例:北京时间 2016 年 4 月 19 日 5 时 6 分 7 秒
    55 aa 00 1c 00 08 01 10 04 13 05 06 07 02 5f

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

Wi-Fi 功能性测试(扫描指定路由)

  • 模组内部目前扫描指定的 SSID:tuya_mdev_test,返回扫描结果和信号强度百分比。

  • 这里为了最大程度防止不良品这里建议客户将路由于设备距离控制在 5 米左右,信号强度大于等于 60%为合格,这里可以根据自己产线和工厂环境的情况自行调整。

    发送测试指令,请在模组初始化完成后发送,否则可能无效。更多详情,请参考 Wi-Fi 模组初始化流程

MCU 发送

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

示例55 aa 03 0e 00 00 10

模组返回

字段 字节数 说明
帧头 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 求余

示例:未扫描到指定的 ssid:55 aa 00 0e 00 02 00 00 0f

获取模组内存

获取 Wi-Fi 模组剩余内存

MCU 发送

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

例:55 aa 03 0f 00 00 11

模组返回

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

例:MemorySize: 53328 Byte:55 aa 00 0f 00 04 50 d0 00 00 32

打开获取天气数据功能(可选)

打开获取天气数据功能

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x20
数据长度 2 N((L+K)+(L+K)…)
数据 n data:
  • L:占用 1 byte,表示 K 的长度
  • K:请求参数名称
  • L:0x06 K:w.temp
  • L:0x06 K:w.pm25
  • L:0x0a K:w.humidity
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

天气服务支持的字段功能说明可参考 天气预报服务功能

示例:请求参数 w.temp,w.pm25

55 aa 03 20 00 0e 06 77 2e 74 65 6d 70 06 77 2e 70 6d 32 35 80

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x20
数据长度 2 0x0002
数据 2
  • Data[0]:
    • 0x00 表示失败,失败具体错误原因见 Data[1]的错误码说明
    • 0x01 表示成功
  • Data[1]:
    • 0x00 无错误
    • 0x01 错误码,数据格式非法
    • 0x02 错误码,异常错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例 55 aa 00 20 00 02 01 00 22

下发天气数据(可选)

下发天气数据,在打开天气数据功能后模组定时下发,开启功能后会立马下发一次,后续以 30 分钟的间隔下发。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x21
数据长度 2 N((LKTLV)+(LKTLV)+…)
数据 Data
  • 0x00:表示失败
  • 0x01:错误码,表示参数服务没权限(确认是否购买了该参数服务或是否通过 0x20 命令字打开天气服务功能)
  • 0x01:表示成功
  • L:参数名长度
  • K:参数名
  • T:0x00 整形、0x01 字符串
  • L:字段名长度
  • V:字段值
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x21
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余
  • 请求参数如 w.temp,w.pm25 返回 w.temp,返回参数少于请求参数请仔细检查请求参数名是否正确。

  • 天气服务支持的字段功能说明可参考 天气预报服务功能

示例:w.humidity:69,w.temp:32,w.pm25:10

55 aa 00 21 00 30 01 0a 77 2e 68 75 6d 69 64 69 74 79 00 04 00 00 00 45 06 77 2e 74 65 6d 70 00 04 00 00 00 20 06 77 2e 70 6d 32 35 00 04 00 00 00 10 1e 5c

主动请求天气服务数据

  • 针对有些产品需求,需要在半个小时主动发送的天气服务基础上,拥有主动获取天气服务数据的能力,我们提供这个命令用于用户主动获取天气服务接口数据。
  • 这个命令使用频率不能小于 20 分钟,20 分钟内的多次请求只处理 1 次。
  • 这个命令用于确认数据请求,数据下发还是通过 0X21 的下发天气数据的命令。

MCU 发送

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

示例55 aa 03 34 00 01 03 3a

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x03(子命令)
1 执行结果:
  • 0x00:成功。
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 00 34 00 02 03 00 38

获取当前 Wi-Fi 信号强度(可选)

MCU 发送

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

示例55 aa 03 24 00 00 26

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x24
数据长度 2 0x0001
数据 Data
  • 0x00:表示失败
  • 小于 0:表示信号强度,如(-60db)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:RSSI: -20:55 aa 00 24 00 01 ec 10

通知 Wi-Fi 模组关闭心跳(可选)

MCU 发送

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

例:55 aa 03 25 00 00 27

模组返回

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

例:55 aa 00 25 00 00 24

对于需要休眠降低功耗的 MCU 模组,可在休眠前发送该指令关闭 Wi-Fi 模组心跳,方便进入休眠状态。该指令请勿在设备刚上电时发送,Wi-Fi 模组上电后需要和 MCU 建立心跳连接。

串口配网接口(可选)

  • 标准对接使用 App 与模组交互实现配网功能的客户无需实现此命令功能。

  • 适用于本地配网的场景,利用涂鸦 App 或者涂鸦 App 的 SDK 自主开发,拿到相关配网参数,并通过串口给到模组这些数据,来实现通过串口通信完成模组的配网操作。

  • 模组必须处于待配网状态才能完成串口配网。

  • 模组返回成功接收串口配网信息的应答之后便会使用拿到的信息去连接路由,并到云端激活。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x2A
数据长度 2 xx
数据 Data {“s”:“xxx”, “p”:“yyy”, “t”:“zzz”}
  • s:SSID
  • p:密码
  • t:Token,由 App 生成
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:{“s”:“xxx”, “p”:“12345678”, “t”:“zzz”}

55 aa 03 2a 00 24 7b 22 73 22 3a 22 78 78 78 22 2C 22 70 22 3a 22 31 32 33 34 35 36 37 38 22 2c 22 74 22 3a 22 7a 7a 7a 22 7d B7

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x2A
数据长度 2 0x0001
数据 x
  • 0x00:数据接收成功
  • 0x01:不在配网状态
  • 0x02:JSON 数据非法
  • 0x03:其他错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 2a 00 01 01 2b

获取当前设备联网状态

设备联网状态 描述 状态值
状态 1 Wi-Fi 快连配网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x00
状态 2 热点联网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x01
状态 3 Wi-Fi 已配置但未连上路由器 0x02
状态 4 Wi-Fi 已配置且连上路由器 0x03
状态 5 设备成功连接到云端 0x04
状态 6 主联网设备处于低功耗模式 0x05
状态 7 Wi-Fi 设备处于 Wi-Fi 快连配网和热点联网配置状态(Wi-Fi & 蓝牙 LE 模组:蓝牙也处于配网状态) 0x06

报告设备联网状态 保持一致。

MCU 发送

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

示例 55 aa 03 2b 00 00 2d

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x2B
数据长度 2 0x0001
数据 1
  • 0x00 :Wi-Fi 快连配网配置状态
  • 0x01 :热点联网配置状态
  • 0x02 :Wi-Fi 已配置但未连上路由器
  • 0x03 :Wi-Fi 已配置且连上路由器
  • 0x04 :已连上路由器且连接到云端
  • 0x05 :Wi-Fi 设备处于低功耗模式
  • 0x06 :Wi-Fi 设备处于 Wi-Fi 快连配网和热点联网配置状态
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:状态 4(已连上路由器且连接到云端): 55 aa 00 2b 00 01 04 2f

扫地机地图数据服务(可选)

  • 扫地机流服务的命令不是所有模组都支持,需要使用特定的模组开通相关服务才可以正常使用该服务。

  • 该服务目前针对扫地机地图数据传输的服务,作为扫地机和涂鸦 App 地图数据在线上的一个特殊快捷通道。

  • 扫地机一次完整的地图数据靠协议中的地图 ID 去区分,同一个 ID 的数据 App 端会认为这是一张地图数据会一直累加处理。

  • 扫地机在清扫过程中需要在全屋范围内移动,这里涉及到部分区域 Wi-Fi 信号弱可能会导致数据上传失败,在模组内存充足的前提下,目前可以缓存 24 条数据。

串口协议

地图流数据传输

  • 偏移量表示一次地图数据 MCU 已经发送的数据总长。

  • 目前模组串口最大可以缓存的数据部分可以达到 1024 字节,一包地图数据包数据部分不能超过 1024 字节,每包地图数据内容建议 512 字节。

  • 地图 ID 作为一次完整地图数据的标志,数据传输方需要在一次清扫完成,也就是一张地图数据结束后,新的清扫开始时,改变地图 ID,一般以递增的方式进行。当地图 ID 改变,当前地图数据 App 界面显示,会清除之前数据,重新开始显示。

  • 开始数据传输后,模组会停止心跳包发送,保证地图数据的优先传输,后面模组不断电的前提下不会主动恢复心跳包的发送。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x28
数据长度 2 0x0006+N
数据 2 data[0]–data[1]地图 ID 号:地图 ID 号作为一张地图数据的归属标识。
4 data[2]–data[5]偏移量(首包为 0)
N data[6]–data[N]实体数据(大端模式)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:地图 ID:123。包偏移量:0

55 aa 03 28 xx xx 00 7b 00 00 00 00 xx xx xx xx xx

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x28
数据长度 2 0x0001
数据 1 Data
  • 0x00:成功
  • 0x01:流服务功能未开启
  • 0x02:流服务器未连接成功
  • 0x03:数据推送超时
  • 0x04:传输的数据长度错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 28 00 01 00 28

地图流数据传输(支持多张地图数据)(可选)

说明:

  • 扫地机流服务的命令不是所有模组都支持,需要使用这个服务需要使用特定的模组开通相关的服务才可以正常使用。

  • 这个服务目前针对扫地机地图数据传输的服务,作为扫地机和涂鸦 App 地图线上的一个特殊快捷通道。

  • 此通道用于扫地一张地图显示有多张数据图合成的扫地机机使用。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x30
数据长度 2 0x0009+N
数据 1 地图服务协议版本:0x00
2 地图服务会话 ID 号:作为一次地图显示的标志
6
  • BUF[0]:子地图 ID 号。一次地图会话可以由多张地图数据合成,比如路径图。
  • BUF[1]:地图 ID 数据处理方式。0x00:继续累加。0x01:清除子地图 ID 号上传的数据。
  • BUF[2]-BUF[5]:子地图数据偏移量(首包为 0)。
N 实体数据(大端模式)
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 30 00 xx 00 00 00 01 00 00 00 00 xx xx xx xx xx xx

模组返回

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

示例55 aa 03 30 00 01 00 33

获取地图会话 ID(可选)

说明:

  • 此命令为地图流服务单张地图和多张地图传输协议的补充。

  • 地图会话 ID 由模组管理。MCU 在传一张新的地图数据时,可以先向模组申请地图会话 ID(子地图 ID 不用申请,根据子地图个数,依次为 0x01、0x02、0x03……即可),模组会在回复时将此次地图会话 ID 返回给 MCU,随后 MCU 传输这张地图的地图会话 ID 都需要使用此 ID。

  • 用户如果想自行管理地图会话 ID,可以不使用此命令。

MCU 发送

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

示例55 aa 03 30 00 01 00 33

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0004
数据 1 0x06(子命令)
1 传输结果。
  • 0x00:成功
  • 0x01:流服务未开启
  • 0x02:获取 ID 失败
2 地图会话 ID(如果传输结果失败,此数据为无效数据)。
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 00 34 00 04 06 00 00 00 3d

Wi-Fi 功能性测试(连接指定路由)

  • MCU 发送路由信息模组返回成功后,模组会使用相关信息去连接路由。

  • MCU 判断是否连接上路由器,根据收到模组 报告设备联网状态 中的(状态 4-Wi-Fi 已配置且连上路由器)的包为准。MCU 收到返回失败,或者长时间(超过 15s)没有收到连上路由的状态包,认为测试失败。

  • 产测成功重复进入产测可以重新发送测试命令,没有收到连上路由的包表示模组正在产测中需要重置模组或者重新上电后发送测试命令才有效。

  • 模组需要在处于未被配网的状态下才能完成连接测试。

  • 产测前必须回复模组的心跳包且产品查询包模组完成初始化才能进入连接路由的产测。

  • 路由器名称字符串长度最大支持 32 个字节,路由器密码字符串长度最大支持 64 个字节。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x2C
数据长度 2 n
数据 n {“ssid”:“xxx”, “password”:“xxxxxxxx”}
  • ssid:路由名称
  • password:路由密码
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:{“ssid”:“xxx”, “password”:“12345678”}

55 aa 03 2c 00 24 7b 22 73 73 69 64 22 3a 22 78 78 78 22 2c 22 70 61 73 73 77 6f 72 64 22 3a 22 31 32 33 34 35 36 37 38 22 7d 2c

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x2C
数据长度 2 0x0001
数据 1 数据长度为 1 字节。
Data[0]:
  • 0x00:路由信息接收失败。请检查发出的路由 JSON 包数据是否完整。
  • 0x01:路由信息接收成功。结果请注意 报告设备联网状态 的网络状态包。
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 2c 00 01 01 2d

获取模组 MAC

MCU 发送

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

示例55 aa 03 2d 00 00 2f

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x2d
数据长度 2 0x0007
数据 Data
  • data[0]:获取 MAC 地址是是否成功的标志
    • 0x00 表示成功,表示后面 6 字节的 MAC 地址有效
    • 0x01 表示获取 MAC 失败,表示后面 6 字节的 MAC 无效
  • data[1]~data[6]:当获取 MAC 地址标志位 data[0]表示成功则表示模组有效的 MAC 地址
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:MAC: 508A0E3A2D9

55 aa 00 2d 00 07 00 50 8a 06 e3 a2 d9 71

红外状态通知(可选)

设备红外状态 描述 状态值
状态 1 正在发送红外码 0x00
状态 2 发送红外码结束 0x01
状态 3 红外学习开始 0x02
状态 4 红外学习结束 0x03
  • 红外功能的通过涂鸦开发者平台配置或者相关项目经理手动开通并寄样。

  • 红外码发送的时间周期非常短,并且需要保持好的实时性,这里的串口数据直接发送,不做相关重发。

  • 客户根据自己的开发需求,根据红外状态做相关状态显示。

  • 红外功能的发码和接受红外码需要使用到模组的两个 IO 脚,如果您的设备使用的联网状态也是模组自处理模式,请注意 IO 口不要设置相关的 IO 脚。

模组发送

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

示例55 aa 00 2e 00 01 00 2e

MCU 返回

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

示例55 aa 03 2e 00 00 30

红外进入收发产测(可选)

串口协议
  • 红外产测功能需要在未配网状态下才会进入。

  • 模组进入红外产测状态就会进入红外学习状态。

  • 模组一旦进入红外产测模式就会一直处于产测状态,不断根据学习到数据再发送出来,当模被配上网或者被断电就会退出产测。

MCU 发送

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

示例55 aa 03 2f 00 00 31

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x2f
数据长度 2 0x0001
数据 Data
  • 0x00 表示进入红外收发产测成功
  • 0x01 表示进入红外收发产测失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 2f 00 01 00 2f

射频功能相关协议(可选)

  • 此部分协议功能的使用,需要通过 0x3700 命令字中 abv 字段使能打开此部分协议功能。
  • 由于射频码会存在某些产品一次操作有多个键值下发的场景,考虑到 MCU 的资源,因此 MCU 可通过 0x3700 命令字中的 buf 字段,通知 MCU 的串口 BUF 资源情况(考虑到键值的最大数据 MCU 的资源应大于 256 字节)。
    Wi-Fi 模组在多键值下发的情况下以此判断是否需要分包发送,最小分包数据量是一个键值。 默认多键值时以一条串口命令下发所有键值数据内容。
  • 射频功能的执行方是在 MCU 侧,从用户使用角度考虑 Wi-Fi 模组侧不会实现自处理工作状态指示的功能。

射频学习状态控制

  • 命令字为模组控制 MCU 射频部分的学习状态命令。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x33
数据长度 2 0x0002
数据 1 子命令。0x01:射频学习类命令
1 控制状态。
  • 0x01:进入射频学习状态
  • 0x02:退出射频学习状态
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 00 33 00 02 01 01 36

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x33
数据长度 2 0x0003
数据 1 子命令:0x01
1 控制状态。0x01:进入射频学习状态
1 ACK 状态。
  • 0x00:成功
  • 0x02:退出射频学习状态
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 03 33 00 03 01 01 00 3a

射频数据下发

  • 射频数据简称键值,一条完整射频数据可由多个键值组成,键值数过多可串口分包发送。

  • 射频数据编码方式为固定编码,即根据发送速率决定每个 bit 发送时长,单个 bit 为 1 为发送为 0 为不发送,高位先发。

  • 学习码下发 MCU 无需解析频率与发送速率字段,只需解析 Data 字段。

模组发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x33
数据长度 2 0x07+n*(T+D+I+L+C)
数据 1 子命令:0x02
1 发送类型。0x00:码库下发 0x01:学习码下发
1 键值数: n
1 键值偏移序号。
  • 0xFF:整包发送所有键值数据。
  • 0x00-0xFE:指偏移序号,首包为 0,最后一包为键值数-1。
1 频率。0:315 Mhz,1:433.92 Mhz
2 发送速率。例如,2777bps
N Data
  • T: times,发送次数,1 字节长度。当是学习码下发时,此内容无效,填充默认值 0x00
  • D:delay,key 之间时间间隔,2 字节长度。 当是学习码下发时,此内容无效,填充默认值0x0000
  • I:intervals,每次发送时间间隔,2 字节长度。 当是学习码下发时,此内容无效,填充默认值0x0000
  • L: code len,射频发送数据部分长度。2 字节长度。
  • C: code,射频发送数据部分。N 字节
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 33 00 xx 02 01 00 ff 00 0a d9 00 00 00 00 00 00 xx xx xx xx xx xx xx

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x33
数据长度 2 0x0002
数据 1 子命令:0x02
1 ACK 状态:
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 33 00 02 02 00 36

射频学习数据上报

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x33
数据长度 2 0x0002+N
数据 1 子命令 :0x03
1 状态。
  • 0:学习成功
  • 1:学习失败
N 内容:学习失败无此字段,学习成功:学习数据上报无固定格式,MCU 端可理解的格式即可
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 03 33 xx xx 03 00 xx xx xx xx xx xx

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x33
数据长度 2 0x0002
数据 1 子命令:0x03
1 ACK 状态。
  • 0x00:上报成功
  • 0x01:上报失败
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 00 33 00 02 03 00 37

文件传输服务(可选)

  • 当 MCU OTA 的过程中,不执行文件传输功能。此文件传输服务支持大文件传输,支持各种文件类型。
  • 使用文件传输功能时请确认模组固件是否支持此功能。

文件下载服务

文件下载流程:

串口协议
  • 此图示意了单个文件下载流程,多文件下载是在此示意图上的循环。

  • 当文件传输的过程中,模组端因为数据超时发送退出,则退出所有下载流程

  • 在文件传输的过程中会停止心跳查询,以及终止 dp 下发等其他的相关操作,文件传输流程只执行文件传输相关交互。

文件传输下载启动通知

  • 当有下载事件触发时,使用此命令通知 MCU。MCU 根据当前设备情况确认是否执行文件下载操作。

  • 此命令当使用的业务为非扫地机语音文件下载功能时下载启动通知。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0002
数据 1 子命令:0x01
1 0x01:固定 0x01
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 37 00 02 01 01 3a

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0003
数据 1 子命令:0x01
1 Ret:是否同意启动下载服务:0x01:拒绝 0x00:同意
1
  • Ret 为 0x00 时: 此字节表示文件传输时每包文件的传输大小,目前支持的设置参数如下: 0x00:256 字节。0x01:512 字节。 0x02:1024 字节。0x03:2048 字节。0x04:3072 字节。0x05:4096 字节。 0x06:5120 字节。 0x07:10240 字节。
  • Ret 为 0x01 时: 此字节表示拒绝启动下载服务的原因。0x01—0xFF:有关拒绝原因,请参考 附录 2
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 37 00 03 01 00 07 41

文件传输下载信息同步

  • 当有下载事件触发时,使用此命令通知 MCU 当前所下载文件信息。

  • 扫地机语音文件下载业务无此功能命令。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0001+N
数据 1 子命令:0x02
N {
“num”:n,此次批量下载文件数量
“name”: [“xx”, “xx”, “xx”,…], 文件名称
“id”:[n,n,n,……] ,文件序号
“len”: [n,n,n,…] ,文件长度
“type”: [n,n,n,…] ,每个文件类型
“file_info”:[“xx”, “xx”,…],每个文件自定义数据
“ext_info”:“xxxx”,自定义数据,用于此次下载的拓展数据
“act”:xx 此次下载的文件的对应操作
}
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

字段说明:

  • Name: 文件的名称,客户可自定义文件的名称。
  • Id: 文件的 ID。
  • Len: 文件的长度。
  • Type: 文件的类型,比如 txt,jpg 等。具体参见 附录 5
  • File_info: 每个文件的客户自定义数据,需要对应文件有自定义填充的信息时,可使用此字段填充,此字段信息 Wi-Fi 模组透传,具体的数据格式 MCU 自定义。
  • Ext_info: 此次下载文件的客户自定义数据,用户可以编辑使用每次下载操作的一些自定义需要的信息,此字段信息 Wi-Fi 模组透传,具体的数据格式 MCU 自定义。
  • Act: 对于此次下载的文件需要执行的操作,比如:打印、语音播放等,具体定义如下:
名称 打印 文本显示 语音播放 视频播放 存储
类型数值 1 2 3 4 5

注:若客户未使用其中的数据内容,Wi-Fi 模组将不会传输这个字段。

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0002
数据 1 子命令:0x02
1 Ret:执行结果。
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:55 aa 03 37 00 02 02 00 3d

文件包下载传输

  • 升级包传输数据格式:包偏移(unsigned short) + 包数据。

  • MCU 若收到该帧数据长度为 5 且包偏移 ≥ 固件大小,则包传输结束。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x02+0x0004+数据包长度
数据 1 子命令:0x03
1 当前对应传输文件偏移序号。第一个文件为 1,第二个文件为 2……
4 当前文件包的包偏移量
N 数据包内容
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:文件序号为 1。包偏移量为 0

55 aa 00 37 xx xx 03 01 00 00 00 00 00 xx xx xx xx xx

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0002
数据 1 子命令:0x03
1 Ret:执行结果。
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 37 00 02 03 00 3e

文件执行结果反馈(可选)

说明:此功能命令是用于 MCU 反馈文件的执行状态,是否成功执行。

此功能是可选功能,具体的执行依赖业务场景,当业务需要展示执行状态时,通过此功能命令反馈。协议中 Act 的数据也是可选的,根据具体业务来反馈。

此功能中的 ID 数据对应于 0x3702 命令中的 ID(文件序号),这个是唯一的,也需要做好对应关系。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x01+l+L+2
数据 1 子命令:0x05
1 ID 的长度
L 文件的 ID: 对于 0x3702 命令字中的 ID 数据
1 Act:
  • 0x00:执行完成。
  • 0x01:执行中。
  • 0x02:执行失败。
1
  • Act 为 0x00 时,此字节填充 0x00。
  • Act 为 0x01 时,此字节填充执行进度百分比,比如 20% 就给 20。
  • Act 为 0x02 时,此自己表示失败原因,具体参考 附录 2
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:打印机业务,打印 ID 为 10 的文件进行 20%

55 aa 03 37 05 05 01 0a 01 14 63

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0002
数据 1 子命令:0x05
1 Ret
  • 0x00:成功。
  • 0x01:数据不合法。
  • 0x02:上报失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 37 00 02 05 00 3d

文件上传服务

文件上传流程:

串口协议

文件上传启动通知

MCU 需要文件上传时,使用此命令通知。

MCU 发送

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0001+N
数据 1 子命令:0x06
N

{

“num”:n;此次批量下载文件数量

“files”[

{

“name”:“xx”,文件名称

“id”:n 文件序号

“len”:n,文件长度

“type”: n, 每个文件类型

“file_info”:“xx”,每个文件自定义数据

},

{

“name”:“xx”,文件名称

“id”:n 文件序号

“len”:n,文件长度

“type”: n, 每个文件类型

“file_info”:“xx”,每个文件自定义数据

},

……

]

“ext_info”:“xxxx”

}

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

模组返回

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

文件包上传

  • 升级包传输数据格式:包偏移(unsigned short) + 包数据。
  • 模组若收到该帧数据长度为 4 且包偏移 ≥ 固件大小,则包传输结束。

MCU 发送

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x00020x0004 + 数据包长度
数据 1 子命令:0x07
2 当前对应传输文件 ID
4 固件包偏移
N 数据包内容
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

模组发送

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0003
数据 1 子命令:0x07
1
  • Ret:操作结果
  • 0x00:成功
  • 0x01:失败
  • 0x02:已取消
1
  • Ret0x00 时:此字节返回 0x00
  • Ret0x01 时:此字节表示失败原因,0x010x0FF。具体原因请参考 附录 3
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

MCU 主动获取/更新文件传输状态

  • 当 MCU 在文件传输过程中需要主动中断传输的,可使用此命令同步。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0003
数据 1 子命令:0x04
1 Ret:
  • 0x00:终止传输(所有流程终止)
  • 0x01:终止当前文件传输(多文件下载时,使用此命令只会终止当前传输的文件,并开启下个文件的传输)
  • 0x02:获取当前传输状态
  • ……
1
  • Ret 为
    • 0x00/0x01:此字节表示终止下载服务的原因
    • 0x01—0xFF:拒绝原因,请参考 附录 2
  • Ret 为其他:此字节填充 0x00
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 37 00 03 04 02 00 42

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0003
数据 1 子命令:0x04
1 Ret:
  • 0x01:终止传输
  • 0x02:获取当前传输状态
1
  • Ret 为 0x01 时:表示执行结果 0x00:成功。0x01:失败
  • Ret 为 0x02 时:表示的传输状态。请参考 附录 3
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 37 00 03 04 02 00 3f

文件传输结果反馈

  • 此命令用于文件传输状态结果反馈,无论是文件下载还是文件上传,均用此命令来通知传输结果。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x37
数据长度 2 0x0004
数据 1 子命令:0x08
1
  • 0x01:文件下载
  • 0x02:文件上传
1 Ret:执行结果。
  • 0x00:成功
  • 0x01:失败
1
  • Ret 为 0x00 时:此字节返回 0x00。
  • Ret 为 0x01 时:此字节表示失败原因,0x01—0x0FF,请参考 附录 3
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 37 00 04 08 01 00 00 43

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x37
数据长度 2 0x0001
数据 1 子命令:0x08
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 37 00 01 08 42

语音模组相关协议(可选)

  • 本目录下的协议适用语音模组 VWXR2 的通用对接

  • 其他非语音模组的通用固件没有本目录下相关协议功能

获取语音状态码(可选)

语音模组的语音状态码会自动返回,MCU 也可以主动查询。

MCU 发送

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

示例55 aa 03 60 00 00 62

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x60
数据长度 2 0x0001
数据 1 语音状态码:
  • 0:空闲
  • 1:MIC 静音状态
  • 2:唤醒
  • 3:正在录音
  • 4:正在识别
  • 5:识别成功
  • 6:识别失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 60 00 01 00 60

MIC 静音设置(可选)

该命令字可以设置静音,也可查询静音状态。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x61
数据长度 2 0x0001
数据 1 静音设置值。
  • 0:MIC 开启
  • 1:MIC 静音
  • 0xA0:查询静音状态
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 03 61 00 01 00 64

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x61
数据长度 2 0x0001
数据 1 静音状态值。
  • 0: MIC 开启
  • 1: MIC 静音
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 61 00 01 00 61

Speaker 音量设置(可选)

该命令字可以设置音量,也可查询音量。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x62
数据长度 2 0x0001
数据 1
  • 音量值:0-10
  • 查询音量:0xA0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 03 62 00 01 03 68

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x62
数据长度 2 0x0001
数据 1 音量值:0-10
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 62 00 01 03 65

音频产测(可选)

  • 音频产测就是边录边播,通过声学仪器对比模组的输入和输出音频信号。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x63
数据长度 2 0x0001
数据 1 音频产测值。
  • 0:关闭音频产测
  • 1:MIC1 音频环路测试
  • 2:MIC2 音频环路测试
  • 0xA0:查询当前产测状态
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 03 63 00 01 02 68

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x63
数据长度 2 0x0001
数据 1 音频产测状态
  • 0: 关闭音频产测
  • 1: MIC1 音频环路测试
  • 2: MIC2 音频环路测试
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 63 00 01 02 65

唤醒产测(可选)

进入唤醒测试后,要求 10s 播放唤醒词电信号,10s 超时返回失败。

MCU 发送

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

示例55 aa 03 64 00 00 66

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x64
数据长度 2 0x0001
数据 0 唤醒结果返回
  • 0: 唤醒失败
  • 1: 唤醒成功
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 64 00 01 01 65

扩展功能

扩展语音模组的相关系统功能增加:

  • 播放/暂停、蓝牙开/关、本地闹钟、语音控制组合功能的状态通知和设置
  • 播放/暂停功能:音乐、古诗、笑话等功能的播放与暂停功能。
  • 蓝牙开/关功能:蓝牙音箱的蓝牙开关。
  • 本地闹钟功能:语音和 App 设置的闹钟数据同步通知。
  • 语音控制组合功能:上一首、下一首等语音控制指令的通知。
MCU 功能设置

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 N
数据 1 子命令:0x00
Data:
{
“play”:true,
“bt_play”:true
,“ctrl_group”:“xxxx”}
  • play:播放/暂停功能。true(播放)/false(暂停)。
  • bt_play:蓝牙开关功能。true(开)/false(关)。
  • ctrl_group:播放控制。next(下一首)/pre(上一首)。
MCU 设置暂仅支持播放/暂停、蓝牙开关
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:{“play”:true,“bt_play”:true,“ctrl_group”:“next”}

55 aa 03 65 00 31 00 7b 22 70 6c 61 79 22 3a 74 72 75 65 2c 22 62 74 5f 70 6c 61 79 22 3a 74 72 75 65 2c 22 63 74 72 6c 5f 67 72 6f 75 70 22 3a 22 6e 65 78 74 22 7d c7

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x0002
数据 1 子命令:0x00
1 操作结果:
  • 0x00: 成功
  • 0x01: 失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 65 00 02 00 00 66

状态通知

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 1+N
数据 1 子命令:0x01
Data:{
“play”:true,
“bt_play”:true,“
alarm”:“xxxx”, “
ctrl_group”:“xxxx”
}
  • play:播放/暂停功能,true(播放)/false(暂停)
  • bt_play:蓝牙开关功能,true(开)/false(关)
  • alarm:本地闹钟功能,"xxx"为字符串
  • ctrl_group:语音控制组合功能,"xxx"为字符串
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例:{“play”:true,“bt_play”:true,“ctrl_group”:“next”, “alarm”:“xxx”}

55 aa 00 65 00 3f 01 7b 22 70 6c 61 79 22 3a 74 72 75 65 2c 22 62 74 5f 70 6c 61 79 22 3a 74 72 75 65 2c 22 63 74 72 6c 5f 67 72 6f 75 70 22 3a 22 6e 65 78 74 22 2c 22 61 6c 61 72 6d 22 3a 22 78 78 78 22 7d 36

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 2
数据 1 子命令:0x01
1 操作结果。
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 03 65 00 02 01 00 6a

唤醒模组
  • 此功能为 MCU 主动唤醒模组。

  • 目前此功能只有 Linux 系统的通用对接模组支持。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x01
数据 1 子命令:0x02
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 01 02 6a

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x02
1 操作结果。
  • 0x00:成功。
  • 0x01:失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 02 00 68

打开 asr 识别文本通知
  • 此功能开启后 asr 识别的文本会通过 0x6504 命令字传输。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x03
1
  • 0x00:关闭。
  • 0x01:开启。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 03 00 6c

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x03
1 操作结果。
  • 0x00:操作成功。
  • 0x01:操作失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 03 00 69

asr 识别通知

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0xXX
数据 1 子命令:0x04
1 {
“text”:“UTF-8 内容”,
“speaker”:“human”,//robot
“id”:1171
}
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例: {“text”:“xx”, “speaker”:“human”, “id”:1171}

55 aa 03 65 00 2b 04 7b 22 74 65 78 74 22 3a 22 78 78 22 2c 22 73 70 65 61 6b 65 72 22 3a 22 68 75 6d 61 6e 22 2c 20 22 69 64 22 3a 31 31 37 31 7d 69

MCU 返回

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

示例55 aa 00 65 00 01 04 69

查询当前播放节目
  • 此功能为查询当前歌曲&内容信息。
  • 此功能返回的数据中的中文内容按照 UTF-8 编码,hex 传输发送。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x01
数据 1 子命令:0x05
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 01 05 6d

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x0002+N
数据 1 子命令:0x05
1 操作结果:
Data[0]:
  • 0x00: 查询成功
  • 0x01: 查询失败
N 操作结果为 0x01 时无此部分内容。
{
“artist”:“贝多芬”,
“trackTitle”:“D 大调小夜曲”
}//中文按照 UTF-8 编码
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:{“artist”:“贝多芬”, “trackTitle”:“D 大调小夜曲” }

55 aa 00 65 00 34 05 00 7b 22 61 72 74 69 73 74 22 3a 22 e8 96 9b e4 b9 8b e8 b0 a6 22 2c 22 74 72 61 63 6b 54 69 74 6c 65 22 3a 22 e5 8a a8 e7 89 a9 e4 b8 96 e7 95 8c 22 7d dc

上报模组状态

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x06
状态。
  • 0x00:在线
  • 0x01:蓝牙
  • 0x02:通话
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 06 00 6f

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x06
1 操作结果。
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 06 00 6c

模组录音上报 - 自动结束

该命令可主动触发模组进入录音状态,设备会智能拾取人声并自动结束录音,最大录音时长为 10 秒。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x07
状态。0x01:开始录音
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 07 01 71

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x07
1 操作结果。
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 07 00 6d

模组录音上报 - 手动结束

该命令可主动触发模组进入录音状态,需要手动发送结束录音,最大录音时长为 10 秒。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x08
1 状态。
  • 0x00:结束录音
  • 0x01:开始录音
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 08 00 71

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x08
1 操作结果。
  • 0x00:成功。
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 08 00 6e

打开闹铃通知

此功能开启后闹铃会通过 0x650A 命令字传输。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x09
1
  • 0x00:关闭。
  • 0x01:打开。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 09 01 73

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x09
1 操作结果。
  • 0x00:成功。
  • 0x01:失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 09 00 6f

闹铃下发

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0xXX
数据 1 子命令:0x0A
  • Data[0]:闹铃数量 N
  • Data[1]: 操作类型 0:poll; 1:add ;2:del ;3:update ----以下为重复内容
  • Data[2~7]:闹铃 ID
  • Data[8]:年份
  • Data[9]:月份
  • Data[10]:日期
  • Data[11]:小时
  • Data[12]:分钟
  • Data[13]:bit7~bit1 循环规则 * (例:“0111000” //星期一二三执行(从星期天到星期六,为 1 的那天执行) “0000000” //单次执行)* bit0 闹铃状态 *(0 启动,1 暂停)*
  • Data[14]:闹钟铃声 ID *闹钟铃声: 0-在线铃声,其他-设备本地铃声*
  • Data[15~35]:铃声描述 *在线闹钟铃声描述: 用于匹配播放歌曲* ----
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:闹钟 ID:1。时间:2021/08/23 17:32。单次执行。

55 aa 00 65 00 24 0a 01 01 00 00 00 00 00 01 15 08 17 11 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 fa

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x01
数据 1 子命令:0x0A
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 01 0a 72

查询闹铃列表

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x01
数据 1 子命令:0x0B
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 01 0b 73

模组返回闹铃用命令字 0x650A 下发

关闭本地闹铃

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x0C
状态。0x00:关闭,0x01: 开启
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 02 0c 00 75

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x0C
1 操作结果: 0x00: 成功 0x01: 失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 0c 00 72

闹铃操作

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0xXX
数据 1 子命令:0x0D
状态。
  • 0x01:新增闹铃
  • 0x02:修改闹铃
  • 0x03:删除闹铃
  • 0x04:打开闹铃
  • 0x05:关闭闹铃
JSON 数据,参考下方说明
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:{“date”:“20210326”, “time”:“17:05”, “loops”:“0000000”, “timeZone”:“+08:00”, “bell”:0}

55 aa 03 65 00 53 0d 01 7b 22 64 61 74 65 22 3a 22 32 30 32 31 30 33 32 36 22 2c 22 74 69 6d 65 22 3a 22 31 37 3a 30 35 22 2c 22 6c 6f 6f 70 73 22 3a 22 30 30 30 30 30 30 30 22 2c 22 74 69 6d 65 5a 6f 6e 65 22 3a 22 2b 30 38 3a 30 30 22 2c 22 62 65 6c 6c 22 3a 30 7d 9e

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x09
数据 1 子命令:0x0D
1 操作码。
  • 0x01:新增闹铃
  • 0x02:修改闹铃
  • 0x03:删除闹铃
  • 0x04:打开闹铃
  • 0x05:关闭闹铃
1 操作结果。
  • 0x00:操作成功
  • 0x01:JSON 格式错误
  • 0x02:参数缺失
  • 0x03:服务调用失败
  • 0x04:其他错误
6 操作的 timerId
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 09 0d 01 00 00 00 00 00 00 0a 85

闹钟操作 JSON 数据格式

添加闹钟:

名称 类型 描述 参数是否可选
time String 闹钟时间,例如:08:30。 N
loops String 循环执行,从星期天到星期六,为 1 的那天执行。如 0100001,表示星期 1 和星期 6 执行。 N
date String 闹钟日期,循环闹钟取默认值 00000000,单次取要执行的那天的日期。例如:20181126。 N
timeZone String 时区,如:+08:00。 N
bell Integer 铃声:格式正整数。
  • 0:在线铃声。
  • 其他:设备本地铃声,默认为 1。
Y
bellDesc String 在线铃声描述,用于播放选择具体的歌曲。 Y
  • 单次示例:{ "date": "20181126", "time": "20:30", "loops": "0000000", "timeZone": "+08:00", "bell":1 }
  • 循环示例:{ "date": "00000000", "time": "08:00", "loops": "0111110", "timeZone": "+08:00", "bell":1 }

修改闹钟:

名称 类型 描述 参数是否可选
time String 闹钟时间,例如:08:30。 N
loops String 循环执行,从星期天到星期六,为 1 的那天执行。如 0100001,表示星期 1 和星期 6 执行。 N
date String 闹钟日期,循环闹钟取默认值 00000000,单次取要执行的那天的日期。例如:20181126。 N
timerId Long 闹钟 ID。 N
timeZone String 时区,如:+08:00。 N
bell Integer 铃声:格式正整数。
  • 0:在线铃声。
  • 其他:设备本地铃声,默认为 1。
Y
bellDesc String 在线铃声描述,用于播放选择具体的歌曲。 Y
  • 单次示例: { "timerId": 10164075, "date": "20210322", "time": "14:30", "loops": "0000000", "timeZone": "+08:00", "bell":1 }
  • 循环示例: { "timerId": 10164075, "date": "20210322", "time": "14:30", "loops": "0111110", "timeZone": "+08:00", "bell":1 }

删除闹钟:

请求参数
名称 类型 描述 参数是否可选
timerId Long 闹钟 ID N

请求示例

{“timerId”: 1002}

暂停闹钟:

请求参数
名称 类型 描述 参数是否可选
timerId Long 闹钟 ID N

请求示例

{“timerId”: 1002}

启动闹钟:

请求参数
名称 类型 描述 参数是否可选
timerId Long 闹钟 ID N

请求示例

{“timerId”: 1002}

查询提醒数量

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x01
数据 1 子命令:0x0E
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 65 00 01 0e 76

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x02
数据 1 子命令:0x0E
1 提醒个数 0~30
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 0e 02 76

主动在线内容下发

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x65
数据长度 2 0x0001+N
数据 1 子命令:0x0F
N {
“text”: “xxx”, //设备端保存的文本播放内容或文本指令
“type”: “tts/music”, // tts 为播报文本内容,music 为后续自定义铃声
“target”: “alert/clock”, //闹钟还是提醒
}
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:{“text”:“播放贝多芬的歌”, “type”:“music”, “tasget”:“alert”}

55 aa 03 65 00 41 0f 7b 22 74 65 78 74 22 3a 22 e6 92 ad e6 94 be e6 9e 97 e4 bf 8a e6 9d b0 e7 9a 84 e6 ad 8c 22 2c 22 74 79 70 65 22 3a 22 6d 75 73 69 63 22 2c 22 74 61 73 67 65 74 22 3a 22 61 6c 65 72 74 22 7d 91

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x0002
数据 1 子命令:0x0F
1 操作结果。
  • 0x00:成功。
  • 0x01:JSON 格式错误。
  • 0x02:参数缺失。
  • 0x03:其他错误。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 65 00 02 0f 00 75

模组拓展服务

打开模组时间服务通知

  • 如果 MCU 需要模组每次重新上电通知 MCU 模组的时间是否已经到云端校准,MCU 可以通过这个命令打开模组的主动通知 MCU 需要的时间数据服务。

  • 模组上电后收到服务开启,当时间校准后会根据 MCU 发送的主动通知相关需要的时间服务,选择发送相关 MCU 需要的时间数据。

  • 模组不重新上电的情况下服务开启后不接受重复开启,模组不重启的情况下需要获取时间走时间相关获取协议。

  • 目前 获取系统时间(格林时间)获取本地时间 的获取时间协议,模组在连接上服务器之后时间戳并不会马上校准,有个时间周期导致每次上电都要 MCU 不断的重试去获取时间,这个服务开启后,模组在时间校准之后会主动通知 MCU。

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x01(子命令)
1
  • 0x00:格林时间
  • 0x01:本地时间
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 34 00 02 01 01 3a

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x01(子命令)
1 0x00:服务开启成功。0x01:服务开启失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 34 00 02 01 00 36

模组时间服务通知

  • 模组根据 MCU 发送的打开时间通知的服务,选择发送相对应的时间数据。

  • 模组重新上电,服务都是关闭的,都需要 MCU 重新发送打开模组时间通知服务。

模组发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0009
数据 1 0x02(子命令)
1
  • 0x00:格林时间
  • 0x01:本地时间
7 数据长度为 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 结束
  • Data[6] 为星期,从 1 开始到 7 结束,1 代表星期一
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:Type: 1(本地时间), Time: 2021/08/23 18:35:28 星期一

55 aa 00 34 00 09 02 01 15 08 17 12 23 1c 01 c5

MCU 返回

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

示例55 aa 03 34 00 01 02 39

打开模组重置状态通知(可选)

目前模组支持本地移除、App 移除、App 恢复出厂设置,但是 MCU 无法知道模组这些状态的通知,这个服务用于有需要的用户打开模组状态通知。

MCU 发送

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

示例55 aa 03 34 00 01 04 3b

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x04(子命令)
1 执行结果:
  • 0x00:成功
  • 0x01:失败
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 34 00 02 04 00 39

模组重置状态通知(可选)

设备重置状态 描述 状态值
状态 1 模组本地重置 0x00
状态 2 App 远程重置 0x01
状态 3 App 恢复出厂重置 0x02

重置状态的发送最多也会重发两次,重发间隔保持 1 秒。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 1 0x05(子命令)
1 重置状态:
  • 0x00:模组本地重置
  • 0x01:App 远程重置
  • 0x02:App 恢复出厂重置
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例55 aa 00 34 00 02 05 00 3a

MCU 返回

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

示例55 aa 03 34 00 01 05 3c

获取 Wi-Fi 模组相关数据信息

  • 针对有些产品需求,需要知道 Wi-Fi 模组的一些运行数据情况,都统一使用这个字段用于获取。

  • MCU 可根据自己所需要的数据发送对应功能编码来获取。当 MCU 需要多种数据时请按照对应编码,依次顺序排列发送给 Wi-Fi 模组。

  • 若 MCU 需要获取当前所有支持的数据,使用 0xff 编码即可。

  • 此命令当前只支持获取 AP 热点 SSID 功能。其他功能后续根据需求增加。

  • 当 AP 热点是默认的 smartlife 时,此命令只返回 smartlife 信息,实际热点名称为 smartlife_xxxx(设备 MAC 后四位)。

    • 此字段数据格式为 JSON 字符串的形式,data 数据长度不一定。
    • MCU 发送命令的数据长度至少有 2 个字节,即子命令+1 字节 data 编码,若长度不对则返回失败。
    • 数据编码是一一对应关系,请勿使用错误,且不可使用预留编码。
    名称 编码
    获取所有当前支持的数据信息 0xff
    AP ssid 名称 0x01
    国家码 0x02
    SN 信息 0x03
    FFS 授权记录 0x04
    ……… ………
  • 模组返回数据字段说明表:模组运行信息字段说明表

    • 目前,普通 Wi-Fi 类设备不支持获取 SN 信息。
    • 在获取 FFS 授权信息记录时,若无 FFS 授权记录,则模组返回的信息中只有 FFS 字段,且内容为 0
    • 若有 FFS 授权信息,模组会返回 FFS 内容且内容为 1,并携带 SN 信息用于辅助校验信息合法性。

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x34
数据长度 2 0x01+0x01+…N
数据 1 子命令 0x07
Data(1)
  • 0x01:获取 AP ssid 名称
  • 0x02:国家码
  • 0x03:模组 SN
  • ………
  • 0xFF:获取所有当前已经支持的数据内容(此编码只在第一字节有效,且优先级最高,解析到此编码时即推送所有信息)
Data(2)
  • 0x01:获取 AP ssid 名称
  • 0x02:国家码
  • 0x03:模组 SN
  • ………
Data(N)
  • 0x01:获取 AP ssid 名称
  • 0x02:国家码
  • 0x03:模组 SN
  • ………
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 34 00 02 07 01 40

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x02+N
数据 1 0x07(子命令)
1 执行结果: 0x00:成功; 0x01:失败 (当执行失败后,无后续 data 内容)
Data(N) {
“ap” :“xxxxx”;
“cc” :xx;
“sn”:“xxxx”;
“ffs”:x
}
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例:{“ap”:“PlusStyle”}

55 aa 00 34 00 14 07 00 7b 22 61 70 22 3a 22 50 6c 75 73 53 74 79 6c 65 22 7d 8e

蓝牙相关功能(可选)

蓝牙功能性测试(扫描指定蓝牙信标)

  • 模组内部目前扫描指定的蓝牙信标: ty_mdev,返回扫描结果和信号强度百分比。

  • 为了最大程度防止不良品,建议客户将路由于设备距离控制在 5 米左右,信号强度大于等于 60%为合格,用户也可以根据自己产线和工厂环境的情况自行调整。

MCU 发送

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

示例55 aa 03 35 00 01 01 39

模组返回

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

示例55 aa 00 35 00 03 01 01 14 4d

报告设备蓝牙连接状态

设备蓝牙状态 描述 状态值
状态 1 未绑定,未连接 0x00
状态 2 未绑定,已连接 0x01
状态 3 已绑定,未连接 0x02
状态 4 已绑定,已连接 0x03
状态 5 未知状态 0x04
  • 设备蓝牙连接状态含义如下。1:未绑定,未连接。2:未绑定,已连接。3:已绑定,未连接。4:已绑定,已连接。5:未知状态。其中状态 1 和 2 是蓝牙配网阶段产生。

  • 模组自处理工作模式相应的 LED 显示含义如下。1:快闪状态。2 或 3:长暗状态。4:长亮。5:慢闪状态。

当模组检测到 MCU 重启或 MCU 断线再上线的过程,则主动下发蓝牙状态至 MCU。

  • 当模组的蓝牙状态发生变化,则主动下发 Wi-Fi 状态至 MCU。
  • 如设置模组工作模式为模组自处理,则 MCU 无需实现该协议。

此命令字的发送,需要 MCU 上电发送 0x3700 命令字中 abv 字段的 bit0 使能

上电默认为未知状态。

模组发送

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

示例55 aa 00 35 00 02 04 03 3d

MCU 返回

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

示例55 aa 00 35 00 01 04 39

主动获取设备蓝牙连接状态

设备蓝牙状态 描述 状态值
状态 1 未绑定,未连接 0x00
状态 2 未绑定,已连接 0x01
状态 3 已绑定,未连接 0x02
状态 4 已绑定,已连接 0x03
状态 5 未知状态 0x04

报告设备蓝牙连接状态命令字功能状态保持一致。

MCU 发送

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

示例55 aa 03 35 00 01 05 3D

模组返回

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x35
数据长度 2 0x0002
数据 子命令 0x05
Data 指示蓝牙工作状态。
  • 0x00:状态 1
  • 0x01:状态 2
  • 0x02:状态 3
  • 0x03:状态 4
  • 0x04:状态 5
  • 0x05:状态 6
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 35 00 02 05 00 3E

蓝牙/Beacon 遥控器功能—数据通知

  • 该服务的前提是需要开启蓝牙遥控器服务。
  • 模组上电完成 02 命令字交互后即可进入待配对状态,蓝牙遥控器的配对时间为 30 秒,30 秒后关闭配对功能。
  • 遥控器最大配对数量为 5。若超出遥控器配对数量,会出现配对失败情况。

模组发送

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x35
数据长度 2 0x0007
数据 1 子命令 0x06
N
  • Data[0]:品类 ID,1 字节。
  • Data[1]:控制命令 1 字节。
  • Data[2]-Data[5]:控制数据 4 字节。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 35 00 02 05 00 3E

MCU 返回

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

示例55 aa 03 35 00 02 05 00 3E

控制命令表


控制命令字

(1 字节)

控制命令(1 字节)

以下为通用命令

控制数据(4 字节)没用到补 0

品类 ID

全品类: 0xFF



单个品类

照明:0x01

插座/排插:0x02

窗帘开关:0x03

晾衣架:0x04

风扇:0x05

浴霸:0x06

空调:0x07

车库控制:0x08

水阀控制:0x09

消毒控制:0x0A

温控插座:0x0B

调光开关:0x0C

情景灯插座:0x0D

开关:0x0E

窗帘通断器:0x0F

键值发送:0x01

字节 1:type(0 单击、1 双击、2 长按、3 长按保持、4 长按抬起)

字节 2:键值

开关:0x04

字节 1:0 关闭、1 开启、2 暂停

字节 2:路数,路数为 0 时表示总控

喜好收藏:0x05

字节 1:1 收藏状态 2 切换到该收藏

字节 2:收藏号:0-3

倒计时功能:0x06

字节 1、2:倒计时时间,秒为单位(0 为取消倒计时) (大端格式)

字节 3:字节定时执行功能:(暂时不用,待功能标号确定,默认关灯功能)

一键群组查询:0x07

(用于子设备广播通知已加入的群组)

照明开关:0x08

字节 1:0 关闭、1 开启

字节 2:0 总开关、1 白光开关、2 彩光开关

亮度调节:0x09

字节 1:0 亮度值、1 亮度+、2 亮度-

字节 2:0 设备当前模式亮度、1 白光模式亮度

字节 3:字节 1 为 0 时表示亮度百分比(1-100%) 字节 1 为 1,2 时表示亮度步进值(1-100%)

亮度无极调节:0x0A

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:0 设备当前模式亮度、1 白光模式亮度

字节 3:速率(每 1s 调节的百分比)

字节 4:无极调节目标值

色温调节:0x0B

字节 1:0 色温值、1 色温+、2 色温-

字节 2:字节 1 为 0 时表示色温百分比(0-100%) 字节 1 为 1,2 时表示色温步进值(0-100%)

色温无极调节:0x0C

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值

七彩调节:0x0D

字节 1:0 相对切换、1 具体颜色、2 循环调节开始、3 循环调节结束

字节 2:具体颜色时的具体颜色 ID

H 值调节:0x0E

字节 1:0 H 百分比值、1 步进加+、2 步进减-

字节 2:字节 1 为 0 时表示 H 百分比值(0-100%) 字节 1 为 1,2 时表示 H 步进值(0-100%)

H 值无极调节:0x0F

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值

S 值调节:0x10

字节 1:0 S 百分比值、1 步进加+、2 步进减-

字节 2:字节 1 为 0 时表示 S 百分比值(0-100%) 字节 1 为 1,2 时表示 S 步进值(0-100%)

S 值无极调节:0x11

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值

V 值调节:0x12

字节 1:0 V 百分比值、1 步进加+、2 步进减-

字节 2:字节 1 为 0 时表示 V 百分比值(1-100%) 字节 1 为 1,2 时表示 V 步进值(1-100%)

V 值无极调节:0x13

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值

HSV 控制:0x14

字节 1:H 百分比值(0-100%)

字节 2:S 百分比值(0-100%)

字节 3:V 百分比值(1-100%)

场景调节:0x15

字节 1:0 相对切换、1 具体场景、2 循环调节开始、3 循环调节结束

字节 2:具体场景时的场景 ID

照明模式设置:0x16

字节 1:1 小夜灯模式

电机转动行程调节:0x20

字节 1:0 正转、1 反转、2 暂停

字节 2:行程百分比(0-100%) 0 表示连续转动

字节 3:路数(0 表示总路数)

电机行程设置:0x21

字节 1:0 进入行程点设置、1 进入微调行程点、2 确认 行程点

字节 2:0 上行程设置、1 下行程设置、2 中间行程设置

字节 3:路数(0 表示总路数)

电机速度调节:0x22

字节 1:0 档位值、1 步进+,步进-

字节 2:具体档位或步进档位 字节 3:路数(0 表示总路数)

电机速度无极调节:0x23

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值 字节 4:路数(0 表示总路数)

温度调节:0x24

字节 1:0 温度值、1 步进+、2 步进-

字节 2、3:字节 1 为 0 时具体温度 字节 1 为 1、2 时步进温度 (两字节温度值,大端表示,最高位表示正负,其他位的值表示温度单位值,以 0.1 摄氏度为单位,相乘得到具体温度)

温度无极调节:0x25

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3、4:无极调节目标值 温度值同上

湿度调节:0x26

字节 1:0 湿度值、1 步进+、2 步进-

字节 2:具体档湿度或步进湿度

湿度无极调节:0x27

字节 1:0 连续加开始、1 连续减开始、2 连续结束

字节 2:速率(每 1s 调节的百分比)

字节 3:无极调节目标值

以下为品类定制命令

定制品类(1 字节)

定制命令(1 字节)

参数(3 字节)

照明定制:0xFF

RGBY 控制:0x01

字节 1:0 向 R 色调节,1 向 G 色调节,2 向 B 色调 节,3 向 Y 色调节

风扇定制:0xFE

风扇模式切换:0x01

字节 1:0:手动风 1:自然风 2:睡眠风

浴霸定制:0xFD

浴霸模式切换:0x01

字节 1:0 暖风、1 换气、2 干燥、3 吹风

空调定制:0xFC

睡眠:0x01

字节 1: 0:off,1:on

附类型 DP 上报/下发拓展服务

本节功能目前只有语音业务支持。

打开附 DP 类型拓展服务

  • 该服务主要拓展 datapoint 下发端来源类型,主要的来源类型分为:局域网、广域网、蓝牙等等。

  • 该拓展服务打开后附 DP 类型命令下发与命令下发呈互斥关系。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x36
数据长度 2 0x0002
数据 1 子命令:0x01
1 0x00:关闭附 DP 类型拓展服务。0x01:开启附 DP 类型拓展服务。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 36 00 02 01 01 3c

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x36
数据长度 2 0x0002
数据 1 子命令:0x01
1 0x00:服务开启/关闭成功。0x01:服务开启/关闭失败。
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 36 00 02 01 00 38

附 DP 类型命令下发

  • datapoint 状态数据单元说明,请参考 3.7 节。

  • 命令下发可含多个 datapoint 命令数据单元。

  • 命令下发为异步处理协议,对应于 MCU 的 datapoint 状态上报。

  • datapoint 下发来源类型需要手动设置,并与命令下发的状态上报互斥

  • Datapoint 下发来源类型除支持的部分外,其他的不支持。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x36
数据长度 2 取决于命令数据单元类型以及个数 N+2
数据 1 子命令:0x02
1 Datapoint 下发来源类型。
  • 0x00:未知来源类型。
  • 0x01:局域网。
  • 0x02:广域网。
  • 0x03:本地定时。
  • 0x04:广域网场景联动。
  • 0x05:可靠的通道。
  • 0x06:蓝牙。
  • 0x07:本地场景联动。
  • 0xF0:离线语音模组。
N 3.7.1 命令数据单元组
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:局域网系统开关对应 3 号 DP,使用 bool 型变量,开机数值为 1。

示例55 aa 00 36 0007 02 01 03 01 0001 01 45

附 DP 类型状态上报

目前仅离线语音模组业务支持,其他业务可直接使用 3.8 状态上报。

  • datapoint 状态数据单元说明,请参考 3.7 节。

  • 状态上报为异步处理协议,状态上报触发机制有三类:

    • MCU 收到附 DP 类型命令下发处理帧时,正确执行相应 datapoint 命令,再通过附 DP 类型状态上报帧将变化后的 datapoint 状态发送至模组。

    • MCU 主动检测到 datapoint 有变化,将变化后的 datapoint 状态发送至模组。

    • MCU 收到 3.9 节的状态查询帧时,将所有的 datapoint 状态发送至模组。

    • 状态上报可含多个 datapoint 命令数据单元。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x36
数据长度 2 取决于 状态数据单元类型以及个数 N+3
数据 1 子命令:0x03
1
  • 0x00:MCU 主动上报
  • 0x01:回应状态查询
  • 0x02:回应附 DP 类型命令下发
1 在 MCU 主动上报回应状态查询两种情况下统一使用 0x00 回应附 DP 类型命令下发需要返回数据的来源。
  • 0x00:未知来源类型
  • 0x01:局域网
  • 0x02:广域网
  • 0x03:本地定时
  • 0x04:广域网场景联动
  • 0x05:可靠的通道
  • 0x06:蓝牙
  • 0x07:本地场景联动
  • 0xF0:离线语音模组
N 3.7.1 状态数据单元组
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例:回应广域网下发的湿度对应 5 号 DP,使用 valve 型变量,湿度为 30℃

示例55 aa 03 36 000b 03 02 02 05 02 0004 0000001e 73

风扇类产品服务(可选)


特殊类型产品服务,此类型产品才支持,使用时请注意功能。

风扇功能测试

  • 如:风速步长 20,保持时间 5,模组依次控制电机 0%-20%-40%-60%-80%-100%,每个挡位的间隔时间为 5 秒

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x72
数据长度 2 0x03
数据 1 0x01(子命令)
1 0x0a(风速步长 1-99)
1 0x05(挡位保持时间 1-100s)
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 03 72 00 03 01 0a 05 87

模组返回

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

示例55 aa 00 72 00 02 01 00 74

占空比设置

当设置的占空比为 70%的时候,PWM1 输出 70%,PWM2 输出 0%,检测到过零信号后 PWM1 输出 0%、PWM2 输出 70%。

MCU 发送

字段 长度 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x72
数据长度 2 0x02
数据 1 0x02(子命令)
1 0x0a(0%-100%)
校验和 1 从帧头开始按字节求和得出的 结果对 256 求余

示例55 aa 03 72 00 02 02 0a 82

模组返回

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

示例55 aa 00 72 00 02 02 00 75

附录

附录中仅列出已经定义的内容,未定义的请勿使用。

模组运行信息字段说明表

名称 说明 支持选项 获取 设置
cc 国家码 0:表示 CN,包含区域:中国(包含中国大陆和中国香港,中国澳门),韩国,新加坡,澳大利亚,日本(1-13),其他。
1:表示 US,包含区域为:美国,中国台湾,加拿大。
2:表示 JP,包含区域为:日本(1-14)
3:表示 EU,包含区域为:欧洲
支持 不支持
ap 表示 ap 热点 字符型数据 支持 不支持
sn 表示 SN 信息 这里是获取模组内部在经过授权后写入的 SN 信息。 不支持 不支持
ffs 表示模组是否有 FFS 授权信息 0:表示无 FFS 授权信息。
1:表示有授权信息,当模组反馈 1 时也同时会同步 SN 信息,用于辅助判断授权信息的准确性。
支持 不支持

文件下载异常原因

异常原因描述 状态值
设备关机 0x00
传输超时 0x01
电量不足 0x02
过热 0x03
文件过大 0x04
设备空间不足 0x05
设备工作状态异常
(示例:缺纸/卡纸/开盖)
0x06

文件传输状态表

传输状态 描述 状态值
状态 1 无文件传输触发 0x00
状态 2 启动文件传输中 0x01
状态 3 文件传输中 0x02
状态 4 文件传输/下载完成 0x03
状态 5 文件上传云端成功 0x04
状态 6 文件传输与 MCU 交互超时失败 0x05
状态 7 文件上传获取云端 URL 失败 0x06
状态 8 文件上传云端失败 0x07
状态 9 文件下载云端数据获取失败 0x08
状态 10 文件传输 MCU 回复失败 0x09

MCU OTA 升级状态表

状态 描述 状态值
状态 1 升级启动 0x00
状态 2 升级中 0x01
状态 3 升级完成 0x02
状态 4 升级失败 0x03

文件类型值对应表

说明 数值
txt 1
doc 2
pdf 3
excle 4
png 5
jpg 6
bmp 7
tif 8
gif 9
pcx 10
tga 11
exif 12
fpx 13
svg 14
psd 15
cdr 16
pcd 17
dxf 18
ufo 19
eps 20
ai 21
raw 22
WMF 23
webp 24
avif 25
WAV 26
FLAC 27
APE 28
ALAC 29
WavPack(WV) 30
MP3 31
AAC 32
Ogg Vorbis 33
Opus 34
MP4 35

更新记录

版本 编写/修订说明 修订日期 备注
1.2.5 修改文档 20220616 1. 文件下载功能
2. 增加蓝牙/ Beacon 遥控器功能相关协议
3. 增加蓝牙连接状态通知功能相关协议
1.2.4 修改文档 20210701 1. 增加支持多类型的 MCU 固件
2. 增加射频功能相关协议
3. 增加支持获取 Wi-Fi 模组相关数据。
4. 增加红外状态指示灯
5. 完善语音模组扩展功能
6. 增加蓝牙遥控器功能相关协议
7. 增加风扇类产品功能协议
1.2.3 修改文档 20200521 1. 增加产品信息包红外功能和低功耗开关选择字段
2. 增加主动获取天气服务的命令
3. 增加重置状态通知的命令
4. 修改模组工作模式名称说明
1.2.2 修改文档 20200411 增加语音模组 VWXR2 扩展协助,支持播放/暂停、蓝牙开关、本地闹钟、控制群组等功能
1.2.1 修改文档 20200409 1. 增加 Wi-Fi 成品产测。
2. 增机 Wi-Fi 遥控器控制功能
1.2.0 修改文档 20200331 适配 CI 基线相关新增功能新增网络状态包和产品信息字段
1.1.9 修改文档 20200326 1. 重整语音模组部分协议
2. 增加模组拓展服务
3. 增加双模蓝牙产测
1.1.8 修改文档 20200218 1. 增加语音模组 VWXR2 音量设置,mic 控制协议
2. 增加音频产测和唤醒产测协议
1.1.7 修改文档 20191119 1. 增加扫地机多张地图数据协议
2. 增加第三方文件下载通道
3. 完善文档协议说明
1.1.6 修改文档 20190828 增加红外能力相关协议
1.1.5 修改文档 20190824 1. 增加获取模组 MAC 地址接口
2. 完善获取天气数据功能说明
1.1.4 修改文档 20190617 1. 增加 Wi-Fi 连接方式的性能测试
2. 优化流服务流程,只保留流数据上报协议,固件兼容老版本流服务机制
1.1.3 修改文档 20190415 1. 完善相关功能命令机制描述
2. 加入针对扫地机地图服务命令
1.1.2 修改文档 20181217 1. 增加串口配网协议
2. 增加 MCU 获取 Wi-Fi 联网状态协议
1.1.1 修改文档 20180810 修改 MCU 固件升级启动返回包内容(可兼容旧固件)
1.1.0 修改文档 20180329 增加 3.20 关闭 Wi-Fi 模组心跳协议
1.0.9 修改文档 20180119 1. 增加同步指令上报 3.18 支持,收到同步指令 Wi-Fi 模组在上报成功或失败后会通知 MCU
2. 增加 Wi-Fi 信号强度获取 3.19,单位 db
1.0.8 修改文档 20170512 1. 增加打开获取天气数据接口
2. 增加下发天气数据接口
3.心跳检测间隔调整为 15s
1.0.7 修改文档 20170216 1. 增加配网模式设置(扩展查询产品信息接口)
2. MCU 协议版本号统一升级为 0x03
1.0.6 修改文档 20161110 1. 增加 Wi-Fi 工作状态
2. MCU 协议版本号统一升级为 0x02
1.0.5 修改文档 20160607 1. 删除升级查询指令
2. 删除通知 MCU 进入产测模式指令
3. 修改升级启动协议,支持 64KB 以上文件大小
1.0.4 修改文档 20160512 1. 增加获取本地时间指令
2. 增加 Wi-Fi 功能性测试
3. 增加获取模组内存指令
1.0.3 修改文档 20151114 1. 增加 MCU 获取时间功能
2. 增加 MCU 获取时区功能
3. 增加进入产测功能
1.0.2 修改文档 20151017 1. 心跳检测协议中新增 MCU 重启检测功能
2. 心跳检测间隔调整为 10s
3. 模组 Wi-Fi 状态上报更新为模组主动上报状态至 MCU
1.0.1 修改文档 20151013 将查询 product ID 改为查询模组信息,新增设备版本信息返回
1.0.0 创建文档 20151010 首次创建