端侧具身智能网球机器人 —— 面向 AI 教育机器人的策略闭环

对应赛题： 面向智能机器人的 AIOS（高校赛题，原文见大赛官网；本仓库不转载赛题文件） 一句话： 在一台百元级开源机器人（LicheeRV Nano / AKA-00，SG2002 / CV181x）上，用自研的 StarryOS 操作系统基座跑通「摄像头 → JPEG 硬解 → 量化 ACT 推理 → 差速底盘」的端侧闭环，让机器人自己看球、跟着把球保持在画面水平中心；从数据采集、仿真生成、训练、量化到 NPU 部署，整条链路都落在几百元的硬件上、都在端侧完成。

决赛提交仓库，目录按大赛《决赛作品提交说明》组织：源码在 src/，文档在 docs/，测试与验证材料在 tests/，可复现交付物在 demo/，答辩 PPT 在 presentation/（演示视频见 §15 的网盘包），作品原创承诺书在根目录。

赛题要求、我们的理解与契合度
项目简介与应用场景
系统架构与数据流
研发历程（里程碑）
关键技术点与试错记录
主要功能
系统环境
依赖要求
构建方法
运行方法
测试方法
性能与精度数据
已知限制
未来展望
交付物与外部链接清单
第三方组件与 AI 工具使用
开源贡献与操作系统能力增强
复现手册

1. 赛题要求、我们的理解与契合度

1.1 赛题要求（要点）

按赛题《面向智能机器人的 AIOS》（基于 RK3588 / SG2002 开发板）：

维度	赛题原文要点
总体要求	把开源机器人（RK3588 / SG2002）的操作系统从 C 语言的 Linux 完整迁移到 Rust 组件化内核（如 StarryOS）；在此基础上实现或补全系统调用、文件接口、关键外设驱动（NPU / USB / UART / 摄像头等），打通基于 NPU 的推理链路，并通过内核级调度 / 内存管理优化与模型轻量化，在性能（端到端延迟、启动速度、推理帧率）、硬件资源消耗与能耗比上超越 Linux 基线。
第一阶段	在 rk3588 / sg2002 开发板上启动 Rust 组件化内核；运行开源机器人程序；NPU 加载模型并推理（”完成基本的模型加载”）。
第二阶段	完善 USB 等驱动以支持机器人机械臂的感知；实现串口驱动机械臂电机；加载模型成功拾取网球等物体。
第三阶段	对照 Linux 基线，优化内核在项目中的性能表现（模型推理效果、功耗、启动延迟等），包括启动速度、识别网球的距离 / 准确度、推理一帧所需时间、机械臂定位与抓取速度、内存消耗等。

评分角度	分值	关注点
系统架构与底层创新性	30	框架设计的合理性、对 AI 模型 / Agent 的支持、技术实现难度
可靠性与完成任务能力	30	多次移动抓取任务的稳定性与准确度
执行效率与性能开销	20	与 Linux 基线完成同样任务的执行效率对比
代码规范与开源生态贡献	20	镜像（ROM）、自动化编译脚本、设计报告、测试文档是否完整；跨平台 / 跨版本迁移潜力

1.2 我们的理解

把上面的赛题翻译成可执行的技术目标，我们理解它是四件事：

内核与驱动是地基。 赛题要的不是”某块板子上跑个 demo”，而是要一套能在 SG2002 上真正承载机器人程序的组件化内核。所以我们把力气花在板级适配 + 驱动打通上：让 WiFi、USB 主机、UVC 相机、UART、JPU（JPEG 硬解）、VDEC、NPU、ION 在 StarryOS 下全部可用，并且**不是”能跑一次”，而是”掉一次链还能自己恢复”**。
“AI 应用”必须是端侧闭环。 赛题反复强调”加载模型 → 推理 → 完成任务”，我们把它做实为相机 → NPU → 执行器的实时闭环，而不是离线跑一堆图片。
数据与模型是一条长链路。 从数据采集 / 生成、训练、导出、量化到 NPU 部署，每一环都会决定最终能不能上板；因此每一环都做成可复现的脚本 + 实测数字。
系统级优化才是真正的加分项。 真正的瓶颈往往不在算力，而在数据搬运（SD 读盘、相机出帧）与单核争用；跨层地看清”延迟”和”吞吐”两笔账，比堆参数更有价值。

1.3 与赛题的契合度（逐条对照）

赛题要求	我们做了什么	代码 / 证据位置	口径与说明
从 Linux 迁移到 Rust 组件化内核	StarryOS（上游 `tgoskits` 基线）+ 本项目板级适配	`src/os`、`src/scripts/axbuild`、`src/platforms`	内核基座来自上游开源项目，本项目的工作集中在板级使能与驱动 / 应用；不重复造内核
补全系统调用 / 文件接口	`pseudofs` 下的设备节点：`/dev/cvi-tpu0`、`/dev/cvi-usb-camera0`、`/dev/cvi_vc_dec0`、`/dev/ttyS1`、`/dev/ttyS2`、`/dev/ion`、`/dev/pinmux`	`src/os/StarryOS/kernel/src/pseudofs/dev`	每个节点都随带本机桩测试或板上验证
关键外设驱动（NPU / USB / UART / 摄像头）	aic8800 WiFi、DWC2 USB 主机（等时通道修复）、UVC 相机（帧完整性校验 + 卡死恢复）、UART1/2、JPU / VDEC、NPU、ION	`src/drivers/**`、`src/thirdparty/sg200x-bsp`	详见 §5；其中几处修的是”一次小故障就永久卡死”的硬伤
打通基于 NPU 的推理链路	ONNX → `cvimodel`（BF16 / INT8），板上 `/dev/cvi-tpu0` 前向	`src/tools/tpu`、`src/apps/starry/aka00-act-tpu`	板上 INT8 前向约 23 ms（§12）
第一阶段：内核启动 + 模型加载	交付镜像可启动；38 MiB 的 INT8 `cvimodel` 在板上加载约 10.6 s（含 ION 分配）	`tests/logs/board-act40-baseline.md`	加载时间偏长，如实记录，见 §12 / §13
第二阶段：串口驱动电机	`/dev/ttyS1` → ESP32-C3 差速底盘（AA55 协议）；`/dev/ttyS2` → ZP10S 舵机总线	`src/apps/starry/master-compe-tennis`、`src/tools/esp32_base_control`	两路串口都在初赛路线里跑通
第二阶段：USB 感知 + 拾取网球	抓取能力在初赛的 YOLO 路线里：YOLOv8n 检测网球 + 三态跟踪状态机 + 差速底盘 + ZP10S 三段式抓取动作	`src/apps/starry/master-compe-tennis`、初赛演示视频	决赛的 ACT 路线只做”把球保持在画面水平中心”的方向伺服，不带抓取。ACT 要加抓取需要真机示范数据做微调，属下一步工作（§14）。这条口径我们如实写，不混淆两条路线
第三阶段：性能优化（延迟 / 帧率 / 内存）	量化 INT8、JPU 硬解 + 1/4 硬缩放、每帧重规划、匀速控制律、单核流水线取舍分析、坏帧自愈	`src/apps/starry/aka00-*`、§5、§12	见 §12 的六档实测表
第三阶段：与 Linux 基线对比	本版未做同板 Linux 基线对比	——	许多驱动能力尚未与 Linux 对齐（相机、JPU、NPU 的路径都还在打磨），此时做对比不公平也不可信；我们只给自身实测数据，并把”与 Linux 的同板对比”列为后续工作
第三阶段：识别准确度	仿真闭环居中率 ACT 95.2% vs 专家 97.1%（同种子）；INT8 逐帧 mean\|err\| 0.0116（零偏修正后）	`src/tools/sim`、`src/tools/tpu`	是仿真指标；真机只做定性验收（能稳定识别并跟踪球）
代码规范与开源生态	目录结构按决赛要求组织；板端 app 与模型各有构建脚本、板级配置与说明；测试、日志、报告齐备	`src/tools/`、`src/os/StarryOS/configs/board/`、`tests/`、`demo/`	提交材料结构与命名对齐组委会说明

