610 lines
13 KiB
Markdown
610 lines
13 KiB
Markdown
# 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 逻辑本质上是两步：
|
||
|
||
```bash
|
||
source /home/lcf/catkin_ws/install/setup.bash
|
||
ros2 launch odin_ros_driver odin1_ros2.launch.py
|
||
```
|
||
|
||
你当前环境里已经额外有一个一键脚本：
|
||
|
||
```bash
|
||
/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 访问权限问题：
|
||
|
||
```bash
|
||
sudo vim /etc/udev/rules.d/99-odin-usb.rules
|
||
```
|
||
|
||
写入：
|
||
|
||
```bash
|
||
SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
sudo udevadm control --reload
|
||
sudo udevadm trigger
|
||
```
|
||
|
||
### 6.3 可能遇到的 USB 权限问题
|
||
|
||
如果启动时报：
|
||
|
||
- `LIBUSB_ERROR_ACCESS`
|
||
- `LIBUSB_ERROR_BUSY`
|
||
|
||
优先检查：
|
||
|
||
1. 是否已经添加 udev 规则
|
||
2. 当前用户是否在 `plugdev` 组
|
||
3. 是否有旧的 `host_sdk_sample` 进程还在占用设备
|
||
|
||
可用命令：
|
||
|
||
```bash
|
||
ps aux | grep host_sdk_sample
|
||
killall host_sdk_sample
|
||
```
|
||
|
||
## 7. 你当前环境下的推荐使用方式
|
||
|
||
### 7.1 一键启动
|
||
|
||
```bash
|
||
/home/lcf/catkin_ws/runros.sh
|
||
```
|
||
|
||
该命令会自动：
|
||
|
||
1. 加载 `/opt/ros/humble/setup.bash`
|
||
2. 加载 `/home/lcf/catkin_ws/install/setup.bash`
|
||
3. 执行：
|
||
|
||
```bash
|
||
ros2 launch odin_ros_driver odin1_ros2.launch.py
|
||
```
|
||
|
||
### 7.2 只加载环境
|
||
|
||
```bash
|
||
source /home/lcf/catkin_ws/runros.sh
|
||
```
|
||
|
||
### 7.3 只开一个干净 shell
|
||
|
||
```bash
|
||
/home/lcf/catkin_ws/runros.sh --shell
|
||
```
|
||
|
||
## 8. Odin1 的三种工作模式
|
||
|
||
官方通过 `config/control_command.yaml` 中的 `custom_map_mode` 控制工作模式：
|
||
|
||
- `0`：里程计模式
|
||
- `1`：SLAM 建图模式
|
||
- `2`：重定位模式
|
||
|
||
### 8.1 里程计模式
|
||
|
||
```yaml
|
||
custom_map_mode: 0
|
||
```
|
||
|
||
特点：
|
||
|
||
- `map` 和 `odom` 视为同一位姿
|
||
- 不进行回环建图
|
||
- 适合只看实时位姿和点云
|
||
|
||
如果里程计漂移，官方建议在运行过程中执行：
|
||
|
||
```bash
|
||
cd /home/lcf/catkin_ws/src/odin_ros_driver
|
||
./set_param.sh algo_reset 1
|
||
```
|
||
|
||
### 8.2 SLAM 建图模式
|
||
|
||
```yaml
|
||
custom_map_mode: 1
|
||
```
|
||
|
||
特点：
|
||
|
||
- 在里程计模式基础上增加回环检测和地图保存能力
|
||
- 启动后自动开始建图并缓存地图数据
|
||
- 地图不会自动保存，必须手动触发保存
|
||
|
||
### 8.3 重定位模式
|
||
|
||
```yaml
|
||
custom_map_mode: 2
|
||
```
|
||
|
||
特点：
|
||
|
||
- 基于已有地图重新定位
|
||
- 必须指定地图文件路径
|
||
- 成功后会发布 `map -> odom` 的 TF
|
||
|
||
## 9. ROS2 下怎么建图
|
||
|
||
这是你最关心的部分，按下面流程做。
|
||
|
||
### 9.1 第一步：修改配置为建图模式
|
||
|
||
编辑实际运行中的配置文件：
|
||
|
||
- `/home/lcf/catkin_ws/src/odin_ros_driver/config/control_command.yaml`
|
||
|
||
至少确认这些字段：
|
||
|
||
```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`
|
||
- 是否显示路径
|
||
|
||
如果你想更明显地看路径，可考虑：
|
||
|
||
```yaml
|
||
showpath: 1
|
||
```
|
||
|
||
### 9.2 第二步：启动驱动
|
||
|
||
推荐直接执行：
|
||
|
||
```bash
|
||
/home/lcf/catkin_ws/runros.sh
|
||
```
|
||
|
||
或者手动执行：
|
||
|
||
```bash
|
||
source /home/lcf/catkin_ws/install/setup.bash
|
||
ros2 launch odin_ros_driver odin1_ros2.launch.py
|
||
```
|
||
|
||
### 9.3 第三步：移动设备开始建图
|
||
|
||
驱动启动后，Odin1 会自动开始建图并缓存地图数据。
|
||
|
||
建议操作方式：
|
||
|
||
- 使用 USB3.0 连接
|
||
- 启动后缓慢移动设备
|
||
- 尽量覆盖你希望建图的区域
|
||
- 尽量回到已走过区域，帮助回环闭合
|
||
- 场景中应有足够几何/纹理特征
|
||
|
||
### 9.4 第四步：保存地图
|
||
|
||
建图完成后，进入包目录：
|
||
|
||
```bash
|
||
cd /home/lcf/catkin_ws/src/odin_ros_driver
|
||
```
|
||
|
||
执行官方命令：
|
||
|
||
```bash
|
||
./set_param.sh save_map 1
|
||
```
|
||
|
||
`set_param.sh` 的本质是向 `/tmp/odin_command.txt` 写入：
|
||
|
||
```bash
|
||
set save_map 1
|
||
```
|
||
|
||
主驱动会读取这个命令并调用 SDK 保存地图。
|
||
|
||
### 9.5 第五步：找到保存出来的地图文件
|
||
|
||
配置文件里写明：
|
||
|
||
```yaml
|
||
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 第六步：重复保存
|
||
|
||
官方说明允许重复执行：
|
||
|
||
```bash
|
||
./set_param.sh save_map 1
|
||
```
|
||
|
||
但两次保存之间建议至少间隔 **5 秒**。
|
||
|
||
## 10. 重定位怎么用
|
||
|
||
官方重定位文档单独给了更详细说明，这里按实用方式整理。
|
||
|
||
### 10.1 自动重定位
|
||
|
||
修改配置：
|
||
|
||
```yaml
|
||
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 指定初始位姿重定位
|
||
|
||
如果你知道大概起点位置，可设置：
|
||
|
||
```yaml
|
||
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°：
|
||
|
||
```yaml
|
||
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. 启动：
|
||
|
||
```bash
|
||
/home/lcf/catkin_ws/runros.sh
|
||
```
|
||
|
||
3. 缓慢移动 Odin1，采完整个区域
|
||
4. 返回包目录保存地图：
|
||
|
||
```bash
|
||
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. 再执行：
|
||
|
||
```bash
|
||
/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`
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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 在复杂网络环境下容易因为广播导致阻塞，从而出现设备断开。
|
||
|
||
如果不需要跨设备通信，可先尝试：
|
||
|
||
```bash
|
||
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`
|
||
|
||
录制时建议：
|
||
|
||
```bash
|
||
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`
|
||
|
||
设置：
|
||
|
||
```yaml
|
||
custom_map_mode: 1
|
||
```
|
||
|
||
### 16.2 启动建图
|
||
|
||
```bash
|
||
/home/lcf/catkin_ws/runros.sh
|
||
```
|
||
|
||
### 16.3 保存地图
|
||
|
||
```bash
|
||
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`
|
||
|
||
设置：
|
||
|
||
```yaml
|
||
custom_map_mode: 2
|
||
relocalization_map_abs_path: "/home/lcf/catkin_ws/src/odin_ros_driver/map/你的目录/你的地图.bin"
|
||
```
|
||
|
||
然后再次启动：
|
||
|
||
```bash
|
||
/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`
|
||
|