VLen六路水族排插 - 机智云WiFi类设备接入协议文档（MCU方案）
- 产品名称
- VLen六路水族排插
- 产品类型
- 电工/排插/自定义多路排插
- 生成日期
- 2023-06-20
本页为 MCU 与 WiFi 通讯模组的串口通讯协议（机智云标准接入协议 v4.3.1）的 **单页 MediaWiki** 版。完整覆盖 1~4 章，字段逐条展开，并在各命令下以表格列出“字段名 / 字节长度 / 说明”。
1. 设备通讯信息
- 通讯方式：UART
- 波特率：9600
- 数据位：8
- 奇偶校验：无
- 停止位：1
- 数据流控：无
- 供电：3.3V，电流（Max）150 mA
2. 约定
2.1 传输字节序
默认采用 **大端** 编码（高字节在前，低字节在后）。
2.2 通信交互形式
- 采用 **一问一答**；每条命令需要接收方给出 ACK 确认；
- 超时时间 **200 ms**，超时后重发；最多 **重发 3 次**；其后丢弃该包。
2.3 协议格式
指令总体结构
- 包头（2B）= `0xFFFF`。注意：**非包头部分**如出现 `0xFF`，发送方需在其后**插入** `0x55`；接收方检测到非包头的 `0xFF 55` 需要**移除**该 `0x55`。该填充字节**不计入**包长度及校验和。
- 包长度（2B）：**从命令开始**至**校验和**的字节数（含命令与校验和）。
- 命令（1B）。
- 包序号 SN（1B）：由发起方给出，自 0 递增，超过 255 后回绕；ACK 回复需回填收到的 SN。
- Flags（2B）：高字节为**通用标记**（跨命令），低字节为**命令内私有标记**（仅本命令意义）。
- 有效负载：由产品数据点/业务定义。
- 校验和（1B）：对 **[包长度…有效负载]** 做逐字节求和，再取 **mod 256**。
3. 基本通讯协议（必须）
3.1 获取设备信息
WiFi 模组上电后向 MCU 查询设备信息，成功后方可正常工作。
WiFi → MCU（请求）
| 序号 |
字段名称 |
长度（B） |
内容说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x01
|
| 4 |
包序号 |
1 |
0x##
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
校验和 |
1 |
0x##
|
MCU → WiFi（应答）
| # |
字段名称 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x02
|
| 4 |
包序号 |
1 |
回填请求 SN
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
通用串口协议版本号 |
8 |
字符串，如 “00000004”
|
| 7 |
业务协议版本号 |
8 |
字符串，如 “00000002”
|
| 8 |
硬件版本号 |
8 |
字符串
|
| 9 |
软件版本号 |
8 |
字符串
|
| 10 |
产品标识码 ProductKey |
32 |
字符串
|
| 11 |
可绑定状态失效时间 |
2 |
秒（大端）。0=随时可绑定；>0 为进入可绑定后的失效秒数
|
| 12 |
设备属性 attributes |
8 |
bit0…bit63 定义（见下）
|
| 13 |
产品秘钥 ProductSecret |
32 |
Hex 字符串
|
| 14 |
DataLen |
2 |
环境参数长度；0=无 Data
|
| 15 |
Data |
DataLen |
环境参数字符串（键值对，见下）
|
| 16 |
校验和 |
1 |
0x##
|
- 设备属性 attributes（bit0→bit63，自右向左）
- bit0=1：设备是**中控**；
- bit1=1：**自动化生成代码**；
- bit2~bit5（当 bit0=1 生效）：中控重置范围：
- 0000：中控重置
- 0001：中控重置 + **所有子设备**重置
- 0010：中控重置 + **所有子设备与用户绑定关系**
- 0011：中控重置 + **部分子设备**重置（与该中控有关联的子设备）
- 0100：**所有子设备**重置
- 0101：**所有子设备与用户绑定关系**
- 0110：**部分子设备**重置
- 0111：**部分子设备与用户绑定关系**
- bit6=1：UDP **加密**；
- bit7=1：**变长数据点**；
- bit8=1：设备是**网关**；
- bit9~bit12（当 bit8=1 生效）：网关重置范围：
- 0000：网关重置
- 0001：网关重置 + 所有子设备重置
- 0010：所有子设备重置
- bit13=1：**低功耗**产品；
- bit14~bit63：**预留**（保持 0 以免影响云端连接）。
- 环境参数 Data（key=value，用‘&’连接；示例：
"wechatId=...&server=...&port=...&apName=...&apPwd=...&m2mKeepAL=...&m2mHT=...&tz=...&LocalHT=...&LocalAckT=...&nwcName=...&cfgMode=...&tScanNum=...&tCon=...&runMode=..."）
- wechatId：设备微信设备公众号 ID
- server：默认服务器域名
- port：默认服务器端口
- apName：SoftAP 热点名，**后缀追加 4 位 MAC**
- apName0：SoftAP 热点名，**不追加 MAC**
- apPwd：SoftAP 热点密码；为空=Open
- m2mKeepAL：M2M keepalive 秒
- m2mHT：M2M 心跳秒
- tz：默认时区
- LocalHT：串口心跳秒
- LocalAckT：串口等待 ACK 基础时间（毫秒）
- nwcName：网卡名，例 "eth0"
- cfgMode：初始化运行模式（1=SoftAP，2=AirLink）
- tScanNum：初始化扫描热点次数（默认 2）
- tCon：产测是否连路由（0=否，1=是（默认））
- runMode：运行模式（1=单通道（默认）；2=双通道，如 Wi‑Fi+BLE/4G+BLE）
3.2 WiFi 模组控制设备
WiFi → MCU，命令 `0x03`，`action=0x11`；MCU 回复 `0x04`（ACK）。
帧格式
| # |
字段 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x03
|
| 4 |
包序号 |
1 |
0x##
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
action |
1 |
0x11
|
| 7 |
attr_flags |
6 |
**是否设置标志位位图**（见下）
|
| 8 |
attr_vals |
Max 249 |
**按位顺序紧凑排列**的数据值（见下）
|
| 9 |
校验和 |
1 |
0x##
|
- 规则
- `attr_flags` 中**某位=1**，表示 `attr_vals` 中**对应字段**的**数值存在且有效**；为 0 表示该字段**忽略**。
- `attr_vals` 的字段顺序与 `attr_flags` 的位定义一一对应，按**从低位到高位**、从**bool → 标量 → binary** 的**固定顺序**连续排列。
attr_flags 位定义（共 48 位，bit0→bit47）
| 位 |
字段 |
类型 / 说明
|
| bit0 |
switch_1 |
bool（开关 1）
|
| bit1 |
switch_2 |
bool（开关 2）
|
| bit2 |
switch_3 |
bool（开关 3）
|
| bit3 |
switch_4 |
bool（开关 4）
|
| bit4 |
switch_5 |
bool（开关 5）
|
| bit5 |
switch_6 |
bool（开关 6）
|
| bit6 |
power |
bool（总电源）
|
| bit7 |
High_temperature_alarm |
bool
|
| bit8 |
Low_temperature_alarm |
bool
|
| bit9 |
High_Humidity_alarm |
bool
|
| bit10 |
Low_Humidity_alarm |
bool
|
| bit11 |
High_tds_alarm |
bool
|
| bit12 |
Low_tds_alarm |
bool
|
| bit13 |
High_ph_alarm |
bool
|
| bit14 |
Low_ph_alarm |
bool
|
| bit15 |
humidity |
uint8（0..100，y=1*x+0）
|
| bit16 |
ph_value |
uint8（0..140，**y=0.1*x**）
|
| bit17 |
switch_mode_1 |
uint8（0..10）
|
| bit18 |
switch_mode_2 |
uint8（0..10）
|
| bit19 |
switch_mode_3 |
uint8（0..10）
|
| bit20 |
switch_mode_4 |
uint8（0..10）
|
| bit21 |
switch_mode_5 |
uint8（0..10）
|
| bit22 |
switch_mode_6 |
uint8（0..10）
|
| bit23 |
Temperature_alarm_max |
uint8（0..100）
|
| bit24 |
Temperature_alarm_min |
uint8（0..100）
|
| bit25 |
Humidity_alarm_max |
uint8（0..100）
|
| bit26 |
Humidity_alarm_min |
uint8（0..100）
|
| bit27 |
ph_alarm_max |
uint8（0..140，y=0.1*x）
|
| bit28 |
ph_alarm_min |
uint8（0..140，y=0.1*x）
|
| bit29 |
temp_current_1 |
uint16（0..1200，**y=1*x-200**）
|
| bit30 |
temp_current_2 |
uint16（0..1200，**y=1*x-200**）
|
| bit31 |
Total_dissolved_solids |
uint16（0..5000）
|
| bit32 |
current_voltage |
uint16（0..5000）
|
| bit33 |
Current_power |
uint16（0..10000）
|
| bit34 |
tds_alarm_max |
uint16（0..5000）
|
| bit35 |
tds_alarm_min |
uint16（0..5000）
|
| bit36 |
urt_value |
uint32（0..600000）
|
| bit37 |
Current_current |
uint32（0..100000）
|
| bit38 |
cur_timestamp |
uint32（Unix 秒）
|
| bit39 |
cycle_mode_set |
binary（24B，数组 [1,2,3…]）
|
| bit40 |
temperature_mode_set |
binary（12B）
|
| bit41 |
humidity_mode_set |
binary（12B）
|
| bit42 |
time_mode_set_1 |
binary（30B）
|
| bit43 |
time_mode_set_2 |
binary（30B）
|
| bit44 |
time_mode_set_3 |
binary（30B）
|
| bit45 |
time_mode_set_4 |
binary（30B）
|
| bit46 |
time_mode_set_5 |
binary（30B）
|
| bit47 |
time_mode_set_6 |
binary（30B）
|
- attr_vals 编码顺序与示例（节选）
- bool 组合位（byte0）：`switch_1…switch_6` + `power` + 各报警位，**bit0→bit7**；
- 接着是 `switch_mode_1…6`（6×uint8）→ `Temperature_alarm_max/min`（2×uint8）→ `Humidity_alarm_max/min`（2×uint8）→ `ph_alarm_max/min`（2×uint8，y=0.1x）→ `tds_alarm_max/min`（2×uint16）→ `cur_timestamp`（uint32）→ `cycle/temperature/humidity_mode_set`（binary）→ `time_mode_set_1…6`（各 30B）。
MCU → WiFi（ACK）
| # |
字段 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x04
|
| 4 |
包序号 |
1 |
回填请求 SN
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
校验和 |
1 |
0x##
|
- 实施建议
- 无论状态是否改变，**执行控制后建议立即上报一次**最新设备状态（参见 3.4 上报）。
3.3 WiFi 模组读取设备的当前状态
WiFi → MCU：命令 `0x03`，`action=0x12`；MCU → WiFi：命令 `0x04`，`action=0x13`。
请求
| # |
字段 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x03
|
| 4 |
包序号 |
1 |
0x##
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
action |
1 |
0x12
|
| 7 |
attr_flags |
6 |
与控制命令一致（筛选需要返回的状态）
|
| 8 |
校验和 |
1 |
0x##
|
应答（含 dev_status）
| # |
字段 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x04
|
| 4 |
包序号 |
1 |
0x##
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
action |
1 |
0x13
|
| 7 |
attr_flags |
6 |
与控制命令一致
|
| 8 |
dev_status |
Max 270 |
**设备状态**（字段顺序/类型与 3.2 对应）
|
| 9 |
校验和 |
1 |
0x##
|
- dev_status 字段说明
- 位/字段定义与 3.2 `attr_flags` 一致，**编码顺序**与 3.2 的 `attr_vals` 相同；
- 定标公式：同 3.2 中各字段（例如 `ph_value`、`ph_alarm_*` 为 0.1x；温度 current_* 为 1*x-200）。
3.4 设备 MCU 主动上报当前状态
MCU → WiFi：命令 `0x05`，`action=0x14`，负载为 `dev_status`。
| # |
字段 |
长度（B） |
说明
|
| 1 |
固定包头 |
2 |
0xFFFF
|
| 2 |
包长度 |
2 |
len(命令…校验和)
|
| 3 |
命令 |
1 |
0x05
|
| 4 |
包序号 |
1 |
0x##
|
| 5 |
flags |
2 |
0x0000
|
| 6 |
action |
1 |
0x14
|
| 7 |
attr_flags |
6 |
按需设置（哪些状态有效即置位）
|
| 8 |
dev_status |
Max 270 |
状态体（字段/顺序同 3.2/3.3）
|
| 9 |
校验和 |
1 |
0x##
|
- 上报策略（建议）
- 接收到“控制设备”命令后，**立即上报**被控制后的数据点组合；
- 因用户手动或环境变化导致设备状态改变时，仅上报**发生变化**的数据点组合；
- 可设置**定期上报**（例如每 10 分钟一次）。
3.5 心跳
- WiFi → MCU：`0x07`；MCU → WiFi：`0x08`。
3.6 通知 WiFi 模组进入配置模式
- 命令：`0x09`（请求）/ `0x0A`（应答）；支持 SoftAP / AirLink / BLE 等。
3.7 重置 WiFi 模组
- 命令：`0x0B`（请求）/ `0x0C`（应答）；清除 SSID/密码/DID/Passcode，恢复出厂。
3.8 推送 WiFi 模组工作状态
- 命令：`0x0D`（WiFi 状态上报）/ `0x0E`（ACK）；状态包含 SoftAP/Station/Onboarding/绑定状态/RSSI/蓝牙模式等。
3.9 非法数据包通知
- 命令：`0x11`（WiFi→MCU）/ `0x12`（MCU→WiFi）；
- 错误码：1=校验和错误；2=命令不可识别；3=其他错误；4=文件类型不匹配。
3.10 MCU 通知 WiFi 模组进入可绑定模式
- 命令：`0x15`（请求）/ `0x16`（应答）；倒计时（可绑定失效秒）见 3.1 字段。
3.11 MCU 重启通讯模组
- 命令：`0x29`（请求）/ `0x2A`（应答）；ACK 成功后模组再重启。
4. 扩展通讯协议（可选）
4.1 重启 MCU
- WiFi → MCU：`0x0F`（请求）；MCU → WiFi：`0x10`（应答）。
- 注意：MCU **在回复 ACK 后等待 ~600 ms** 再重启，避免 WiFi 端未收到 ACK 而重复请求。
4.2 MCU 请求 WiFi 模组进入产测模式
- MCU → WiFi：`0x13`；WiFi → MCU：`0x14`。
4.3 MCU 请求获取网络时间
- MCU → WiFi：`0x17`；WiFi → MCU：`0x18`（返回本地时区时间 + NTP 秒）。
| 字段 |
长度（B） |
说明
|
| year |
2 |
年（大端），如 2015
|
| month |
1 |
月
|
| day |
1 |
日
|
| hour |
1 |
时
|
| minute |
1 |
分
|
| second |
1 |
秒
|
| ntp |
4 |
NTP 秒计数
|
4.4 大数据下发：发起者请求
- WiFi → MCU：`0x19`；MCU → WiFi：`0x1A`。
负载含：**数据大小**、**文件类型**、**MD5**。
4.5 大数据下发：接收者确认
- MCU → WiFi：`0x1B`；WiFi → MCU：`0x1C`。
负载含：**分片大小**（建议 128B）。
4.6 大数据下发：分片传输
- WiFi → MCU：`0x1D`；MCU → WiFi：`0x1E`。
| 字段 |
长度（B） |
说明
|
| total_packets |
2 |
总分片数
|
| packet_index |
2 |
当前分片号（0 起）
|
| data |
N |
分片数据
|
- Flags.bit1 = 1 表示**最后一包**。
4.7 大数据下发：发起者取消
- WiFi → MCU：`0x1F`；MCU → WiFi：`0x20`。
4.8 大数据下发：接收者取消
- MCU → WiFi：`0x27`；WiFi → MCU：`0x28`。
4.9 MCU 获取通讯模组信息
- MCU → WiFi：`0x21`；WiFi → MCU：`0x22`。
| # |
字段 |
长度（B） |
说明
|
| 1 |
module_type |
8 |
模组类型（字符串）
|
| 2 |
protocol_version |
8 |
协议版本（字符串）
|
| 3 |
hardware_version |
8 |
硬件版本（字符串）
|
| 4 |
software_version |
8 |
软件版本（字符串）
|
| 5 |
mac |
max 13 |
以 '\\0' 结尾的字符串，例如 "5CF9388AE8F0\\0"
|
| 6 |
ip |
max 16 |
以 '\\0' 结尾的字符串，例如 "192.168.100.254\\0"
|
| 7 |
attributes |
8 |
模组属性（预留）
|
| 8 |
校验和 |
1 |
0x##
|
A. 附录：数据点/字段的缩放与边界
- `ph_value`、`ph_alarm_*`：**y=0.1*x**；
- `temp_current_1/2`：**y=1*x-200**（原始 0..1200）；
- `humidity`、`Temperature/Humidity_alarm_*`：**y=1*x+0**；
- `Total_dissolved_solids`、`tds_alarm_*`：uint16（0..5000）；
- `current_voltage`：uint16（0..5000）；`Current_power`：uint16（0..10000）；
- `urt_value`：uint32（0..600000）；`Current_current`：uint32（0..100000）；
- `cur_timestamp`：uint32（Unix 秒）。
B. 附录：布尔组合位（byte0）编码
- bit0…bit5 = `switch_1…switch_6`；bit6=`power`；bit7..bit14=各报警位（高温/低温/高湿/低湿/高 TDS/低 TDS/高 pH/低 pH）。