一句话总结契合度： 我们把赛题的”内核迁移 + 外设驱动 + NPU 推理链路”这三件地基活做扎实，并在”端侧 AI 应用”这一层给出了两条能上板跑通的完整路线——初赛的 YOLO + 状态机 + 抓取，与决赛的 量化 ACT + 方向伺服闭环；两条路线的能力边界（抓取 vs 只跟方向）在本文里都写清楚。

2. 项目简介与应用场景

2.1 项目简介

把”模仿学习（ACT，Action Chunking Transformer）策略”真正搬进一块单核 RISC-V + 小 NPU 的嵌入式板子，并跑成一台能自己看球转的机器人。整条链路都在端侧：板子自己抓 UVC 相机、自己硬解 JPEG、自己量化推理、自己驱动底盘；网络只用于把画面 / 结果看出去（可选）。

工作分三层，每层都能独立构建与验证：

操作系统与驱动基座（src/os、src/drivers、src/scripts/axbuild）：在 SG2002 上把 WiFi、JPU（JPEG 硬解）、VDEC、UVC 相机、TPU 设备、板级构建打通，并修掉几个会”永久卡死” 的坑。
端侧策略闭环（src/apps/starry/aka00-*）：量化 ACT 推理 + 相机输入 + 底盘控制，提供”纯机器人””带画面（MJPEG 推流）””只出数字（不推流）”三种成品形态。
数据与模型流水线（src/tools/sim、src/tools/tpu）：Three.js 纯 Web 仿真生成示范数据 → 训练 ACT → 导出 ONNX → 编成 cvimodel 部署到板子。

2.2 应用场景

AI 教育机器人：把”具身智能 + 模仿学习”放进一架百元级机器人，让学生直接改策略、改硬件、看真机效果，而不是只在仿真里跑。
端侧视觉伺服：只有单核 + 小 NPU 的低成本平台上的实时视觉闭环，整机可离线（充电宝供电）。
嵌入式 AI 部署教学：从仿真数据 → 训练 → 量化 → NPU 部署的完整链路，每步都有可复现脚本与实测数据。

3. 系统架构与数据流

3.1 三层结构

