面向智能机器人的 AIOS：网球拾取机器人（高校赛题）

团队

YPWsys.

项目简介

把一台网球拾取机器人的操作系统内核，从 C 语言的 Linux 迁移到 Rust 组件化内核 StarryOS，并在 Sophgo SG2002 开发板上补齐摄像头、串口、TPU 推理等关键链路，完成「视觉识别 → 底盘追踪 → 机械臂抓取」的闭环。感知与控制都跑在这一颗 SoC 上，不依赖上位机。

SG2002 是异构双核 RISC-V SoC：大核 C906B（1 GHz，S-mode）运行 StarryOS，小核 C906L（700 MHz，M-mode）运行自研 Rust 裸机采集固件，两核通过共享 DRAM、硬件邮箱与 PLIC 中断协同。检测模型为 YOLOv8n 单类网球，mAP50 87.6%， INT8 量化后约 3.3 MB，运行于板载 TPU。

指标	迁移/优化前	现在
用户态视觉闭环	约 3.7 fps	27.5 fps
摄像头采集	9.3 fps	60.0 fps
系统启动	12.52 s	5.10 s
rsext4 mkfs	46.31 s	0.405 s
文件写入（iozone 四进程初始写）	Linux 的 0.9%	Linux 的 59.3%

全部数字为真机实测，测量方式与原始数据见 tests/ 与 docs/comp-docs/。

应用场景

网球场自动捡球机器人：在场地上自主搜寻网球、追球、对准并抓取，替代人工捡球，可长时间连续工作；
嵌入式视觉 AIOS 参考实现：为「单颗异构双核 SoC 上跑完整感知—决策—控制闭环」提供一套 Rust 组件化内核的落地范例（跨核设备、硬件编解码、TPU 推理、实时串口控制的系统集成方式）；
教学与二次开发：分层文档 + 全套实测数据 + 可复现实验，可作为操作系统竞赛/课程中驱动、文件系统、异构通信方向的工程教材。

主要功能

跨核摄像头采集子系统：小核裸机固件完成 USB UVC 抓帧与 JPU 硬件解码，帧数据经共享 DRAM 由大核用户态 mmap 零拷贝读取（/dev/cvi-usb-camera0、 /dev/cvi-yuv），硬件邮箱 + PLIC 双向中断做核间同步；
TPU 目标检测：YOLOv8n INT8 量化模型推理 + NMS 后处理，单类网球检测；
机器人控制闭环：追球/对准/抓取状态机，串口协议驱动底盘电机（/dev/ttyS3）与 ZP10D 机械臂（/dev/ttyS2）；
存储 I/O 优化：SD 驱动多块传输 + ADMA2 + 中断 + 时钟调优，rsext4 文件系统三轮低 IOPS 优化与写死锁修复；
离线自检与调试：akars detect 单图推理验证模型/TPU 链路；akars serve 内置 Web 遥控前端（支持 --mock 无硬件运行）；
模型训练与部署链路：数据集训练 → tpu-mlir 量化转换 → cvimodel 上板。

系统环境

目标硬件

部件	规格
SoC	Sophgo SG2002（RISC-V 双核：C906B 1 GHz @S-mode + C906L 700 MHz @M-mode）
开发板	LicheeRV Nano（SG2002）及 AKA-00 机器人底盘
摄像头	USB UVC 摄像头，640×480 MJPEG
执行器	串口底盘电机 + ZP10D 六自由度机械臂
加速器	板载 TPU（CVI runtime）、JPU 硬件 JPEG 编解码
存储	SD 卡（FAT32 引导分区 + ext4 rootfs）

软件栈：大核 OpenSBI + U-Boot → StarryOS（Rust 组件化内核，musl 用户态）；小核 Rust 裸机固件（no_std，无操作系统）。

开发主机：Linux x86_64，需网络（首次构建下载工具链与 crates）。

依赖要求

