AKA-00

辰龙AI教育机器人

新闻

• 2026-03-03 添加对zl-zp10s舵机的支持
• 2026-02-12 小车模拟器可用了
• 2026-02-06 AKA-00 小车添加了对 MG996R 舵机的支持，目前支持 STS3215 和 MG996R
• 2026-01-30 opi5p 开发板可以驱动 AKA-00 小车了

开始使用

• 快速开始 - 快速让机器人跑起来
• 项目介绍 - 了解 AKA-00 核心能力
• 硬件接线 - 正确连接硬件

配置指南

• 机器人连接 - 网络设置
• 软件部署 - 项目本地启动并部署到控制板
• 初始化配置 - 初始化配置

使用文档

• Web 界面 - 远程控制界面
• API 文档 - HTTP API 接口

开发资料

• 开发板使用 - SG2002 开发指南
• 代码结构 - 项目代码组织
• 调试方法 - 调试技巧
• 镜像的制作 - 自定义镜像制作

项目介绍

AKA-00 是一个面向教学的低成本AI机器人，通过提供简单的平台实现多种算法的训练和仿真。

核心能力

技术架构

AKA-00
├── cpp/
│   ├── capp/         # aka-capp 服务：HTTP/WS 服务 + 接口路由
│   ├── csrc/         # 平台与硬件层：摄像头、板载屏、串口、舵机、电机、推理
│   └── board/        # 板上部署内容（config.toml、init.sh、demo/）
├── frontend/         # React 前端源码
├── static/           # 前端构建产物（打包时收进部署目录）
└── tests/            # 板测工具与测试脚本

各目录职责与"想改什么改哪里"见代码结构。

硬件平台

快速开始

本文档帮助你快速开始让 AKA-00 跑起来。

1. 组装

参考 硬件接线 完成机械臂、电机、摄像头的连接。

2. 通电

1. 连接电源，等待控制板指示灯亮起
2. 等待 60 秒，网络模块启动
3. 连接机器人热点（格式：chenlong-robot-xxxxx）
4. 浏览器访问 192.168.4.1，进入控制界面
5. 之后可以通过手机上的遥控器控制小车

3. 部署（首次/更新）

项目以单文件 aka-00-server 分发，拷贝到控制板执行：

# 打包（在开发机上；改了前端要先 cd frontend && npm run build）
make -C cpp ota                 # → cpp/dist/aka-00-server

# 拷贝到控制板（-O：板载 sshd 不认新版 SFTP 协议）
scp -O cpp/dist/aka-00-server root@<robot>:/root/

# 首次部署：解包 + 热点 + 开机自启
ssh root@<robot> '/root/aka-00-server --init'

更新部署（保留 config.toml、证书、demo 卡片等现场数据）：

scp -O cpp/dist/aka-00-server root@<robot>:/root/
ssh root@<robot> 'setsid /root/aka-00-server --update >/root/ota.log 2>&1 < /dev/null'

• 别放 /tmp：板上 /tmp 是 53MB 的内存盘，20MB 的固件放那儿会把内存打爆。
• 想让本次带的默认配置连 config.toml 一起覆盖，用 AKA_OTA_RESET_CONFIG=1 ... --update。
• setsid 是因为 --update 结尾是 exec init.sh，会把服务挂在当前 ssh 会话上； 也可以升级完直接 reboot（开机由 /etc/init.d/S99webstart 拉起）。

4. 使用

启动后通过以下方式控制：

• Web 界面: 访问 http://<机器人IP>/
• API: 使用 /api/control 接口

详细说明见 Web 界面 和 API 文档

下一步

• 配置 WiFi
• 了解代码结构
• 常见问题

硬件参数

主控板

机械臂舵机和控制板

控制板

微雪UART串口通信控制板

使用的舵机

支持的舵机

当前 C++ 实现里编了驱动的两种（config.toml 的 [arm] backend 选）：

• ZL-ZP10S（backend = "zp10s"，默认）
• STS3215（backend = "sts3215"）

底盘控制板（ESP32-C3）

使用的电机

主控不再直连电机 PWM/GPIO —— 旧文档里那张「PWM Chip 4 / Channel 0,1,2,3」的 接线表已经不适用，那套是 Python 版用 GPIO 直驱的做法。 角度/距离闭环（CMD_MOVE_DISTANCE）和限速都在 ESP32 固件里做，主机只发目标值、 读回 rpm 与状态。

板载屏

只有带屏版会驱动它（make 默认，AKA_WITH_SCREEN=1）；不带屏版（make noscreen） 把整个显示栈编译期裁掉，二进制更小且完全不碰 /dev/fb0，[display] 配置被忽略。

硬件接线

接线示意

主控接口图

本项目使用了以下接口：

• 底盘控制（UART1）
  • A18：UART1 RX
  • A19：UART1 TX
• 机械臂舵机（UART2）
  • A28：UART2 TX
  • A29：UART2 RX
• 板载屏（SPI）
  • SCK：SPI 时钟
  • SDO：SPI 数据输出（接屏的 SDI）
  • CS：SPI 片选
  • IO5：LCD_RS（数据/命令选择）
  • IO6：LCD_RST（复位）
• VBUS 5V
• GND

底盘控制板接口图

• VM：电机供电
• NC：置空
• GND：接地
• A、BO1、2：接电机
• A、BIN1、2：控制信号输入
• STBY：SLEEP控制，底电平有效

机械臂控制板接口图

• D：数据总线
• V：舵机供电正级
• G：舵机接地
• DC+：主控供电正级
• DC-：主控供电负极
• TX：控制输入
• RX：控制接收
• GND：接地
• A UART：UART总线控制模式
• B USB：USB总线控制模式

控制电路连线图

接线前请确保断电操作。

机械臂 UART

• 机械臂舵机控制板接主控 UART2（A28 / A29），设备节点 /dev/ttyS2
• 波特率：115200

底盘 UART

• 底盘控制板（ESP32-C3）接主控 UART1（A18 / A19），设备节点 /dev/ttyS1
• 波特率：115200
• 主控不再直连电机 PWM：A16~A19 原本那四路 PWM 现在不用了（A18/A19 复用成 UART1）， 电机驱动与编码器都归 ESP32 底盘板管

板载屏（SPI）

板载屏（ST7796S，320x480）走 SPI，接法如下（左＝屏的排针，右＝主控）：

• 屏是只写设备（没有 MISO / 触摸没有引出），capp 不直接操作 SPI 引脚，只往 内核暴露出来的 /dev/fb0 写画面。
• SPI 时钟在设备树里（节点 st7796s@0 的 spi-max-frequency）：出厂 4MHz 只有 ~420KB/s（约 2fps），本板实测稳定上限 20MHz（~2MB/s），24MHz 起白屏。 杜邦线转接会明显拉低能跑的频率。
• 屏的参数（开关、全屏/半屏、方向、帧率）都在 config.toml 的 [display] 里配， 没有 HTTP 接口；调参依据见 cpp/README.md 的「板载屏显示」一节。
• 排查接线用 ./tools/screen_test（colors 看通道序/方向、bench 看写屏带宽）。

接口一览

引脚复用（哪些脚要做 UART）见开发板说明。

更多原理图

硬件原理图位于 hardware/ 目录：

• LicheeRV_Nano-70418_Schematic.pdf - 主控板原理图
• sg2000_trm_cn.pdf - SG2000 技术参考手册
• 众灵舵机使用手册-250508.pdf - 舵机使用说明

第一次连接

如何连接机器人

第一步，连接机器人自身的热点，用于配置机器人

1. 确保机器人已连接到电源，等待机器人控制板灯亮
2. 等待20秒到30秒，此时控制板正在启动网络模块
3. 开发者打开电脑/手机，进入wifi连接，找到控制板的热点并连接，例如chenlong-robot-02

第二步，让机器人连接到开发者的WiFi网络

1. 连接热点之后，打开浏览器，输入192.168.4.1（不同的机器人可能不同，已实际为准），即可进入机器人的遥控界面
2. 在配置页面中，刷新网络，找到开发者需要的WiFi网络，点击连接，如有密码需要输入密码
3. 连接成功后，网页会显示当前连接的WiFi网络名称以及为机器人分配的IP

第三步，ssh登录机器人的控制板

1. 第二步进行完之后，开发者需要记下为机器人分配的IP,并且让自己的电脑和机器人连接到同一个WiFi网络
2. 开发者打开终端，输入ssh root@[机器人分配的IP]，即可登录机器人的控制板，密码为root
3. 登录成功后，即可在终端中操作机器人的控制板，输入ping www.baidu.com或者curl www.baidu.com，用来检测控制板网络是否成功连接并且能够访问互联网

开发环境与部署

本机跑起来（不需要板子）

设备端是个普通的 C++ 程序，可以直接在开发机上编一份跑，配置、前端页面、demo 脚本 都用仓库里的实体文件：

# 1. 前端（改了前端才需要）
cd frontend && npm i && npm run build      # 产物写到仓库根 static/

# 2. 设备端（host 版，不会覆盖交叉编译产物）
cd cpp/capp && make                        # → bin/aka-capp-dev
AKA_HOME=cpp/board ./cpp/capp/bin/aka-capp-dev

AKA_HOME 一定要指向 cpp/board，否则找不到 config.toml 和 static/。 串口和摄像头拆掉也能启动（对应模块退化成 mock 并打日志），所以只写接口、调页面时 不用接硬件。

前端热更新：

cd frontend && npm run dev

vite 的 dev server 把 /api、/ws 代理到 localhost:5000，而 C++ 版 capp 默认监听 80（config.toml 的 [web] port）。要联调，要么改 frontend/vite.config.ts 里的 proxy target，要么临时把 capp 的端口设成 5000。

打包

正式构建统一走 cpp/Makefile（在 orb 里直接跑；在 macOS 上会自动经 orb run 转发 交叉编译）：

cd cpp
make              # 一条龙：libjpeg/mbedtls/lua → csrc → capp → package → ota
make noscreen     # 不带屏版本（整个显示栈编译期裁掉）
make clean        # 清理构建产物

