# e:net 协议 Rust 独立验证程序 —— 实施计划

> 目标：关闭 SymphoLight 5.5，用 Rust 程序独立扮演 e:cue 主机，按《enet_protocol.md》
> 对每一条协议做**实测验证**（连接真机 Butler S2 192.168.123.1，以其真实应答为判据）。

---

## 0. 前置条件

| 项 | 动作 | 状态 |
|----|------|------|
| P1 | 关闭 SymphoLight 5.5（PID 检查 + Stop-Process） | 待执行 |
| P2 | 确认 Butler 在线（ping 192.168.123.1） | 已通 |
| P3 | 网口"以太网 3" = 192.168.123.113/24（Rust 程序绑定此地址） | 已确认 |
| P4 | 抓包样本齐备（discovery/dmx40s/rdm3 classic pcap）用于报文参数提取 | 已有 |
| P5 | 注意：SymphoLight 关闭后 Butler 回落 standalone 播 SD show（DMX 输出仍活动），Rust 程序需完成"发现→认领"接管 | 已知 |

---

## 1. 技术选型与工程结构

```
enet-validator/
├── Cargo.toml          # clap(CLI) anyhow hex rand；(无 async，std::net::UdpSocket 足够)
├── src/
│   ├── main.rs         # 子命令入口：discover / dmux / session / rdm / all
│   ├── enet.rs         # ENet 帧构造/解析（§2 通用头：magic+type+port+len）
│   ├── discovery.rs    # §3：type=01 发现请求/应答解析、宣告帧、type=02 心跳、EUCE 帧
│   ├── dmx.rs          # §4.1：形态A DMX 帧（60B头+1024B通道，序号0x1A、时间戳0x22）
│   ├── event.rs        # §4.2-4.4：形态B 事件帧、ACK 配对、状态帧解析
│   ├── rdm.rs          # §5：RDM 事件帧封装(0x4A cc01)、应答解析(0x28长度+cc01)、UID/TN
│   └── report.rs       # 验证报告输出（JSON + 控制台 PASS/FAIL）
└── samples/            # 从 pcap 提取的基准报文（hex 常量，参数化模板）
```

报文构造策略：**以实测样本为模板**（非凭空拼字段）——从 pcap 提取 222B 发现请求、
686B 宣告、1126B DMX 帧、1126B 事件帧的原始字节，替换可变字段（序号/时间戳/通道值）。

---

## 2. 验证项分解（对应协议文档章节，判据=Butler 实际行为）

| ID | 协议条目（文档章节） | 程序动作 | PASS 判据 |
|----|---------------------|----------|-----------|
| T1 | 发现请求 222B 广播（§3.1→§3.2） | 发 type=01 请求 → 监听 31772 | 收到 259B 应答；含 ASCII "Butler S2"、MAC `00:16:1c:f1:2e:39`、负载长字段 0xD9 ✓ |
| T2 | 主机宣告 686B（§3.3） | 发 type=01 宣告（主机名GUID/时间/密钥材料按模板） | 不破坏会话；后续 Butler 状态流正常 |
| T3 | type=02 心跳 78B（§3.4） | 发主机 IP+MAC 标识帧 | 同上，无异常 |
| T4 | EUCE 帧 582B（§3.5） | 发 EUCE 魔数帧（版本05@0x0C） | 同上（观察性验证） |
| T5 | DMX 数据帧（§4.1） | 按 A·B·B 节奏发形态A：序号 0x1A 递增、0x22 时间戳变化、0x3C 起 1024B 通道值（先全0→渐变图案） | Butler 持续 ACK/状态应答（不回落 standalone）；7 段显示离开 standalone |
| T6 | 事件帧 + ACK 配对（§4.2/4.3） | 每帧 DMX 配 2 事件帧，记录事件序号 0x22 与 ACK 序号 0x20 | ACK 配对率 ≥95%；序号规律与文档一致 |
| T7 | 状态帧解析（§4.4） | 被动接收 171-247B 状态帧 | 长度字段 0x14 自洽率 100%；"Butl"前缀 100% |
| T8 | 会话保持（§6） | 持续会话 ≥60s | 全程无中断；通道值变化（全0↔全255↔渐变）期间 ACK 持续 |
| T9 | 回落行为（§6 注） | 停发 10s 后观察 | Butler 回落 standalone（状态帧模式变化）→ 再恢复会话成功 |
| T10 | RDM 应答解析（§5.1-5.2） | 主动监听（若 Butler 已 Enable RDM）或发送 RDM 请求事件帧（0x4A cc01 模板） | 收到 cc01 起始帧；0x28 长度自洽；提取灯具 UID |
| T11 | 写地址探索（§5.4） | 在 RDM 请求模板中尝试标准 PID 0x0330 SET 与私有 PID 0x2100 族 | 观察 Butler 是否下发 RDM 应答（记录 PID 行为，产出逆向数据） |

判据统一由程序自动记录（报文 hex + 时间戳 + PASS/FAIL），输出 `validation_report.json`。

---

## 3. 执行阶段

- **阶段0 准备**（P1-P5）：关 SymphoLight、（可选）抓 10s standalone 对照流量存档。
- **阶段1 骨架**：Rust 工程 + pcap 样本提取器（PowerShell 导出基准 hex 常量）。
- **阶段2 单向验证**：T1→T2/T3/T4（每项独立子命令，互不依赖）。
- **阶段3 会话验证**：T5→T6→T7→T8（核心：接管 Butler，验证 DMX/ACK/状态全链路）。
- **阶段4 行为验证**：T9 回落与恢复。
- **阶段5 RDM 探索**：T10/T11（可选，依赖 Butler RDM 端口已启用状态）。
- **阶段6 报告**：validation_report.json + 更新 enet_protocol.md（修正/补充实测发现）。

## 4. 风险与对策

| 风险 | 对策 |
|------|------|
| Butler 在 standalone 播 show 干扰观察 | T5 认领成功即接管 DMX；必要时临时拔 SD 卡（用户决定） |
| DUT(ESP32-P4) 仍在总线上 | 验证前确认 DUT 状态：保持暂停（download mode）或已恢复；勿冲突 |
| 报文字段拼错导致 Butler 无响应 | 全部以 pcap 样本为模板参数化；T1 失败时 diff 实发与样本 |
| 端口 31772 被占（SymphoLight 残留） | P1 确认进程退出；程序绑定失败即报错 |
| RDM 未启用时 T10/T11 无效 | 作为可选阶段，跳过不影响主结论 |

## 5. 交付物

1. Rust 工程（可执行 `enet-validator.exe`，子命令式）
2. `validation_report.json` + 控制台报告
3. `enet_protocol.md` 增补（以 Rust 实测修正/确认各字段）