AUTOAIM：RoboMaster 视觉自瞄调试项目

面向 RoboMaster 大学生机器人大赛，基于 SHtech_auto_aim 的开发板源码快照，主要使用 AX650 + 海康 USB 相机 + 串口下位机。这里保留开发板适配修改，采用独立 Git 历史，并非上游完整历史的克隆。

首次上手先用视频和模拟串口。默认 launch.cfg 是相机输入、/dev/ttyS1 真实串口，不能当作离线配置直接运行。下位机必须适配新协议后才能联机。

当前状态

• 处理流程：图像输入 → 装甲板检测 → 位姿解算与跟踪 → 瞄准规划 → 串口或 TXT 输出。
• 下行协议已精简为五字段，命令字 0x0504，14 字节数据区、23 字节整帧。
• 开发板完整编译通过；封包、CRC、解包回读及坏包拒绝测试通过。新协议尚未完成真实下位机联调。
• MVS 5.0.2 / 相机 SDK 4.8.1.2 独立取图测试通过；MV-CS016-10UC 在当时 USB 2.0 链路下采集 1440 × 1080，约 23 FPS。取图速度不等于整套算法速度。

目录导航

所有工程代码位于 SHtech_auto_aim/，CMake 命令也在该目录执行。

位置	用途
main.cpp、main.hpp	初始化和流水线编排
launch.cfg	输入源、串口、模型和调试配置
sensor/、detect/	相机/视频输入、检测和角点精修
predict/、planner/	目标选择、运动预测、瞄准与射击请求
timedserial/	串口、模拟驱动和协议结构体
asset/	模型及相机、规划参数
tools/test_protocol_v2.cpp	不访问物理串口的封包测试

仓库不含系统镜像、AXCL 运行库、MVS 安装包、RMCVSerial 源码包、测试视频、编译产物和运行日志。之前打包的 RMCVSerial 及 offline-check/ 材料只在本机保存，不随 Git 克隆。

1. 准备环境

已配置好的开发板

当前使用 SD 卡上的 Debian chroot：

内容	开发板宿主路径	chroot 内路径
运行环境	/mnt/autoaim/rootfs	/
工程	/mnt/autoaim/rootfs/root/auto-aim	/root/auto-aim
海康 SDK	/mnt/autoaim/rootfs/opt/MVS	/opt/MVS
RMCVSerial 源码	/mnt/autoaim/rootfs/opt/rmcv_serial	/opt/rmcv_serial

SSH 登录后，以 root 执行。先确认 SD 卡挂载，避免写入宿主系统空间：

mountpoint /mnt/autoaim || exit 1
for part in dev proc sys; do
  mountpoint -q /mnt/autoaim/rootfs/$part ||
    mount --bind /$part /mnt/autoaim/rootfs/$part
done
chroot /mnt/autoaim/rootfs /bin/bash

进入后设置环境变量，后续编译和运行均在此环境执行：

export MVS_PATH=/opt/MVS/lib/aarch64
export MVCAM_COMMON_RUNENV=/opt/MVS/lib
export LD_LIBRARY_PATH=/soc/lib:/usr/local/lib:/opt/MVS/lib/aarch64
cd /root/auto-aim

/soc 必须已有相应 AX650 头文件和运行库；挂载设备目录不会自动安装它们。

新设备或首次克隆

git clone https://github.com/0bCyan/AUTOAIM.git
cd AUTOAIM/SHtech_auto_aim

私有仓库需要 GitHub 访问权限。克隆只获取源码，新环境还需支持 C++20 的编译器、CMake、OpenCV、Eigen3、Boost、RMCVSerial、AX650 运行环境和 MVS SDK。

普通 x86 电脑不能直接运行 AX650 后端。其他后端验证不充分；INFERENCE_BACKEND=ONNX 使用 MIGraphX/ROCm，不是通用 ONNX Runtime。新板可参考上游环境项目，但不要在现有 SD 卡环境盲目重跑安装脚本，以免覆盖已更新的 SDK。

2. 编译

在工程目录执行：

cmake -S . -B build -DINFERENCE_BACKEND=AXCL -DUSE_HIKCAM=ON
cmake --build build -j1

已有构建目录时通常只需第二条。开发板内存有限，建议 -j1；暂不要使用旧 build.sh 的 make -j6。Release 链接优化可能耗时数分钟。

3. 第一次运行：视频 + TXT

程序读取当前工作目录里的 launch.cfg。先执行 cp -n launch.cfg launch.cfg.local-backup 备份，再编辑已有配置中的以下字段，其他字段保留：

source=/root/auto-aim/test.avi
port=None
model=asset/models/SKD250526.axmodel
camera_para=asset/camParam/cam_param_hik1_.yml
planner_para=asset/plannerParam/planner_param_sentry.yml
timed_serial_log_text=true

test.avi 不在 Git 仓库内，先准备视频并填写实际路径。上面的目录适用于现有开发板，新克隆环境应按实际目录调整。无显示器时保留所有 *_show_image=false。

确认 port=None 后运行：

