ESP32-S3 摄像头图传（Rust / ESP-IDF / UDP）

两块 ESP32-S3-WROOM-1-N16R8 图传板（DVP 接口接 OV5640），向队伍客户端与裁判终端推 UDP 图传。

固件是跑在 ESP-IDF 上的 Rust，用官方 esp32-camera 组件采集；客户端是 Rust + Slint 桌面程序。

protocol/   线路格式 + 帧重组    两端共用，无 ESP-IDF 依赖，13 个单元测试
.           固件  -> ESP32-S3    交叉编译，Xtensa
client/     桌面客户端           Slint，队伍端 / 裁判端两种身份

三个 crate 各自独立构建，各有自己的 .cargo/config.toml。

拓扑

                    ┌──────────────────────────────┐
                    │  裁判终端（PC，仅显示）      │
                    │  队伍一 + 队伍二 + 双方血量   │
                    └───────────────┬──────────────┘
                                    │  同一个局域网，广播可用
               ┌────────────────────┼────────────────────┐
               │                    │                    │
       ┌───────┴───────┐    ┌───────┴───────┐    ┌───────┴───────┐
       │  图传板 A     │    │  图传板 B     │    │  装甲板 ×4    │
       │  (队伍一)     │    │  (队伍二)     │    │  (预留，未实现) │
       └───────────────┘    └───────────────┘    └───────────────┘

两块板子不区分队伍。 它们只知道自己是谁（MAC 派生的 sender_id），"哪一边"由 客户端决定。烧同一份固件即可，配置全在客户端一侧。

裁判终端同时收两块板子。队伍客户端也收全部板子的视频，然后在界面层过滤到绑定的 那一块。

实测性能

VGA 640x480，传感器产出上限 22 fps（OV5640 在此配置下的实测值）。

	TCP（HTTP MJPEG）	UDP（现在）
传感器实际产出	22 fps	22 fps
客户端实际收到	1.9 fps	22 fps
实际吞吐	0.28 Mbit/s	1.6 Mbit/s
丢帧	—	0%

TCP 那一栏只用了链路能力的 1% 左右（ESP32-S3 在良好 2.4GHz 链路上 TCP 实测上限约 20–30 Mbit/s）。链路是空的，帧却堵在队头阻塞后面等一个实时画面等不起的重传计时 器。

UDP 没有重传与确认：缺了分片的帧整个丢弃，下一帧顶上。丢帧率实测 0%，因为带宽从来 不是瓶颈——即便如此也只用掉 6–9%。

其余数字：平均帧 22 kB，约 350 包/秒，每帧约 17 个分片，客户端观测的帧间隔 7 ms。

为什么视频走 UDP 而不是 TCP

延迟优先。 丢失 5% 的画面远好于等待 500 ms 的重传。

没有队头阻塞。 一帧的任一分片卡住，后面所有帧都跟着卡——对实时画面这正好是错 的方向。

带宽不是约束。 见上表，TCP 那栏证明了链路是空的，所以 TCP 的优势在这里换不来 任何东西。

代价是丢包丢整帧。这被接受了：撕裂的画面比过期的画面更糟，所以接收端不做补洞， 只等下一张完整帧。

帧率必须按计数除以墙钟

"22 fps" 这个数字不是对帧间隔取平均得来的，是每个窗口的帧数增量除以窗口时长。

一次 UI 轮询（33ms）之间可能完成多帧，平均间隔量的是显示的刷新快慢而不是相机 的出帧快慢——那会把上限 22fps 的传感器报成 36fps。一个笃定的错误数字比没有数字更 糟，现场你会以为还有性能余量，然后花时间去找一个不存在的问题。

这个错误在本项目里出现过两次（客户端的 View::update_fps、探测脚本的分窗打印），两 次都是同一个形状：分子用累计值，分母用窗口值，于是报出随时间单调上升的假数字。

快速开始

1. 固件

cp .env.example .env      # 填 WIFI_SSID / WIFI_PASS
./scripts/flash.sh --monitor 20