Rust（rustup 安装，含 riscv64gc-unknown-linux-musl 等目标；各子目录的 rust-toolchain.toml 会自动切换）；
riscv64-linux-musl-cross 交叉工具链（内核构建时需在 PATH 中）；
玄铁 C906 GCC 工具链 V3.4.0（src/akars/scripts/setup.sh 自动下载并校验 SHA-256，也支持离线 --archive 安装）；
TPU SDK（作为 src/akars 的 submodule 自动获取）；
Python ≥3.10（模型训练/量化：src/tennis-train/requirements.txt）；
tpu-mlir 工具链（cvimodel 转换，仅在重新生成模型时需要）；
测试工具：iozone（存储对比）、cargo test（单元测试与 rsext4 回归）。

仓库结构

├── README.md                 本文件
├── src/                      项目源代码（git submodule）
│   ├── tgoskits/             StarryOS 内核：跨核设备节点、SD 块设备与 rsext4 优化
│   ├── sg200x-bare-metal/    C906L 小核裸机固件：USB 采集、JPU 解码、跨核交付
│   ├── sg200x-bsp/           SG2002 板级支持包：JPU、IVE、DWC2、pinmux 等 no_std 驱动
│   ├── akars/                机器人主控（用户态 Rust）：取帧、TPU 推理、电机与机械臂、状态机
│   └── tennis-train/         网球检测模型的训练、量化与 cvimodel 转换
├── docs/
│   ├── 项目说明书.pdf / 项目创新说明.pdf / 成员分工及主要贡献说明.pdf
│   ├── 人工智能及第三方工具使用说明.pdf
│   ├── 编译说明.md           逐组件复现的构建/烧录步骤
│   └── comp-docs/            13+ 篇设计报告（架构、优化历程、测试方法、失败案例）
├── tests/                    测试及验证材料（单元测试入口 + 11 组真机实验原始数据）
├── demo/                     可运行交付物（启动脚本、量化模型、离线自检脚本）
├── presentation/             决赛现场演示 PPT 与演示视频
└── 作品原创承诺书.pdf

首次克隆后请初始化子模块：

git submodule update --init --recursive

构建方法

各组件的完整构建与烧录步骤见 docs/编译说明.md，要点如下。

1）StarryOS 内核（大核）

cd src/tgoskits
cargo starry defconfig licheerv-nano-sg2002
cargo starry build
# 产物 target/riscv64gc-unknown-linux-musl/release/starryos.uimg
# 配套 dtb：os/StarryOS/configs/board/licheerv-nano-sg2002.dtb

2）小核裸机采集固件

cd src/sg200x-bare-metal
make build    # 产物 cvirtos.bin，入口 0x8FE00000

3）用户态主控 akars

cd src/akars
scripts/setup.sh    # 安装目标、TPU SDK submodule、玄铁工具链（一次）
scripts/build.sh    # 产物 target/.../release/akars
scripts/upload.sh /dev/sdX2   # 写入 SD 卡 rootfs 分区

4）检测模型（仅在需要重新训练/量化时）

cd src/tennis-train
python -m src.tennis_train.train --model yolov8n.pt --data configs/tennis_ball.yaml --epochs 100
# 量化与 cvimodel 转换命令见 src/tennis-train/docs/project_summary.md

运行方法

方式一：烧录整卡镜像（推荐）

下载 disk.img（见下文「系统镜像下载」）；
烧录 SD 卡：dd if=disk.img of=/dev/sdX bs=4M status=progress oflag=sync；

SD 卡装入机器人，上电进入 StarryOS shell 后执行：

./run.sh    # 即 demo/run.sh：取帧 → TPU 推理 → 追球 → 抓取

方式二：手动组装启动（自行构建时，详见 docs/编译说明.md）

SD 卡第一个分区 FAT32 放 fip.bin（OpenSBI+U-Boot）、starryos.uimg、dtb；第二个分区 mkfs.ext4（-b 4096 -O ^orphan_file）作 rootfs。U-Boot 中：

