Orbbec ROS2 SDK 安装问题解决指南

本文档记录了在Ubuntu 22.04上安装和配置Orbbec ROS2 SDK时遇到的常见问题及其解决方案。

🎯 目标

成功安装并运行 Orbbec ROS2 SDK，使 DaBai DCW 等 Orbbec 3D 相机能够在 ROS2 Humble 环境中正常工作。

🔧 系统环境

• 操作系统: Ubuntu 22.04 LTS
• ROS版本: ROS2 Humble
• Python版本: 3.10.12
• 测试设备: DaBai DCW (序列号: CH2J74300BY)

⚠️ 常见问题及解决方案

问题1: Python环境冲突 - ModuleNotFoundError

错误现象

ModuleNotFoundError: No module named 'catkin_pkg'
ModuleNotFoundError: No module named 'em'

编译时显示使用了错误的Python路径：

execute_process(/home/ubuntu22/anaconda3/bin/python3 ...)

根本原因

• 系统中同时安装了 Anaconda 和系统 Python
• PATH 环境变量中 Anaconda 路径优先级高于系统 Python
• ROS2 需要使用系统 Python 而不是 Anaconda Python

解决方案

1. 临时修改 PATH 环境变量：

export PATH="/usr/bin:/usr/local/bin:$PATH"

2. 验证 Python 路径：

which python3
# 应该输出: /usr/bin/python3

3. 安装缺失的依赖：

pip3 install catkin_pkg empy

4. 清理编译缓存：

cd ~/ros_ws
rm -rf build/ install/ log/

问题2: SDK库文件损坏

错误现象

/usr/bin/ld: file format not recognized; treating as linker script
/usr/bin/ld: syntax error

诊断方法

file /path/to/OrbbecSDK_ROS2/orbbec_camera/SDK/lib/x64/libOrbbecSDK.so
# 错误输出: ASCII text, with no line terminators
# 正确输出: ELF 64-bit LSB shared object

根本原因

Git仓库中的二进制文件没有正确下载，导致 libOrbbecSDK.so 只有20字节的文本内容而不是11.8MB的二进制文件。

解决方案

1. 重新克隆仓库：

cd ~/ros_ws/src
rm -rf OrbbecSDK_ROS2
git clone --recursive https://github.com/orbbec/OrbbecSDK_ROS2.git

2. 验证库文件完整性：

ls -la ~/ros_ws/src/OrbbecSDK_ROS2/orbbec_camera/SDK/lib/x64/
# libOrbbecSDK.so 应该约为 11.8MB

问题3: 编译缓存问题

现象

即使解决了Python环境问题，CMake仍然使用缓存的错误配置。

解决方案

cd ~/ros_ws
rm -rf build/ install/ log/
export PATH="/usr/bin:/usr/local/bin:$PATH"
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release

🚀 完整安装步骤

1. 环境准备

# 确保ROS2 Humble已安装
source /opt/ros/humble/setup.bash

# 安装依赖
sudo apt install libgflags-dev nlohmann-json3-dev \
ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins \
ros-${ROS_DISTRO}-compressed-image-transport ros-$ROS_DISTRO-image-publisher \
ros-$ROS_DISTRO-camera-info-manager ros-$ROS_DISTRO-diagnostic-updater \
ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
ros-$ROS_DISTRO-backward-ros libdw-dev

2. 创建工作空间

mkdir -p ~/ros_ws/src
cd ~/ros_ws/src

3. 获取源码

git clone https://github.com/orbbec/OrbbecSDK_ROS2.git

4. 设置Python环境

export PATH="/usr/bin:/usr/local/bin:$PATH"
pip3 install catkin_pkg empy

5. 编译

cd ~/ros_ws
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release

6. 安装udev规则

source ./install/setup.bash
cd ~/ros_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger

🧪 测试验证

1. 检测设备

source ~/ros_ws/install/setup.bash
ros2 run orbbec_camera list_devices_node

2. 启动相机节点

# 根据你的相机型号选择对应的launch文件
ros2 launch orbbec_camera dabai_dcw.launch.py      # DaBai DCW
ros2 launch orbbec_camera gemini_330_series.launch.py  # Gemini 330系列
ros2 launch orbbec_camera astra2.launch.py         # Astra 2

3. 检查话题

ros2 topic list | grep camera
# 应该看到以下话题：
# /camera/color/image_raw
# /camera/depth/image_raw
# /camera/depth/points

4. 检查数据流

ros2 topic hz /camera/color/image_raw
ros2 topic hz /camera/depth/image_raw

5. 获取设备信息

ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo "{}"

📊 可用的ROS2接口

话题 (Topics)

• /camera/color/image_raw - 彩色图像
• /camera/color/camera_info - 彩色相机参数
• /camera/depth/image_raw - 深度图像
• /camera/depth/camera_info - 深度相机参数
• /camera/depth/points - 点云数据

服务 (Services)

• /camera/get_device_info - 获取设备信息
• /camera/get_sdk_version - 获取SDK版本
• /camera/set_laser_enable - 控制激光器
• /camera/set_color_exposure - 设置彩色曝光
• /camera/save_point_cloud - 保存点云

🎮 可视化

# 启动RViz2进行3D可视化
rviz2

在RViz2中添加以下显示项：

• Image显示: /camera/color/image_raw
• Image显示: /camera/depth/image_raw
• PointCloud2显示: /camera/depth/points

🔧 故障排除

如果Python环境问题重现

1. 检查当前Python路径: which python3
2. 重新设置PATH: export PATH="/usr/bin:/usr/local/bin:$PATH"
3. 清理并重新编译

如果库文件损坏

1. 删除并重新克隆仓库
2. 检查文件大小和类型
3. 确保网络连接稳定

如果相机无法检测

1. 检查USB连接
2. 验证udev规则安装
3. 查看dmesg日志: dmesg | tail

📚 支持的设备

• Astra 2
• Astra Mini/Mini Pro
• DaBai DCW
• Femto Bolt/Mega
• Gemini 2/2L/2XL
• Gemini 330系列

🤝 贡献

如果你遇到了其他问题或有改进建议，欢迎提交Issue或Pull Request。

📄 许可证

本项目遵循与Orbbec SDK相同的许可证。

---

注意: 本指南基于实际遇到的问题和解决过程编写，可能不适用于所有环境配置。如有疑问，请参考官方Orbbec ROS2文档。