┌──────────────────────────────────────────────────────────────────────────────┐
│  数据与模型流水线（开发期，x86 主机）                                        │
│  Three.js 仿真 → 示范数据（frames/*.jpg + actions.jsonl）                    │
│      → 训练 ACT(PyTorch) → 导出 ONNX(IR 9) → TPU-MLIR → cvimodel(BF16/INT8)  │
└──────────────────────────────────────────────────────────────────────────────┘
                                   │  cvimodel + 静态 ELF + rootfs
                                   ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  端侧策略闭环（SG2002 运行态，单核 C906）                                    │
│  UVC 640x480 MJPEG ─► JPU 硬解 ─► YUV→RGB + 缩放 160x120 + 归一化            │
│        ─► NPU(INT8 cvimodel) ─► 动作块(20,2) 取第 0 拍 ─► 匀速轮速 ─► 底盘   │
└──────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  操作系统与驱动基座（StarryOS，Rust 组件化内核）                             │
│  WiFi(aic8800) · USB 主机(DWC2) · UVC 相机 · UART1/2 · JPU/VDEC · NPU · ION  │
│  板级构建 / 启动 / 出卡（upstream axbuild + 本项目板级配置）                 │
└──────────────────────────────────────────────────────────────────────────────┘

3.2 板端数据流（成品形态）

UVC 640x480 MJPEG            ← 一个循环里只抓一次
  ├─ 原始 JPEG 原样透传给 /stream 客户端（纯透传，不解码/不重编码）──► WiFi 浏览器
  └─ JPU 硬解 → YUV→RGB+缩放+归一化 160x120 → ACT(int8) → 左右轮速 → 底盘(ESP32)

同一份 JPEG 既推流又喂控制，所以浏览器里看到的就是机器人正在看的那一帧。

4. 研发历程（里程碑）

时间从初赛算起（本仓库首条提交 2026-07-24）。以下里程碑与 src/ 里的源码、 tests/ 里的日志一一对应，可逐条复核。

M1｜初赛：网球检测与抓取机器人（2026-07-24 → 07-29）

在 SG2002 上先做一条传统视觉 + 规则的完整闭环：

一键出 SD 卡镜像；C 推理源码与构建脚本；
USB 相机（UVC）支持 + UVC 相机驱动缺陷修复；
YOLOv8n 网球检测 app：JPU 硬解 → CPU resize 224×224 → NPU → 后处理 / NMS；
三态跟踪状态机（UNKNOWN / TRACKING / LOST）+ 差速底盘控制；
两路串口：/dev/ttyS1 → ESP32-C3 底盘（AA55），/dev/ttyS2 → ZP10S 舵机总线，实现三段式抓取动作；
相机 / 推理基准工具、双线程流水线实验、测试与调试工具；
UART1 时钟修正（见 §5.1，这是初赛里最”隐蔽”的一处系统级 bug）。

产出：src/apps/starry/master-compe-tennis——能检测网球、跟踪并把球抓起来的机器人。

M2｜迁移到上游基线 + 板级驱动打通（2026-09-14 → 09-19）

把 OS 基座迁到上游 tgoskits 基线，并集中啃板级驱动：

aic8800 WiFi 驱动：收发 / 加密 / 省电；
sg200x-jpu：超时自愈 + 注入标准 Huffman 表（见 §5.2）；
cvi-vdec：按实际布局解禁 4:2:2 / 4:4:4（见 §5.3）；
cvi-usb-camera：帧完整性校验与卡死恢复；
补齐 /dev/cvi-tpu0 设备节点；
ax-net 队列运行时调整；axbuild 板级构建与启动流程；
引入上游 sg200x-bsp 0.7.1 的本地 fork，修 DWC2 等时通道语义。

M3｜板端 ACT 实验台（2026-09-20 → 09-24）

为把量化 ACT 搬上板做”隔离变量”的实验台（src/apps/starry/aka00-act-tpu）：

ACT 常量与张量读写接口；
观测输入层（raw / JPEG / 摄像头 + 软解）；
自带 JPU 硬解封装（含 4:2:2 / 4:4:4）；
推理基准主程序（serial / pipeline 对照 + 分阶段计时）；
200 帧数据分片与参考值、数据集抽帧脚本；
板端日志汇总与二进制检查脚本；
六档对照入口脚本与说明（设计见 §12）。

M4｜三个成品形态（2026-09-25 → 09-29）

aka00-act-robot：摄像头 → 量化 ACT → 底盘，每帧重规划 + 匀速轮速；
aka00-act-cam：一体成品——同一份 JPEG 既推流成 MJPEG 网页，又喂推理；
aka00-act-web：推理监视——网页只看推理结果（左右轮速 + 20 拍动作块），不推流；
master-compe-tennis 决赛版（决策与状态机）+ 构建 / 测试 / 文档。

M5｜数据与模型流水线 + 配套工具（2026-09-29 → 10-04）

web-ctl：板端网页遥控 + 数据录制（(画面, 动作) 成对记录）；
esp32_base_control：ESP32-C3 双路编码电机控制器 + AA55 串口协议；
mem-probe：缓存属性 / 访存带宽对照实验；
aic8800_fw：WiFi 固件 crate；
tpu：ONNX → cvimodel 编译流水线（BF16 / INT8，含逐帧误差比对）；
ai-chat：板端 ↔ DeepSeek 桥；
sim：Three.js 纯 Web 仿真场景与示范数据生成；
sim：ACT 训练与 ONNX 导出、逐帧 BC 基线、闭环评测与诊断、sim-to-real 测试图集。

M6｜板端六档实测与交付（2026-10-05 → 10-06）

板端六档对照实验的原始日志（tests/logs/board-act40-baseline.md）；
上一代网球项目与上一代 TPU 部署复现手册（作为外部参考，见 §5.7）；
排除模型 / 数据 / 构建产物，整理决赛提交仓库。

5. 关键技术点与试错记录

这一节只写有意义的探索：哪些路走通了、哪些被证伪、结论是什么。所有数字都能在 tests/ 或 src/ 里复核。

5.1 串口：UART1 的时钟不是 25 MHz（DTS 修正）

现象： 上位机发给 ESP32 的帧，前两个字节（AA 55 帧头）正常，之后字节开始错位。
根因： SG2002/CV181x 的 UART1 实际时钟约 25.8048 MHz，而驱动在没有 clock-frequency 时回退到 25 MHz 默认值，产生约 3.2% 的波特率误差——115200 的帧跑几个字节就漂移出采样窗口。
修法： 在板级 DTS（src/os/StarryOS/configs/board/licheerv-nano-sg2002.dtb）里为 UART1 补上正确的 clock-frequency = 25,804,800，与 Linux 内核实测的 DLL=14, DLF=0 对齐，波特率回到精确的 115200。
教训： 这类”看起来像协议 bug、其实是时钟 bug”的问题，最省事的定位方式是和 Linux 侧同一寄存器的量测值对齐。

5.2 JPU：坏帧只丢一帧，而不是”永久毒死一块板”

现象： UVC 是等时传输、没有重传，丢一个微帧就把这一帧 MJPEG 截断；JPU 把码流读完还在等数据，既不上报 DONE 也不上报 ERROR（MJPEG_PIC_STATUS 的 INT_JPU_BIT_BUF_EMPTY）。旧逻辑会空转到 poll 上限，然后把解码器永久置毒——之后每一帧都直接 Poisoned → EIO，只能重启板子。
修法： 照厂商 u-boot 参考实现的语义重建一套可恢复状态机：
1. 轮询按 DONE → ERROR → BIT_BUF_EMPTY 顺序分派；
2. “位流已空且消费位计数（GBU_TT_CNT）连续 50k 次不前进“判定为截断帧；
3. 失败后做 IssueStop / CompleteStop 握手 + 软件复位，并把 DMA 缓冲回收复用；
4. 只有软复位确实没完成，才回落到隔离 + 置毒（此时那句 “reboot is required” 才成立）。
效果： 上层分别看到 EINVAL（截断）/ ETIMEDOUT（真超时），channel 不用重建；一轮 300 帧只丢个别帧、正常跑完，自愈成功时内核打印 cvi-jpu: recovered JPU after a failed decode。

5.3 VDEC ABI 层解禁任意色度布局（相机小档位可用）

现象： 320×180 / 320×240 等小档位，相机能协商上、JPU 通道也能建，但第一帧 SEND_STREAM 直接 EOPNOTSUPP（errno 95）。
根因： UVC 相机在低分辨率下给的 MJPEG 不是 4:2:0（常见是 4:2:2），而 cvi_vdec.rs 的 ABI 层把输出钉死在 PIXEL_FORMAT_YUV_PLANAR_420，布局检查直接拒了。旁证：UVC 协商把小档位的等时带宽从 1024 B/µframe 降到 128。
修法：
1. validate_layout 改为接受任何能映射成厂商 PIXEL_FORMAT_* 的平面布局；
2. frame_info 按实际布局回报 pixel_format（4:2:0→13、4:2:2→12、4:4:4→14）；
3. 缓冲按最坏情况开（4:2:2 是 2 B/px、4:4:4 是 3 B/px，只按 4:2:0 的 1.5 B/px 会先吃 StorageFull / ENOSPC）；
4. 上层 YUV→RGB 按水平 / 垂直子采样分支，色度取整按整高计算。
验证： 从板上 dump 的相机首帧 SOF 采样因子读出 0x21 = 4:2:2，据此定位根因；修复后 640×480 等档位稳定出帧。

5.4 量化 ACT 的三件事（ONNX IR、校准集、零偏）

把 PyTorch 里的 ACT 编成 cvimodel 并部署到板端，踩到三个必须处理的点：

ONNX IR 版本必须是 9。 IR 10 会被 onnx 1.14.1 的 checker 拒掉 → TPU-MLIR 的常量折叠整段跳过 → MultiheadAttention 在权重上切 Q/K/V 的 Split 漏进转换器，报 operand ...in_proj_weight not found。src/tools/sim/export_onnx.py 导出时已自动降到 9。
INT8 的校准集要贴部署分布。 “挑动作最大的帧”看着更合理，实测更差：
- 按回合均匀随机抽帧 → mean|err| 0.025，转弯帧方向一致率 87.5%；
- 每回合挑”动作最大”的帧 → 0.037，方向一致率 50%。满舵帧把激活量程撑大，反而压掉了”球在中间”那一段的分辨率。--asymmetric、 TPU-MLIR 自带的 run_calibration（含 --bc）也都试过，没用（数值逐位相同）。
INT8 有一份与画面无关的常数零偏。 实测平均 L ≈ +0.011 / R ≈ +0.039；而轮速指令本身常常只有 0.02–0.05，不扣掉就会在”球居中”的画面上凭空转弯。板上按 l -= 0.0111; r -= 0.0390 扣掉后，样本外 mean|err| 0.025 → 0.0116。

另外：**cvimodel 的 md5 每次重新构建都不一样（codegen 会把构建时间戳和 tpu-mlir 版本号写进文件）。所以校验认体积 + 逐帧误差**，别拿 md5 当身份。

5.5 单核流水线的边界：它是”延迟工具”，不是”吞吐工具”

背景： 外部参考工作里的模型大、推理长，双缓冲流水线收益明显；于是我们也照搬到板端实验里做 serial vs pipeline 对照。
实测（相机档，同一颗相机、同一个模型）：
- 串行：单帧 82.17 ms，300 帧 / 25.44 s → 11.8 fps；
- 流水线：单帧 32.02 ms（主线程），300 帧 / 27.25 s → 11.0 fps。
结论： 我们的模型前向只有 ~23 ms，数据来源（相机出帧 / SD 读盘）才是瓶颈；把”等数据”挪到另一个线程，只是把它和主线程的算力争用同一颗核——流水线收益有限，相机档里甚至略慢。单核上，流水线只有”计算长于等待”时才划算。

5.6 真机采不出示范数据 → 改用仿真造数据

背景： 本地相机出帧节奏慢、抖动大（受自动曝光影响），采不出可用于训练模仿学习策略的稳定示范；”直接采数据 → 训 ACT”这条路走不通。
做法： 用 Three.js 纯 Web 3D 仿真造数据——随机天空 / 地面噪声 / 光照 / 柱箱障碍、随机球位与机器人初始位姿，用一个”专家控制器”把球保持在画面中心，自动产出 (画面, 动作)，输出格式与真机录制同构（episode_NNN/{frames/*.jpg, actions.jsonl, meta.json}）。
踩坑：
- WebGL 必须开 preserveDrawingBuffer，否则浏览器合成一次后缓冲区被清空， toDataURL 抓到的全是空白（第一版数据集整片白图就是这个原因）；
- 球必须够近、够显眼（前方 15–80 cm、绿色带自发光），否则 160×120 观测里只剩一两个暗像素，学不到东西。

5.7 与上一代 / 外部参考工作的关系（分开说明）

在另一项比赛（全国大学生计算机系统能力大赛 OS 功能挑战赛道）里，我们做过一版基于 SD 卡预录制帧 + QEMU 基线的 ACT 推理优化：QEMU 上横评 ncnn / ONNX Runtime / tract，把 ORT + INT8 压进 256 MB 内存；板上用 ADMA2 DMA + 双缓冲把单帧从 550 ms 压到约 126 ms。

这份工作只作为”外部参考 / 对照”出现，不属于本次作品的开发历程（它的输入是预先录好的数据集，不接摄像头、不做实时闭环）。它的数字仅在 §12.3 与我们的端到端链路做横向参考。

6. 主要功能

功能	位置	说明
端侧策略闭环	`src/apps/starry/aka00-act-robot`	摄像头 → 量化 ACT → 差速底盘，每帧重规划
一体成品（带画面）	`src/apps/starry/aka00-act-cam`	同一份 JPEG 既透传成 MJPEG 网页，又喂推理
推理监视（无画面）	`src/apps/starry/aka00-act-web`	网页只看推理结果（左右轮速 + 20 拍动作块），不推流；可在网页上实时调轮速
板端对照实验	`src/apps/starry/aka00-act-tpu`	六档对照（bf16/int8 × raw/jpeg/相机 × 串行/流水线），分阶段计时
初赛网球抓取 app	`src/apps/starry/master-compe-tennis`	YOLO 检测 + 三态跟踪状态机 + 差速底盘 + ZP10S 舵机抓取
网页遥控 + 录制	`src/tools/web-ctl`	板子自己当 Web 服务器；遥控、看画面、把 (画面, 动作) 录成数据集
仿真与训练	`src/tools/sim`	Three.js 仿真生成示范；训练逐帧 BC 与 ACT；闭环评测
模型编译	`src/tools/tpu`	ONNX → `cvimodel`（BF16/INT8），含逐帧误差比对
底盘固件	`src/tools/esp32_base_control`	ESP32-C3 双路编码电机控制器 + AA55 串口协议
配套小工具	`src/tools/{mem-probe,ai-chat,qperf,tennis,tpu-docs,aic8800_fw}`	缓存 / 访存带宽对照、板端大模型桥、perf 采集、上一代网球参考、上一代 TPU 手册、WiFi 固件 crate

7. 系统环境

项	内容
板卡	LicheeRV Nano / AKA-00（SG2002 / CV181x，RISC-V C906 大核 + C906L 小核，256 MB DRAM）
操作系统	StarryOS（Rust 组件化内核，基于上游 `tgoskits` 基线，本项目做板级适配）
加速器	CV181x NPU（`/dev/cvi-tpu0`）、JPU/VDEC（JPEG 硬解，`/dev/cvi_vc_dec0`）、UVC 相机（`/dev/cvi-usb-camera0`）
执行机构	ESP32-C3 双路编码电机控制器（`/dev/ttyS1`，AA55 协议）；ZP10S 舵机总线（`/dev/ttyS2`，初赛抓取用）
无线	aic8800（WiFi，凭据编译进内核）
交叉工具链	Xuantie-900 GCC 14.3.0（musl）+ 预编译 SG200x SDK

8. 依赖要求

构建镜像（宿主机）：Docker（docker context 用 default），容器用 ghcr.io/rcore-os/tgoskits-container:latest（内含 RISC-V 交叉工具链）；宿主需要 mkimage dumpimage dtc sfdisk mformat mcopy mmd。

交叉编译板端 app：Xuantie-900 GCC + 预编译 SG200x SDK，在 src/apps/starry/aka00-tennis-yolo/ 下按它的 scripts/setup.sh 安装。

编译模型：只用官方 sophgo/tpuc_dev 镜像，tpu_mlir 装在挂载卷的 venv 里。

仿真与训练：Node（headless Chromium / Playwright）跑仿真，Python + PyTorch 训练，详见 src/tools/sim/README.md。

组装 SD 卡镜像：内核由上游 axbuild + 本项目板级配置（src/os/StarryOS/configs/board/、 src/apps/starry/*/board-aka-00-sg2002.toml）出，再与基线 rootfs、厂商 fip.bin 一起打成 SD 卡镜像；rootfs 与 fip.bin 随 SG200x SDK 获取。评审可直接烧写 demo/ 提供的成品镜像，跳过这一步。