产物两样：cpp/dist/AKA-00/（部署目录）与 cpp/dist/aka-00-server（自解压安装器）。

前端不参与 make：打包时直接拿仓库根 static/ 里已有的产物，所以改了前端要先 cd frontend && npm run build（不带屏版是 npm run build:noscreen），拿错版本打包 脚本会告警。

部署到控制板

# 首次部署：解包 + 配热点 + 开机自启
scp -O cpp/dist/aka-00-server root@<板子IP>:/root/
ssh root@<板子IP> '/root/aka-00-server --init'

# 升级：保配置换包 + 重启服务
scp -O cpp/dist/aka-00-server root@<板子IP>:/root/
ssh root@<板子IP> 'setsid /root/aka-00-server --update >/root/ota.log 2>&1 < /dev/null'

• scp 加 -O（板载 sshd 不认新版 SFTP 协议）；固件别放 /tmp（那是 53MB 的内存盘， 20MB 的固件会把内存打爆）。
• --update 默认保留板上的 config.toml、speed_config.json、arm_angles.json、 cert.pem、key.pem，以及 demo 卡片（板上优先）和用户上传的模型（取并集）。 想让包里带的新配置生效：AKA_OTA_RESET_CONFIG=1 ... --update。
• 换包用 staging + 目录改名，旧目录留成 $AKA_HOME.old 作回滚点；只解包不重启用 --extract。
• --update 结尾是 exec init.sh，服务会挂在当前 ssh 会话上，所以要 setsid， 或者升级完 reboot（开机由 /etc/init.d/S99webstart 拉起）。

更完整的说明见仓库根 README.md 的「📦 打包」与「🚀 部署」两节。

初始化配置

这部分为机器人的初始化部分，都会在用户拿到设备前实现，如果用户需要自行初始化也可以按照本流程实现。

烧录镜像

从Releases下载最新镜像，通过烧入工具将镜像烧录到tf卡中，镜像中会自带一份项目文件。

连接主控

通过type-c接口可以将板子连接到电脑上

在win下在终端里输入ipconfig，找到一个新的以太网，例如 10.163.124.100。 之后可以使用ssh进行连接，ssh root@10.163.124.1

部署 aka-00-server

将 aka-00-server 拷贝到控制板，一条命令完成初始化：

# 1. 拷贝到控制板（-O：板载 sshd 不认新版 SFTP 协议；别放 /tmp，那是内存盘）
scp -O cpp/dist/aka-00-server root@<robot>:/root/

# 2. 一键初始化（解包 + AP 热点 + DHCP + 开机自启）
ssh root@<robot> '/root/aka-00-server --init'

--init 自动完成：

• 解包到 $AKA_HOME（默认 /root/AKA-00）
• 配置 AP 热点（SSID chenlong-robot-<数字>，由 wlan0 的 MAC 推出，开放无密码， channel 6；要加密码就取消 /etc/hostapd.conf 里 wpa=2 那几行注释）
• 配置 DHCP（192.168.4.100~192.168.4.200，网关 192.168.4.1）
• 写入 S98apstart / S99webstart 自启脚本
• 立即启动热点

之后每次开机由 /etc/init.d/S99webstart 拉起 init.sh（内部自愈循环，capp 崩了自动重启）。

手动更新：

scp -O cpp/dist/aka-00-server root@<robot>:/root/
ssh root@<robot> 'setsid /root/aka-00-server --update >/root/ota.log 2>&1 < /dev/null'

--update 默认保留板上的 config.toml、speed_config.json、arm_angles.json、 cert.pem、key.pem 与 demo 卡片/模型；想让包里带的新配置生效，加 AKA_OTA_RESET_CONFIG=1。结尾是 exec init.sh，会把服务挂在当前 ssh 会话上， 所以要 setsid（或者升级完 reboot）。

HTTPS 证书生成命令

通常不需要手工执行 —— init.sh 启动前会调 https_init.sh 自动生成 （缺 cert.pem/key.pem 时），端口默认 443。下面这条只在你想自己换/重置证书时用。

• 无交互生成自签名证书，有效期10年（3650天）

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
    -keyout key.pem -out cert.pem -days 3650 -nodes \
    -subj "/C=CN/ST=Beijing/L=Beijing/O=MyOrg/OU=MyDept/CN=localhost"

网络配置

修改 /etc/wpa_supplicant.conf 文件

ctrl_interface=/var/run/wpa_supplicant
ap_scan=1

network={
  ssid="wifi名"
  psk="wifi密码"
  priority=8
}

network={
  ssid="#####"
  psk="********"
  priority=5
}

network={
  key_mgmt=NONE
  priority=1
}

镜像烧录

本文档介绍如何将系统镜像烧录到开发板。

准备工作

所需工具

• SD 卡（2GB或以上）
• SD 卡读卡器
• BalenaEtcher 或其他镜像烧录工具

下载镜像

从项目 releases 页面下载最新的系统镜像文件（.img 格式）。 镜像文件地址

烧录步骤

Windows 系统

1. 插入 SD 卡
2. 打开 BalenaEtcher
3. 点击 "Flash from file"，选择下载的镜像文件
4. 点击 "Select target"，选择 SD 卡设备
5. 点击 "Flash" 开始烧录
6. 等待烧录完成（约 5-10 分钟）

macOS / Linux 系统

使用 dd 命令烧录：

# 查看 SD 卡设备名称
diskutil list

# 卸载 SD 卡（假设设备为 /dev/disk2）
diskutil unmountDisk /dev/disk2

# 烧录镜像（注意：of 后面的设备名称不能包含 partition 号）
sudo dd if=./aka-image.img of=/dev/rdisk2 bs=4M status=progress

# 烧录完成后弹出 SD 卡
diskutil eject /dev/disk2

首次启动

1. 烧录完成后，将 SD 卡插入开发板的 SD 卡槽
2. 连接电源
3. 等待系统启动（约 1-2 分钟）
4. 通过串口或网络连接进行后续配置，详见初始化配置

常见问题

无法启动

• 检查电源是否正常供电
• 确认 SD 卡已正确插入
• 尝试重新烧录镜像

Web 界面

启动服务后，访问 http://<机器人IP>/ 进入 Web 控制界面。

功能区域

遥控器

通过方向键控制机器人运动：

• 前进/后退：前进/后退
• 左转/右转：左转/右转

夹爪控制

• 抓取：控制机械臂向下夹取夹爪闭合
• 释放：控制机械臂夹爪张开

WiFi 配置

访问 WiFi 配置页面，可重新设置机器人连接的 WiFi 网络。

详细步骤见 WiFi 配置

进入试验平台

可进入自带的实验平台进行实验

WebSocket 控制接口

底盘遥控这类高频操作走 WebSocket，比 HTTP 轮询延迟低得多。控制页的虚拟摇杆用的就是 这条通道。

连接

ws://<机器人IP>/ws/control          # HTTPS 页面上用 wss://

协议格式

双方都发二进制帧，第一个字节是类型标记。

客户端 → 服务端

摇杆换算：fy = y/127、fx = x/127，左 = (fy+fx)×100、右 = (fy-fx)×100，限幅 到 ±100 后下发。不带时长、不阻塞，所以松手要自己补一帧停止。

JSON 命令（0xDD + JSON）：

其它 type 会被忽略（只记 debug 日志）。

服务端 → 客户端

前端示例

const ws = new WebSocket("ws://192.168.4.1/ws/control");
ws.binaryType = "arraybuffer";

ws.send(new Uint8Array([0xAA, 0, 50]));   // 前进
ws.send(new Uint8Array([0xAA, 0, 0]));    // 停

ws.onmessage = (event) => {
    const b = new DataView(event.data);
    if (b.getUint8(0) === 0xBB) {
        const left = b.getInt16(1, true) / 1000;
        const right = b.getInt16(3, true) / 1000;
        console.log(`左: ${left} m/s, 右: ${right} m/s`);
    }
};

生命周期与断线

• 服务端每 4 秒 ping 一次；90 秒收不到任何字节才判死回收连接 —— 阈值给得宽是 因为手机 WiFi 省电模式会让上行停摆几十秒，秒级判死只会造成反复断开重连。
• ⚠️ 断开连接不会停车（这点和 Python 版相反）：判死只用于回收僵尸连接，不再承担 安全停车职责。停车靠指令本身（摇杆发 0 或 action stop），以及 ESP32 固件侧的 心跳看门狗。
• 同一时刻只保持一个控制连接：多个连接同时发会互相抢（谁后发谁生效）。

API 文档

控制接口

GET /api/control?action=<action>&speed=<speed>&time=<time>&distance=<distance>&angle=<angle>

参数

| 参数 | 类型 | 必填 | 说明 | |------|------|------| | action | string | 是 | up / down / left / right / stop / grab / release | | speed | int | 否 | 电机百分比（1~100），默认 50 | | time | int | 否 | 持续时间（毫秒），无 distance/angle 时生效 | | distance | float | 否 | 移动距离（厘米 cm），up/down 有效 | | angle | float | 否 | 转动角度（度 °），left/right 有效 |

优先级：distance/angle > time。传了 distance 或 angle 就忽略 time。

所有"会动"的请求都只回一个 completed（true = 这次动作执行完了，失败时多一个 error 说明原因；细节看 /api/motor/status 或日志）。三个入口一致： ?distance=/?angle=、?time=、以及 POST /api/demo/init|run 带 "wait": true。

返回时机：

请求	何时返回	返回
?distance= / ?angle=	阻塞到 ESP32 固件闭环报结果（最多 30s）	{"completed": …}
?...&time=	阻塞到动作做完并自动停车	{"completed": …}
?action=up（不给 distance/time）	立刻返回（持续运动，靠 ?action=stop 停）	{status: success}
?action=grab / release	阻塞到夹爪那套序列做完（ZP10S 约 3.5s）	{"completed": …}

grab/release 不排队：上一段还没做完时，后来的请求直接回 {"completed":false,"error":"夹爪正忙：上一段动作还没做完（这次没做，也没排队）"}（400）， 不会攒成一串挨个执行（实测连点 5 次 → 只执行 1 次）。

