RMIC::2026 · 视野链路系统

黑龙江大学 602 实验室 · Simba Robotics

面向机器人对抗赛的局域网图传与装甲板系统。ESP32-S3 采集 OV5640 的硬件 JPEG，经 UDP 发送到桌面端；ESP32-C3 上报装甲板血量，桌面端提供操作手视野、裁判双路监看、截图录制和 USB 固件维护。

文档首页 · 硬件接线 · 故障排查 · 改动记录 · 开发约定

Note

版本、构建号与线路协议号以 version.json 为准。改动记录从 Git 历史生成，维护方式见版本说明。

导航

• 系统架构
• 功能与验证范围
• 快速开始
• 发现与收流时序
• 仓库结构
• 开发与验证
• 文档与后续工作

系统架构

flowchart LR
    subgraph Camera["图传板 · ESP32-S3"]
        Sensor["OV5640<br/>硬件 JPEG"] --> Firmware["采集与分片<br/>最新帧发送"]
    end

    subgraph Armor["装甲板 · ESP32-C3"]
        Piezo["四路压电片"] --> Rules["受击规则与整车血量"]
        Rules --> LEDs["四路 WS2812"]
    end

    subgraph Desktop["RMIC::2026 · 桌面端"]
        Core["Rust 核心<br/>发现、重组与血量状态"]
        Backend["Tauri 后端<br/>本地通道、截图与录制"]
        UI["React / WebView<br/>用户端或裁判端"]
        Core --> Backend
        Backend -->|"本地 WebSocket：JPEG 与状态"| UI
        UI -->|"IPC：配置与操作"| Backend
    end

    Firmware -->|"UDP 5600：Hello 与视频分片"| Core
    Core -->|"Subscribe：广播与定向续订"| Firmware
    Rules -->|"UDP 5601：血量广播"| Core

两块图传板各自发送，裁判端同时接收两路；用户端只接收绑定图传板的画面。装甲板主板连接四路传感器和灯带，其余从板不含 MCU。

网络项	配置	说明
图传板 Wi-Fi	2.4 GHz	板卡与客户端需处于可互通的局域网
视频与发现	UDP 5600	Hello、Subscribe 与 JPEG 分片
装甲板上报	UDP 5601	每 200 ms 广播四路血量
本地界面通道	回环 WebSocket + Tauri IPC	JPEG 由 WebView 解码，网络接收线程不做视频解码

Important

网络需要允许广播和设备间互访。请关闭 AP 客户端隔离，并允许客户端通过防火墙。VPN / 虚拟网卡可能影响广播路由，排查方法见客户端说明。

功能与验证范围

模块	已有功能	使用条件与边界
图传固件	VGA 彩色 JPEG、UDP 分片、多端订阅、Wi-Fi 重连、过期帧放弃	当前记录约 30 fps；不同网络、板卡与画质下需复测1
用户端	本队画面、双方装甲条、瞄准器、偏移校准、命中反馈	先绑定图传板与装甲板；改绑、切换模式和退出受密码限制
裁判端	双路画面、队名编辑、装甲板发现、槽位分配、截图、录制与回放	录制需要 ffmpeg；图传槽位可手动指定
装甲板	四路受击检测与灯带、整车血量、UDP 上报	初始 100 血，每次受击扣 3 点；队伍号在编译期选择
固件维护	USB 读取设备、检查固件包、选择候选槽位、备份和写后回读	App 写入与回读已有实机记录；完整分区切换尚未验证

发送端在有限预算内提交当前帧，超时后转向新帧；本地视频通道与 WebView 会放弃滞留超过 100 ms 的旧帧。这个期限约束的是本机积压，不代表相机到屏幕的端到端延迟。

Warning

固件维护会写入设备 Flash。使用前核对芯片、分区和备份，并阅读已验证与未验证范围。ESP32-S3 与 ESP32-C3 的固件不能混用。

快速开始

1. 无板卡：先看界面

安装 Node.js 和 pnpm 后，在仓库根目录执行：

cd desktop
pnpm install --frozen-lockfile
pnpm dev

打开 用户端预览 或 裁判端预览。预览由浏览器合成状态和画面，无需 Rust 后端或板卡。

Tip

检查首次启动流程时，可使用 ?preview=first-run 和 ?preview=password。需要测试实际接收、重组和录制路径时，使用原生客户端的 --demo 模式；两种方式显示的都是合成数据。

2. 连接板卡：运行桌面端

先按客户端说明安装宿主平台依赖。Windows x64 需要 Rust stable MSVC、Visual Studio C++ Build Tools、Windows SDK 和 WebView2；录制另需 ffmpeg。

Windows x64：开发运行与安装包

在 desktop/ 执行。显式指定目标，并清空从根固件项目继承的 build-std：

pnpm install --frozen-lockfile
pnpm app --target x86_64-pc-windows-msvc -- --locked --config 'unstable.build-std=[]'

生成 NSIS 安装包：

pnpm tauri build --target x86_64-pc-windows-msvc --bundles nsis --ci -- --locked --config 'unstable.build-std=[]'

安装包位于 desktop/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/nsis/。显示名为 RMIC::2026，Windows 可执行文件和安装包使用 RMIC-2026。

macOS / Linux：目标选择与演示模式

desktop/.cargo/config.toml 默认目标为 aarch64-apple-darwin。Intel Mac 使用 x86_64-apple-darwin，常见 Linux x64 使用 x86_64-unknown-linux-gnu；其他架构先用 rustc +stable -vV 核对 host。

以 Linux x64 为例，在 desktop/ 执行：

pnpm install --frozen-lockfile
pnpm app --target x86_64-unknown-linux-gnu -- --locked --config 'unstable.build-std=[]'