大文件（不进仓库，走网盘）：交付镜像、INT8 模型、数据集；清单见 §15。

9. 构建方法

# 1) 交叉编译板端 app（仓库内直接可跑，需要 Xuantie-900 GCC + 预置 SG200x SDK）
cd src/apps/starry/aka00-act-web && make

# 2) ONNX → cvimodel（只用官方 sophgo/tpuc_dev 镜像）
./src/tools/tpu/build_cvimodel.sh

# 3) 组装 SD 卡镜像（内核 + rootfs + /actexp /robot /cam /web）：内核来自上游 axbuild，
#    再与基线 rootfs、厂商 fip.bin 打包；需要厂商 fip.bin 与基线 rootfs。
#    评审可直接烧写 demo/ 提供的成品镜像，跳过这一步。

10. 运行方法

# 烧卡（镜像下载见 §15）
sudo dd if=sg2002_act.img of=/dev/sdX bs=4M status=progress conv=fsync && sync

# 板上：镜像开机自启推理监视（轮子先按住）
cd /web && ./run.sh          # 串口会打 http://<板子IP>/
# 浏览器打开 → 看到左右轮速与 20 拍动作块 → 按「开始」才驱动

# 想跑带画面的版本
cd /cam && ./run.sh          # http://<板子IP>/ 直接看 MJPEG 画面

