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
├── tennis_hunter.py     # 机器人主程序
├── run.py               # Web 服务器
├── src/
│   ├── arm_control/     # 机械臂控制（舵机驱动）
│   ├── base_control/    # 底盘控制（电机驱动）
│   └── cameras/         # 摄像头模块
├── app/                 # Flask Web 应用
├── frontend/            # React 前端
└── models/              # YOLOv8 模型

硬件平台

快速开始

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

1. 组装

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

2. 通电

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

3. 部署（首次/更新）

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

# 打包（在开发机上）
make -C cpp ota                 # 打包（用已有前端产物）
cd frontend && npm run build    # 需要重建前端时先跑这个
make -C cpp ota                 # 再打包

# 拷贝到控制板
scp cpp/dist/aka-00-server root@<robot>:

# 首次部署：一键初始化（解压 + 热点 + 自启）
ssh root@<robot> 'aka-00-server --init'

# 之后每次开机自动启动，也可手动运行
ssh root@<robot> 'aka-00-server'

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

scp cpp/dist/aka-00-server root@<robot>:/tmp/
ssh root@<robot> 'chmod +x /tmp/aka-00-server && /tmp/aka-00-server --update'

想让本次带的默认配置连 config.toml 一起覆盖，用 AKA_OTA_RESET_CONFIG=1 ...--update。

4. 修改代码常用命令

# SSH 登录控制板
ssh root@<机器人IP>

# 本地修改代码后，重新打包并部署
make -C cpp ota && scp cpp/dist/aka-00-server root@<robot>:/usr/local/bin/

# 在控制板上重启服务
ssh root@<robot> 'aka-00-server --update'

5. 使用

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

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

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

下一步

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

硬件参数

主控板

机械臂舵机和控制板

控制板

微雪UART串口通信控制板

使用的舵机

支持的舵机

• STS3215
• MG996R
• ZL-ZP10S

电机控制板(DRV8833)

使用的电机

硬件接线

接线示意

主控接口图

本项目使用了以下接口：

• 电机控制
  • A16：PWM4
  • A17：PWM5
  • A18：PWM6
  • A19：PWM7
• 舵机控制
  • A28：UART2TX
  • A29：UART2RX
• 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控制

• 机械臂串口连接至 /dev/ttyACM0
• 波特率：115200

电机PWM控制

更多原理图

硬件原理图位于 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，用来检测控制板网络是否成功连接并且能够访问互联网

项目本地启动并部署到控制板

项目本地启动

1. 安装Miniconda用于控制python的版本

安装miniconda，请按照官方安装指南

创建 python 3.11 环境

conda create -n aka python=3.11 -y

2. 运行 pip install -r requirements.txt 安装依赖

pip install -r requirements.txt

3. 安装前端依赖

cd frontend && npm i

4.打包前端项目

npm run build && cd ..

5. 运行项目

python run.py

之后访问本地的80端口或443端口即可

本地对于硬件调用的接口进行了隔离，所以可以直接启动

打包部署到控制板

使用 make -C cpp ota 将整个项目打包为单个自解压可执行文件 aka-00-server，然后拷贝到 SG2002 控制板即可运行。

# 构建（在开发机上执行）
make -C cpp ota                 # 打包（用已有前端产物）
cd frontend && npm run build    # 需要重建前端时先跑这个
make -C cpp ota                 # 再打包

# 输出: cpp/dist/aka-00-server（约 9MB 自解压安装器）
#       cpp/dist/AKA-00/（部署目录，就是板上 $AKA_HOME 的样子）

首次部署

# 1. 拷贝 aka-00-server 到控制板
scp cpp/dist/aka-00-server root@<robot>:/usr/local/bin/

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

更新部署

清除旧数据后重新运行：

scp cpp/dist/aka-00-server root@<robot>:
ssh root@<robot> 'aka-00-server --update'

工作原理

aka-00-server 是一个自解压程序：

1. 首次运行时自动解压项目文件到 ${AKA_HOME:-$HOME/AKA-00}
2. 执行 uart_init.sh 初始化串口（如果存在）
3. 启动 python3 run.py 运行 Web 服务

后续运行时跳过解压步骤，直接启动服务。

初始化配置

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

烧录镜像

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

连接主控

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

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

部署 aka-00-server

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

# 1. 拷贝到控制板
scp cpp/dist/aka-00-server root@<robot>:/usr/local/bin/

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

--init 自动完成：

• 解压项目文件到 $HOME/AKA-00
• 配置 AP 热点（SSID: chenlong-robot-xxxxx，基于 MAC 地址唯一）
• 配置 DHCP（192.168.4.100-200）
• 写入 S98apstart / S99webstart 自启脚本
• 立即启动热点

之后每次开机自动运行 aka-00-server。如需手动更新：

scp cpp/dist/aka-00-server root@<robot>:/usr/local/bin/
ssh root@<robot> 'aka-00-server --update'

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 控制接口