flash.sh 会编译、挑选避开坏字节的 app 偏移、烧录三段（bootloader / 分区表 / app）、打印串口日志。ESP-IDF 位置从 .cargo/config.toml 读，不用先 activate。

.env：

WIFI_SSID=你的2.4G网络
WIFI_PASS=密码

# 以下都有默认值：
#CAM_RES=vga          # qqvga | qvga | cif | hvga | vga | svga | xga | sxga | uxga
#CAM_QUALITY=12       # 0-63，数字越小画质越好、字节越少
#CAM_VSYNC_INVERT=1   # 若板子在硬件上反相了 VSYNC，填 0
#WIFI_AUTH=wpa2       # 固定认证方式，仅当扫描看不到 AP 时需要（如隐藏 SSID）

凭据由 env! 在编译期读取，所以没有运行时解析路径，也不会因为忘了读 .env 而 在板子上带着别人的密码。

WIFI_AUTH 一般不用设：固件先扫描 AP，用它报告的真实认证方式去连，只有扫不到时才 需要人工指定。指定之后只试这一种方式——不成功就直接报错，而不是挨个试 10 秒。 挨个试等于在猜一个本该已知的值。

2. 客户端

cd client && cargo build --release
./target/aarch64-apple-darwin/release/cam-client --list

--list 列出发现的板子。然后：

cam-client                                  # 裁判端，无需配置
cam-client --role team --team 1             # 队伍端，首次运行问绑定

client/.cargo/config.toml 里的 target = "aarch64-apple-darwin" 换机器必须改。 client/ 嵌在固件的目录树里，会继承父目录那个 xtensa-esp32s3-espidf 的交叉编译配 置，然后在依赖深处以 libc 找不到 MAP_FAILED 的形式失败。

发现是双向的

单靠一个方向建立不了"谁要看我"：

• 板子每 2 秒广播一次 Hello —— "我在线，我是谁"
• 客户端每 800 ms广播一次 Subscribe —— "我是这个角色，请给我画面"

板子从订阅的源地址学到推流目标（所以客户端的 socket 必须固定绑 5600 端口，不能 用临时端口）。

对端靠源地址记忆，不发探测包。续订本来就每 800 ms 一次，所以"还活着吗"这个问题 由续订本身回答了——超时即代表它离开了，多一份心跳状态就多一个能出错的地方。

两端各有自己的超时淘汰，阈值不同：

	超时	为什么是这个量级
固件丢弃订阅者	6 s	续订间隔 800 ms，7 倍余量，偶发丢包不会把人踢掉
客户端移除板子	60 s	只影响界面列表，不影响推流

客户端的 60 s 刻意很长：界面列表里留着一块刚重启还没广播的板子，比它短暂消失更可接 受。而它每 5 秒才扫一次，不值得为这个上一份状态。

固件同时最多向 4 个订阅者推流（MAX_PEERS）。每个对端每帧要一次 sendto，这是帧 CPU 成本的倍数；三台客户端（两队 + 裁判）够用，且不让一个陈旧的地址条目拖慢每一帧。

身份：为什么用 MAC 派生

protocol::id_from_mac() 用 FNV-1a 从 MAC 派生 sender_id，避开 0（裁判终端的保留 值）。

用 MAC 而不是 IP，因为客户端要把绑定存进配置文件并在重启后继续有效——DHCP 换地 址是常态，MAC 不会变。用 MAC 也意味着烧同一份固件即可，不需要任何"我是谁"的配置。

线路格式

27 字节头 + 至多 1400 字节载荷，全部小端。细节在 protocol/README.md，那里有完整 的字节图和每个拒收条件。

三处关键决定：

• 27 字节不凑整。 头只占每个 1427 字节数据报的 1.9%，而为对齐在两端各写一段 手写偏移常量，是引入静默错位的更划算的代价。
• 每个数据报 1427 字节，低于 1500 MTU。 超 MTU 的数据报要么被 AP 丢、要么被 IP 分片，两种情况的丢包都记在应用账上而不是网络账上——后者本来更容易排查。
• version 不匹配就拒收，而不是按错误布局继续解析。后者表现为随机崩溃或画面错 乱，比拒绝连接难查得多。

