查看“︁Vlen socket v600”︁的源代码

= 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（请求） ====
{| class="wikitable"
! 序号 !! 字段名称 !! 长度（B） !! 内容说明
|-
| 1 || 固定包头 || 2 || 0xFFFF
|-
| 2 || 包长度 || 2 || len(命令…校验和)
|-
| 3 || 命令 || 1 || 0x01
|-
| 4 || 包序号 || 1 || 0x##
|-
| 5 || flags || 2 || 0x0000
|-
| 6 || 校验和 || 1 || 0x##
|}

==== MCU → WiFi（应答） ====
{| class="wikitable"
! # !! 字段名称 !! 长度（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）。

==== 帧格式 ====
{| class="wikitable"
! # !! 字段 !! 长度（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） ====
{| class="wikitable"
! 位 !! 字段 !! 类型 / 说明
|-
| 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） ====
{| class="wikitable"
! # !! 字段 !! 长度（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`。

==== 请求 ====
{| class="wikitable"
! # !! 字段 !! 长度（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） ====
{| class="wikitable"
! # !! 字段 !! 长度（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`。

{| class="wikitable"
! # !! 字段 !! 长度（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 秒）。
{| class="wikitable"
! 字段 !! 长度（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`。  
{| class="wikitable"
! 字段 !! 长度（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`。  
{| class="wikitable"
! # !! 字段 !! 长度（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）。

[[Category:协议文档]]
[[Category:水族智能设备]]