Horldsence
1c65eaabc6
`seen >= expected` 判断分片是否收齐是错的：UDP 会重复投递，一个丢失的 分片可以被另一个包的副本凑数，于是计数达标而缓冲区里留着空洞，交出去 一张尾部是 0 的 JPEG。 这个 bug 很隐蔽——帧率完全正常，没有任何报错线索，只是偶尔几张图解不 出来。实测 10 秒内出现 34 张这样的坏帧。 改为按分片下标记录是否收到，重复的直接跳过且不计数；再显式确认最后一个 分片确实到过。实测坏帧降到 1（板子启动瞬间的残帧），完整帧率不变。 补两个测试覆盖它——原有测试没有一个会重复发分片，所以这个 bug 一直没被 发现： - a_duplicate_cannot_complete_a_frame_with_a_hole - a_gap_that_is_never_filled_never_yields_a_frame 同时更新 scripts/udp_probe.py：它有同一个 bug，所以测不出修复效果。它还 把 Subscribe 的 role 字节多填了 12 个零字节，固件按偏移严格读取因而拒收， 表现为"板子在线但 0 clients subscribed"。脚本的意义正是独立核对线路格式， 所以这些偏移是手写的，改协议时必须同步。 另删 scripts/pick-flash-pad.sh：链接期 padding 已被证明移不动 .flash.text 内部，flash.sh 现在会自动挑选避开坏字节的 app 偏移。
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，两端共用同一个常量。