Horldsence
4f893ce140
两块 ESP32-S3-WROOM-1-N16R8 图传板（DVP 接口接 OV2640/OV3660/OV5640）， 向队伍客户端与裁判终端推 UDP 图传。固件是跑在 ESP-IDF 上的 Rust，用官方 esp32-camera 组件采集；客户端是 Rust + Slint 桌面程序。 三个 crate 各自独立构建： . firmware，交叉编译到 Xtensa protocol/ 线路格式与帧重组，两端共用，无 ESP-IDF 依赖，有单元测试 client/ Slint 桌面客户端 视频走 UDP 而非 TCP：实测传感器产出 22 fps，TCP MJPEG 只送出 1.9 fps， 且只占用链路能力的 1%——链路是空的，帧堵在队头阻塞后面等一个实时画面 等不起的重传计时器。改为独立数据报、不重传、缺片丢整帧后达到 20.8 fps。 发现是双向的：板子每 2 秒广播 Hello，客户端广播 Subscribe，板子据此定向 推流。板子身份由 MAC 派生，重启不变，所以客户端可以把绑定存进配置。 裁判端同时收两块板子（每个发送方一个重组器），队伍端绑定其中一块并只显示 自己那一边的血量。装甲板接口已预留（ArmorSource trait + ARMOR_PORT）， 当前无数据源，界面显示占位符。 vendor 了 esp32-camera 2.1.7：组件注册表的版本求解器找不到它，且需要打一处 补丁（见 components/esp32-camera/target/esp32s3/ll_cam.c）。 .gitignore 三条 target/ 都锚定在根目录，因为 protocol/ 与 client/ 各自也是 独立 crate；而 components/esp32-camera/target/ 是上游的按芯片分目录，里面是 源码，必须保留。
protocol
摄像头 UDP 图传的线路格式，固件与客户端共用。
这是本仓库里最该被测试的部分：帧重组和编码都极易出微妙错误，而这两件事都无法 在固件上验证——你只会看到"不出画面"。
因此它没有 ESP-IDF 依赖，会为宿主架构编译：
cargo test
7 passed
线路格式
每个数据报 = 20 字节头 + 至多 1400 字节 JPEG 数据：
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-------------------------------+-------------------------------+
| magic (u32) | frame_id (u32) |
+-------------------------------+-------------------------------+
| frag_index (u16) | frag_count (u16) |
+-------------------------------+-------------------------------+
| total_len (u32) | width (u16) | height (u16) |
+-------------------------------+---------------+---------------+
| payload (0..=1400) |
+---------------------------------------------------------------+
全部整数为小端——ESP32-S3（Xtensa）和所有桌面架构都原生如此，编解码就是
to_le_bytes / from_le_bytes，没有字节序转换步骤。
magic固定值，用于把同端口上的无关 UDP 包挡掉。total_len是整张 JPEG 的长度，接收端据此预分配缓冲并判断帧是否完整。width/height每个分片都重复携带（不只是第 0 个），这样每个数据报都能独立 解析，中途加入的接收端也能立刻知道分辨率。
为什么是 UDP 而不是 TCP
这是本 crate 存在的原因，也是实测数据：
| TCP（HTTP MJPEG） | UDP | |
|---|---|---|
| 传感器实际产出 | 22 fps | 22 fps |
| 客户端实际收到 | 1.9 fps | 20.8 fps |
| 实际吞吐 | 0.28 Mbit/s | 1.72 Mbit/s |
关键在于链路是空的：TCP 那一栏只用了链路能力的 1% 左右（ESP32-S3 在良好的 2.4GHz 链路上，TCP 实测上限约 20–30 Mbit/s），帧却堵在队头阻塞后面等一个实时画面 等不起的重传计时器。
UDP 没有任何重传与确认：缺了分片的帧被整个丢弃，下一帧顶上。这换来低延迟，也把 本来就有的带宽真正用起来了——但即便如此也只用掉 6–9%，说明瓶颈从头到尾都不在 带宽上。
接收端的取舍
FrameAssembler 的策略就是全部要点：只有分片全部到齐才显示该帧，且最新的帧永远
优先。
UDP 不保证跨数据报的顺序或到达，所以试图"补洞"的接收端做的功比"等下一张完整帧" 更多——而且补的过程中会显示撕裂的画面。
另外有一个有界超时，用来堵住另一种失败模式：发送方在帧中途死掉时，半截缓冲会 永远留在这里。
| 字段 | 含义 |
|---|---|
frag_count == 0 |
非法，立即拒绝 |
frag_index >= frag_count |
自相矛盾，立即拒绝 |
payload_len > total_len |
损坏，立即拒绝（在造成大额分配之前就挡住） |
发送端
fragment_frame() 从 JPEG 长度推出分片数，因此调用方不可能产出与自身矛盾的
分片集合。
Fragment::encode_into() 追加写入而不分配：发送端对每帧的每个分片复用同一个缓冲，
在 22fps 下这是每秒约 250 次分配与不分配的区别——在 WiFi 栈也要抢内部 RAM 的芯片
上，这个差别很实在。
不变量
- 一个数据报不超过
HEADER_LEN + MAX_FRAGMENT_PAYLOAD= 1420 字节，低于典型以太网 的 1500 MTU。 这一点比看起来重要：超过 MTU 的数据报要么被 AP 丢掉，要么被 IP 分片，而两种情况 的丢包都会记在应用账上而不是网络账上——后者本来更容易排查。 - VGA 下
MAX_FRAGMENT_PAYLOAD对应每帧 8–10 个数据报。 DEFAULT_PORT= 5600，两端共用同一个常量。