11. 测试方法

# 板端 app 的本机桩测试（不需要板子）
cd src/apps/starry/aka00-act-web && ./test/http_test.sh
cd src/apps/starry/aka00-act-cam && ./test/http_test.sh

# 板上对照实验：/actexp/run_1..run_6，日志喂 scripts/summarize.py 出报告
# （原始日志已整理到 tests/logs/，见 §12）

# 模型逐帧误差：src/tools/tpu/eval_cvimodel.py
# 闭环评测（仿真里与专家同种子对比）：cd src/tools/sim && node eval_policy.mjs

详细索引见 tests/README.md。

12. 性能与精度数据

口径说明： 本节板端数字以 tests/logs/board-act40-baseline.md（原始串口日志 tests/logs/board-act40-baseline.raw.txt）为准。注意 SD 卡存在周期性停顿（实测每约 10 帧出现一次 ~270–290 ms 的读盘尖峰），因此 read 的均值会被尖峰拉高；同时”单帧”（主线程一次迭代）与”整段吞吐”是两笔不同的账。我们两个都列，避免用一个数字掩盖另一个。

12.1 模型与量化精度

模型：ACT40，约 40.9 M 参数，输入 [1,3,120,160]（160×120 观测），输出 [1,20,2]（20 拍动作块）。

量化	体积	ONNX(fp32) ↔ cvimodel	转弯帧方向一致率
BF16	79 972 256 B（≈76 MiB）	max\|err\| 0.0098、mean\|err\| 0.0023、cos 0.99998	100%
INT8	40 283 920 B（≈38 MiB）	max\|err\| 0.106、mean\|err\| 0.025	87.5%
INT8 + 零偏修正	同上	max\|err\| 0.072、mean\|err\| 0.0116	87.5%

交付版用 INT8 + 零偏修正。逐帧比对工具：src/tools/tpu/eval_cvimodel.py。

12.2 板端六档对照（相机 / 解码 / 流水线）

六档的设计是每档只比上一档多一个变量（1→2 量化、2→3 双缓冲、4→5 解码器、5→6 输入源）：

档	输入	模式	N	read 均值(p50/p90) ms	prep 均值 ms	feed 均值 ms	tpu 均值(p50/p90) ms	单帧均值 ms	整段	吞吐
2	int8 + raw	串行	200	27.68 (0.48/1.07)	0.00	3.24	23.04 (23.03/23.25)	53.98	11282.1 ms	17.7 fps
3	int8 + raw	流水线	200	28.35 (0.47/2.29)	0.00	3.41	23.09 (23.04/23.39)	26.52	11015.1 ms	18.2 fps
4	int8 + jpeg 软解	流水线	300	24.59 (24.05/28.62)	44.65	5.53	23.40 (23.27/24.10)	28.96	14101.7 ms	21.3 fps
5	int8 + jpeg JPU	流水线	300	27.48 (28.48/32.95)	12.16	7.55	23.77 (23.59/24.77)	31.36	8201.0 ms	36.6 fps
6	int8 + 相机 + JPU	流水线	300	71.57 (63.65/104.05)	15.07	8.86	23.14 (22.37/27.08)	32.02	27252.9 ms	11.0 fps
6’	int8 + 相机 + JPU	串行（对照）	300	40.91 (38.31/57.73)	14.98	3.31	22.95 (22.91/23.19)	82.17	25442.9 ms	11.8 fps

读表要点：

NPU 前向稳定在 ~23 ms，与输入源、解码器、串并行都无关——它已经是”快的那一环”。
解码器换代（档 4 → 5）把预处理从 44.65 ms 降到 12.16 ms，是六档里最明显的一处系统级收益。
单帧 ≠ 吞吐：档 3 单帧只有 26.52 ms，整段却要 11 s（18.2 fps）——因为 SD 卡的周期性停顿被 reader 线程吸收，不进”单帧”，但进”整段”。
相机档串行（11.8 fps）略快于流水线（11.0 fps）：模型太短，流水线收益有限（§5.5）。

档 1（bf16 + raw 串行）的脚本在仓库里（run_1_bf16_serial.sh），但本次日志未包含它的板端分档数字；BF16 的精度见 §12.1。模型加载 6 次实测 10.54–10.63 s（38 MiB cvimodel，含 ION 分配）。

12.3 与外部参考工作的横向参考