distance/angle 的结论来自固件（它自己闭环 + 回状态），不是主机猜的 —— 车被卡住会回 aborted/timeout 而不是 completed。

speed 是直接发给 ESP32 PID 控制器的目标百分比（setMotorSpeed(±100) → target_rpm = speed × 150 / 100）。100% 对应约 0.49 m/s，由 PWM_RPM_MAX=150 RPM × 轮径62mm × π / 60 推出。

距离运动示例

# 前进 30 厘米，速度 50%
curl "http://<ip>/api/control?action=up&distance=30&speed=50"

# 后退 15 厘米，速度 30%
curl "http://<ip>/api/control?action=down&distance=15&speed=30"

# 左转 90 度，速度 40%
curl "http://<ip>/api/control?action=left&angle=90&speed=40"

# 右转 45 度（用默认 speed=50）
curl "http://<ip>/api/control?action=right&angle=45"

时间运动示例

# 前进 2 秒，速度 50%
curl "http://<ip>/api/control?action=up&speed=50&time=2000"

# 停止
curl "http://<ip>/api/control?action=stop"

抓取

curl "http://<ip>/api/control?action=grab"
curl "http://<ip>/api/control?action=release"

speed 物理含义对照

speed 是 ESP32 PID 控制器的目标百分比。所有路径（摇杆 / 方向键 / REST+time / REST+distance）共用同一套物理含义：

电机直接控制

GET /api/motor/direct?left=<left>&right=<right>&duration=<duration>

# 全速前进
curl "http://<ip>/api/motor/direct?left=100&right=100"

# 原地右转
curl "http://<ip>/api/motor/direct?left=50&right=-50"

# 前进 1.5 秒
curl "http://<ip>/api/motor/direct?left=80&right=80&duration=1.5"

电机状态

GET /api/motor/status

{
  "left_speed": 0.0,
  "right_speed": 0.0,
  "left_target": 50,
  "right_target": 50,
  "gripper_status": "stopped"
}

速度配置

GET /api/config/speed
POST /api/config/speed

{"forward_speed": 50, "turn_speed": 50}

摄像头

状态

GET /api/camera/status

{"camera_on": true}

打开 / 关闭

POST /api/camera/open
POST /api/camera/close

{"camera_on": true}     // open 成功；打不开返回 500
{"camera_on": false}    // close

摄像头是全局唯一的一份：屏显示、浏览器取流、单帧推理共用它。 关闭会同时熄屏（屏上显示待机图），对前端透明；打开后屏自动实时出图。

抓拍（单张图）

GET /api/camera/snapshot

{
  "image": "<base64 JPEG>",
  "width": 640,
  "height": 360,
  "format": "jpeg",
  "m": 2671.82,
  "c": -2.82
}

摄像头没开会自动打开（注意有副作用：camera_on 变成 true、板载屏开始实时出图），所以这里 拿到的是实时帧。打不开时（设备被占用/不存在）返回 500 + {"error":"camera not available"}。

MJPEG 摄像头是原帧直通（不重新编码，quality 参数对它无效）；只有 YUYV 摄像头才编码，quality=70。

视频流（MJPEG）

GET /api/camera/stream?fps=<fps>

响应为 multipart/x-mixed-replace; boundary=frame 的 MJPEG 流（浏览器 <img src> 直接用），持续到客户端断开。

默认直通摄像头原始 MJPEG 帧（服务端零解码零编码）；只有配置了 [camera] stream_scale = true 才会在服务端缩放到 stream_width x stream_height 后重编码下发 —— 那是拿 CPU 换 WiFi 带宽。

有人在看流时，板载屏会自动降帧到 [display] fps_streaming（0 = 暂停显示）让出 CPU 给浏览器： 单核 SoC 上"全屏写屏 + 浏览器取流"会互相拖慢，所以默认浏览器优先。

底盘速度 / 综合状态

两个历史命名的接口，回的实际是底盘与电机状态（不是摄像头信息），保留是为了兼容前端：

GET /api/camera/speed
GET /api/camera/all_status?timestamp=<timestamp>

{
  "left_speed": 0.0,
  "right_speed": 0.0,
  "left_target": 50,
  "right_target": 50,
  "gripper_status": "stopped",
  "gripper_target": 0,
  "timestamp_ms": 1730000000000
}

all_status 在此之上多三个字段：motor（电机连接状态）、image（base64 JPEG，quality=25）、 image_format；传给它的 timestamp 会原样回显。gripper_status 是夹爪运行状态，夹爪未连接时是 unknown。

这个接口不会打开摄像头（与 snapshot 不同）：摄像头关着时它读的是内存里缓存的最后一帧， 因此 image 依然是关闭前那一张、HTTP 依然 200，而 camera_on 为 false。实测：关闭后连续两次 取图，图片字节完全相同。响应里没有帧时间戳，要判断实时性只能看 camera_on。 从来没出过帧时 image 为 null。

单帧推理（物体检测）

GET /api/detect?model=<模型名>

取当前摄像头的一帧跑一次模型，返回检测框的四个角。

参数

摄像头没开会自动打开（与 /api/camera/snapshot 行为一致）；但刚打开时可能还没出帧， 这时返回 {"ok":false,"error":"no frame"}，隔一下重试即可。

conf 管「这个框够不够可信」：调低减少漏检、调高压掉误检。 iou 管「两个框要不要合成一个」：同一个目标画出两个框就调低它， 挨着的两个目标被吃掉一个就调高它。

两个参数给错值（不是数、或不在 0~1）返回 400，不会悄悄用默认值 —— 调参时最怕 「以为生效了其实没生效」。不给就是 0.25 / 0.45，与老版本行为完全一致。

响应

{
  "ok": true,
  "count": 1,
  "boxes": [{"x1": 236.0, "y1": 88.5, "x2": 436.0, "y2": 283.5}]
}

坐标是原图像素（采集分辨率，默认 640x360），与 GET /api/camera/snapshot 返回的图 同一坐标系 —— 可以直接把框画到那张图上核对。

只回框的四个角，不回类别/分数/耗时。

失败

一律 400 或 500 + {"ok":false,"error":"..."}：

示例

# 检测网球（模型 = $AKA_HOME/demo/models/tennis.cvimodel）
curl "http://<ip>/api/detect?model=tennis"

# 换另一颗模型
curl "http://<ip>/api/detect?model=block"

{"boxes":[{"x1":234,"x2":434,"y1":88.5,"y2":285.5}],"count":1,"ok":true}

说明

• 模型只有一个来源：部署目录下的 demo/models/（make package 整目录照搬）。裸名字只在 库里查，不存在就报错，没有隐式回退。
• 接口是同步的：每个请求现场取帧 → 推理 → 返回。模型首次请求时加载，之后常驻； 只有 ?model= 变了才重新加载。
• TPU 是单实例：/api/detect 与流程脚本共用同一个检测器（各自串行）， 但别在脚本跑的时候另起一个吃 TPU 的进程。
• 换自己的模型时对一下规格。本仓库 demo/models/tennis.cvimodel 板上实测：输入 640x480、YUV420_PLANAR、8 位量化；输出 [1,5,6300,1] FP32、单类别 （6300 = 80×60 + 40×30 + 20×15，即三个 stride 的网格点数之和）。 输入尺寸与格式都从模型张量里读，不写配置 —— 模型吃什么就喂什么。

模型管理

给外部调用方（平台）用：把模型送进部署目录的 demo/models/ —— 也就是 /api/detect 唯一认的那个模型库。

上传模型（平台 → 小车，推荐）

POST /api/models/upload?name=<模型名>
Content-Type: application/octet-stream
（body = 模型文件的二进制内容）

# raw body：平台直接推文件（推荐）
curl --data-binary @tennis.cvimodel "http://<ip>/api/models/upload?name=tennis"

# multipart：浏览器 / form 客户端也行
curl -F "file=@tennis.cvimodel" "http://<ip>/api/models/upload?name=tennis"

{"ok": true, "name": "tennis", "path": "/root/AKA-00/demo/models/tennis.cvimodel", "size": 3540016}

同步接口：文件收完、校验通过、写盘换入之后才返回（3.5MB 的模型在内网上是一瞬间的事，不需要进度查询）。

为什么是"推"而不是"拉"：小车在机器人的内网里（通常是热点/局域网），平台未必能被它反向访问； 这就是模型进入板子的唯一方式：由平台把文件推过来（不需要小车去访问平台， 也不需要板上有任何"模型商店/下载"的界面）。

同名覆盖，且覆盖即生效：/api/detect 每次请求都会 stat 模型文件，大小或 mtime 变了就重新加载 —— 换新版本不用重启 capp（代价是那一次请求多等一次模型加载）。

文件先落成 .part，校验通过后原子换入（rename）—— 传到一半、内容不对、中途断电都不会 破坏正在用的那颗模型。

校验两道：文件头必须是 CviModel（挡住"上传了别的文件"）；大小上限 32MB （请求体是整块读进内存的，板上可用内存约 50MB；模型实际约 3.5MB）。

校验只看文件头，所以「文件头对、内容是坏的」这种能被装上 —— 这时 /api/detect 会明确报 注册模型失败（CVI_NN_RegisterModel rc=…），重新传一个正确的即可，不需要别的清理动作。

删除模型

POST /api/models/delete
{"name": "tennis"}

{"ok": true, "name": "tennis", "cards": ["追网球接近"]}

只删 demo/models/<名字>.cvimodel 这一个文件（Demo 页上模型标签右上角那个 ✕ 走的就是它）。 用它建过的卡不会跟着删：卡片配置不动，只是变成 ready=false、点开始报 模型文件缺失 —— 重传一个同名模型就原地复活。响应的 cards 是"正在用它的卡片名"，界面拿它提示后果。

板上删掉包里自带的模型只到下次 OTA 为止：升级按文件名取并集，同名会用包里的版本 （见 cpp/scripts/build-ota.sh）。想让它彻底不来，得从 cpp/board/demo/models/ 里去掉。

训练平台直传（浏览器 → 小车）