test -f /root/auto-aim/test.avi || exit 1
unset AUTOAIM_MOCK_TX_PORT
export AUTOAIM_MOCK_ENEMY_COLOR=1
export AUTOAIM_MOCK_OUTPUT="$PWD/robot-output-v2.txt"
timeout -s INT -k 5s 15s ./build/auto-aim

AUTOAIM_MOCK_ENEMY_COLOR=1 选择蓝色目标，取消该变量则默认红色，应与视频对应。模拟状态使用水平姿态、28 m/s 射速，并非真实测量。

TXT 第一行是说明，第二行是列名，后续数据以制表符分隔：

elapsed_ms  yaw_deg  pitch_deg  distance  shoot  target_id

时间戳不进入串口协议。每次启动会覆盖指定 TXT，要保留历史请换文件名。视频结束后程序可能持续报取帧失败，因此这里限时运行；达到 timeout 时退出码通常为 124，不等于算法崩溃。

4. 相机与实机运行

先只改 source=0，保持 port=None，并取消 AUTOAIM_MOCK_TX_PORT。这样使用真实相机、模拟机器人状态，不向物理串口发送；目标颜色仍由模拟环境变量指定。

实机联调前，再把 port 改为已确认引脚映射的设备路径。当前配置为 /dev/ttyS1，已确认是启用的非控制台 UART，并能设置 921600、8E1；旧 /dev/ttyS4 在当前设备树中未启用。用户确认排针采用树莓派布局（物理 8=TX、10=RX、9=GND），但 /dev/ttyS1 到这组排针的物理连接仍需回环或下位机测试，不能把软件打开成功视为引脚验证通过。相机内外参必须对应实际镜头和安装方式。

开发板以前部署过 /mnt/autoaim/run-auto-aim，这是板端脚本，不在仓库中，使用 /root/auto-aim/launch.cfg 运行。新克隆不会获得该脚本。初次调试推荐在正确目录前台运行 ./build/auto-aim，用 Ctrl+C 停止，不急于开机自启。

AUTOAIM_MOCK_TX_PORT 可以让模拟驱动向真实串口发送，仅设置 port=None 不足以保证没有物理输出。AUTOAIM_DEBUG_NO_SHOOT 仅作用于 MockDriver，不是所有模式的总禁射开关。旧 install_service.py 生成的脚本包含异常退出后重启设备的逻辑，启用前需单独审阅。

5. 串口协议速查

115200、8N1（无校验）、无流控（USB-TTL 联调配置，原为 921600、8E1）；命令字 0x0504，数据区 14 字节，整帧 23 字节，小端序。

字段	类型	含义
yaw	float32	相对水平修正量，度，顺时针为正
pitch	float32	相对俯仰修正量，度，向上为负
distance	float32	目标距离，米
shoot	uint8	0 禁止；1 允许连发；2 下位机判断；3 单发请求
target_id	uint8	目标编号，0 表示无目标

A5 | 数据长度(2) | 序号(1) | CRC8(1) | 命令字(2) | 数据(14) | CRC16(2)

没有固定帧尾，末尾是 CRC16。序号当前固定为 0，不能用于单发去重。yaw/pitch 不是绝对角度，不能把重复收到的修正量不断累加。MCU 需同步更新解析、校验及超时禁射逻辑，其固件不在仓库内。

完整字节偏移、CRC 和示例帧见串口 V2 协议。入站 IMU 0x1021 和裁判信息 0x1022 未修改。实机路径仍用临时固定射速 24.5 m/s 覆盖入站射速，正式使用前需确认。

不访问串口的封包自测：

g++ -std=c++17 -I. tools/test_protocol_v2.cpp -lRMCVSerial -o /tmp/test-protocol-v2
LD_LIBRARY_PATH=/usr/local/lib /tmp/test-protocol-v2

末尾应输出 PASS。测试故意损坏一帧验证拒包，出现一次 CRC16 error 是预期现象。

6. 常见问题

现象	优先检查
not defined env: MVS_PATH	编译前设置 MVS_PATH=/opt/MVS/lib/aarch64
找不到 .so	chroot、LD_LIBRARY_PATH、依赖是否齐全
lsusb 有相机，SDK 枚举 0 台	SDK、初始化、USB 挂载、线材和供电；USB 2.0 不必然导致枚举失败
相机帧率约 24 FPS	lsusb -t 链路速度、Hub、曝光和带宽限制
画面偏暗	镜头盖、光圈、曝光、增益；取帧成功不等于成像正常
没有目标输出	颜色、视频路径、模型、标定参数及目标可见性
下位机无法解包	115200、8N1、0x0504、14 字节数据区、CRC、小端序；不能沿用旧布局
克隆后没有启动脚本或视频	属于板端或本机部署材料，未提交到 Git

进一步阅读

• 算法与模块说明
• 协议结构体与发送实现
• 依赖说明：其中上游安装包版本是历史记录，当前部署以本页和实际环境为准。
• LICENSE与第三方声明：模型、SDK 和第三方组件不自动继承源码许可。

已知历史问题包括装甲板切换时间窗口的整数截断等，详见模块 README。本项目不是“克隆后即可直接用于比赛”的整机交付包，标定、下位机、引脚映射和实机验证需要分别完成。