load mmc 0:1 0x82200000 starryos.uimg
load mmc 0:1 0x83000000 licheerv-nano-sg2002.dtb
bootm 0x82200000 - 0x83000000

辅助运行：demo/detect-check.sh 离线验证 TPU 检测（无需摄像头/电机）； akars serve --listen 0.0.0.0:8080 打开 Web 遥控（开发机可 --mock）。详见 demo/README.md。

测试方法

全部测试与验证材料的索引及使用方法见 **tests/README.md**：

主机端单元测试（无需硬件）：bash tests/run-host-tests.sh （akars 的串口协议、NMS 后处理、图像预处理等模块，TPU 走 stub）；
文件系统正确性：src/tgoskits/components/rsext4 下 cargo test 回归（11 个测试二进制）+ mock 低 IOPS 设备建模，三轮优化每轮全绿；
真机性能实验：tests/optimize/ 下 11 组实验的原始日志/CSV/图表（启动计时、SD 时钟、iozone 三方对比、JPU vs CPU 解码、小核分阶段计时等）；
模型精度：YOLOv8n mAP50 87.6%，评估配置见 src/tennis-train/docs/project_summary.md；
失败案例：IVE 硬件 CSC 未跑通、C906L wfi 不可用等负结果证据链（见 docs/comp-docs/10-限制与后续.md）。

已知限制

IVE 硬件 CSC 未跑通：驱动可配置、返回成功，但实测输出缓冲从未被写入（8 种格式误差矩阵一致、帧间变化 0/2964）；当前由模型直接吃 YUV420 绕开，证据与根因分析见 docs/comp-docs/10-限制与后续.md §10.1；
帧率与画质的取舍：仓库默认 ae_priority: None，常光下采集 33 fps （强制 60 fps 会恶化弱光画质）；
单缓冲无硬件同步：YUV/RGB 各一份缓冲，靠帧周期余量压碰撞概率；跨核邮箱缺少完整 seqlock，实测观察到过一次撕裂读；
小核 100% 忙等：C906L 读 CLINT 触发异常、wfi 不可用（已逐一排除候选中断源），CPU 占用无法下降；UART0 大小核共用，输出可能交错；
存储仍有差距：iozone 单线程初始写约为 Linux 的 3%，ext4 journal 路径与 0715 构建的单线程读回归待进一步定位（docs/comp-docs/04、10 篇）。

演示视频与展示材料

材料	位置
决赛演示视频（与 Linux 基线对比）	presentation/决赛演示视频-和linux基线对比.mp4
演示视频（完整流程）	presentation/demo.mp4
决赛现场演示 PPT	`presentation/决赛现场演示PPT.pptx`
设计报告全集	docs/comp-docs/

系统镜像下载

通过网盘分享的文件：disk.img（整卡镜像，含内核、rootfs 与预置程序）

链接: https://pan.baidu.com/s/1As96-etkhgmCm4b0kmn5Yw?pwd=sv1i 提取码: sv1i

下载后在 Linux 主机上按「运行方法」烧录 SD 卡即可复现完整闭环。

人工智能及第三方工具使用说明

项目中使用生成式 AI 辅助代码编写与文档整理，方案设计、代码审查与所有技术决策由团队完成。使用的工具与第三方组件、模型、数据及许可证的详细声明见 docs/人工智能及第三方工具使用说明.pdf。

主要使用的 AI 工具：Claude Code（claude-opus 4.6 / glm5.2）。

致谢

感谢 StarryOS 与 ArceOS 社区提供的内核基础设施，感谢 Sophgo 提供的 TPU SDK 与 tpu-mlir 工具链，感谢 tock-registers 项目提供的类型安全 MMIO 访问抽象，感谢 Roboflow 社区提供的公开网球数据集。硬件行为的理解过程中参考了 cvitek 开源驱动与 FreeRTOS 移植层的实现思路，一并致谢。