# protocol

摄像头 UDP 图传的线路格式，**固件与客户端共用**。

这是本仓库里最该被测试的部分：帧重组和编码都极易出微妙错误，而这两件事都无法
在固件上验证——你只会看到"不出画面"。

因此它没有 ESP-IDF 依赖，会为宿主架构编译：

```sh
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，两端共用同一个常量。