同一命令末尾追加 -- --demo 可启动原生演示模式。它将合成数据报送入正常接收与重组路径，适合检查截图、录制和命中反馈；预览与演示的区别见客户端说明。

首次启动选择用户端或裁判端。用户端需要设置现场密码并绑定本车板卡；裁判端自动分配图传槽位，装甲板按上报队伍分配。对应关系不符时，在设置中手动指定。

3. 编译图传或装甲固件

硬件	构建目标	入门文档
Freenove ESP32-S3-WROOM CAM + OV5640	xtensa-esp32s3-espidf	环境、参数与烧录
ESP32-C3 装甲板主板	riscv32imc-esp-espidf	接线、规则与构建

已装好图传工具链：构建命令

先按固件入门安装固定的 esp-1.97.0.0 工具链与 ESP-IDF 依赖。在仓库根目录准备 .env；已有文件时不要覆盖。

Windows PowerShell：

if (-not (Test-Path -LiteralPath .env)) {
    Copy-Item -LiteralPath .env.example -Destination .env
}
# 用编辑器填写 .env 中的 Wi-Fi 配置后再构建。
.\scripts\build.ps1 -Package

Linux / macOS（Bash）：

test -f .env || cp .env.example .env
# 用编辑器填写 .env 中的 Wi-Fi 配置后再构建。
. "$HOME/export-esp.sh"
scripts/build.sh --package

上述命令只构建和打包。烧录步骤、引脚与分区偏移请按固件入门核对；不要将 ELF 当作 BIN 写入。

Wi-Fi 凭据会编入固件。.env 已被 Git 忽略，分享固件前也需检查其中的凭据。

发现与收流时序

sequenceDiagram
    participant Board as ESP32-S3 图传板
    participant Client as 桌面 Rust 核心
    participant View as WebView 画面

    Board-->>Client: Hello 广播（每 2 秒，含版本与协议号）
    Client->>Board: Subscribe（每 800 ms 续订）
    Note over Board,Client: 按订阅包源地址推流；6 秒未续订则移除

    loop 采集与发送
        Board-->>Client: JPEG 分片（27 字节头 + 最多 1400 字节载荷）
        alt 分片完整且通过接收检查
            Client->>View: 本地通道投递完整 JPEG
            View->>View: 解码并绘制最新有效帧
        else 缺片或超时
            Client->>Client: 丢弃未完成帧，等待后续帧
        end
    end

分片按 sender_id 和 frame_id 隔离，不重传缺失分片。线路格式、去重和拒收条件见 UDP 协议。

仓库结构

路径	职责	说明
src/	ESP32-S3 固件	采集、分片、发现订阅、发送与重连
components/	C 组件与 FFI	本地相机驱动、封装及补丁
protocol/	共享线路协议	编解码与帧重组，可在主机测试
desktop/core/	桌面核心	网络、装甲板、配置、密码与槽位
desktop/src-tauri/	Tauri 后端	本地通道、命令、录制与固件维护
desktop/src/	React 前端	用户端、裁判端、维护与延迟校准
armor/	ESP32-C3 独立 workspace	受击规则、灯带与血量广播
scripts/	构建与诊断工具	烧录、打包、版本、协议与性能探测
reference/armor/	早期 C 版参考工程	用于核对硬件与实现差异
docs/	项目文档	入门、开发、硬件、测试、发布与提案

Caution

components/esp32-camera/target/ 是按芯片分类的驱动源码，包含本地补丁。它不是构建缓存，不能随其他 target/ 目录一起清理。

开发与验证

按修改范围运行对应检查。主机 Rust 测试需显式选择宿主目标，避免继承 ESP32 的构建配置；各平台说明见开发与验证。

前端检查与 Windows 主机 Rust 检查

前端命令在 desktop/ 执行：

pnpm build
pnpm test:stream
pnpm test:latency

以下 Rust 命令在仓库根目录执行：

cargo +stable test --locked --manifest-path protocol/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
cargo +stable test --locked --manifest-path desktop/core/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
cargo +stable check --locked --manifest-path desktop/src-tauri/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'

录制相关测试会调用 ffmpeg / ffprobe。主机测试、前端构建通过后，仍需按变更范围检查真实 WebView、板卡与网络行为。

提交使用 Conventional Commits，如 docs(readme): 完善项目入口。版本由 Git 历史计算，在根目录执行：

node scripts/version.mjs --write
node scripts/version.mjs --check

生成的改动记录位于 docs/releases/；派生文件清单见版本维护。

文档与后续工作

文档沿用 Firefox 仓库的分类与索引思路：根目录保留项目入口和协作约定，详细说明集中到 docs/index.md。

要做什么	从哪里开始
首次准备图传板	固件入门 → 硬件接线
使用或调试桌面端	客户端说明 → 故障排查
更新设备固件	固件维护
修改受击规则或灯带	装甲板说明
复核帧率和延迟	最新帧记录 → 延迟测量
参与开发	AGENTS.md → 开发与验证

实现状态与待验证事项分开记录：

• UDP 图传、发现订阅与桌面双模式
• 装甲板血量上报、HUD、命中反馈与录制
• USB 固件包校验、App 写入与回读
• 完成固件维护的完整实机分区切换验证
• 确认并实现比赛控制与直播提案

仓库地址

仓库已由 ESP32S3_vt 改名为 simba-rmic-2026，旧地址会重定向。SSH 地址：

git@git.simba-robotics.com:PRAM/simba-rmic-2026.git

---

1. 最新帧处理记录、功率与拥塞记录和延迟测量保留了配置、观察窗口与测量限制。历史数字不是所有部署环境的性能保证。 ↩︎