RC_WheelLeg/catkin_ws/odin1的使用手册.md

Odin1 的使用手册

1. 文档来源与适用范围

本文根据 Odin1 官方仓库内容整理，官方仓库克隆位置为：

• /home/lcf/catkin_ws/ziliao/odin_ros_driver

本手册重点面向你当前这台机器上的 ROS2 使用方式，并结合你当前工作空间实际路径整理为可直接操作的版本：

• 工作空间根目录：/home/lcf/catkin_ws
• 实际运行包目录：/home/lcf/catkin_ws/src/odin_ros_driver
• 官方参考仓库目录：/home/lcf/catkin_ws/ziliao/odin_ros_driver

2. Odin1 是什么

Odin1 官方 ROS 驱动 odin_ros_driver 是一个同时支持 ROS1 和 ROS2 的驱动包，核心用途包括：

• 连接 Odin1 设备并发布点云、IMU、RGB、里程计、TF 等数据
• 提供里程计模式、SLAM 建图模式、重定位模式
• 支持 RViz 可视化
• 支持在线调节 AE/AWB
• 支持地图保存与重定位

官方说明里明确推荐：

• ROS2 推荐使用 Humble
• Ubuntu 推荐使用 22.04
• 设备固件版本要求 v0.11.11

3. 官方仓库里与 ROS2 最相关的文件

• README.md
  • 官方主说明，包含安装、运行、建图、常见问题
• RELOCALIZATION_GUIDE.md
  • 重定位专门说明
• config/control_command.yaml
  • 运行参数总配置，建图和重定位主要看这个文件
• launch_ROS2/odin1_ros2.launch.py
  • ROS2 启动入口
• script/build_ros2.sh
  • 官方 ROS2 构建脚本
• set_param.sh
  • 用于在运行时发送参数命令，保存地图时会用到

4. ROS2 启动流程总结

官方 README 的 ROS2 逻辑本质上是两步：

source /home/lcf/catkin_ws/install/setup.bash
ros2 launch odin_ros_driver odin1_ros2.launch.py

你当前环境里已经额外有一个一键脚本：

/home/lcf/catkin_ws/runros.sh

这条命令现在默认就等价于上面两条命令，所以日常使用时建议优先用它。

5. ROS2 启动时实际会拉起什么

根据官方 launch_ROS2/odin1_ros2.launch.py，启动时会拉起以下节点：

• host_sdk_sample
  • 主驱动节点，负责设备连接、数据流和核心逻辑
• pcd2depth_ros2_node
  • 深度图相关节点
• cloud_reprojection_ros2_node
  • 点云投影相关节点
• image_overlay_node
  • 图像叠加相关节点
• rviz2
  • 默认会同时启动 RViz2，并加载 config/odin_ros2.rviz

所以官方 ROS2 launch 不是只起一个驱动进程，而是“驱动 + 辅助处理节点 + RViz2”的完整演示链路。

6. 先决条件

6.1 系统与依赖

官方建议：

• Ubuntu 22.04
• ROS2 Humble
• OpenCV 只保留一个版本
• 已安装 yaml-cpp、libusb、Eigen3、OpenSSL 等依赖

6.2 Udev 规则

官方要求添加 udev 规则，否则可能遇到 USB 访问权限问题：

sudo vim /etc/udev/rules.d/99-odin-usb.rules

写入：

SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"

然后执行：

sudo udevadm control --reload
sudo udevadm trigger

6.3 可能遇到的 USB 权限问题

如果启动时报：

• LIBUSB_ERROR_ACCESS
• LIBUSB_ERROR_BUSY

优先检查：

1. 是否已经添加 udev 规则
2. 当前用户是否在 plugdev 组
3. 是否有旧的 host_sdk_sample 进程还在占用设备

可用命令：

ps aux | grep host_sdk_sample
killall host_sdk_sample

7. 你当前环境下的推荐使用方式

7.1 一键启动

/home/lcf/catkin_ws/runros.sh

该命令会自动：

1. 加载 /opt/ros/humble/setup.bash
2. 加载 /home/lcf/catkin_ws/install/setup.bash
3. 执行：

ros2 launch odin_ros_driver odin1_ros2.launch.py

7.2 只加载环境

source /home/lcf/catkin_ws/runros.sh

7.3 只开一个干净 shell

/home/lcf/catkin_ws/runros.sh --shell

8. Odin1 的三种工作模式

官方通过 config/control_command.yaml 中的 custom_map_mode 控制工作模式：

• 0：里程计模式
• 1：SLAM 建图模式
• 2：重定位模式

8.1 里程计模式

custom_map_mode: 0

特点：

• map 和 odom 视为同一位姿
• 不进行回环建图
• 适合只看实时位姿和点云

如果里程计漂移，官方建议在运行过程中执行：

cd /home/lcf/catkin_ws/src/odin_ros_driver
./set_param.sh algo_reset 1