方案	输入	单帧 / 前向	说明
本作品（决赛 ACT 端侧闭环）	实时相机	前向 ~23 ms；相机档端到端 11–12 fps	本文主线
本作品（初赛 YOLO + 状态机 + 抓取）	实时相机	（定性）规则化、可预测；带抓取动作	传统视觉路线，稳定性来自手工规则
外部参考（另一项比赛的 ACT 推理优化）	SD 卡预录帧	BF16 前向 ~86 ms；单帧 109–145 ms	输入非实时、不接相机；仅作横向参考

赛题要求”与 Linux 基线对比”，本版未做同板对比（驱动能力尚未对齐，见 §1.3）。

12.4 闭环效果（仿真，同种子对比）

策略	居中率	平均画面偏移
ACT（本项目）	95.2%	0.031
专家控制器	97.1%	0.013
逐帧 BC 基线	94.1%	0.034

这些数字来自多轮数据 / 场景设计迭代（不同结构的数据集），不是同一次受控对比；早期的数据 / 场景设计下居中率低得多，说明”数据与场景设计”才是策略能不能学的关键。真机验证为定性：烧录交付镜像、网页按「开始」后，机器人能稳定识别并跟踪球。

13. 已知限制

单核：SG2002 只有一个大核。瓶颈是数据来源（SD 读盘的周期性停顿、相机出帧节奏）与单核争用，而不是 NPU 前向；流水线收益因此有限（§5.5）。
控制台键盘：发起 WiFi 连接后串口键盘会失效（根因未修）。所以交付镜像把入口做成 开机自启的网页（带「开始 / 停止」手刹），这也正是”能在手机上看图 / 操作”的意义。
模型偏置：INT8 模型在”球居中”时仍输出约 +0.18 的轮速，目前用死区压掉；彻底修需要真实帧上做微调（sim-to-real）。
未做 Linux 基线对比：许多驱动能力尚未与 Linux 对齐（§1.3）。
抓取不在决赛路线：ACT 只做方向伺服；抓取能力在初赛的 YOLO 路线里（§1.3）。
模型加载偏慢：38 MiB 的 cvimodel 在板上加载约 10.6 s（含 ION 分配）。
相机档精度不可比：档 6 的帧不是数据集里那批画面，只看端到端时间与帧率。

14. 未来展望

ACT 接上抓取：当前 ACT 只输出”怎么转”；要加抓取，需要用真机示范数据对策略做微调，让它同时输出底盘与舵机动作——这是最直接的下一步。
sim-to-real 微调：用真机录制帧对仿真训出的策略做小幅微调，压掉”球居中时的小偏置”。
与 Linux 的同板对比：等相机 / JPU / NPU 的驱动能力对齐后，在同一块板上做端到端延迟、帧率、CPU 占用、内存的公平对比。

15. 交付物与外部链接清单

15.1 仓库内交付物

类别	路径
源代码	`src/`
提交文档（四份 PDF）	`docs/`
测试与验证材料	`tests/`
可复现交付物说明	`demo/`
答辩 PPT / 决赛演示视频	`presentation/`
作品原创承诺书	`作品原创承诺书.pdf`（根目录）

15.2 演示材料（成片在 `presentation/`，其余走网盘）

大赛要求的决赛成片 presentation/决赛演示视频.mp4 在本目录保留一份；其余演示视频与 PPT 整页设计原图作为 presentation/ 的网盘包上传，见 presentation/README.md：

视频	内容	文件
决赛演示视频	左侧是车、右侧是 `/web` 推理监视仪表盘（左右轮意图、20 拍动作块、帧率 / 推理耗时、轮速滑杆），左右同步（21.4 s，1920×1080，大赛要求的成片）	`决赛演示视频.mp4`
ACT 推理小车结果	机器人自己看球、转向（21 s，1920×1080，只有车与地面，无仪表盘叠加）	`act推理小车.mp4`
初赛 YOLO 夹取	初赛路线：YOLOv8n 网球检测 + 三态跟踪状态机 + ZP10S 舵机三段式抓取（85 s，720×1280 竖屏）	`初赛yolo夹取.mp4`
初赛讲解（补充材料）	11 分钟讲解视频（1920×1080）	`讲解视频.mp4`

备注： act小车_控制台对照.mov 与 决赛演示视频.mp4 是同一段内容（车 + 控制台对照），保留其一即可。

15.3 网盘包（按目录打包，大文件不进 Git）

大文件不进 Git（大赛禁用 Git LFS），按目录各打一个包：

压缩包	内容	大小（压前 → 压后）	链接
`demo-deliverables.zip`	`sg2002_act.img` + `act40_int8/bf16.cvimodel` + `datasets/`	4.8 GB → 3.1 GB	百度网盘提取码 `88rv`
`presentation-material.zip`	5 段演示视频 + 10 张 PPT 整页设计	206 MB → 185 MB	百度网盘提取码 `d8pw`

两个包解压后各自是一个同名目录（demo-deliverables/、presentation-material/），放进对应目录即可对上文中所有相对路径。说明书与 PPT 用的插图不需要额外的网盘包：它们已直接嵌在四份 PDF 与 答辩PPT.pptx 里。

各包的清单、md5 与用法分别见 demo/README.md 与 presentation/README.md。

16. 第三方组件与 AI 工具使用

第三方代码 / 模型 / 数据与许可证、以及生成式 AI / 代码补全 / 检索等工具的使用情况，逐项列于 docs/人工智能及第三方工具使用说明.pdf。摘要：

stb_image v2.30（public domain / MIT）——JPEG 软件解码（对照路线）；
sg200x-bsp 0.7.1（MIT）的本地 fork——仅改动 DWC2 等时通道一处；
Ultralytics YOLOv8 网球检测 cvimodel（来源 BattiestStone4/akars）——传统视觉对照路线；
Three.js（MIT）/ Playwright（Apache-2.0）/ PyTorch（BSD-3）等为开发期依赖，未随作品分发；
厂商工具链与运行时（Xuantie GCC、SG200x SDK、cviruntime）以依赖形式由安装脚本获取。

17. 开源贡献与操作系统能力增强

本作品的操作系统基座是上游 tgoskits（StarryOS）。板级适配中遇到的问题基本都落在驱动与板级配置里，我们就在那一层修，并把可复用的部分回馈上游。下面三组工作都在 src/ 里可以直接对照。

17.1 串口：修正板级设备树的 UART1 输入时钟，打通底盘通信