训练平台（yolotrain.chenlongrobot.com）训练完，浏览器把模型直传小车（同一局域网）， 车端不做任何运行切换，只落盘 —— 后续验证人工做。与上面那个接口的区别：名字在表单里 （走 query 的旧接口是给 curl / 云端推模型用的），响应字段是 status/name/size。 模型落盘即可用：动作脚本是预定义的、与模型无关，不再给每个模型生成脚本 —— 传完要么在 Demo 页新建一张卡片（动作 × 这个模型），要么直接 POST /api/demo/init {"action":"grab","model":"orange"}。

POST /api/model/upload
Content-Type: multipart/form-data

file = <模型二进制，文件名固定 model.cvimodel>    （必填）
name = <槽位名，如 orange>                        （必填）

curl -F "file=@model.cvimodel" -F "name=orange" "http://<ip>/api/model/upload"

成功：

{"status":"ok","name":"orange","size":12865136,
 "path":"/root/AKA-00/demo/models/orange.cvimodel",
 "script":"","script_created":false,"actions":["approach","grab"]}

（script / script_created 是为兼容训练平台那份契约保留的字段，现在恒为 "" / false； actions 是当前可用的动作清单，方便平台侧提示"能用哪些动作"。都不属于必须消费的字段。）

落盘与副作用：

• 模型 → demo/models/<name>.cvimodel（同名覆盖，原子换入，坏包不会顶掉正在用的）
• 脚本：不再生成。动作脚本是仓库里预定义的 demo/grab.lua / demo/approach.lua， 与模型无关；传完模型后要么在 Demo 页新建一张卡片（动作 × 这个模型），要么直接 POST /api/demo/init {"action":"grab","model":"<名字>"} 跑一下。
• CORS 与 OPTIONS 预检由服务器统一处理（所有响应带 Access-Control-Allow-Origin: *， 预检回 200），浏览器跨域直传不需要额外配置。

Demo（本地演示）

板上的 一张 demo 卡片 = 动作 × 模型：

• 动作是预定义的通用脚本（demo/grab.lua 追到就夹、demo/approach.lua 只接近不夹， 你也可以再放一份 demo/<动作>.lua 加新动作）—— 与模型无关；
• 模型是 demo/models/ 里的一颗 .cvimodel；
• 卡片由用户在 Demo 页新建（选动作、选模型、起个名字、填参数），名字随便起（中文也行）， 配置存在 demo/configs/<卡片名>.json。

GET  /api/demo/list                     → {"demos":[...], "actions":[...], "models":[...]}
POST /api/demo/init {"name":"追网球接近"}              → 跑存下来的那张卡片
POST /api/demo/init {"action":"grab","model":"tennis"} → 直接跑，不用建卡
POST /api/demo/init {"name":"追网球接近"}              → **默认等它跑完再返回**
POST /api/demo/stop                     → 停

GET /api/demo/list 一次给全三份数据（列表 + 可用的动作 + 可用的模型，新建表单直接用）：

{
  "demos": [
    {"name":"追网球接近", "action":"approach", "model":"tennis",
     "ready":true, "script":"approach", "path":"/root/AKA-00/demo/models/tennis.cvimodel",
     "kind":"card", "error":""}
  ],
  "actions": [{"id":"approach","name":"接近瞄准"}, {"id":"grab","name":"追到就夹"}],
  "models": ["block", "tennis"]
}

动作的显示名来自脚本第一行的约定注释 -- name: 接近瞄准；没写就用文件名。 ready=false 表示动作脚本或模型文件缺了（卡片照样列出来，点开始会明确报错）。

卡片配置（一张卡片一份）

GET  /api/demo/config?name=追网球接近
     → {"name":"追网球接近","action":"approach","model":"tennis",
        "target_size":300,"speed":50,"turn_speed":25,"mode":"once"}
POST /api/demo/config  {"name":"追网球接近","action":"approach","model":"tennis",
                        "target_size":300,"speed":30,"turn_speed":25,"mode":"loop"}
POST /api/demo/delete  {"name":"追网球接近"}

POST 就是"新建或覆盖一张卡片"：界面上的"新建"与"保存"走的是同一个接口 （改参数时要把 action/model 一起回传，否则会当成新建）。改名 = 用新名字 POST 一份、 把旧的 POST /api/demo/delete 掉。

这些值就是脚本里 params() 读到的东西（另外宿主还会注入 model，见下节）。