8.2 SLAM 建图模式

custom_map_mode: 1

特点：

• 在里程计模式基础上增加回环检测和地图保存能力
• 启动后自动开始建图并缓存地图数据
• 地图不会自动保存，必须手动触发保存

8.3 重定位模式

custom_map_mode: 2

特点：

• 基于已有地图重新定位
• 必须指定地图文件路径
• 成功后会发布 map -> odom 的 TF

9. ROS2 下怎么建图

这是你最关心的部分，按下面流程做。

9.1 第一步：修改配置为建图模式

编辑实际运行中的配置文件：

• /home/lcf/catkin_ws/src/odin_ros_driver/config/control_command.yaml

至少确认这些字段：

register_keys:
  custom_map_mode: 1
  relocalization_map_abs_path: ""

建议同时关注：

• strict_usb3.0_check
  • 默认 0，允许非严格 USB3.0；但官方强调建图最好使用 USB3.0
• senddtof
  • 点云开关
• sendodom
  • 里程计开关
• sendcloudslam
  • SLAM 点云开关
• sendcloudrender
  • 渲染点云开关
• showpath
  • 是否显示路径

如果你想更明显地看路径，可考虑：

showpath: 1

9.2 第二步：启动驱动

推荐直接执行：

/home/lcf/catkin_ws/runros.sh

或者手动执行：

source /home/lcf/catkin_ws/install/setup.bash
ros2 launch odin_ros_driver odin1_ros2.launch.py

9.3 第三步：移动设备开始建图

驱动启动后，Odin1 会自动开始建图并缓存地图数据。

建议操作方式：

• 使用 USB3.0 连接
• 启动后缓慢移动设备
• 尽量覆盖你希望建图的区域
• 尽量回到已走过区域，帮助回环闭合
• 场景中应有足够几何/纹理特征

9.4 第四步：保存地图

建图完成后，进入包目录：

cd /home/lcf/catkin_ws/src/odin_ros_driver

执行官方命令：

./set_param.sh save_map 1

set_param.sh 的本质是向 /tmp/odin_command.txt 写入：

set save_map 1

主驱动会读取这个命令并调用 SDK 保存地图。

9.5 第五步：找到保存出来的地图文件

配置文件里写明：

mapping_result_dest_dir: ""
mapping_result_file_name: ""

如果这两个都为空，则官方默认保存到：

• {ws}/src/odin_ros_driver/map/{driver_start_time}/

结合你当前工作空间，默认可按下面路径去找：

• /home/lcf/catkin_ws/src/odin_ros_driver/map/

实际生成的地图文件通常是 .bin 文件。

9.6 第六步：重复保存

官方说明允许重复执行：

./set_param.sh save_map 1

但两次保存之间建议至少间隔 5 秒。

10. 重定位怎么用

官方重定位文档单独给了更详细说明，这里按实用方式整理。

10.1 自动重定位

修改配置：

register_keys:
  custom_map_mode: 2
  relocalization_map_abs_path: "/home/lcf/catkin_ws/src/odin_ros_driver/map/你的地图目录/xxx.bin"
  custom_init_pos: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]

推荐条件：

• 起始位置距离原始建图轨迹 1 米以内
• 起始朝向与建图时偏差不超过 ±10°
• 场景特征明显

启动后行为：

1. 尝试将当前观测和已有地图匹配
2. 成功后发布 map -> odom TF
3. 失败时进入后备模式并继续尝试

10.2 指定初始位姿重定位

如果你知道大概起点位置，可设置：

register_keys:
  custom_map_mode: 2
  relocalization_map_abs_path: "/绝对路径/xxx.bin"
  custom_init_pos: [x, y, z, qx, qy, qz, qw]

含义是：

• x y z：地图坐标系中的位置
• qx qy qz qw：四元数姿态

例如绕 Z 轴 90°：

custom_init_pos: [5.2, -3.1, 0.0, 0.0, 0.0, 0.707, 0.707]

10.3 与官方文档的一个小冲突

官方主 README 的参数表里写过：

• custom_init_pos：currently unused

但官方单独的 RELOCALIZATION_GUIDE.md 已经把它作为重定位功能来详细说明，并给了示例，因此更应以重定位指南为准。

如果你实际测试发现 custom_init_pos 不生效，优先检查：

1. custom_map_mode 是否为 2
2. custom_init_pos 是否正好 7 个值
3. 四元数是否归一化
4. 地图文件路径是否为绝对路径

11. 建图与重定位的推荐操作套路

11.1 首次建图

1. 把 custom_map_mode 设为 1
2. 启动：

/home/lcf/catkin_ws/runros.sh

3. 缓慢移动 Odin1，采完整个区域
4. 返回包目录保存地图：

cd /home/lcf/catkin_ws/src/odin_ros_driver
./set_param.sh save_map 1

5. 到 map/ 目录下找到 .bin 地图文件