现象：底盘（ESP32-C3）挂在 UART1（/dev/ttyS1）。初赛阶段 TX 方向帧头 AA 55 之后字节开始错位、RX 方向一个字节都收不到；而同一块板子刷 Linux 时 UART1 收发正常—— 这个对照把问题从”接线 / 电平”一步推到系统侧。
根因：UART1 的输入时钟约 25.8 MHz，而 DW APB UART 驱动在 DTB 缺 clock-frequency 时回退到 25 MHz 常量，约 3.2% 的波特率误差让每帧跑几个字节就漂出采样窗口；另外 UART1 的 TX/RX 复用在 JTAG_CPU_TMS / JTAG_CPU_TCK 上，需要单独配置引脚复用。
修法：在板级设备树（src/os/StarryOS/configs/board/aka-00-sg2002.dtb、 licheerv-nano-sg2002.dtb）的 UART1 节点补上正确的 clock-frequency，驱动侧 src/drivers/ax-driver/src/serial/ns16550.rs 优先读取 DTB 的值；引脚复用经 /dev/pinmux 配置（0x64 / 0x68 写 6）；用户态串口统一用 O_NONBLOCK + VMIN=0 + VTIME=0 轮询。
回馈上游：该修复作为 PR #1714 **合并进上游 main**；同一轮里上游对 UART 中断调度的重构（PR #1675）也消除了旧基线上 “非 console UART 收不到 RX 中断”的问题。
验证：UART1 连发 1280 字节（00..FF 循环 5 遍）零错误、接收 256 字节准确率 99.6%；与 ESP32 底盘的握手 INIT → ACK → CONFIG → ACK → SET_SPEEDS 全部通过、电机按指令转动。

17.2 WiFi：把板载 AIC8800D80 的整条链路做通

板载网卡是 SDIO full-MAC 架构：扫描、认证、关联与四步握手的中继都由固件完成，主机侧必须自己组装 sm_connect_req（含 RSN IE）、从 M1 推导 PMK/PTK、校验 M2/M3 的 MIC、计算 M4 的 MIC，再自己安装 PTK/GTK——**任何一环缺失，外观上都只是”连不上”**。我们在 src/drivers/net/aic8800/ 上补齐了这些环节：

信道计划：在 2.4 GHz 的 14 个信道之外补齐 25 个 5 GHz 信道；
连接请求：修正 sm_connect_req 的 BSSID 偏移（33；写成 34 会让通配地址变成 00:ff:ff:ff:ff:ff，表现为”换一个 AP 就连不上”）；
WPA2 握手：实现 AES-128-CMAC（带 RFC 4493 KAT 测试向量）；密钥描述符版本从 M1 读出后钉住整个握手、比较时先掩掉版本位；构造 RSN IE；PMF 声明 MFPC、不声明 MFPR；在混合模式 AP 下让 TKIP 组密钥（32 B GTK）与 CCMP 单播共存；
熵源：PMK 派生需要无偏随机源，驱动拿不到就拒绝启动——板级构建把 32 字节 seed 烘焙进设备树的 /chosen/rng-seed；
固件与总线：SDIO 枚举与固件加载，每个 blob 按 pinned SHA-256 逐字节校验，并支持本地缓存目录；
健壮性与省电：认证 / 关联被拒（reason=15）时用同一套件重发整轮连接（最多 3 次）；保持厂商默认的省电策略——关掉后 SDIO 电平型中断会把同核的 UART RX 饿死，串口键盘失效。

验证：WPA/WPA2 混合模式 AP 与纯 CCMP 手机热点都跑通——完成关联与四步握手、安装密钥、拿到 DHCP 租约、ARP 连通，板上自带的网页服务（web-ctl / /web）可访问。

17.3 其它驱动与系统能力增强

方向	做了什么	代码位置
JPU（JPEG 硬解）	重建可恢复状态机：`BIT_BUF_EMPTY` 已置位且消费位计数不前进即判为截断帧，失败后 STOP 握手 + 软复位并回收 DMA 缓冲——坏帧只丢一帧，不再”一次丢微帧永久毒死解码器”（§5.2）	`src/drivers/vpu/sg200x-jpu/`
VDEC	ABI 层接受任意色度布局（4:2:0 / 4:2:2 / 4:4:4）并按实际布局回报 `pixel_format`，缓冲按最坏情况开——相机小档位（UVC 低分辨率常给 4:2:2）因此可用（§5.3）	`src/os/StarryOS/kernel/src/pseudofs/dev/cvi_vdec.rs`
UVC 相机	帧完整性校验与卡死自动重挂	`src/os/StarryOS/kernel/src/pseudofs/dev/cvi_usb_camera.rs`
USB 主机	DWC2 等时通道语义修复：非 split 周期通道不软件 halt，等核心在帧边界释放，修掉”一次丢微帧就永久卡死”	`src/thirdparty/sg200x-bsp`（本地 fork）
设备节点	补齐 `/dev/cvi-tpu0`、`/dev/cvi-usb-camera0`、`/dev/cvi_vc_dec0`、`/dev/ttyS1`、`/dev/ttyS2`、`/dev/ion`、`/dev/pinmux`	`src/os/StarryOS/kernel/src/pseudofs/dev/`
板级构建与启动	板级构建配置与 SD 卡启动链（DTB / `.its` / 启动参数），使内核能出卡并在真机启动	`src/os/StarryOS/configs/board/`、`src/scripts/axbuild/`

以上改动均在 src/ 内，可逐条对照；其中 UART1 时钟修复已合并进上游 main（PR #1714）。

18. 复现手册

照着做就能重现。最快的是 A（直接用成品镜像，不编译任何东西，也是评审口径）； B 从源码重建板端程序与模型；C 复核测试与实验数据。每一步都给出期望结果，对不上时先看 §18.5。

18.0 需要什么

项	规格 / 说明
板卡	LicheeRV Nano / AKA-00（SG2002 / CV181x，RISC-V C906，256 MB DRAM）
相机	UVC（USB）摄像头，支持 640×480 MJPEG
底盘（可选）	ESP32-C3 双路编码电机控制器，接板子的 `/dev/ttyS1`；不接也能跑（只推流 / 只出数字）
SD 卡与读卡器	≥ 4 GB（镜像 2 576 351 232 B）
串口	115200 8N1；进系统后提示符是 `root@starry:/root #`
宿主机	A 只要 Linux + `dd` + 浏览器；B 还要 Docker 与 Xuantie-900 GCC + SG200x TPU SDK（`src/apps/starry/aka00-tennis-yolo/scripts/setup.sh` 自动下载并校验 SHA-256）；C 的仿真评测还要 Node + Playwright

18.1 A. 直接跑成品（最快，评审口径）

# 1) 从 §15.3 的 demo-deliverables.zip 取 sg2002_act.img，先核对体积与 md5
ls -l sg2002_act.img                      # 2 576 351 232 B
md5sum sg2002_act.img                     # d139bc11011b2e0c1aa0541faca79ddc