卡片是用户在板上建的现场数据：OTA 升级时按"板上优先"保留 —— 同名卡片升级不会 覆盖你在界面上调好的参数（包里带的那些只在板上没有同名时才落地，当出厂预设）。 demo/*.lua（动作脚本）相反是仓库里的代码，升级按包里结算 —— 想调参就改卡片配置， 别改动作脚本，否则升级会丢。

临时组装一个 demo 直接跑（不建卡）

"模型 + 动作 + 那几个值"凑齐就是一次完整的 demo 请求，不用先建卡。刚传上来一个新 模型想立刻试、或者要把一条命令发给别人让他在板上按自己的参数跑一遍，都用这条：

curl -X POST http://<ip>/api/demo/init \
     -H 'Content-Type: application/json' \
     -d '{"action":"approach","model":"apple","target_size":320,"speed":30,"turn_speed":20,"mode":"once"}'

效果与建一张卡再跑一样（宿主会把 model=apple 注入给动作脚本）；区别是不落盘、 不会在 Demo 页留下卡片。想让它出现在页面上反复用，再按上面的卡片配置建成卡片。

跑完再返回（默认行为）

POST /api/demo/init / /api/demo/run 默认等这次跑完才返回，直接给完成标志：

curl -X POST -H 'Content-Type: application/json' \
  -d '{"name":"追网球接近"}' http://<ip>/api/demo/init
# → {"completed": true}
# → {"completed": false, "error": "目标丢失（1520ms 没看到目标）"}

completed: false 时 error 说明原因（脚本 fail / 丢目标 / 被人的指令接管 / timeout: 到最大执行时间（5 分钟））。过程中发生了什么看 /api/demo/status 的 state / message / round / notes。

执行一次（mode: "once"）有 5 分钟上限，到点宿主自己收工（停电机、状态落 aborted、 error 写"到最大执行时间"）—— 所以 wait 的请求最多 5 分钟必定有结论。 循环执行不受它管：loop 本来就不该自己结束，等不到就去 POST /api/demo/stop。

唯一的例外是脚本卡在不调用任何原语的死循环里（宿主只在原语入口查打断）： 那时请求会等到 310 秒回一条 timeout: 等了 310 秒还没跑完…，脚本仍在跑， 但 POST /api/demo/stop 会在它下一次调原语时生效。

想立刻返回（不等，自己轮询状态 —— 界面就是这么用的）就显式传 "wait": false， 此时响应是 {"status":"started", "name":…, "script":…}：

curl -X POST -H 'Content-Type: application/json' \
  -d '{"name":"追网球接近","wait":false}' http://<ip>/api/demo/init
curl http://<ip>/api/demo/status          # 边跑边看

mode=loop（循环执行）例外：它不会自己结束，所以默认不等（立刻回 started， 否则等于把连接挂死）；对它显式传 "wait": true 会被 400 拒掉 （loop 模式不会自己结束，wait 没有意义（要停就 POST /api/demo/stop））。要停就 POST /api/demo/stop。

流程脚本（Lua）

"看 → 对准 → 靠近 → 抓"这类流程天生要反复调参。写在 C++ 里，改一个数就得交叉编译 + 部署 + 重启（一轮几分钟）；写在脚本里就是改一行存盘重跑。所以 capp 内置了一个 Lua 宿主： 原语在 C++（快、稳），流程在 $AKA_HOME/demo/*.lua（好改）。

POST /api/demo/run       {"script":"grab",
                          "params":{"model":"tennis","target_size":300,"speed":20}}
     → {"ok":true,"state":"running","script":"grab","mode":"once"}
GET  /api/demo/status
     → {"state":"running","script":"grab","model":"tennis","card":"追网球","message":"","calls":42,"action":"forward",
        "notes":{"box_w":"212","offset":"-33"}}
POST /api/demo/stop
     → {"ok":true,"state":"aborted"}（立刻刹车，不等脚本配合）

脚本能用的原语（全部只有这些）

数学/字符串/table 标准库可用；没有 io / os / package / coroutine / debug，也没有 pcall （见下）。

安全边界（宿主强制，脚本绕不过去）

这是会真开电机的功能，所以下面这些都不在脚本手里：

示例：demo/grab.lua（追到目标并抓起来）

curl -X POST http://<ip>/api/camera/open
curl "http://<ip>/api/detect?model=tennis"      # 先看框多大，据此定 target_size
curl -X POST -H 'Content-Type: application/json' \
  -d '{"script":"grab","params":{"model":"tennis","target_size":300,"speed":20,"mode":"once"}}' \
  http://<ip>/api/demo/run
curl http://<ip>/api/demo/status                # 边跑边看 action/notes
curl -X POST http://<ip>/api/demo/stop          # 随时打断

判据（"框宽 = 距离"这一条轴，参数与判据照搬隔壁仓库 aka0 那个预编译 demo，实机调过参）： 取面积最大的框当目标，然后五选一 ——

丢目标 1.5s 没找回就收工。三处脉冲的上下限都不是拍的：下限必须大于电机启动时间 （板上实测这块底盘 ~250ms 才转得起来），上限是"别转过头/退过头"（车尾没有眼睛）。

与那套 demo 的四处有意差异：① 用框宽像素判定（本项目口径）而不是框面积占比； ② 不做"抓前左转 3 次"的爪子偏置补偿（实测夹空再加）；③ 丢目标即收工，不做没有超时的 原地找球；④ 凑太近会先退一小段（原来没有这一支，车几乎贴上去、夹爪反而够不着）。

夹爪（ZP10S）没有位置反馈，"夹到没有"无法确认 —— 脚本只能报告"抓取序列已执行完"。 另外 TPU 是单实例：跑动作脚本时别再并发调用 /api/detect（宿主内部串行，但会互相拖慢）。

WiFi

都作用在 wlan1 上（wlan0 是那台给用户连的 AP 热点，不动它）。

扫描网络

GET /api/wifi/scan

{"list": [{"ssid": "…", "id": "…", "signal": -52, "secured": true, "is_connected": false}],
 "connected": "…"}

阻塞最多约 5 秒；排序是「已连接优先，其次信号从强到弱」，同名网络只留最强的那个。

连接

POST /api/wifi/connect
Content-Type: application/json

{"ssid": "WiFi名", "password": "密码"}

无密码时 password 传空字符串。阻塞约 8 秒等关联、再加最多 6 秒等 DHCP，成功回 {"ip": "…"}（还没拿到地址时回 "获取中..."）；失败回 408 + {"error":"连接超时" | "连接失败，请检查密码或信号" | "未找到该网络"}。

连接成功会把 {ssid, password} 记进 /etc/aka-wifi.json（0600），capp 每次启动在 后台重放一次，所以不用每次开机都重连（只保留最后一个；rm 掉即"忘记网络"）。

状态

GET /api/wifi/status     # {"ssid": "…"|null, "ip": "…"}
GET /api/wifi/ip         # {"ip": "…"}（没连上时回热点地址 192.168.4.1）

系统 IP

GET /api/system/ip       # {"ip": "…"}

OTA 固件升级

当前版本

GET /api/ota/version       # {"version": "v0.6.1", "updated": 1730000000, "service": "AKA-00"}

检查更新

GET /api/ota/check

去 config.toml 的 [ota] check_url 取版本信息，比语义版本号（退而比 updatedAt）：

{"current_version": "…", "update_available": true, "latest_version": "…",
 "hardware_desc": "…", "software_desc": "…", "url": "…"}

没有可用更新时回 404 {"status":"error","message":"未找到可用更新"}。

在线升级

POST /api/ota/upgrade

异步下载固件并安装，立刻回 {"status":"ok","task_id":"…"}；已经是新版则回 {"status":"ok","message":"已是最新版本"}。固件与暂存都在 $AKA_HOME/.ota（不放 /tmp， 那是内存盘）。

直接上传固件升级（不联网）

POST /api/ota/update       # multipart/form-data，文件部分就是固件

回 {"status":"ok","task_id":"…","message":"upload received, installing..."}；没有文件回 400 {"status":"error","message":"no firmware file"}。

OTA 状态

GET /api/ota/status                              # 没有进行中的任务时 {"status":"idle"}
GET /api/ota/upgrade/progress?task_id=<id>       # {"progress": 0-100, "status": "downloading|installing|done|error", "message": "…"}

系统信息

GET /api/system/info

{"ip": "192.168.4.1", "mac": "b8:27:eb:xx:xx:xx"}

GET /api/system/heartbeat

返回 CPU、内存、磁盘、运行时间等信息。

检测 · 识别 · Demo 运行 API

给调用方（平台、脚本、别人写的程序）的一份独立文档：从"看一眼画面"到"让小车自己追过去 把东西夹起来"这一整条链的 HTTP 接口。全部在板上实测过，坐标单位一律是原图像素。

想一次看全部接口（电机/机械臂/OTA/WiFi/系统）见 API 文档；这篇只讲 摄像头 → 推理 → 跑动作这条链，覆盖 /api/camera/*、/api/detect、/api/models/* 与 /api/demo/*。

一分钟上手

IP=<板子IP>

# ① 开摄像头（检测的前提；不开会回 "camera not available"）
curl -X POST http://$IP/api/camera/open

# ② 看一眼识别结果（框的四个角，原图像素）
curl "http://$IP/api/detect?model=tennis"
# → {"ok":true,"count":1,"boxes":[{"x1":2,"x2":172,"y1":0,"y2":360}]}

# ③ 跑一次 demo：用 tennis 模型做"接近瞄准"，框宽到 320px 就算到位
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d '{"action":"approach","model":"tennis","target_size":320,"speed":30,"turn_speed":25}'
# → {"completed":true}          ← 默认等它跑完再返回（下面的"wait"一节）

③ 里没有建任何卡片：action + model + 参数凑齐就是一次完整请求。车会真的动。

1. 摄像头（检测的前提）

snapshot 的响应（实测 640x360 q70 约 46KB JSON）：

{"image":"/9j/4AAhQVZ...", "format":"jpeg", "width":640, "height":360, "m":0.05, "c":-2.82}

m / c 是像素→实际距离的标定系数（config.toml 的 [camera] calib_m/calib_c）， 用来自算"这个框离我多远"。不需要就算着玩，detect 不用它们。

分辨率/帧率/画质都在 config.toml 的 [camera]（width/height/fps/jpeg_quality）， 接口里不能改。stream 默认直通摄像头原始 MJPEG（服务端零解码零编码），所以带宽约 4~7 Mbps；嫌大就调低 jpeg_quality。

2. 检测 / 识别：GET /api/detect

"检测"和"识别"在这个系统里是同一件事：把一帧送进模型，拿回几个框。模型认什么由它自己 训练决定（网球、方块、橘子…），接口不管语义 —— 它只把框给你。

GET /api/detect?model=<模型名>[&conf=0.25][&iou=0.45]

成功（HTTP 200）：

{"ok": true, "count": 1, "boxes": [{"x1": 2, "x2": 172, "y1": 0, "y2": 360}]}

框宽 = x2 - x1，中心 = (x1+x2)/2, (y1+y2)/2 —— REST 版只给四角，宽高/中心/面积 自己算。脚本里的 detect() 会多给 w/h/cx/cy/area（见 §5）。

坐标是原图（如 640x360），不是页面上 stream 缩放后的尺寸 —— 两个尺寸不一致时 别拿标尺去量屏幕。

失败：

要"连续看"就轮询这个接口（车上一帧推理约 100~340ms，取决于有没有同时写着屏）； 要高帧率画面用 /api/camera/stream，它不跑模型。

conf 给错值直接报错而不是悄悄用默认 —— 调参时最怕"以为生效了其实没生效"。

3. 模型（"认什么"）

模型就是 $AKA_HOME/demo/models/<名字>.cvimodel 一个文件，文件名去掉后缀就是 model 参数的值。 GET /api/demo/list 的 models 字段能拿到板上现有的清单：

curl http://$IP/api/demo/list
# → {"demos":[…], "actions":[{"id":"approach","name":"接近瞄准"},…], "models":["block","orange","tennis"]}

上传

curl --data-binary @orange.cvimodel "http://$IP/api/models/upload?name=orange"
# → {"ok":true,"name":"orange","path":"/root/AKA-00/demo/models/orange.cvimodel","size":12864632}

curl -F "file=@orange.cvimodel" -F "name=orange" "http://$IP/api/model/upload"
# → {"status":"ok","name":"orange","size":12864632,"path":"…"}

同名覆盖，且覆盖即生效（下一次 /api/detect 就用新模型，不用重启）。校验：文件头必须是 CviModel（挡"传错文件"）、大小上限 32MB；先落 .part 再原子换入，传一半断了不会毁掉 正在用的那颗。

删除

curl -X POST http://$IP/api/models/delete -H 'Content-Type: application/json' -d '{"name":"orange"}'
# → {"ok":true,"name":"orange","cards":["追橘子"]}      ← cards = 正在用它的卡片名

只删这一个文件。用它建过的卡片不会跟着删，只是变成 ready:false、点开始报 模型文件缺失 —— 重传一个同名模型就原地复活。删完记得 GET /api/demo/list 刷新清单。

4. Demo 运行

概念：一张卡片 = 动作 × 模型

• 动作 = demo/<动作>.lua 脚本（预定义、与模型无关：approach 接近瞄准、grab 追到就夹）；
• 模型 = demo/models/<模型>.cvimodel；
• 卡片 = 用户起的名字 + 上面两者 + 四个参数，存 demo/configs/<卡片名>.json。

卡片不是必需的：action + model + 参数 直接发就是一次完整请求（不落盘、页面不留卡片）。 卡片只是"存下来反复用"的壳。

跑一次：POST /api/demo/init

两种形状，二选一：

// ① 跑存下来的卡片（界面上点"开始"就是这条）
{"name": "追网球接近"}

// ② 临时组装一次（不用建卡）
{"action": "approach", "model": "tennis",
 "target_size": 320, "speed": 30, "turn_speed": 25, "mode": "once"}

响应：

// 默认（wait=true）：等这次跑完再返回，只给一个完成标志
{"completed": true}
{"completed": false, "error": "目标丢失（1595ms 没看到目标）"}     // 跑完了但没成功
{"completed": false, "error": "timeout: 到最大执行时间（5 分钟）"}   // 到时限被宿主收工

// wait=false：立刻返回"起来了"
{"status":"started","name":"approach","script":"approach","action":"approach",
 "model":"tennis","pid":682,"pgid":682,"completed":false}

wait 的语义（最容易被误解的一条）：

• 它只决定这一个 HTTP 请求等不等，不是脚本的时限。
• once 默认等 → 一次请求拿到结论；loop 默认不等（循环不会自己结束，等下去就是挂死 连接），显式传 "wait": true 直接 400。
• 请求最多等 310 秒；而脚本自身在 once 模式下最多跑 5 分钟（到点宿主收工、 状态落 aborted、error 写明"到最大执行时间"）。所以正常情况是先由脚本收工、请求拿到 真实原因。
• 想自己轮询就传 "wait": false，然后看 /api/demo/status。

失败响应：

一次只能跑一个：脚本驱动电机是独占的，第二个请求 409。要换就 stop 再起。

最底层那条：POST /api/demo/run

{"script": "grab", "params": {"model": "tennis", "target_size": 300, "mode": "once"}}

和 init 的区别：不校验模型/卡片，params 原样交给脚本（调试、一次性用）。响应字段与 init 一致（{ok,state,script,mode} / 等跑完时 {completed:…}）。

看状态：GET /api/demo/status

{"state":"running","script":"approach","model":"tennis","card":"追网球接近","mode":"once",
 "round":1,"calls":92,"action":"forward","message":"",
 "notes":{"box_w":"298","offset":"28"}}

停：POST /api/demo/stop

立刻刹车、不等脚本配合；脚本会在下一次调原语时被中断，状态转 aborted。 没在跑时返回 {"status":"already_stopped"}（不报错）。

卡片管理

ready:false 表示动作脚本或模型文件缺了 —— 卡片照样列出来（点开始会明确报错），不会凭空消失。

5. 动作脚本（要加新动作时）

动作就是 $AKA_HOME/demo/<动作名>.lua 一个文件，宿主内置 Lua 解释器跑它。 第一行的约定注释给显示名（界面上的"接近瞄准"就是这么来的）：

-- name: 我的动作
local p = params() or {}
local model = p.model                      -- 宿主注入：卡片/请求里配的模型
local target = tonumber(p.target_size) or 300

while true do
    local d, err = detect(model)           -- 取一帧跑一次推理
    if not d then fail("推理失败：" .. tostring(err)) end
    local best = nil
    for _, b in ipairs(d.boxes) do
        if not best or b.area > best.area then best = b end
    end
    if not best then standby(); sleep_ms(50)
    elseif best.x2 - best.x1 >= target then brake(); return "到位了"
    else forward(p.speed or 20); sleep_ms(600); standby() end
end

能用的原语（全部只有这些）

有 math/string/table 标准库；没有 io / os / package / coroutine / debug，也没有 pcall （脚本吞掉宿主的打断就糟了）。内存预算 4MB。

板上现成两个动作：approach（-- name: 接近瞄准，只靠近不夹）、grab（-- name: 追到就夹）。 别改这两个文件 —— 它们是仓库里的代码、OTA 会按包覆盖；想调参请改卡片配置或另写一个 动作脚本（demo/<新名字>.lua，OTA 不会删你新加的）。

6. 安全边界（宿主强制，脚本和调用方都绕不过去）

7. 一条龙例子（可直接复制）

IP=<板子IP>; MODEL=tennis

# 1) 传一颗模型（同名覆盖、覆盖即生效）
curl --data-binary @orange.cvimodel "http://$IP/api/models/upload?name=orange"

# 2) 开摄像头，看它在哪、框多大（据此定 target_size）
curl -X POST http://$IP/api/camera/open
curl "http://$IP/api/detect?model=$MODEL&conf=0.5"

# 3) 跑一次：不建卡，直接组装；默认等跑完
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d "{\"action\":\"approach\",\"model\":\"$MODEL\",\"target_size\":320,\"speed\":30,\"turn_speed\":25}"

# 4) 想边跑边看：wait=false + 轮询 status（notes 里有 box_w/offset，调参就看它）
curl -X POST http://$IP/api/demo/init -H 'Content-Type: application/json' \
     -d "{\"action\":\"approach\",\"model\":\"$MODEL\",\"target_size\":320,\"wait\":false}"
while true; do curl -s http://$IP/api/demo/status; echo; sleep 1; done

# 5) 停
curl -X POST http://$IP/api/demo/stop

8. 常见坑（都是踩过的）

底盘 · 电机控制 API（前端对接用）

面向写界面/客户端的人：怎么让小车动、怎么读它的实时状态、怎么让摇杆跟手。 覆盖 /api/control、/api/motor/*、/api/config/speed，以及 /ws/control 里与驱动有关的部分。 下面所有响应都是板上实测的。

本文只管"底盘怎么动"。推理与 demo 见 检测 · 识别 · Demo 运行 API， WebSocket 完整协议见 WebSocket 控制接口。

0. 四条路，先选对

1. GET /api/control —— 命名动作

GET /api/control?action=up&speed=40&time=500

响应只有完成标志（客户端不用为失败另写一套解析）：

{"completed": true}                                            // 200
{"completed": false, "error": "unsupported action: forward"}    // 400，动作名写错
{"status": "error", "message": "angle 仅对 left/right 动作有效"} // 400，参数配错动作

• speed 的别名注意：没有 forward，前进叫 up。
• 两种失败形状不同（实测）：动作名不认识 = {"completed":false,"error":"unsupported action: xxx"}； distance/angle 配错动作 = {"status":"error","message":"…"} （distance 仅 up/down、angle 仅 left/right）。都带 400。
• distance/angle 是阻塞的（等固件闭环回报），大距离能挂几秒~几十秒；客户端别设短超时， 服务端自己 30 秒兜底。
• grab/release 是臂动作，服务端会等那套约 3.5 秒的序列做完再回 completed。

2. GET /api/motor/direct —— 直接给左右轮速度

GET /api/motor/direct?left=25&right=-25&duration=2

// duration > 0
{"status":"success","left":25,"right":-25,"duration":10,"completed":true,"mode":"completed",
 "left_speed":0.1363,"right_speed":-0.0974}      // 后两个是**实测**轮速 m/s

// duration = 0
{"status":"success","left":0,"right":0,"left_speed":0,"right_speed":0}

板上实测（2026-09-21）：

两个要记住的点：

1. 响应里的 left/right 是你发的原值，不是生效值（超范围会被静默截断）； 要生效值看 left_speed/right_speed（实测）或 /api/motor/status 的 *_target。
2. 不要指望服务端替你保活：duration=10 的请求会阻塞 10 秒，但期间不重发速度命令。 实测这块板子上单发一条能连续转 10 秒以上（代码注释里"只转 0.2~0.9s"的旧说法已不成立）， 所以外部控制器 1 秒发一条足够；要更稳就自己定时重发。

3. GET /api/motor/status —— 前端显示用

{"left_speed":0.0649,"right_speed":0.0844,"left_target":150,"right_target":0,
 "gripper_status":"unknown","gripper_target":0,
 "motor":{"backend":"tt_pid","state":"connected","connected":true,"enabled":true,"attempts":0,"error":""}}

轮询建议：状态采集是 10Hz，界面用 200~500ms 轮询足够；要跟手就用 WS 推送（§5）， 别用 50ms 轮询（单核板子会被拖慢）。

4. GET/POST /api/config/speed —— 界面上的"默认速度"

GET  /api/config/speed        → {"forward_speed":55,"turn_speed":40}
POST /api/config/speed  body: {"forward_speed":55,"turn_speed":40}

存在 $AKA_HOME/speed_config.json。

后端不做任何运动决策时会用它：它只是"界面默认值"的存储。 现在的前端是 BaseControlPage 拿 forward_speed（并 clamp 到 ≤60）当摇杆的初始速度、 SpeedConfigPage 拿它当设置页的初值 —— 发指令时速度是显式带的（WS/HTTP 参数）， 所以改了这里不会影响已经发出去的指令，也不会影响 demo 脚本（脚本的速度来自卡片参数）。

5. WebSocket /ws/control —— 摇杆 / 实时控制（推荐）

一条长连接，双向：发动作、收轮速。前端现有的摇杆就是这么做的。

发（JSON 文本帧）：

{"type":"action","action":"up","speed":40,"time":300}   // time 毫秒；0 = 不停，需要自己发 stop
{"type":"action","action":"stop"}                       // 急停

• 服务端回 {"type":"action","result":{…}}（result 就是 §1 里那些字段）。
• 只认命名动作（up/down/left/right/stop/grab/release）—— 没有直接给左右轮的通道； 要差速控制走 HTTP 的 /api/motor/direct。

收（二进制帧）：

摇杆交互的常见坑：拖动时按帧率发 action（例如 10Hz）就能跟手；松手必须发一次 stop（time 只保证"最长转多久"，不保证松手就停）。

6. 三种"停车"，别搞混

界面上的"停止"按钮用 action=stop（急停）更符合直觉。

7. 谁优先：人的指令 > 脚本

• 任何运动指令（HTTP 或 WS）都会让正在跑的 demo 脚本被判 superseded: 被新的运动指令取代（人接管） 并立刻中断、交出控制权 —— 设计如此， 摇杆一动脚本就停。
• /api/control、/api/motor/direct 不受"一次只能一个脚本"的 409 限制：随发随生效。
• 底盘掉线（motor.connected:false）时运动指令被丢弃 —— 界面上应该据此禁用摇杆并提示。

8. 常见坑（都实测过）

9. 前端最小示例

// ① 摇杆：按住时按帧率发，松手发 stop
const ws = new WebSocket(`ws://${location.host}/ws/control`);
ws.binaryType = "arraybuffer";
ws.onmessage = (e) => {
    const dv = new DataView(e.data as ArrayBuffer);
    if (dv.getUint8(0) === 0xBB) {                       // 轮速推送（mm/s）
        const left = dv.getInt16(1, true) / 1000;        // → m/s
        const right = dv.getInt16(3, true) / 1000;
        setWheelSpeed({left, right});
    }
};
const drive = (action: string, speed: number) =>
    ws.send(JSON.stringify({type: "action", action, speed, time: 300}));
const stop = () => ws.send(JSON.stringify({type: "action", action: "stop"}));

// ② 走一段 / 转个角度（阻塞到做完，别设短超时）
await fetch("/api/control?action=up&speed=40&distance=50");     // 前进 50 厘米
await fetch("/api/control?action=left&speed=35&angle=90");      // 左转 90 度

// ③ 差速直驱（自己算闭环）
await fetch("/api/motor/direct?left=30&right=15&duration=2");   // 2 秒后自动停

// ④ 显示
const st = await fetch("/api/motor/status").then(r => r.json());
// st.left_speed / st.right_speed（实测 m/s）、st.motor.connected（掉线提示）

距离标定

小车支持通过 YOLO 视觉检测 + 标定公式估算目标物体的真实距离。

标定公式

D = m / P + c

标定参数

标定参数 m 和 c 是 C++ 侧的编译期常量，在 cpp/csrc/include/csrc/config.hpp：

// 距离标定: D = m / P + c
double calib_m = 2671.82;
double calib_c = -2.82;

注意：它们不在 config.toml 里，改了要重新交叉编译 + 部署（make -C cpp ota） 才生效 —— 不像相机/电机那些参数改配置文件重启就行。

如何标定：将目标物体（如网球）放在已知距离处，在画面中测量其像素尺寸 P，代入公式反算出适合自己场景的 m 和 c 值。

获取标定参数

小车的 /api/camera/snapshot 接口在返回图片的同时，会携带当前的标定参数：

GET /api/camera/snapshot

响应：

{
  "image": "<base64 jpeg>",
  "width": 640,
  "height": 360,
  "format": "jpeg",
  "m": 2671.82,
  "c": -2.82
}

YOLO 距离仪表盘

项目提供了电脑端仪表盘 tests/server_dashboard.py，可从浏览器直观查看检测结果和距离估算。

启动

python tests/server_dashboard.py --model tests/model/tennis.onnx --port 8080

浏览器打开 http://localhost:8080，输入小车 IP 地址（如 192.168.4.1），点击「开始」即可。

工作流程

小车                         电脑端仪表盘
─────                        ─────────────
/api/camera/snapshot  ←───  拉取图片 + m, c
                             本地 YOLO 检测目标
                             计算 D = m / P + c
                             画框标注，显示距离

界面说明

参数说明

如果没有 YOLO 模型或模型加载失败，仪表盘仍可运行，仅显示图片和 m/c 参数，不进行检测。

使用sg2002

SG2002 是一款面向 AIoT 领域的高性能、低功耗 SoC，内置多个处理器核心，集成 TPU、视频编解码器、丰富外设接口，适用于智能视觉、边缘计算等场景。

硬件架构

• 处理器

  主处理器： RISCV C906 @ 1.0Ghz 和 ARM Cortex-A53 @ 1.0Ghz 协处理器： RISCV C906 @700Mhz

• TPU

  算力为 1TOPS（INT8），适用于AI推理计算

• 视频子系统

  视频输出：支持 2L MIPI DSI 输出（分辨率 2880×1620@30fps），兼容 LVDS、BT.601/656/1120 等传统接口。
  视频输入：支持 ISP（图像信号处理器），最高 5MP@30fps；支持 4L 或 2L+2L MIPI CSI 接口，兼容 DVP、Sub-LVDS、HisPI 等。
  视频编解码：解码：H.264，支持 5MP@30fps。
  编码：H.264/H.265，支持 5MP@30fps。

连接方式

• 串口连接

  sudo apt install minicom     # 安装minicom
  minicom -D /dev/ttyUSB0 -b 115200    # 连接串口，用户名：root,密码：root
  

• usb rndis 网口连接

  ip a show     # 查看网口信息.如果主机是10.245.118.100，则开发板是10.245.118.1。
  ssh root@10.245.118.1    # 连接开发板，密码：root
  

• wifi 连接

  # 假设分配的地址为192.168.1.2
  ssh root@192.168.1.2    # 连接开发板，密码：root
  

配置 UART 串口

• 验证方法

  # 开发板上验证外设串口（板载 busybox 没有 miniterm，用随包发布的板测工具）
  ./tools/tt_pid_test /dev/ttyS1 40 3000    # 底盘链路直测，默认 /dev/ttyS1 40 3000
  ./tools/cam_probe                         # 摄像头出帧直测（跑之前先停 capp）
  
  # 主机上执行（利用minicom）
  minicom -D /dev/ttyUSB0 -b 115200    # 连接串口
  

• uart0 默认开启，无需配置

• uart1 默认开启，无需配置。但如果要同时使用uart1和uart2, 则需要进行配置。

  devmem 0x03001070 32 0x2 # GPIOA 28 UART2 TX
  devmem 0x03001074 32 0x2 # GPIOA 29 UART2 RX
  devmem 0x03001068 32 0x6 # GPIOA 18 UART1 RX
  devmem 0x03001064 32 0x6 # GPIOA 19 UART1 TX
  

• uart3 引脚默认复用为SDIO。而SDIO被用于wifi连接。所以在有wifi连接的情况下，不能使用uart3。

  devmem 0x030010D0 32 0x5 # GPIOP 18 UART3 CTS
  devmem 0x030010D4 32 0x5 # GPIOP 19 UART3 TX
  devmem 0x030010D8 32 0x5 # GPIOP 20 UART3 RX
  devmem 0x030010DC 32 0x5 # GPIOP 21 UART3 RTS
  

代码结构

板上跑的一切都在 cpp/ 里：编译成单个 riscv64 静态二进制 aka-capp，加上配置和前端 产物，一起打进 aka-00-server 安装器（见快速开始）。根目录其余 部分是 Python 版（历史实现）的遗留文件，不再维护。

目录

AKA-00/
├── cpp/
│   ├── capp/                    # aka-capp 服务进程
│   │   ├── src/main.cpp         #   入口：读配置 → 起服务
│   │   ├── src/http/            #   自研 HTTP 服务（socket + 线程 + 路由 + 报文）
│   │   ├── src/routes/          #   接口路由，一个域一个文件（motor/camera/arm/demo/…）
│   │   ├── src/services/        #   业务服务：控制、摄像头、demo、推理、WiFi、上报
│   │   ├── src/websocket.cpp    #   /ws/control 二进制通道
│   │   ├── src/script.cpp       #   Lua 流程脚本宿主
│   │   └── include/capp/        #   头文件（context.hpp 是全局上下文）
│   │
│   ├── csrc/                    # 平台与硬件层（编成 libcsrc.a，不依赖 capp）
│   │   ├── src/camera/          #   V4L2 采集 + JPEG 解码
│   │   ├── src/display/         #   板载 SPI 屏显示（仅带屏版编译）
│   │   ├── src/motor_pair.cpp   #   差速运动学
│   │   ├── src/tt_pid.cpp       #   ESP32 底盘串口协议（闭环）
│   │   ├── src/gripper.cpp      #   夹爪
│   │   ├── src/zp10s.cpp        #   ZL-ZP10S 舵机
│   │   ├── src/sts3215.cpp      #   STS3215 舵机
│   │   ├── src/yolo*.cpp        #   NPU 推理（.cvimodel）
│   │   ├── src/{config,state,serial,system_utils,angle_config}.cpp
│   │   ├── src/{http_client,https_client}.cpp  # OTA / 状态上报的出栈请求
│   │   ├── tools/               #   板测工具：cam_probe / tt_pid_test / screen_test
│   │   └── include/csrc/        #   头文件
│   │
│   ├── board/                   # 板上 $AKA_HOME/ 的镜像（实体文件，见下）
│   ├── scripts/                 # 第三方库构建（libjpeg / mbedTLS / Lua）+ 安装器打包
│   └── third_party/             # 交叉编译产物（构建时生成，不进版本库）
│
├── frontend/                    # React 前端源码，构建产物写到 ../static
├── static/                      # 前端构建产物（打包时收进部署目录）
├── tests/                       # 板测 demo 源码（demo_camera.c 等）与测试脚本
├── hardware/                    # 原理图、舵机手册
└── docs/                        # 本文档（mdBook）

板上目录（$AKA_HOME）

部署到板子上的内容 = cpp/board/ 原样 + 三样构建产物（aka-capp、static/、 tools/）。所以"这个文件是哪来的"只有两种答案：要么在 cpp/board/ 里，要么是编出来的。

$AKA_HOME/
├── aka-capp            # riscv64 静态二进制（构建产物）
├── static/             # 前端页面（构建产物）
├── tools/              # 板测工具（构建产物）
├── config.toml         # 唯一配置文件：端口、串口、摄像头、屏、OTA 地址
├── init.sh / stop.sh   # 启动（自愈循环，崩溃自动重启）/ 停止
├── init_ap_web.sh      # 装 AP 热点 + 开机自启（一次性，无状态）
├── S97akaap            # 首次开机自举 AP（带幂等锁）
├── https_init.sh       # 缺证书时自动生成自签证书
├── demo/               # grab.lua / approach.lua（动作脚本）+ models/ + configs/
├── arm_angles.json     # 机械臂标定角度（现场数据）
├── arm_angles_default.json
├── speed_config.json   # 行驶速度（现场数据）
├── VERSION             # 版本号（OTA 比对用）
└── start_img.jpg       # 屏显示待机图

想改什么，改哪里

别在板子上直接改文件：OTA 升级是整目录换包，只有 config.toml、speed_config.json、 arm_angles.json、cert.pem、key.pem 这几个文件，以及 demo/configs/（板上优先）和 demo/models/（取并集）会被保留，其余一律按包里的结算。想改什么就改仓库， 走 make -C cpp ota 重新打包部署。

调试方法

串口连接

# 安装 minicom
sudo apt install minicom

# 连接串口
minicom -D /dev/ttyUSB0 -b 115200

网络连接

USB RNDIS 网口

# 查看网口
ip a show

# 如果主机是 10.245.118.100，则开发板是 10.245.118.1
ssh root@10.245.118.1

WiFi SSH

ssh root@<机器人IP>

日志查看

capp 不写日志文件，输出直接走 stdout：开机由 /etc/init.d/S99webstart 拉起时打在 串口控制台上；手工启动想留一份就自己重定向：

AKA_HOME=$HOME/AKA-00 $HOME/AKA-00/init.sh > /root/aka.log 2>&1 &
tail -f /root/aka.log

日志详细程度由 config.toml 的 [logging] level 控制（默认 info）。

测试硬件

板子自带一套板测工具（部署目录的 tools/，make 打包时一并放进去）：

./tools/tt_pid_test /dev/ttyS1 40 3000   # 底盘：直发速度看车动不动（绕过 Web 层）
./tools/cam_probe                        # 摄像头：验证能否出帧
./tools/screen_test                      # 板载屏：写屏带宽/颜色（仅带屏版）

这些工具会独占对应设备，跑之前先停 capp（$AKA_HOME/stop.sh）。

网络诊断

# 检测网络连通性
ping www.baidu.com

# 检测外网访问
curl www.baidu.com

HTTPS 证书

不用手工生成：init.sh 启动前会调 https_init.sh，缺 cert.pem/key.pem 时自动 签一张（EC prime256v1，10 年），已经有的不会被覆盖。要换成 CA 签发的证书，把两个文件 放到 $AKA_HOME/ 即可；端口在 config.toml 的 [web] https_port（默认 443， 设 0 关闭 HTTPS）。手工重签的命令见初始化配置。

自定义镜像的制作

1. 基础镜像的选择

我们需要选择一个基础镜像，在它的基础上进行修改。从项目 releases 页面下载最新的系统镜像文件（.img 格式）。 镜像文件地址

2. 镜像的挂载

我们需要挂载镜像文件到本地，以便进行修改。具体步骤如下：

sudo losetup -fP /path/to/image.img --show  # 把镜像对应到loop设备，返回loop设备的路径
# 假设返回的loop设备路径为/dev/loop0
sudo mount /dev/loop0p2 /mnt    # 挂载loop设备的p2分区到/mnt目录

3. 镜像的修改

在挂载后，我们可以对镜像文件进行修改。具体步骤如下：

cd /mnt/root/ # 进入挂载目录
rm -rf AKA-00 # 删除旧版本
cp -r /path/to/AKA-00 . # 复制新的部署目录（= cpp/dist/AKA-00/）

用 make -C cpp package 生成 cpp/dist/AKA-00/，它就是板上 $AKA_HOME （镜像里即 /root/AKA-00/）该有的样子：cpp/board/ 的实体文件 + 三样构建产物 （aka-capp、static/、tools/）。前端有更新时先 cd frontend && npm run build， 打包会自动把仓库根的 static/ 收进去。

4. 镜像的卸载

在修改完成后，我们可以卸载镜像文件。

sudo umount /mnt    # 卸载loop设备
sudo losetup -d /dev/loop0    # 卸载loop设备

5. 镜像的压缩

在修改完成后，我们可以压缩镜像文件，以便于传输。

xz -zk /path/to/image.img

AKA-00教育机器人测试文档 - 测试概述与策略

1. 测试概述

1.1 文档目的

本文档旨在为教育机器人（AKA-00教育机器人）提供从实验室到产品化过程中的标准测试流程指导。测试覆盖硬件功能、极限工况等多个方面，以验证机器人的功能完整性、稳定性和鲁棒性，确保产品交付质量。

1.2 测试范围

1.3 教育机器人基本信息

1.4 测试环境

1.5 测试设备清单

1.6 参考文档

• 《0_测试需求.md》

2. 测试策略

2.1 测试方法

• 黑盒测试：验证功能是否符合预期，不关注内部实现
• 白盒测试：检查代码逻辑和算法正确性
• 集成测试：验证各模块协同工作能力
• 系统测试：验证整个系统在真实环境下的表现
• 极限测试：验证极端工况下的系统稳定性

2.2 测试分类

2.3 测试流程

1. 测试准备：搭建测试环境、准备测试设备、明确测试参数（如安全温度上限）
2. 单元测试执行：按照测试用例执行各硬件模块测试
3. 集成测试执行：验证模块间协同工作能力
4. 极限工况测试：在极端环境下验证系统稳定性（包括组装过程中的电机和舵机连续运行温度测试）
5. 系统测试执行：验证完整功能流程
6. 缺陷记录：记录测试中发现的问题
7. 缺陷修复：开发人员修复问题
8. 回归测试：验证修复效果
9. 测试报告：汇总测试结果

2.4 测试优先级

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

AKA-00教育机器人测试文档 - 硬件测试

3. 硬件测试

3.1 电机测试与电机控制电路测试

3.1.1 测试目标

验证电机驱动功能和电机控制电路模块的工作状态，包括电机转动和控制芯片状态。

3.1.2 测试环境

• 底盘垫高，车轮离地
• 计时器

3.1.3 测试用例

3.2 摄像头测试与控制板USB测试

3.2.1 测试目标

验证摄像头的图像采集功能是否正常。

3.2.2 测试环境

• 室内测试环境

3.2.3 测试用例

3.3 舵机测试与舵机控制电路测试

3.3.1 测试目标

验证舵机驱动功能和舵机控制电路模块的工作状态，包括3个舵机的独立控制。

3.3.2 测试环境

• 平坦地面
• 计时器

3.3.3 测试用例

3.4 电池测试

3.4.1 测试目标

验证12V电池的输出电压和续航时间是否满足要求。

3.4.2 测试环境

• 室内/室外测试场地
• 满电状态的电池
• 万用表
• 计时器

3.4.3 测试用例

3.5 降压模块测试

3.5.1 测试目标

验证降压模块的输出电压和输出电流是否正确（7.5V给舵机供电，5V给控制板和电机供电）。

3.5.2 测试环境

• 实验室测试环境
• 万用表
• 电流表

3.5.3 测试用例

3.6 UART通信测试

3.6.1 测试目标

验证控制板两路UART接口的通信功能，分别用于控制电机和舵机。

3.6.2 测试环境

• 实验室测试环境
• 串口调试工具
• 电机控制板
• 舵机控制板

3.6.3 测试用例

3.7 NPU功能测试（含YOLO网球识别）

3.7.1 测试目标

验证控制板NPU（神经网络处理器）的YOLO网球识别功能。

3.7.2 测试环境

• 室内测试环境
• 网球

3.7.3 测试用例

3.8 WiFi功能测试

3.8.1 测试目标

验证控制板WiFi连接功能和SSH远程连接能力。

3.8.2 测试环境

• 室内测试环境
• WiFi网络环境
• SSH客户端

3.8.3 测试用例

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

AKA-00教育机器人测试文档 - 极限工况测试

4. 极限工况测试

4.1 测试目标

验证机器人在极端环境条件下的安全运行能力，包括不同温度环境、阳光直射等工况下的长时间运行稳定性。

4.2 测试环境

• 高温测试环境（40℃）
• 低温测试环境（0℃）
• 室外阳光直射环境
• 温度测量设备
• 计时器

4.3 测试用例

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

AKA-00教育机器人测试文档 - 交互测试

5. 交互测试

5.1 手机APP遥控测试

5.1.1 测试目标

验证手机APP遥控功能是否正常。

5.1.2 测试环境

• 手机安装控制APP
• 机器人处于遥控模式

5.1.3 测试用例

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

AKA-00教育机器人测试文档 - 系统集成测试

6. 系统集成测试

6.1 完整捡球流程测试

6.1.1 测试目标

验证机器人完整捡球流程的功能完整性，包括自主捡球模式的各项功能。

6.1.2 测试环境

• 室内/室外测试场地
• 放置网球和目标容器

6.1.3 测试用例

6.2 性能指标测试

6.2.1 测试目标

验证机器人的性能指标是否满足要求。

6.2.2 测试环境

• 室内/室外测试场地

6.2.3 测试用例

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

AKA-00教育机器人测试文档 - 缺陷管理与测试报告

7. 缺陷管理

7.1 缺陷分类

7.2 缺陷记录模板

8. 测试报告模板

8.1 测试摘要

8.2 测试结果统计

8.3 缺陷统计

8.4 测试结论

• 测试是否通过：□ 通过 □ 未通过
• 主要问题：
• 改进建议：
• 测试人员签名：

附录：测试用例状态说明

文档版本：V1.0
创建日期：2026-06-11
文档状态：待审核

常见问题

连接问题

Q: 机器人热点无法连接？

1. 确保机器人已通电且指示灯亮起
2. 等待 60 秒让网络模块完全启动
3. 确认电脑/手机 WiFi 已开启

Q: 无法 SSH 登录？

1. 确认电脑和机器人在同一 WiFi 网络
2. 检查 IP 地址是否正确
3. 尝试使用串口连接调试

Q: WiFi 配置页面打不开？

浏览器访问 192.168.4.1，确认已连接机器人热点。

运行问题

Q: 启动失败，提示缺少依赖？

板上没有"依赖"可缺 —— 设备端是静态二进制，不依赖 Python 或任何库。启动失败看 init.sh 的输出（串口控制台），常见就两种：

• aka-capp not found or not executable —— 包没解全或可执行位丢了，重跑一次 ./aka-00-server --update；
• 端口被占（日志里 bind failed）—— 多半起了两个实例，ps 看一眼 init.sh 与 aka-capp。

如果是开发机上编译失败，那才是环境问题（缺 riscv64-musl 工具链）： 见开发环境与部署。

Q: 机械臂不响应？

1. 确认舵机控制板接在主控 UART2（/dev/ttyS2，115200）
2. 确认舵机供电正常 —— 舵机是独立供电，别只靠主控
3. ls -l /dev/ttyS2 看设备在不在，config.toml 的 [arm] port / backend 是否对得上
4. 直接读一下角度：curl http://<ip>/api/arm/angles

Q: 电机不转动？

底盘是 ESP32-C3 底盘板闭环控制的，主控并不直连电机 PWM，所以按链路查：

1. 底盘板供电、串口接线（主控 UART1 /dev/ttyS1，115200）
2. 看 GET /api/motor/status 的 motor.connected / motor.state：是 reconnecting 就是串口没通 —— 服务会按退避自动重连，不用重启
3. 用 ./tools/tt_pid_test /dev/ttyS1 40 3000 绕过 Web 层直测（先停 capp）
4. 配置为空也会导致行为不对：config.toml 丢了/0 字节时所有配置静默取默认值， 接口看着正常但车不动 —— init.sh 启动时会对空配置告警，日志里搜 config.toml

Q: 摄像头无法识别？

1. 检查 USB 连接
2. 确认设备文件 /dev/video0 存在
3. 测试摄像头：ls -l /dev/video0

其他

Q: 如何查看机器人 IP？

GET /api/system/ip（热点模式下网关固定 192.168.4.1，接路由器后的 IP 也可以看 GET /api/wifi/status）。

Q: 如何开启 HTTPS？

不用手工做：cpp/board/https_init.sh 会在 capp 启动前自动生成自签证书 （EC prime256v1，10 年有效期；openssl 没编 EC 时退回 RSA-2048），缺一才生成 —— 已有的证书不会被覆盖。生成位置固定 $AKA_HOME/cert.pem / key.pem。

要手工换证书（比如换成 CA 签发的），把这两个文件放到 $AKA_HOME/ 即可， 端口在 config.toml 的 [web] https_port（默认 443）。

Q: 如何设置开机自启？

参考 机器人连接 中的开机自启配置。