11.2 下次基于已有地图定位

1. 把 custom_map_mode 改为 2
2. 把 relocalization_map_abs_path 指到上一步生成的 .bin
3. 若知道起点，补 custom_init_pos
4. 再执行：

/home/lcf/catkin_ws/runros.sh

12. 常用参数解释

以下参数来自官方 control_command.yaml，是 ROS2 下最常用的一批。

12.1 时间与同步

• use_host_ros_time
  • 0：使用设备时间，官方推荐
  • 1：收到数据时用主机 ROS 时间
  • 2：对齐到主机时间轴

建议：

• 一般先保持 0

12.2 传感器输出

• sendimu
  • 是否发布 IMU
• sendodom
  • 是否发布里程计
• senddtof
  • 是否发布原始点云
• sendcloudslam
  • 是否发布 SLAM 点云
• sendcloudrender
  • 是否发布渲染后的点云
• sendrgb
  • 是否发布 RGB 图像
• sendrgbcompressed
  • 是否发布压缩 RGB 图像

12.3 点云质量相关

• cloud_raw_confidence_threshold
  • 原始点云置信度阈值，官方示例是 35
• dtof_fps
  • 官方注释给出 100、145、290 等档位

12.4 其他

• recorddata
  • 是否录制官方私有格式数据，空间占用很大
• devstatuslog
  • 是否记录设备状态日志
• showpath
  • 是否显示路径
• showcamerapose
  • 是否显示相机位姿

13. ROS2 下常用话题

官方 README 给出的常用话题包括：

• /odin1/imu
• /odin1/image
• /odin1/image_undistort
• /odin1/image/compressed
• /odin1/cloud_raw
• /odin1/cloud_render
• /odin1/cloud_slam
• /odin1/odometry
• /odin1/odometry_high
• /odin1/path
• /tf
• /odin1/reprojected_image

重定位成功后，/tf 中会出现 map -> odom 关系。

14. 在线调参能力

官方驱动提供四个 ROS2 服务，可在驱动运行时调整自动曝光和自动白平衡：

• /odin1/get_ae
• /odin1/get_awb
• /odin1/set_ae
• /odin1/set_awb

示例：

source /home/lcf/catkin_ws/install/setup.bash
ros2 service call /odin1/get_ae  odin_ros_driver/srv/GetAe
ros2 service call /odin1/get_awb odin_ros_driver/srv/GetAwb
ros2 service call /odin1/set_ae odin_ros_driver/srv/SetAe "{mode: 0}"
ros2 service call /odin1/set_awb odin_ros_driver/srv/SetAwb "{mode: 0}"

15. 常见问题总结

15.1 启动后设备很快断开

官方认为 ROS2 在复杂网络环境下容易因为广播导致阻塞，从而出现设备断开。

如果不需要跨设备通信，可先尝试：

export ROS_LOCALHOST_ONLY=1

15.2 RViz 卡死或长时间无响应

官方建议先给 Odin1 重新上电。

15.3 重启设备后 RViz 出现 TF_OLD_DATA

官方说明这是时间戳冲突导致的，点击 RViz 底部 reset 按钮可清掉旧状态。

15.4 图像相关节点一启动就崩

官方提示这通常与系统里安装了多个 OpenCV 版本有关。

15.5 Missing camera node 'cam_0'

官方建议重新插拔 USB。

15.6 录 bag 时 IMU 或高频里程计丢帧

官方仓库提供了：

• script/rosbag2_qos.yaml

录制时建议：

ros2 bag record -a \
  --qos-profile-overrides-path src/odin_ros_driver/script/rosbag2_qos.yaml \
  -o my_bag

16. 你当前环境下的最简建图命令

16.1 建图前

编辑：

• /home/lcf/catkin_ws/src/odin_ros_driver/config/control_command.yaml

设置：

custom_map_mode: 1

16.2 启动建图

/home/lcf/catkin_ws/runros.sh

16.3 保存地图

cd /home/lcf/catkin_ws/src/odin_ros_driver
./set_param.sh save_map 1

16.4 做重定位

编辑：

• /home/lcf/catkin_ws/src/odin_ros_driver/config/control_command.yaml

设置：

custom_map_mode: 2
relocalization_map_abs_path: "/home/lcf/catkin_ws/src/odin_ros_driver/map/你的目录/你的地图.bin"

然后再次启动：

/home/lcf/catkin_ws/runros.sh

17. 我对官方文档的实用化结论

如果只用一句话总结官方仓库的 ROS2 使用方式：

• 建图：把 custom_map_mode 设为 1，启动驱动，移动设备采图，最后执行 ./set_param.sh save_map 1
• 重定位：把 custom_map_mode 设为 2，设置 relocalization_map_abs_path 指向 .bin 地图，再重新启动驱动
• 启动：在你当前环境里，最省事的方式就是直接运行 /home/lcf/catkin_ws/runros.sh