最近在做一个电力巡检机器人项目，需要在树莓派5上使用 ORBBEC Astra Pro Plus 深度相机，并将数据接入 ROS2 Humble 进行后续的 SLAM 和视觉识别开发。整个过程遇到了不少坑，从硬件识别、驱动编译到 Docker 图形显示，花了整整两天才完全打通。

        网上关于这款相机在树莓派5 + ROS2 环境下的资料非常少，因此把完整的调试过程和踩坑记录整理出来，希望能帮到有同样需求的朋友。

环境概览：

• 硬件：树莓派5（Raspberry Pi 5）+ ORBBEC Astra Pro Plus 深度相机

• 系统：Raspberry Pi OS (Debian Bookworm, 64-bit)

• 容器：Docker + ros:humble-ros-desktop

• 驱动：ros2_astra_camera（ROS2 移植版）

        先说几个意想不到的坑，再说我的完整避坑步骤

避坑指南

一、无法识别到相机

宿主机无法识别

        现象：在树莓派终端执行 lsusb，看不到任何与 Orbbec 相关的设备        

        1.硬件问题

原因	解决方案
USB供电不足（最常见）	Astra Pro Plus 功耗较高，树莓派USB接口供电有限。必须使用带独立供电的USB 3.0 HUB连接相机。
USB线或接口问题	更换高质量USB数据线，尝试插入树莓派不同USB端口（优先蓝色USB 3.0接口）。
硬件故障	将相机连接到其他电脑（Windows/Ubuntu）测试，排除相机本身损坏的可能。
系统未刷新USB总线	重启树莓派或执行 sudo dmesg -w 实时查看插拔日志

        2.软件问题

如果是第一次使用需要检查并安装必要的系统依赖并必须配置 udev 规则（第一次使用尤其关键）

sudo apt update
sudo apt install -y git cmake build-essential libusb-1.0-0-dev libudev-dev
# 创建规则文件
sudo nano /etc/udev/rules.d/56-orbbec-usb.rules

写入以下内容（针对奥比中光通用 Vendor ID）：

SUBSYSTEM=="usb", ATTR{idVendor}=="2bc5", MODE="0666", GROUP="plugdev"

重载规则并触发：

sudo udevadm control --reload-rules
sudo udevadm trigger

然后将相机重新插拔一次，或直接重启树莓派，确保规则生效。

ls -l /dev/bus/usb/*/* | grep 2bc5

输出类似crw-rw-rw- 1 root plugdev 189, 256 Jul 14 12:47 /dev/bus/usb/004/009为成功

Docker容器内无法识别相机

        现象：宿主机 lsusb 已能看到 Orbbec 设备，但进入容器后执行 lsusb 看不到，或相机节点启动时报错 Failed to open device。

原因	解决方案
容器启动时未挂载 /dev 目录	启动容器时必须添加 -v /dev:/dev 参数，将宿主机设备文件映射到容器内。
容器未获得特权模式	启动容器时必须添加 --privileged 参数，赋予容器操作硬件的权限。

只好重新启动docker

docker run -it --privileged \
  --network host \
  -v /dev:/dev \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=:0 \
  --name ros2_humble \
  ros2_humble_with_astra /bin/bash

二、大量依赖缺失

错误1：找不到 catkin

显示：CMake Error: By not providing "Findcatkin.cmake"...

原因：克隆了 ROS1 版本的仓库。
解决：必须使用 ROS2 专用仓库 ros2_astra_camera。

GitHub - orbbec/ros2_astra_camera · GitHub为正确的ros2_astra_camera

错误2：找不到各种依赖

 camera_info_manager image_publisher libglog nlohmann/json.hpp均是我没有的且需要的

sudo apt install -y ros-humble-camera-info-manager
sudo apt install -y ros-humble-image-publisher
sudo apt install -y libgoogle-glog-dev
sudo apt install -y nlohmann-json3-dev

错误3：astra_camera_msgs 未编译

需要先编译消息包，再编译主包：

colcon build --packages-select astra_camera_msgs
colcon build --packages-select astra_camera

三、RViz2 无法启动

现象：Authorization required, but no authorization protocol specifiedqt.qpa.xcb: could not connect to display :0Aborted (core dumped)

原因：树莓派 OS Bookworm 默认使用 Wayland，而 ROS2 的 RViz2 基于 Qt/X11，无法直接在 Wayland 下显示。

sudo raspi-config

使用箭头按键和回车操控
选择  Advanced Options → A6 Wayland → X11 → Finish → 自动重启

echo $XDG_SESSION_TYPE   # 应输出 x11

然后

# 宿主机上执行
xhost +SI:localuser:root

完整避坑流程

1. 硬件连接

        Astra Pro Plus → 独立供电 USB 3.0 HUB → 树莓派5 USB 3.0 口

2. 宿主机配置 USB 权限

sudo nano /etc/udev/rules.d/56-orbbec-usb.rules

内容为

SUBSYSTEM=="usb", ATTR{idVendor}=="2bc5", MODE="0666", GROUP="plugdev"

ctrl+X，Y，回车

sudo udevadm control --reload-rules && sudo udevadm trigger

3.切换树莓派到 X11 会话

sudo raspi-config

选择  Advanced Options → A6 Wayland → X11 → Finish → 自动重启

4. 启动 Docker 容器

xhost +SI:localuser:root
docker run -it --privileged \
  --network host \
  -v /dev:/dev \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=:0 \
  -e QT_X11_NO_MITSHM=1 \
  -e QT_QPA_PLATFORM=xcb \
  --name ros2_humble \
  ros:humble-ros-base /bin/bash

5. 容器内编译驱动

mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
git clone https://gitclone.com/github.com/orbbec/ros2_astra_camera.git
cd ~/ros2_ws

# 安装依赖
sudo apt update
sudo apt install -y ros-humble-camera-info-manager \
  ros-humble-image-publisher \
  libgoogle-glog-dev \
  nlohmann-json3-dev \
  libuvc-dev

# 编译
colcon build --packages-select astra_camera_msgs
colcon build --packages-select astra_camera

6. 加载环境并启动相机

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch astra_camera astro_pro_plus.launch.xml

7. 新终端进入容器并可视化

        进入新的终端输入

# 宿主机新终端
docker exec -it ros2_humble /bin/bash

#不要跟上一个一起复制
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
rviz2

8.rivz的设置

（1）Fixed Frame 设为 camera_link（有个小箭头）

（2）Add → By topic → /camera/color/image_raw 添加 Image 显示

（3）Add → By topic → /camera/color/camera/color，双击 Image 添加彩色图像显示。

（4）Add → By topic → /camera/depth/points 的 PointCloud2 点云显示。