硬件

Freenove ESP32-S3-WROOM CAM，ESP32-S3-WROOM-1-N16R8（16 MB flash + 8 MB octal PSRAM），OV5640。

引脚

src/camera.rs 的 pins 模块：

	GPIO
RESET	0
XCLK	15
PCLK	13
VSYNC	6
HREF	7
SIOD (SDA)	4
SIOC (SCL)	5
DATA[0..8]	11, 9, 8, 10, 12, 18, 17, 16

千万不要套用别的板子的引脚表

这块板子的 GPIO 分配是死的：

范围	占用
26–32	SPI flash
33–37	octal PSRAM
19 / 20	USB
43 / 44	console
45 / 46	模组内部

直接套用 AI-Thinker ESP32-CAM 的引脚表会有 7 根冲突。冲突的表现不是"某根线不 通"，而是 PIN_FUNC_SELECT 把某个外设接到了 flash 或 PSRAM 上，CPU 在传输中途挂 死——没有报错、没有回溯、串口直接静默。

改引脚前先对照上面这张表。

那块坏掉的 flash 字节

测试用的这块模组在 0xFADE7 有个字节的 bit 5–7 写不进去。镜像放在哪里会决定哪 个镜像字节落到这个地址，落上去就校验失败、bootloader 拒绝启动。

镜像本身不因位置而变，所以移动 app 分区就够了。scripts/flash.sh 会挑最低的 64 KB 对齐、且该地址处字节 flash 真的能存的偏移，写回 partitions.csv，然后重新编译 （重编译会让镜像位移，所以编译后再验证一次）。

换到健康硬件：把 factory 分区放回 0x10000，删掉 flash.sh 里的 BAD_FLASH_ADDR，别的什么都不用改。

Flash 跑 DIO @ 40 MHz 而不是这颗片子的标称 QIO/80 MHz：测试模组的坏字节在 quad 模式 下会被推到 boot loop。QIO 对代码执行速度的提升是明显的（程序从 flash 跑，cache miss 直接打在这条总线上），健康硬件上值得换回去试。

PSRAM DMA 是故意关掉的

开着的话，esp32-camera 让 GDMA 直接把帧缓冲写进 PSRAM，然后只在最后一个 DMA 节点 （1 KB）里找 JPEG 结束标记。标记落在窗口外就丢帧并报 NO-EOI——在这块板子上是大部 分的帧，几帧之后驱动干脆不再交出任何帧，而且不恢复。

关掉之后驱动 DMA 到内部 RAM 的中转缓冲，再 memcpy 进 PSRAM。每帧多一次约 23 KB 的 memcpy，但搜索整个缓冲找标记。对一条能用的图传链路，这是对的取舍。

CPU 频率

CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y 是 sdkconfig.defaults 里最值钱的一行， 而且免费。

ESP-IDF v5.5 的 Kconfig 把 ESP32-S3 默认成 160 MHz（见 components/esp_system/port/soc/esp32s3/Kconfig.cpu），所以默认编译悄悄浪费了一半 CPU。相机采集、esp32-camera 里的 JPEG 搜索、lwIP、发送路径全是 CPU 密集的，这一行一 次性把它们全部搬上去。

WiFi 缓冲留在内部 RAM

CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP=n。

这个值曾经按"PSRAM 很空闲"的直觉写成 y，方向恰好相反：WiFi 描述符和 TCP 段每个 包都要碰，内部 SRAM 比隔着内存总线的 PSRAM 快一个数量级。把它们放进 PSRAM 的表现是 高延迟和差吞吐，无论 PSRAM 还剩多少。

帧缓冲相反——它大、相对少碰，留在 PSRAM。

相机任务钉在 CPU1

CONFIG_CAMERA_CORE0=n（即跑在 CPU1）。WiFi 任务钉在 CPU0。esp32-camera 的采集任务 时间是短促且延迟敏感的（DMA 完成、JPEG 标记搜索、拷进帧缓冲），在共享核上会被抢占， 每一帧都被拉长。双核芯片上没有理由共享。