# 2) 烧写并回读校验
sudo dd if=sg2002_act.img of=/dev/sdX bs=4M status=progress conv=fsync && sync
sudo head -c 2576351232 /dev/sdX | md5sum  # 应等于上面那个 md5

上电：串口会打印 http://<板子IP>/；镜像开机自启 /web（推理监视，不推流画面），而且带 --start-paused——相机与推理照跑，轮子是按住的。
浏览器打开该地址，页面上是纯数字仪表盘：左 / 右轮意图、20 拍动作块、帧率、丢帧、推理耗时、相机与底盘状态、轮速滑杆。按「开始」才驱动（串口键盘用不了时这就是手刹）。
期望：球在画面里移动时左右轮速随之翻转，机器人转向把球带回画面水平中心；按「停止」立即停车。想看实时画面：cd /cam && ./run.sh（会接管相机，见 §18.5）。
想跑板端对照实验：cd /actexp && ./run_1_bf16_serial.sh … ./run_6_int8_camera_jpu.sh，日志用 ./scripts/summarize.py 汇总，或直接对照 tests/logs/board-act40-baseline.md。

18.2 B. 从源码重建

以下命令都从仓库根目录开始：

# 1) 编译板端 app（Xuantie-900 GCC + SG200x SDK 由 setup.sh 装好）
cd src/apps/starry/aka00-tennis-yolo && ./scripts/setup.sh     # 只需一次
cd ../aka00-act-web && make            # → act_web，静态 RISC-V ELF ≈3.2 MB
cd ../aka00-act-cam && make            # → act_cam   同理；/robot、/tpu 的 app 各自 make
cd "$(git rev-parse --show-toplevel)"  # 回到仓库根目录

# 2) 编模型（只用官方 sophgo/tpuc_dev 镜像，ONNX 取自数据集包的 datasets/sim-5/）
./src/tools/tpu/build_cvimodel.sh                       # BF16（默认编完在 20 帧上比对 ONNX ↔ cvimodel）
./src/tools/tpu/build_cvimodel.sh -q INT8               # INT8（同上，--eval-num 0 可关掉比对）

# 3) 组装 SD 卡镜像：内核来自上游 axbuild + 本项目板级配置，再与基线 rootfs、
#    厂商 fip.bin 打包（详见 §8 / §9）。评审可直接用 A 的成品镜像跳过这一步。

18.3 C. 跑测试与实验

以下命令同样从仓库根目录开始。

本机桩测试（不需要板子，用桩相机 / 桩 JPU / 桩底盘 / 桩 CVRuntime 顶替）

cd src/apps/starry/aka00-act-web && ./test/http_test.sh   # 期望末行 ALL PASSED
cd ../aka00-act-cam             && ./test/http_test.sh   # 期望末行 ALL PASSED

覆盖：页面为纯数字（无 <img> / 无 /stream）、/status 的左右轮速与 20 拍动作块、 /go 与 /stop、--start-paused 不驱动、/speed?v=N 实时改速、第二个流客户端返回 503、 首帧与源 JPEG 逐字节一致。前置条件是 §18.0 里那份 TPU SDK（setup.sh 装好即可）。

模型逐帧误差（宿主机，需要 §18.1 的 ONNX 与编出来的 cvimodel）

build_cvimodel.sh 编完就会自动比对一次（报绝对误差、余弦与转弯帧方向一致率）。要单独重跑，在 TPU-MLIR 容器里执行（cvimodel 需要 model_runner + cmodel 模拟器）：

python3 src/tools/tpu/eval_cvimodel.py \
    --onnx    src/tools/tpu/build/act40.onnx \
    --cvimodel src/tools/tpu/build/act40_int8.cvimodel \
    --dataset <解压后的数据集>/datasets/sim-5 --num 20

仿真闭环评测（宿主机）：策略通过 HTTP 暴露给 Node 侧的评测脚本，跑同一批种子与专家对比。

cd src/tools/sim
npm install                                            # playwright + three（只需一次）
python3 -m venv .venv && .venv/bin/pip install torch numpy pillow   # 只需一次
.venv/bin/python policy_server.py \
    --model <解压后的数据集>/datasets/sim-5/act.pt --act --port 9300 &
node eval_policy.mjs --episodes 10 --steps 120 --policy http://127.0.0.1:9300

policy_server.py --model 指向训练好的权重：ACT 用 datasets/sim-5/act.pt（加 --act），逐帧 BC 基线用 datasets/sim-4/policy.pt。两个权重都在 demo-deliverables.zip 里，把 <解压后的数据集> 换成解压出来的 datasets/ 路径即可。

18.4 期望值速查（对不上就是环境或版本问题）

步骤	期望	出处
成品镜像	2 576 351 232 B，md5 `d139bc11011b2e0c1aa0541faca79ddc`	`demo/README.md`
模型体积 / 精度	INT8 40 283 920 B（mean\|err\| 0.025 → 零偏修正 0.0116）；BF16 79 972 256 B（max\|err\| 0.0098、cos 0.99998）	§12.1、`demo/README.md`
本机桩测试	两条命令末行都是 `ALL PASSED`	`src/apps/starry/aka00-*/test/http_test.sh`
NPU 前向	22.4–23.8 ms（与输入源 / 解码器 / 串并行无关）	`tests/logs/board-act40-baseline.md`
解码器收益（档 4 → 5）	预处理 44.65 ms → 12.16 ms	同上
相机档单帧 / 吞吐	串行 82.17 ms / 11.8 fps；流水线 32.02 ms（主线程）/ 11.0 fps	同上
模型加载	38 MiB cvimodel 约 10.5–10.6 s（含 ION 分配）	同上
仿真闭环居中率	ACT 95.2% / 专家 97.1% / 逐帧 BC 94.1%（同种子对比）	`src/tools/sim/eval_policy.mjs`

18.5 常见问题

现象	原因与处理
网页打得开但相机没画面 / `/cam` 起不来	`/dev/cvi-usb-camera0` 是独占的：`/web`（自启）与 `/cam` 一次只能跑一个，先停一个再启另一个
串口能看不能敲	发起 WiFi 连接后控制台键盘会失效（根因未修）。所以入口做成开机自启的网页，用网页上的「开始 / 停止」操作
换一个 AP 就连不上	WiFi 凭据是编译期内嵌的，换 AP 要按 §9 重出镜像（`--ssid` / `--password` / `--cipher`）
重编的 cvimodel md5 与文档不同	正常：codegen 会写进构建时间戳。校验请认体积 + 逐帧误差（§12.1）
没有接底盘	程序自动转”干跑”：照常取帧、推理、推流，只是不下发轮速；`--no-chassis` 可显式指定
相机偶发卡死	驱动已做帧完整性校验与重挂：坏帧只丢一帧；连续失败会重开设备