SG2002 网球机器人：StarryOS 决赛工程

本项目在 SG2002 机器人上运行 Rust 组件化 StarryOS 内核和 akars 应用，实现网球检测、定位及移动抓取，并优化视觉链路、内存生命周期和系统启动。决赛交付分支为 master。

主要功能与改进

视觉：USB 摄像头取帧、JPU 硬件解码与半分辨率输出、TPU 推理、取帧预取。
内核：ION／DMA 生命周期修复、TPU 可睡眠等待、初始化命令合并及动态 ELF 装载优化。
应用与验证：底盘、机械臂及夹爪控制，分阶段计时，Linux／StarryOS 基准对照。

当前优化拾球入口为 akars-three-ball，使用半分辨率 JPU、硬件启动预取和后退后等待新帧的控制修正。功能与性能结果见对比汇总及完整 Demo 记录。

目录与材料

项目根目录/
├── README.md
├── src/                    # 内核、应用源码及第三方许可证
├── docs/                   # 四份决赛 PDF
├── tests/                  # 测试脚本、数据、日志及验证材料
├── demo/                   # 构建、启动入口及运行说明
├── presentation/           # 决赛 PPT 和 MP4 视频
└── 作品原创承诺书.pdf

项目说明书、答辩 PPT和演示视频已提供。

版本与来源

比赛 Linux 基线为 AKA-00 v0.4，StarryOS 增量基线为 705e14824519fe519d6e79df1ef1a8fad1dd0e2b。当前内核基于 2c8bd19… 加项目改动。源码版本见 SOURCE_STATE.json，来源及许可证见源码说明和 LICENSES。

环境与构建

开发主机使用 x86_64 Ubuntu、Python 3、C/C++ 构建工具、mkimage 和 dtc；运行设备为 SG2002。应用使用 Rust 1.94.0、RISC-V musl 目标、Xuantie v3.4.0 及固定 TPU SDK；内核使用 nightly-2026-05-28 和 RISC-V musl 交叉工具链。

在仓库根目录检查依赖：

bash demo/scripts/setup-akars.sh --check
bash demo/scripts/build-starryos.sh --check

依赖准备完成后构建应用和内核：

bash demo/scripts/build-akars.sh --offline --features diagnostic-timeline --bins
bash demo/scripts/build-starryos.sh

依赖安装、缓存配置和产物路径见应用构建说明与内核构建说明。构建脚本仅生成产物；部署时使用匹配的内核、设备树、模型、加载器和运行库，并核对文件哈希。

启动与运行

Ubuntu、U-Boot 和 StarryOS 为不同命令环境。以下在 Ubuntu 执行，配合开发板 Reset 进入原 Card C 的 StarryOS：

sudo python3 demo/scripts/enter-uboot.py --boot-starryos

该脚本锁定原镜像路径和大小，新构建镜像需按内核说明核对启动方式。已测产物与配套文件见交付冻结记录。

将配套应用、模型和运行库部署到板端独立目录后，在 StarryOS shell 执行当前入口：

./akars-three-ball yolov8n_tennis_v2.cvimodel vision-run-01 30 gate-run-01

四个参数依次为模型、输出目录、帧数和控制确认目录；两个目录均须不存在，由程序创建。默认仅运行视觉。拾球模式需同时设置 AIOS_PILOT_MOTION=YES 并追加 --motion，会驱动底盘、机械臂和夹爪；运行前清空活动范围并准备观察和断电停止。收球确认及停止方式见运行说明。Linux 共用程序入口见跨系统 Demo 说明。

测试与验证

在 Ubuntu 核验文件清单：

python3 tests/scripts/verify-manifest.py

主机控制、TTY 和 UART 回归使用 bash tests/scripts/run-host-tests.sh，结果写入 tests/.test-results/，运行时会清空该输出目录，不访问真实硬件。板端基准的配置、用法和原始结果见基准测试说明；无运动视觉可使用上面的 akars-three-ball 默认入口。

已知限制

性能数据对应各自的镜像、应用和场景；同帧延迟、结果更新间隔及完整拾球时间分别统计，组合收益按整套方案解释。
已验证实际拾球；多轮成功率、全面识别准确率、长期稳定性、峰值内存及功耗尚未全面测量。
新构建须单独验证，历史成绩以归档产物为准；主机回归只验证源码与接口逻辑，硬件结论依据板端记录。