vendored esp32-camera

components/esp32-camera/ 是上游 2.1.7 的副本，因为组件注册表的版本求解器找不到它。

它打了一处补丁：target/esp32s3/ll_cam.c 里的 CAM_IO_MUX_REG()。这个宏负责把引脚 接到 I2C（OV5640 的 SCCB 走 I2C），不接的话传感器根本不会被发现。

注意这个目录叫 target/，但它不是构建目录。 它是上游组件的按芯片分目录 （esp32/、esp32s2/、esp32s3/），里面是 ll_cam.c 等源码，包含上述补丁。所以 .gitignore 里三条 target/ 规则全部锚定在根目录——这是有意的。

改过 C 文件之后

rm -rf target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*

不删不会重新编译，你的补丁看起来像完全没生效。

摄像头端不编码，客户端不编码

OV5640 的 JPEG 编码器在传感器内部。DVP 接口出来的一帧要么是 JPEG，要么是 YUV 裸 数据。

不编码的话，单帧从约 21 KB 涨到 450 KB（21 倍），而 ESP32-S3 没有硬件 JPEG 编码器（整个 ESP32 系列只有 P4 有，esp_driver_jpeg 里 CONFIG_IDF_TARGET_ESP32P4 是写死的）。

同理，客户端也不编码：板子出的就是传感器里的 JPEG，客户端只解码。ESP32-S3 也没有硬 件 JPEG 解码器。

为什么收包和解码要分开线程

一张 VGA 的 JPEG 解码要几毫秒。放在收包线程里会挤进数据报之间，造成链路上本不存在 的丢帧——不是真的丢了网络包，是应用来不及取走 socket 缓冲。

slint::Image 不是 Send，所以 worker 线程只能处理纯数据（Vec<u8> + 尺寸），Ima ge 的构造必须留在事件循环。这条约束决定了整个客户端的线程结构，细节在 client/README.md。

排查

现象	原因
板子无输出、串口静默	GPIO 冲突。CPU 在传输中途挂了，见上面那张占用表
几帧后停止出图，报 NO-EOI	PSRAM DMA 被打开了
板子在线但 0 clients subscribed	订阅包格式不对。Subscribe 的 role 字节紧跟 27 字节头，在偏移 27
一直接到但画面偶尔解不出来	帧重组的问题。先怀疑你的测量工具：本项目的探测脚本就因为重组状态没按 frame_id 隔离，误报过 34 张坏帧
libc 找不到 MAP_FAILED	client/.cargo/config.toml 的 target 没改成宿主三元组
串口看不到任何输出	非 TTY 下 espflash monitor 不可用，用 /tmp/rd2.py 裸读
WiFi 连不上	SSID 必须在 2.4GHz。5G 频段看不见
裁判端两块画面宽窄不一	检查那两格是否都写了相同的 preferred-width，且占位文字是绝对定位（x/y）而不是普通布局
放大后画面没变清晰	image-fit 必须跟着 zoom 在 contain/fill 之间切。只用 contain 的话画面不会跟着放大

独立核对线路格式：

python3 scripts/udp_probe.py 10

它手写了每一个协议常量，不依赖 protocol crate——正因为如此，如果 crate 的编码 有错，脚本会立刻报出不一致。

三份文档

根 README.md	你在这里。拓扑、性能、构建烧录、硬件坑
protocol/README.md	线路格式、帧重组的取舍、每个拒收条件
client/README.md	命令行、绑定流程、Slint 的硬约束、线程模型

装甲板（预留）

protocol::ArmorHealth、ARMOR_PORT（5601）、MsgType 5 号都已就位。客户端有真实的 ArmorSource trait，当前实现是 NoArmorYet。

界面显示占位符而不是 0。 0 看起来像真值——现场看到两个 0 会以为对方已经没血了。

接上以后板子向 ARMOR_PORT 发这个结构，客户端实现 ArmorSource 即可，界面和其余代 码都不用改。