AKA-00 提供 WebSocket 通道用于低延迟实时控制底盘运动，替代 HTTP REST 轮询。

连接

ws://<机器人IP>/ws/control

允许任意来源跨域访问。连接时自动禁用 Nagle 算法，延迟 < 1ms。

协议格式

双方通信均为二进制帧。

客户端 → 服务端（控制指令）

电机映射：

左轮 = Y + X
右轮 = Y - X

结果限幅到 [-100, 100]。

示例：

服务端 → 客户端（状态上报）

推送策略：速度变化时立即推送，无变化时每 2 秒发一次心跳。

示例：

生命周期

• 连接打开：服务端注册客户端，启动 200ms 定时器推送状态
• 连接关闭：服务端自动执行 run_motor(0, 0) 停止电机
• 异常断开：TCP 断开时 Tornado 触发 on_close，同样停止电机

前端示例

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

// 发送：前进 50
const x = 0, y = 50;
ws.send(new Uint8Array([0xAA, x & 0xFF, y & 0xFF]));

// 接收状态
ws.onmessage = (event) => {
    const buf = new DataView(event.data);
    if (buf.getUint8(0) === 0xBB) {
        const leftSpeed = buf.getInt16(1, true) / 1000;
        const rightSpeed = buf.getInt16(3, true) / 1000;
        console.log(`左: ${leftSpeed} m/s, 右: ${rightSpeed} m/s`);
    }
};

注意事项

• 连接断开后电机自动停止，无需额外发送停止指令
• 每个 WebSocket 连接独立控制电机，多个连接同时发送会导致竞争
• 控制值限幅 ±100，超出范围会被裁剪

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

扫描网络

GET /scan

连接

POST /connect
Content-Type: application/json

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

无密码时 password 为空字符串。

状态

GET /status
GET /api/ip

OTA 固件升级

当前版本

GET /api/ota/version

检查更新

GET /api/ota/check

在线升级

POST /api/ota/upgrade

OTA 状态

GET /api/ota/status

系统信息

GET /api/system/info

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

GET /api/system/heartbeat

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

距离标定

小车支持通过 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 串口

• 验证方法

  # 开发板上执行（利用Python的pyserial库）
  python3 -m serial.tools.miniterm /dev/ttyS0 115200    # 一般 UARTx 对应 /dev/ttySx
  
  # 主机上执行（利用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
  

代码结构

AKA-00/
├── run.py                      # 主入口，启动 HTTP/HTTPS 服务器
├── tennis_hunter.py            # 机器人主程序（网球收集逻辑）
├── requirements.txt            # Python 依赖
├── init.sh                     # 系统初始化脚本
│
├── app/                        # Flask Web 应用
│   ├── __init__.py             # Flask 应用工厂
│   └── routes/
│       ├── api.py              # 控制 API（运动、夹爪）
│       └── frontend.py         # 前端路由
│
├── src/                        # 硬件控制模块
│   ├── arm_control/            # 机械臂控制
│   │   ├── sts3215/            # STS3215 舵机驱动
│   │   ├── mg996r/             # MG996R 舵机
│   │   └── zl/zp10s/           # ZL-ZP10S 机械臂
│   ├── base_control/
│   │   └── n20/                # N20 电机驱动
│   └── cameras/
│       └── opencv/             # 摄像头模块
│
├── frontend/                   # React 前端
│   ├── src/
│   │   ├── App.tsx             # 主应用组件
│   │   ├── pages/
│   │   │   ├── BaseControlPage.tsx   # 遥控器页面
│   │   │   └── WiFiConfigPage.tsx     # WiFi配置页面
│   │   └── ...
│   ├── package.json
│   └── vite.config.ts
│
├── models/                      # YOLOv8 模型文件
│   ├── best.onnx               # CPU 推理模型
│   └── best.rknn               # RK3588 推理模型
│
├── static/                     # Flask 静态文件
└── templates/                  # Flask 模板

关键模块

调试方法

串口连接

# 安装 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>

日志查看

# 查看运行日志
cat app.log

# 实时查看日志
tail -f app.log

测试硬件

# 测试电机
python car_test.py

网络诊断

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

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

HTTPS 证书

如需启用 HTTPS，需生成自签名证书：

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"

自定义镜像的制作

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 # 删除AKA-00目录
cp -r /path/to/AKA-00 . # 复制AKA-00目录到挂载目录
# 注：如果frontend有更新，需要重新生成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: 启动失败，提示缺少依赖？

pip install -r requirements.txt

Q: 机械臂不响应？

1. 检查串口连接是否正确
2. 确认舵机供电正常
3. 检查 /dev/ttyACM0 设备是否存在

Q: 电机不转动？

1. 检查 GPIO 连接
2. 确认 PWM 引脚配置正确
3. 检查电机供电

Q: 摄像头无法识别？

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

其他

Q: 如何查看机器人 IP？

访问 http://<机器人IP>/api/ip

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: 如何设置开机自启？

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