拿到D435i之后我在Ubuntu 22.04上鼓捣librealsense驱动的过程远比预想中曲折。网上教程不少但大多数是 Ubuntu 18.04 或 20.04 时代的产物直接照搬到 22.04 上不是缺依赖就是编译不过甚至装好了却无法识别设备。这篇文章把我从零开始梳理出的完整流程沉淀下来覆盖从源码编译 librealsense、配置 udev 规则到让 pyrealsense2 在 Python 里顺畅取流的每一个核心环节每一步都讲清楚“为什么这么做”最后附上常见问题排查表。适合刚入手 D435i、准备在 Ubuntu 22.04 上做视觉开发或者机器人感知的同学参考也适合想把同款流程复用到其他 RealSense 相机的朋友。1. 准备工作与环境确认1.1 为什么先确认内核和系统版本Ubuntu 22.04 和之前版本最大的区别之一是内核版本直接跳到了 5.15 甚至 5.19。而 RealSense 深度相机在 Linux 下依赖内核的uvcvideo模块来驱动 RGB 图像同时通过内核的 USB 协议栈访问深度和 IMU 数据。内核版本不同uvcvideo的行为会有差异这直接决定了你在编译 librealsense 时要不要启用FORCE_RSUSB_BACKEND。我第一次安装时忽略了这个细节直接按旧教程走了默认的内核后端结果相机能识别但realsense-viewer一打开深度流就报“Frame didnt arrive within 5 seconds”折腾了大半天。后来意识到 5.15 内核下uvcvideo对 D435i 的元数据传递支持不够稳定改用 RSUSB 后端后才彻底解决。所以在开始之前先花两分钟检查基础环境能省掉后面一大堆排查时间。执行下面三条命令lsb_release -a uname -r lspci | grep -i usblsb_release确认系统版本是 22.04uname -r确认内核版本lspci则是看一眼板上 USB 控制器的情况特别是有没有 USB 3.0 控制器。D435i 的深度计算和人脸追踪都对带宽要求高USB 2.0 口虽然能出图像但帧率和稳定性都会打折扣如果条件允许务必插在主机背面的 USB 3.0 口上。1.2 安装编译依赖缺什么补什么librealsense 是一个 C 项目从源码编译需要一整套构建工具链。很多新手在这里栽跟头比如cmake版本不够、缺少libudev-dev导致 udev 规则编译不过、缺libglfw3-dev导致示例程序跑不起来。在 Ubuntu 22.04 上我建议一次性把依赖装全避免编译到一半才发现缺东西又重新来一遍sudo apt update sudo apt install -y git cmake build-essential pkg-config \ libusb-1.0-0-dev libglfw3-dev libgtk-3-dev \ libudev-dev libssl-dev python3-dev python3-pip \ libxinerama-dev libxcursor-dev libxi-dev稍微解释一下每个包的作用libusb-1.0-0-devlibrealsense 通过它直接操作 USB 设备在启用 RSUSB 后端时是核心依赖没有它编译会直接报错。libglfw3-dev和libgtk-3-dev编译realsense-viewer图形界面需要的窗口管理和 OpenGL 上下文库。libudev-dev用于生成动态 udev 规则处理 USB 设备的权限问题。python3-dev和python3-pip编译 pyrealsense2 Python 绑定时需要 Python 头文件后续安装 Python 依赖也会用到。装完之后顺手把系统更新到最新也可以执行一下sudo apt upgrade把内核补丁和 USB 驱动相关的更新打上。这里有一个经验如果你用的是一个刚装完的纯净系统apt upgrade之后最好重启一次保证内核版本统一再往后编译。2. librealsense 源码编译安装2.1 源码编译 vs 预编译包选哪个librealsense 的安装方式有几种apt直接装 Intel 官方仓库的预编译包、下载 Release 二进制包、从源码编译。很多教程默认推荐apt但在 Ubuntu 22.04 上我强烈建议有动手能力的同学直接走源码编译。原因有三点apt 仓库里的版本通常滞后RealSense 官方仓库的版本更新较快但如果你装的是 22.04 自带的源版本可能停留在很旧的阶段容易跟 pyrealsense2 新版本不匹配。源码编译可以选择启用FORCE_RSUSB_BACKEND这个选项在预编译包里是不可控的而它恰恰是解决内核兼容性问题的关键。编译时可以直接带上 Python 绑定让 pyrealsense2 和你编译出来的 librealSense 版本完全对应避免 pip 安装的 wheel 和系统驱动版本错位导致的一系列诡异问题。当然如果你只是临时用一下、不想折腾直接pip install pyrealsense2也能跑但很大概率你会在后面的开发中遇到版本坑。所以要走得长远源码编译是值得的。2.2 克隆源码与版本选择源码编译的第一步是拿到正确版本的源代码。建议不要直接拉master分支因为开发分支经常有 API 变动可能引入了未稳定的功能给后面的编译增加不必要的麻烦。我一般习惯拉取最新的 release tag。cd ~ git clone https://github.com/IntelRealSense/librealsense.git cd librealsense git checkout v2.54.2v2.54.2是我写这篇文章时比较稳定的一个版本你可以在 GitHub 的 Release 页面查看当前最新稳定版。这里有个小技巧如果你后面还要用 ROS 或 ROS2 的realsense-ros功能包最好先查一下它依赖的是哪个 librealsense 版本然后让两者的版本保持一致否则运行时可能出现 ABI 不兼容的问题。2.3 CMake 配置里的关键参数与编译过程进入源码目录后创建一个 build 目录来配置编译cd ~/librealsense mkdir build cd build cmake .. \ -DCMAKE_BUILD_TYPERelease \ -DFORCE_RSUSB_BACKENDON \ -DBUILD_PYTHON_BINDINGSbool:true \ -DBUILD_EXAMPLEStrue \ -DCMAKE_INSTALL_PREFIX/usr/local这里的每个参数背后都是有讲究的逐个说一下-DFORCE_RSUSB_BACKENDON是整个安装最关键的一项。它让 librealsense 不通过内核的uvcvideo驱动而是直接用 libusb 去读写 USB 设备。这么做有两个好处一是绕开了 5.15 内核上uvcvideo对 D435i 元数据支持不稳定、深度流偶发超时的问题二是如果你机器上还插着其他使用uvcvideo的摄像头两者之间不会互相干扰。代价是 CPU 占用会稍微高一点但对现代处理器来说可以忽略不计。-DBUILD_PYTHON_BINDINGSbool:true是在编译 C 库的同时构建 Python 绑定。注意这里的写法比较特殊不是-DBUILD_PYTHON_BINDINGSON而是bool:true这是 librealsense 的 CMake 配置里对 Boolean 参数的特殊处理风格。如果这个参数不起作用后面生成的pyrealsense2.so文件不会出现所以编译完记得检查。-DCMAKE_INSTALL_PREFIX/usr/local指定安装路径按理说默认路径也可以但显式指定/usr/local能保证头文件和库文件被系统正确找到。配置完之后开始编译。默认make会调用所有 CPU 核心但 D435i 相关的模块编译时内存占用不低尤其是 CMake 配置阶段如果内存不够大建议限制一下并行任务数make -j$(($(nproc) - 2))比如 8 核机器就用 6 个并行任务避免内存被吃满。编译过程需要几分钟到十几分钟不等取决于机器配置。编译完成后安装sudo make install sudo ldconfigldconfig这一步很容易被忽略但如果不执行系统可能找不到新安装的动态链接库运行时就会报librealsense2.so: cannot open shared object file之类的错误。2.4 编译后的基础验证编译安装完成后先跑一个简单的命令验证核心库是否正常rs-enumerate-devices如果能看到类似下面的输出说明驱动核心已经工作正常Device info: Name : Intel RealSense D435I Serial Number : 8xxxxxxxxx Firmware Version : 05.13.00.50 ...如果提示no device connected先别慌往下看第 3 章的 udev 规则大概率是权限问题。3. 配置 udev 规则与硬件权限3.1 为什么插上相机却打不开把 D435i 插到电脑上后lsusb能看到设备但rs-enumerate-devices就是找不到这种情况十有八九是 udev 规则没配好。Linux 下普通用户默认没有权限直接访问bus/usb下的设备节点。librealsense 需要向控制传输端点发送 UVC 控制请求如果权限不足请求会被拒绝设备自然无法打开。这和 CH340、FT232R 这类 USB 转串口芯片的驱动逻辑是一样的——都需要 udev 规则来给设备节点赋予读写权限。很多玩嵌入式开发板的人应该都遇到过 CH340 在 Linux 下Permission denied的问题原理完全一致。3.2 安装和重载 udev 规则librealsense 源码仓库里已经带了一份官方 udev 规则文件路径是config/99-realsense-libusb.rules。直接把它复制到系统 udev 规则目录下cd ~/librealsense sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/然后重新加载规则并触发sudo udevadm control --reload-rules sudo udevadm trigger如果你不想手动复制也可以直接执行源码里的脚本sudo ./scripts/setup_udev_rules.sh这个脚本做的事和上面是一样的只是多了一步解压和安装 Intel RealSense 官方提供的补丁固件信息。重载规则之后拔掉相机 USB 线重新插一次再执行rs-enumerate-devices正常情况下就能列出设备了。这里有一个排查小技巧如果重新插拔后仍然不行可以用dmesg | tail -20看一下内核日志如果看到usb 3-1: Permission denied之类的信息基本可以确认是 udev 权限问题检查规则文件的命名和内容是否正确。4. pyrealsense2 Python 接口安装4.1 pyrealsense2 的三种获取方式pyrealsense2 是 librealsense 的 Python 绑定库有了它才能在 Python 里调用 D435i 的深度流和 IMU 数据。获取方式主要有三种pip 安装预编译包pip install pyrealsense2是最简单的方式适合快速验证。但这个 wheel 自带了一份动态库和你系统上源码编译的 librealsense 是相互独立的两者版本可能不一致如果后面要混合使用 C 和 Python容易出现问题。apt 安装sudo apt install python3-pyrealsense2前提是你配置了 Intel 官方源。源码编译在编译 librealsense 时直接启用-DBUILD_PYTHON_BINDINGSbool:true生成的 Python 绑定会和你编译的 C 库完全对应。我的建议是如果你已经走到了源码编译这步就一次性把 Python 绑定也编译了省得后面再折腾版本匹配。如果只是入门学习、不想编译 C 库那直接 pip 装一个反而更快。4.2 检查编译生成的 Python 绑定如果你之前已经按照第 2 章的方式编译并启用了 Python 绑定那么在~/librealsense/build/wrappers/python/目录下应该能找到pyrealsense2的构建产物。有些时候CMake 阶段配置了但编译阶段却没有生成 Python 模块这是因为 Python 绑定的构建需要python3-dev包提前装好否则 CMake 会静默跳过。如果发现没有生成回到第 1 章把python3-dev装上然后重新执行一次cmake和make。把编译好的 Python 模块安装到系统环境cd ~/librealsense/build/wrappers/python sudo pip install .或者更直接一点把编译产物的路径加到 Python 路径里export PYTHONPATH~/librealsense/build/wrappers/python:$PYTHONPATH但这种方式只对当前终端会话有效重启终端就失效了所以还是建议用pip install .装到 site-packages 里。安装完成后再验证一下python3 -c import pyrealsense2 as rs; print(rs.__version__)如果能打印版本号说明 pyrealsense2 已经成功导入。如果报错ModuleNotFoundError: No module named pyrealsense2先检查一下你是不是在虚拟环境里如果是确保虚拟环境用的 Python 版本和编译时一致。4.3 Python 接口的版本一致性说明这里多说一句版本一致性的问题。我遇到过不少同学C 编译了一个版本然后又用 pip 装了一个最新版 pyrealsense2结果 Python 里创建的rs.pipeline和 C 代码跑的驱动是两套东西最后在 ROS 里调用时出现各种莫名奇妙的段错误。如果你打算在 Python 和 C 之间混合开发务必让 pyrealsense2 与 librealSense 的版本完全一致。源码编译就是保证这一点最可靠的方式。检查版本是否一致可以在 Python 里打印rs.__version__再对比rs-enumerate-devices输出版本信息里对应的库版本号两者应保持一致。5. 实际取流验证与基础 Demo5.1 用 realsense-viewer 做可视化验证在进入 Python 编程之前先用官方可视化工具确认整条链路是通的这一步非常省时。如果你在 CMake 阶段开启了-DBUILD_EXAMPLEStrue编译产物里会有一个realsense-viewercd ~/librealsense/build ./tools/realsense-viewer/realsense-viewer界面打开后左侧会列出检测到的设备。点击 D435I 图标然后在右侧打开 Depth 和 Color 模块的开关应该能看到实时深度图和彩色图。深度图里近处物体偏红、远处物体偏蓝这是 D435i 默认的深度着色方案。在 viewer 里还可以顺手验证 IMU把左侧的 Accelerometer 和 Gyroscope 模块打开移动相机可以看到三轴加速度和角速度数据在跳动。如果这两个数据正常说明 D435i 的 IMU 也是好的后面在 Python 里取 IMU 数据就放心了。如果 viewer 打开后画面黑屏或者深度图是花屏大概率是 USB 带宽不够。D435i 的深度流和彩色流同时跑对 USB 3.0 的带宽占用很大如果插在 USB 2.0 口上会出现数据断流、花屏甚至找不到设备的现象。换一个 USB 3.0 口或者减少分辨率帧率问题通常会消失。5.2 编写第一个 Python 取流脚本可视化验证通过之后就可以用 Python 写一个最简单的取流脚本了。这里我贴一个非常实用的 Demo同时取深度、彩色和 IMU 数据import pyrealsense2 as rs import cv2 import numpy as np # 创建 pipeline pipeline rs.pipeline() config rs.config() # 启用深度流和彩色流 config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30) config.enable_stream(rs.stream.color, 640, 480, rs.format.bgr8, 30) # 启动 pipeline profile pipeline.start(config) # 创建对齐对象将深度图对齐到彩色图视角 align rs.align(rs.stream.color) try: while True: # 等待新的一帧数据 frames pipeline.wait_for_frames() aligned_frames align.process(frames) # 获取对齐后的深度图和彩色图 depth_frame aligned_frames.get_depth_frame() color_frame aligned_frames.get_color_frame() if not depth_frame or not color_frame: continue # 转成 numpy 数组 depth_image np.asanyarray(depth_frame.get_data()) color_image np.asanyarray(color_frame.get_data()) # 深度图着色显示 depth_colormap cv2.applyColorMap( cv2.convertScaleAbs(depth_image, alpha0.03), cv2.COLORMAP_JET ) # 拼接显示 images np.hstack((color_image, depth_colormap)) cv2.imshow(D435i Demo, images) if cv2.waitKey(1) 0xFF ord(q): break finally: pipeline.stop() cv2.destroyAllWindows()这段代码有几点值得注意rs.align(rs.stream.color)是深度图对齐到彩色图的关键。D435i 的深度传感器和彩色传感器物理位置不同看到的画面会有视差对齐之后深度图和彩色图的像素才能一一对应。如果你要做目标检测之后取深度值这一步几乎必做。depth_image的类型是uint16单位是毫米直接显示会是一团蓝色所以用cv2.convertScaleAbs(depth_image, alpha0.03)做了一下尺度缩放。pipeline.stop()必须写在finally里否则程序崩溃后相机资源没有被释放下一次运行可能会提示设备忙。5.3 获取 IMU 数据的正确姿势D435i 和普通 D435 最大的区别就是多了 IMU 模块能同时输出三轴加速度和三轴角速度。取 IMU 数据和取图像流不太一样它不是靠wait_for_frames()拿到的而是通过motion_frame类型单独读取。一个简单的参考代码如下imu_pipeline rs.pipeline() imu_config rs.config() imu_config.enable_stream(rs.stream.accel) imu_config.enable_stream(rs.stream.gyro) imu_profile imu_pipeline.start(imu_config) try: for _ in range(100): frames imu_pipeline.wait_for_frames() accel_frame frames.first_or_default(rs.stream.accel) gyro_frame frames.first_or_default(rs.stream.gyro) if accel_frame and gyro_frame: accel_data accel_frame.as_motion_frame().get_motion_data() gyro_data gyro_frame.as_motion_frame().get_motion_data() print(fAccel: {accel_data.x:.4f}, {accel_data.y:.4f}, {accel_data.z:.4f}) print(fGyro: {gyro_data.x:.4f}, {gyro_data.y:.4f}, {gyro_data.z:.4f}) finally: imu_pipeline.stop()需要记住的一点是IMU 数据默认的坐标系遵循右手定则X 轴向右、Y 轴向上、Z 轴朝外。不同安装方向会导致数据范围差异调试时可以用这个姿态确认坐标系方向是否正确。6. 常见问题与排查技巧实录6.1 编译阶段问题速查我把自己在 Ubuntu 22.04 上遇到过的编译问题整理成了一张表方便你快速定位问题现象可能原因解决方法CMake 报Could not find GLFW缺少 OpenGL 相关库sudo apt install libglfw3-dev libgtk-3-dev libxinerama-dev libxcursor-dev libxi-dev编译时提示fatal error: libudev.h: No such file or directory缺少 udev 开发头文件sudo apt install libudev-devCMake 配置后 Python 绑定没有生成缺少 Python 开发头文件sudo apt install python3-dev重新 cmake 再 makemake 过程中内存溢出或卡死-j并行任务数过多用make -j$(($(nproc) - 2))限制并行度rs-enumerate-devices提示找不到库动态库链接未刷新sudo ldconfig编译阶段的问题相对好排查基本都在依赖缺失这个圈子里对照表格一步步补就能解决。6.2 运行阶段常见问题运行阶段的问题更多样我挑几个高频的展开说问题一相机插上之后rs-enumerate-devices找不到设备。可能性很多按优先级排查顺序是先看lsusb是否能看到8086:0b3a这个 IDD435i 的 USB Vendor ID 是 8086看不到说明 USB 识别有问题能看到但 rs 工具找不到就检查 udev 规则是否生效再不行就试着换一个 USB 口很多时候是主板 USB 3.0 控制器和相机兼容性的问题。问题二深度画面花屏或帧率掉得厉害。这是典型的 USB 带宽不足。D435i 在 640x48030fps 下深度加彩色一起跑理论带宽需求接近 400 Mbps如果经过 USB 2.0 Hub 或者主板上的弱供电口就会出现花屏。解决思路是尽量插到主板后置 USB 3.0 口不要通过延长线或者前置面板的 USB 口同时降低分辨率帧率试试比如 640x36015fps。问题三Python 里pipeline.start()报RuntimeError: Couldnt resolve requests。这个错误通常出现在配置流的时候启用的分辨率或帧率组合不是设备支持的。D435i 对分辨率帧率的支持矩阵在官方文档里有建议先用rs-enumerate-devices查看设备支持的模式rs-enumerate-devices | grep -A 5 Stream Profile然后根据输出调整 Python 配置而不是随意填一个值。问题四深度图正常但彩色图全黑。D435i 的彩色传感器是一个独立的 OV2740 摄像头如果它被其他程序占用比如系统相机应用彩色流就会取不到数据。排查方法很简单关闭所有用到摄像头的应用然后重新运行脚本。问题五使用过程中设备发热严重偶尔掉线。D435i 工作时功耗不低长时间高负载运行会发热。如果设备掉线大概率是过热保护。解决方法是不要一直满载跑控制连续取流时间或者加一个主动散热风扇。6.3 关于标定与后续扩展驱动安装成功只是第一步真正用到项目中还需要注意相机标定。D435i 出厂时已经做了内参标定但对于精度要求高的场景比如机械臂抓取、SLAM 建图建议自己重新标定一次深度和彩色内参以及 IMU 与相机的外参。标定工具可以用 Intel 官方推荐的rs-calibration也可以直接用 OpenCV 的棋盘格标定流程。前者不负众望地解决了 D435i 的深度畸变问题后者则更通用适合自己控制流程。至于后续扩展方向最常用的三条路径是一是配合 ROS/ROS2 使用realsense-ros发布相机数据方便接入机器人上下层二是用 Open3D 或 PCL 把深度图转成点云做三维重建三是在机械臂抓取项目里用rs.pipeline实现手眼标定和位姿估计。只要驱动和 Python 绑定这关过了后面这些方向都有成熟方案可以套用。7. 一点实操体会在整个折腾过程中我最大的体会是驱动安装本身不难难的是搞清楚每一步为什么这么做。FORCE_RSUSB_BACKEND这个参数如果不理解它的作用遇到深度流超时的时候你根本不知道从哪里下手。同样udev规则这件事看着简单但它是所有 USB 设备在 Linux 下可用的前提不只是 D435i 如此CH340、FT232R、J-Link 这类工具其实都是同一个逻辑。所以如果你准备入手 D435i我的建议是第一次装驱动不要图省事直接 pip 一把梭耐下心来走一遍源码编译的流程。这个过程虽然多花几十分钟但它会逼着你把整个软件栈的依赖关系理清楚后面遇到任何诡异问题时你排查起来会比别人快十倍。哪怕这套流程跑完之后你把编译目录删掉改用 apt 或者 pip 装一个稳定版本也比一开始就盲装要心里有底得多。