gimbal-edu-tools

国庆培训用的云台套件里，公开给学员的那部分：串口桥，云台描述和相机配置，虚拟云台（没有硬件也能跑通闭环），用法示例，依赖安装脚本和一份课 3 的样例 bag。目标环境是 Ubuntu 22.04，ROS 2 Humble，OpenCV 4.5.4（contrib）。

各课的答案在私有仓库 gimbal-edu-solutions，固件在 gimbal-edu-firmware，通信协议在 gimbal-edu-protocol（本仓库的 protocol/ 是它的 submodule）。

目录

gimbal-edu-tools/
├─ robo_bridge_edu/          串口桥，课 1 到 3 和固件联调用
├─ gimbal_edu_description/   URDF 与外参 yaml（default.yaml，virtual.yaml），发布 gimbal_link 以下的 TF
├─ camera_setup/             UVC 相机（usb_cam），标定说明，640x480 默认内参
├─ virtual_gimbal/           虚拟云台：假下位机，假相机，e2e 评估器
├─ examples/                 bridge_usage_cpp，bridge_usage_py：bridge 的最小用法示例
├─ optional/                 海康相机驱动，带 COLCON_IGNORE，默认不编译
├─ setup/                    依赖安装（deps.md），Dockerfile.humble，串口权限脚本和 udev 规则
├─ data/bags/class3_sample/  课 3 的输入样例 bag（不含 /class3/* 话题）和 README
└─ protocol/                 submodule：gimbal-edu-protocol

各课对应的工具

• 课 1（订阅 IMU，自写 Mahony）：robo_bridge_edu 发布 /offboardlink/imu_data 和 TF world->gimbal_link，虚拟云台提供 /tmp/ttyVGIMBAL 和真值 TF。
• 课 2（ArUco + PnP + TF 链）：gimbal_edu_description 和 camera_setup 提供 gimbal_link->camera_link->camera_optical_frame 和相机内参，虚拟云台的 corners 模式直接发角点，camera 模式用真实相机。
• 课 3（KF 预测，bag 离线评估）：虚拟云台的 corner_noise_px 给角点加噪声用来录验收 bag，data/bags/class3_sample 是录好的输入样例，只有输入，没有课 3 的输出；带评估结果的完整版在私有仓库 gimbal-edu-solutions 的 data/bags/class3_sample_full。
• 课 4（自己写串口协议）：不启动 bridge，学员节点自己收发，虚拟云台作为被测的下位机。
• 课 5（P 控制加限幅，闭环跟踪）：同样不启动 bridge，学员节点自己解析 IMU，自己发 TF，虚拟云台的 corners 模式加评估器验收。

课 4，5 不启动 bridge：同一时刻只能有一个进程打开串口，world->gimbal_link 这条 TF 也只能有一个发布者（课 1 到 3 是 bridge，课 5 是学员节点）。

快速开始

工作区布局

在 ws/src/ 下并列克隆 gimbal-edu-tools 和 gimbal-edu-solutions，都要加 --recursive（protocol/ 是 submodule）。solutions 是私有仓库，学员只克隆 tools 就能做课 1 到 3 的练习。

# 建工作区，并列克隆两个仓库
mkdir -p ws/src && cd ws/src
git clone --recursive <gimbal-edu-tools 的地址>
git clone --recursive <gimbal-edu-solutions 的地址>

漏了 --recursive 的话，在各仓库里补 git submodule update --init。

编译

依赖见 setup/deps.md（原生安装，或用 setup/Dockerfile.humble）。

# 在工作区根目录（ws/）
source /opt/ros/humble/setup.bash
colcon build --symlink-install
source install/setup.bash
colcon test && colcon test-result --verbose

黄金向量在各仓库根的 protocol/golden_frames.txt，包内不放副本。找不到时可以设 GOLDEN_FRAMES_DIR（目录）或 GOLDEN_FRAMES（文件）。黄金向量测试找不到文件会被跳过，跳过不等于通过。

离线时 ament_xmllint 会因为下载 schema 失败，用 colcon test --ctest-args -E xmllint 排除，见 setup/deps.md 第 4 节。

虚拟云台

# 只起虚拟云台：corners 模式，正弦轨迹
ros2 launch virtual_gimbal virtual_gimbal.launch.py vision_mode:=corners trajectory:=sine

课 5 闭环和 e2e.sh 在 gimbal-edu-solutions 里（class5_tracking），依赖本仓库的虚拟云台，同一个工作区里编译即可。

bridge 联调

# 终端 1：虚拟云台
ros2 launch virtual_gimbal virtual_gimbal.launch.py vision_mode:=corners
# 终端 2：bridge，订阅 cmd_vel_gimbal
ros2 launch robo_bridge_edu bridge.launch.py port:=/tmp/ttyVGIMBAL subscribe_cmd_vel:=true
# 终端 3：发小幅正弦指令并打印 IMU
ros2 run bridge_usage_py bridge_usage_py

实机把 port 换成 /dev/gimbal（或 /dev/ttyUSB0），串口权限和 udev 见 setup/setup_serial.sh 与 setup/deps.md 第 1.3，3 节。

WSL 下的 PYTHONNOUSERSITE

在 WSL 里，用户目录 ~/.local 下的 Python 包（pip 装的 numpy，scipy，opencv 等）会盖过系统的和 ROS 的版本，导致 ImportError 或版本不匹配。跑 launch，pytest 之前先 export PYTHONNOUSERSITE=1。

WSL2 还有两点：系统时钟每 30 秒左右向前跳约 1.3 秒（仿真和评估用单调时钟，不受影响）；同一个 ROS_DOMAIN_ID 上有别的仿真在跑时话题会混进来，请换一个 domain。

已知限制

• 虚拟云台没有 CAN 和编码器，也不实现 PROTOCOL 10.4（CAN 掉线）；仿真落后墙钟超过 0.1 s 时评估结果不可信（看 /virtual_gimbal/status 的 sim_skips）。
• UVC 相机，usb_cam 和海康驱动只验证了 launch 的参数传递，没有在有硬件的机器上跑过。
• WSL2 里 CP210x 和 CH341 的内核驱动可能没有，usbipd 和虚拟机 usbip 的命令没有实测（setup/deps.md 第 3 节）。
• docker 镜像因为本机代理的原因没能构建成功过，验证都在原生 Ubuntu 22.04 环境里做（处理办法见 setup/deps.md 第 2 节）。