gimbal-edu-solutions

国庆培训五节课的答案工程。私有仓库，只给讲师用。

这里的包依赖 gimbal-edu-tools（bridge，云台描述，虚拟云台），必须和它在同一个 colcon 工作区里编译。通信协议在 gimbal-edu-protocol，本仓库的 protocol/ 是它的 submodule。

各课答案在哪

• 课 1：class1_mahony，Mahony 节点，加检查脚本 check_ahrs_vs_gt（yaw，pitch 同时运动时 roll，pitch 的 RMS 不超过 2 度）。
• 课 2：class2_aruco_pnp，ArUco 或角点加 PnP，输出 marker 在 world 下的位置。
• 课 3：class3_kf_predict，三维匀速 KF，加 evaluate_prediction.py（RMSE，NIS）和 record_sample_bag.sh（录验收 bag）。
• 课 4：gimbal_serial，串口协议库（打包，解析状态机）加 gimbal_cmd_node，黄金向量测试。
• 课 5：class5_tracking，解析 0x01，发 IMU 和 TF，P 控制加限幅，发 0x30；launch/class5_e2e.launch.py 和 scripts/e2e.sh 做端到端验收。
• data/bags/class3_sample_full：课 3 样例 bag 的完整版（bag/ 里多出 /class3/* 四个话题），加 pred.csv，eval.json，run.json（录制参数和由噪声算出的 sigma）。没有 logs/，里面有个人路径和主机名。公开的 gimbal-edu-tools/data/bags/class3_sample 只有输入话题，是同一次录制去掉 /class3/* 后的版本。
• INTERFACES.md：课间的话题，参数，坐标系和默认值总表，实现，launch，测试和讲义回填都以它为准。

工作区布局

# 建工作区，并列克隆 tools 和 solutions，都要 --recursive
mkdir -p ws/src && cd ws/src
git clone --recursive <gimbal-edu-tools 的地址>
git clone --recursive <gimbal-edu-solutions 的地址>
cd ..
source /opt/ros/humble/setup.bash
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/setup.bash
colcon test && colcon test-result --verbose

class2 和 class3 的少数测试脚本在没有 source 安装空间时，会到 ../gimbal-edu-tools/virtual_gimbal 找虚拟云台的 Python 模块，所以两个仓库的目录名请保持默认。

黄金向量读 protocol/golden_frames.txt，可以用 GOLDEN_FRAMES_DIR 指到别处。找不到时相关测试会跳过。

运行

# 课 5 闭环，虚拟云台 corners 模式，评估跑完后整体退出，结果是一行 JSON
ros2 launch class5_tracking class5_e2e.launch.py vision_mode:=corners evaluate:=true

e2e.sh

# 先 source ROS 2 和工作区的 install/setup.bash
bash class5_tracking/scripts/e2e.sh

跑四种情况：正例必须 PASS；kp=0，yaw_sign=-1，pitch_sign=-1 三个反例必须 FAIL，而且必须是因为跟踪误差超限而失败。退出码 0 表示都符合预期，1 表示有情况不符合，2 表示启动失败。

环境变量：EVAL_DURATION（评估时长，默认 30 s），PORT，OUT_DIR，WS_SETUP，START_TIMEOUT，说明见脚本开头。在 WSL 里跑会自己设 PYTHONNOUSERSITE=1；同一个 ROS_DOMAIN_ID 上有别的仿真时脚本会拒绝运行，请换一个 domain。

验证结果

验证环境是 WSL（Ubuntu 22.04，ROS 2 Humble，apt 版 OpenCV 4.5.4）。原始日志在 docs/verification/。

• ros_test.log：colcon test，501 项测试，0 error，0 failure，0 skipped（当时工作区是合并的，共 11 个包）。
• e2e.log：正例 PASS，RMS 0.9478 度，最大 2.9536 度（门限 2.0 度和 5.0 度）；kp=0，yaw_sign=-1，pitch_sign=-1 三个反例都如期 FAIL。
• 课 3 样例 bag（data/bags/class3_sample_full）的 NIS 均值 3.03，n=1732，落在 95% 区间 [2.89, 3.12] 内。这个判据很严，不同噪声种子的均值会波动约 0.06，落到区间外先看 eval.json 是偏高还是偏低，再重录确认，不要放宽区间。
• 课 1 AHRS 检查（虚拟云台无噪声，30 s）：roll RMS 约 0.003 度，pitch RMS 约 0.015 度。

以上数据只在虚拟云台上得到，课 5 真机模式（real:=true）没有在硬件上跑过。