1. 写在前面为什么D435i在Ubuntu 22.04上这么“玄学”如果你手里有一块Intel RealSense D435i想在Ubuntu 22.04上跑起来第一反应肯定是去GitHub拉librealsense源码编一版然后pip install pyrealsense2收工。但真正动手你会发现这条路比想象中坎坷CMake版本不兼容、内核模块冲突、Python接口对不上、权限问题导致设备列表为空……我在连续装了三台不同配置的机器、踩完一圈坑之后决定把整个流程梳理成这篇完整攻略。先说结论D435i在Ubuntu 22.04下完全可以稳定运行但有两个关键前提——内核UVC模块要正确处理librealsense和pyrealsense2的版本必须严格匹配。只要这两点不出问题整个驱动链路基本就稳了。这篇攻略会从环境准备、依赖安装、源码编译、Python接口配置到常见问题排查完整走一遍适合刚接触RealSense的初学者也适合被驱动折腾过的老手查漏补缺。D435i本质上是“RGB相机双目红外相机IMU”三合一设备其中深度计算依赖相机硬件的IR传感器和内部的深度处理芯片。Ubuntu系统需要通过librealsense才能和它通信而pyrealsense2则是librealsense的Python绑定。两者关系可以理解为librealsense是底层驱动和SDKpyrealsense2是SDK的Python API。所以安装路线也很清晰——先装底层的librealsense再配置Python环境。整个安装过程我踩过不少坑比如编译时缺libusb、运行时提示Permission denied、rs-enumerate-devices能列出设备但Python报错找不到设备等等。这些问题的根因和解决方案我在后面的章节会逐一拆解。如果你现在正好卡在某个环节可以直接跳到对应的排查部分。2. 装机前的环境准备依赖、内核和固件一个都不能少2.1 确认系统版本和内核状态Ubuntu 22.04的官方内核版本是5.15系列librealsense官方对这个内核版本的支持已经比较完善。但很多人的机器是后续自己升过内核的比如升到5.19甚至6.x这时候就要格外小心因为新内核里UVC模块的改动可能会影响D435i的识别。先运行下面命令确认当前的系统版本和内核版本lsb_release -a uname -a如果内核版本在5.13到5.19之间通常问题不大。如果超过6.0建议要么降级内核要么使用librealsense源码中最新的release分支因为新版驱动会针对新内核做兼容适配。另外一定要确认系统已安装build-essential和cmake。我在一台新装的Ubuntu 22.04上编译时就因为缺cmake导致反复报CMake Error后来才发现是最小化安装连构建工具链都没带全。执行以下命令把基础工具装上sudo apt update sudo apt install -y build-essential cmake git pkg-config这里有个小细节Ubuntu 22.04软件源里的CMake版本是3.22.x而librealsense要求CMake 3.8所以一般不用额外升级CMake。如果编译时遇到CMake版本过低的报错再用Kitware官方源升级到3.24即可。2.2 安装librealsense的编译依赖librealsense编译时需要一堆开发库包括libusb、libudev、libgl、libdrm等。直接通过apt安装是最稳妥的方式sudo apt install -y libusb-1.0-0-dev libudev-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev libx11-dev libxrandr-dev libxi-dev libssl-dev libdw-dev如果需要图形化工具比如realsense-viewer还需要安装GTK和OpenGL相关的库sudo apt install -y libgtk-3-dev libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev我个人的建议是直接把这些都装上省得编译到中途发现缺库又要回头补装。编译librealsense依赖OpenGL时最容易出问题的是libgl1-mesa-dev如果提示找不到这个包可能需要先执行sudo apt update刷新软件源。2.3 UVC内核模块D435i能否被正确识别的关键这是最容易踩坑的环节。Linux内核自带一个uvcvideo模块负责通用USB视频设备。D435i本身也是UVC设备所以内核模块能识别到它但默认的uvcvideo可能无法完全开启深度和IMU的功能。librealsense官方的做法是编译一个打了补丁的uvcvideo内核模块替换系统自带的模块。不过这是个双刃剑。如果替换不当可能会导致系统原有的摄像头比如笔记本内置摄像头无法工作。所以我不建议一上来就替换内核模块而是采用librealsense的运行时补丁方案也就是通过scripts/patch-realsense-uvc.sh脚本给当前内核源码打补丁并重新编译模块。实际操作中如果你只是需要读取深度图、彩色图和IMU数据不追求极致性能那么先不替换内核模块直接编译librealsense也可以工作。D435i在默认UVC驱动下能以30fps输出深度流和彩色流IMU也能获取数据。但如果需要更高帧率、更低的延迟或者多个相机同时工作那就必须替换UVC模块。我的建议是先不替换内核模块直接编译librealsense跑通全流程后再决定是否折腾UVC补丁。这样能把变量范围控制到最小后续出了问题也容易定位。2.4 固件版本很多人忽略的“隐藏故障点”D435i的固件版本直接影响驱动行为。librealsense源码中带了一个固件更新工具位于scripts/update-uvc-firmware.sh。我在实际使用中遇到过这样一个情况相机能识别但开启深度流时总是报错后来用rs-fw-update查看才发现固件版本太老和当前librealsense不兼容。检查固件版本的命令是rs-enumerate-devices | grep Firmware如果固件版本过旧低于5.12建议升级固件。升级方法支持通过USB连接方式在librealsense的build目录下运行./tools/fw-update/rs-fw-update -f 文件名.bin固件文件可以从RealSense官方GitHub仓库的firmware目录下载。升级过程中千万不能断电或者拔USB线否则相机有可能变砖。变砖后虽然能用恢复模式救回来但过程非常麻烦我亲眼见过同事把相机刷成无法识别的状态最后靠Intel的恢复工具才搞定。3. 编译安装librealsense从源码到命令行工具3.1 克隆源码与选择版本librealsense的源码托管在GitHub上克隆命令是git clone https://github.com/IntelRealSense/librealsense.git cd librealsense这里要注意分支选择。master分支通常是最新的开发版功能多但稳定性无法保证。我推荐使用最新的release标签版本比如v2.54.2或更高版本可以通过以下命令查看所有标签git tag git checkout v2.54.2版本选择的原则是和你的pyrealsense2版本严格对应。比如你计划安装pyrealsense22.54.2那么librealsense源码也应该切到v2.54.2。两个版本不一致编译可能能通过但运行时会出现各种诡异的问题比如Python接口报找不到符号、或者rs2::error等。我第一次装的时候就没注意这个问题源码用了最新的master分支pyrealsense2装了pip上的最新版结果Python里调用pipelines.start()时报了个莫名其妙的段错误折腾了小半天才发现是版本不匹配。从那以后我再也不混着用了。3.2 CMake配置和编译参数在源码根目录下创建build目录执行CMake配置mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DFORCE_RSUSB_BACKENDtrue -DBUILD_PYTHON_BINDINGSfalse几个关键参数解释一下FORCE_RSUSB_BACKENDtrue强制使用librealsense自带的USB后端而不依赖内核UVC模块。这个选项可以绕过uvcvideo模块的补丁问题对Ubuntu 22.04非常友好推荐开启。开启后即使不替换内核模块也能稳定使用D435i。BUILD_PYTHON_BINDINGSfalse先用纯C方式编译和测试librealsensePython绑定后面单独处理。这样可以减少编译变量出了问题更容易定位。CMAKE_BUILD_TYPERelease编译优化版本运行时性能更好。配置完成后开始编译建议直接用多核编译make -j$(nproc)nproc会在编译时使用全部CPU核心速度会快很多。我实测在8核16线程的机器上全量编译大约需要10到15分钟。如果编译过程中内存不足可以改小并发数比如make -j4。编译完成后安装到系统目录sudo make install sudo ldconfig这一步会把rs-enumerate-devices、rs-viewer、rs-sensor-control等工具安装到/usr/local/bin同时把动态链接库librealsense2.so安装到/usr/local/lib。3.3 配置udev规则让普通用户也能访问设备不配置udev规则D435i就只能用root权限访问。每次运行都要加sudo在ROS环境或者Python开发时会非常恶心。librealsense源码里提供了udev规则文件直接复制到系统目录并重载即可cd .. sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger规则文件生效后拔掉相机USB重新插入普通用户就能直接访问了。我建议插入时最好用USB 3.0口蓝色接口因为D435i的深度流数据量较大USB 2.0虽然能工作但帧率和稳定性都会受影响。3.4 验证安装使用rs-enumerate-devices和rs-viewer安装完成后先运行枚举命令确认设备能被正确识别rs-enumerate-devices如果输出中列出了D435i的详细信息包括相机型号、序列号、固件版本、支持的流等说明驱动安装成功。如果提示找不到设备大概率是udev规则没生效或者USB连接问题。接着运行图形化工具验证深度流rs-viewer打开后能看到相机的深度画面和彩色画面还可以开启IMU数据可视化。如果这些都没问题恭喜librealsense底层的安装已经大功告成。这里我补充一个小经验rs-viewer打开后如果画面是黑色的不要怀疑相机坏了先检查一下镜头保护膜是不是没有撕掉。D435i出厂时镜头上有一层透明的保护膜别问我怎么知道的。4. pyrealsense2环境配置Python接口与librealsense的无缝对接4.1 pip安装还是源码编译两条路线对比pyrealsense2的安装有两条路线一是直接用pip安装预编译的wheel包二是从源码编译Python绑定。两条路线各有优劣我整理了对比安装方式优点缺点适用场景pip install pyrealsense2快速、简单、无需编译版本可能和本地librealsense不匹配受限于Python版本快速验证、不需要修改底层源码编译Python绑定版本完全可控可调试底层编译耗时需要额外配置深度开发、二次封装、排障如果你只是用Python调API获取深度图直接pip安装是最省事的pip install pyrealsense2但要注意pip包自带了Python接口的C扩展它内部链接的是pip包自带或指定版本的librealsense动态库并不一定复用你刚编译安装的系统librealsense。这一点很多人不知道也是“明明librealsense装好了Python却报找不到设备”的常见原因之一。4.2 推荐方案源码编译Python绑定为了保证Python接口和系统librealsense版本严格一致我推荐走源码编译路线操作如下在librealsense源码根目录下重新配置CMake并开启Python绑定选项cd build cmake .. -DCMAKE_BUILD_TYPERelease -DFORCE_RSUSB_BACKENDtrue -DBUILD_PYTHON_BINDINGStrue -DPYTHON_EXECUTABLE$(which python3) make -j$(nproc)编译完成后在build/wrappers/python目录下会生成pyrealsense2的Python扩展模块。可以把它直接拷贝到你当前Python环境的site-packages目录或者通过PYTHONPATH环境变量指定路径。如果你想装到系统Python环境可以执行sudo make install编译生成的pyrealsense2模块会被安装到Python的dist-packages目录。随后验证python3 -c import pyrealsense2 as rs; print(rs.__version__)如果打印出来的版本号和你编译的librealsense版本一致说明Python接口已经正确关联。如果不一致说明Python加载了错误路径下的模块可以通过python3 -c import pyrealsense2; print(pyrealsense2.__file__)查一下实际加载的文件路径。4.3 虚拟环境管理建议使用conda或venv我强烈建议在虚拟环境里使用pyrealsense2而不是直接装系统Python。因为ROS、OpenCV、PyTorch等框架对Python版本和依赖有各自的要求混装容易起冲突。用venv创建虚拟环境python3 -m venv rs_env source rs_env/bin/activate pip install numpy opencv-python如果上一步是把pyrealsense2装到了系统Python里在虚拟环境中可能无法直接导入这时需要把编译好的pyrealsense2拷贝到虚拟环境的site-packages目录。或者更简单的方式是直接在虚拟环境里重新编译一次。用conda的话建议创建Python 3.8或3.10的环境这两个版本对pyrealsense2的兼容性最好。我平时主力用的是Python 3.10实测无论是pip包还是源码编译都能稳定运行。4.4 一个简单的Python读取示例配置好环境后写一个最简单的Python程序验证整个链路是否畅通import pyrealsense2 as rs import numpy as np 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.start(config) try: for i in range(30): frames pipeline.wait_for_frames() depth_frame frames.get_depth_frame() color_frame frames.get_color_frame() if not depth_frame or not color_frame: continue depth_image np.asanyarray(depth_frame.get_data()) color_image np.asanyarray(color_frame.get_data()) print(fFrame {i}: depth shape{depth_image.shape}, color shape{color_image.shape}) finally: pipeline.stop()运行这段代码如果能看到类似depth shape(480, 640), color shape(480, 640, 3)的输出说明pyrealsense2已经完全正常。如果报错大概率是设备权限、USB连接或版本不匹配的问题可以对照下一节的排查清单来定位。5. 实战中挖过的坑常见问题与排查技巧实录5.1 问题速查表从报错到解决方案对照我整理了实际开发中最高频的几类问题做成一张速查表遇到问题时可以直接对照问题现象可能原因解决方法rs-enumerate-devices找不到设备udev规则未生效 / USB接触不良重载udev规则更换USB 3.0口检查数据线Permission denied或Device busy权限不足 / 设备被占用确认udev规则已配置检查是否有其他进程占用相机Python导入pyrealsense2报错No module named虚拟环境中未正确安装模块将编译好的模块拷贝到虚拟环境site-packages或重新编译启动深度流时报Frame didnt arriveUSB带宽不足 / 固件过旧降低帧率或分辨率升级固件换USB 3.0接口彩色图正常但深度图为全黑深度模式配置错误 / 环境光线干扰检查depth stream格式调大激光功率增加环境光IMU数据无法获取未启用IMU流 / 固件不支持确认enable_stream中包含rs.stream.gyro和rs.stream.accel编译过程中报fatal error: libusb.h: No such file缺少libusb开发库执行sudo apt install libusb-1.0-0-devCMake版本过低系统软件源CMake旧版用Kitware官方源升级CMake5.2 深度流“卡帧”或“丢帧”别急先查USB带宽D435i的深度流在640x48030fps设置下数据量接近180MB/s超过了USB 2.0的480Mbps实际可用带宽。如果插在USB 2.0口上会出现深度图刷新率上不去、卡顿明显的问题。而且很多台式机的前置USB口实际上是USB 2.0虽然外观上看不出来。排查方法是运行rs-enumerate-devices查看设备连接信息其中会包含USB type字段。如果是3.0说明连接没问题。如果是2.x就得换一个USB 3.0接口。另外劣质USB延长线也会导致信号质量下降表现为间歇性断流。我自己就遇到过一根看起来很高档的延长线结果连上后深度流每过几秒就中断一次换直连后问题消失。如果确认USB 3.0后仍然丢帧可以尝试降低帧率到15fps或者把深度分辨率降到424x240这是D435i在USB 2.0下也能稳定跑通的配置虽然精度略降但稳定性优先。5.3 多相机同时使用同型号设备的“串台”问题在机器人或多视角采集场景下你可能需要同时接两个甚至更多D435i。这时候有个特别容易踩的坑如果多个相机都是默认配置它们会尝试用相同的USB带宽导致无法同时打开或帧率下降。解决办法有两个思路。第一个思路给每个相机指定不同的设备序列号。通过config.enable_device(serial_number)来区分其中序列号可以从rs-enumerate-devices的输出中获取。第二个思路如果主板没有足够的USB控制器可以考虑使用PCIe USB 3.0扩展卡让不同的相机走不同的USB控制器带宽隔离后稳定性会有明显提升。我在一个视觉抓取项目里就是靠扩展卡解决了两台D435i同帧率采集的问题。5.4 升级固件之后Python反而用不了版本锁定的教训这个问题特别典型。有一次画质异常我直接下载了官网最新的D435i固件刷了进去以为万事大吉结果原有版本的Python程序全部无法打开设备报Device is busy或者Unknown error。查了半天发现新固件改变了部分USB描述符的行为和旧版librealsense的驱动逻辑不再兼容。从那之后我的原则变成升级固件前先确认新固件和你当前librealsense版本的兼容性。尤其是在生产环境或者项目进行到一半时别图一时新鲜盲目升级。操作上先备份原有程序依赖的librealsense和pyrealsense2版本号如果升级后出现问题能用pip和git快速回滚。5.5 ROS环境下的权限与launch文件问题如果你在ROS中使用D435i除了要保证librealsense和pyrealsense2版本正确外还要注意realsense2_camera包的版本匹配。这个ROS功能包内部封装了librealsense如果功能包版本和底层SDK差异过大同样会出现各种问题。我习惯在launch文件中显式指定设备序列号避免多个相机时的设备选择混乱。launch文件中可以这样写launch node namecamera_node pkgrealsense2_camera typerealsense2_camera_node outputscreen param nameserial_no value你的设备序列号/ param namedepth_width value640/ param namedepth_height value480/ param namedepth_fps value30/ param nameenable_gyro valuetrue/ param nameenable_accel valuetrue/ /node /launch另外ROS节点访问设备时如果提示权限不足别忘了检查运行用户是否在realsense组或dialout组中。可以用sudo usermod -a -G dialout $USER把当前用户加入组里然后重新登录。6. 写在最后一套稳定方案的经验总结从librealsense编译到pyrealsense2跑通整个过程说难不难但细节非常多。按照我提供的流程走一遍大概率能一次成功核心就三点第一librealsense源码版本和pyrealsense2版本必须严格一致这是最容易忽略也最容易出问题的点。第二FORCE_RSUSB_BACKENDtrue能帮你绕过UVC内核模块的很多麻烦在Ubuntu 22.04上推荐默认开启。第三udev规则一定要配好不然权限问题会在ROS或者Python环境中反复折磨你。最后再分享一个小技巧如果你需要在多台电脑上重复部署可以先把编译好的librealsense2动态库、pyrealsense2模块、udev规则文件打包拷贝到目标机器后直接放到对应路径再执行sudo ldconfig和udevadm重载省去每台机器重新编译的时间。我自己就是在实验室三台机器上这么干的量产部署时这招特别管用。
Ubuntu 22.04安装Intel RealSense D435i驱动及pyrealsense2全攻略
1. 写在前面为什么D435i在Ubuntu 22.04上这么“玄学”如果你手里有一块Intel RealSense D435i想在Ubuntu 22.04上跑起来第一反应肯定是去GitHub拉librealsense源码编一版然后pip install pyrealsense2收工。但真正动手你会发现这条路比想象中坎坷CMake版本不兼容、内核模块冲突、Python接口对不上、权限问题导致设备列表为空……我在连续装了三台不同配置的机器、踩完一圈坑之后决定把整个流程梳理成这篇完整攻略。先说结论D435i在Ubuntu 22.04下完全可以稳定运行但有两个关键前提——内核UVC模块要正确处理librealsense和pyrealsense2的版本必须严格匹配。只要这两点不出问题整个驱动链路基本就稳了。这篇攻略会从环境准备、依赖安装、源码编译、Python接口配置到常见问题排查完整走一遍适合刚接触RealSense的初学者也适合被驱动折腾过的老手查漏补缺。D435i本质上是“RGB相机双目红外相机IMU”三合一设备其中深度计算依赖相机硬件的IR传感器和内部的深度处理芯片。Ubuntu系统需要通过librealsense才能和它通信而pyrealsense2则是librealsense的Python绑定。两者关系可以理解为librealsense是底层驱动和SDKpyrealsense2是SDK的Python API。所以安装路线也很清晰——先装底层的librealsense再配置Python环境。整个安装过程我踩过不少坑比如编译时缺libusb、运行时提示Permission denied、rs-enumerate-devices能列出设备但Python报错找不到设备等等。这些问题的根因和解决方案我在后面的章节会逐一拆解。如果你现在正好卡在某个环节可以直接跳到对应的排查部分。2. 装机前的环境准备依赖、内核和固件一个都不能少2.1 确认系统版本和内核状态Ubuntu 22.04的官方内核版本是5.15系列librealsense官方对这个内核版本的支持已经比较完善。但很多人的机器是后续自己升过内核的比如升到5.19甚至6.x这时候就要格外小心因为新内核里UVC模块的改动可能会影响D435i的识别。先运行下面命令确认当前的系统版本和内核版本lsb_release -a uname -a如果内核版本在5.13到5.19之间通常问题不大。如果超过6.0建议要么降级内核要么使用librealsense源码中最新的release分支因为新版驱动会针对新内核做兼容适配。另外一定要确认系统已安装build-essential和cmake。我在一台新装的Ubuntu 22.04上编译时就因为缺cmake导致反复报CMake Error后来才发现是最小化安装连构建工具链都没带全。执行以下命令把基础工具装上sudo apt update sudo apt install -y build-essential cmake git pkg-config这里有个小细节Ubuntu 22.04软件源里的CMake版本是3.22.x而librealsense要求CMake 3.8所以一般不用额外升级CMake。如果编译时遇到CMake版本过低的报错再用Kitware官方源升级到3.24即可。2.2 安装librealsense的编译依赖librealsense编译时需要一堆开发库包括libusb、libudev、libgl、libdrm等。直接通过apt安装是最稳妥的方式sudo apt install -y libusb-1.0-0-dev libudev-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev libx11-dev libxrandr-dev libxi-dev libssl-dev libdw-dev如果需要图形化工具比如realsense-viewer还需要安装GTK和OpenGL相关的库sudo apt install -y libgtk-3-dev libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev我个人的建议是直接把这些都装上省得编译到中途发现缺库又要回头补装。编译librealsense依赖OpenGL时最容易出问题的是libgl1-mesa-dev如果提示找不到这个包可能需要先执行sudo apt update刷新软件源。2.3 UVC内核模块D435i能否被正确识别的关键这是最容易踩坑的环节。Linux内核自带一个uvcvideo模块负责通用USB视频设备。D435i本身也是UVC设备所以内核模块能识别到它但默认的uvcvideo可能无法完全开启深度和IMU的功能。librealsense官方的做法是编译一个打了补丁的uvcvideo内核模块替换系统自带的模块。不过这是个双刃剑。如果替换不当可能会导致系统原有的摄像头比如笔记本内置摄像头无法工作。所以我不建议一上来就替换内核模块而是采用librealsense的运行时补丁方案也就是通过scripts/patch-realsense-uvc.sh脚本给当前内核源码打补丁并重新编译模块。实际操作中如果你只是需要读取深度图、彩色图和IMU数据不追求极致性能那么先不替换内核模块直接编译librealsense也可以工作。D435i在默认UVC驱动下能以30fps输出深度流和彩色流IMU也能获取数据。但如果需要更高帧率、更低的延迟或者多个相机同时工作那就必须替换UVC模块。我的建议是先不替换内核模块直接编译librealsense跑通全流程后再决定是否折腾UVC补丁。这样能把变量范围控制到最小后续出了问题也容易定位。2.4 固件版本很多人忽略的“隐藏故障点”D435i的固件版本直接影响驱动行为。librealsense源码中带了一个固件更新工具位于scripts/update-uvc-firmware.sh。我在实际使用中遇到过这样一个情况相机能识别但开启深度流时总是报错后来用rs-fw-update查看才发现固件版本太老和当前librealsense不兼容。检查固件版本的命令是rs-enumerate-devices | grep Firmware如果固件版本过旧低于5.12建议升级固件。升级方法支持通过USB连接方式在librealsense的build目录下运行./tools/fw-update/rs-fw-update -f 文件名.bin固件文件可以从RealSense官方GitHub仓库的firmware目录下载。升级过程中千万不能断电或者拔USB线否则相机有可能变砖。变砖后虽然能用恢复模式救回来但过程非常麻烦我亲眼见过同事把相机刷成无法识别的状态最后靠Intel的恢复工具才搞定。3. 编译安装librealsense从源码到命令行工具3.1 克隆源码与选择版本librealsense的源码托管在GitHub上克隆命令是git clone https://github.com/IntelRealSense/librealsense.git cd librealsense这里要注意分支选择。master分支通常是最新的开发版功能多但稳定性无法保证。我推荐使用最新的release标签版本比如v2.54.2或更高版本可以通过以下命令查看所有标签git tag git checkout v2.54.2版本选择的原则是和你的pyrealsense2版本严格对应。比如你计划安装pyrealsense22.54.2那么librealsense源码也应该切到v2.54.2。两个版本不一致编译可能能通过但运行时会出现各种诡异的问题比如Python接口报找不到符号、或者rs2::error等。我第一次装的时候就没注意这个问题源码用了最新的master分支pyrealsense2装了pip上的最新版结果Python里调用pipelines.start()时报了个莫名其妙的段错误折腾了小半天才发现是版本不匹配。从那以后我再也不混着用了。3.2 CMake配置和编译参数在源码根目录下创建build目录执行CMake配置mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DFORCE_RSUSB_BACKENDtrue -DBUILD_PYTHON_BINDINGSfalse几个关键参数解释一下FORCE_RSUSB_BACKENDtrue强制使用librealsense自带的USB后端而不依赖内核UVC模块。这个选项可以绕过uvcvideo模块的补丁问题对Ubuntu 22.04非常友好推荐开启。开启后即使不替换内核模块也能稳定使用D435i。BUILD_PYTHON_BINDINGSfalse先用纯C方式编译和测试librealsensePython绑定后面单独处理。这样可以减少编译变量出了问题更容易定位。CMAKE_BUILD_TYPERelease编译优化版本运行时性能更好。配置完成后开始编译建议直接用多核编译make -j$(nproc)nproc会在编译时使用全部CPU核心速度会快很多。我实测在8核16线程的机器上全量编译大约需要10到15分钟。如果编译过程中内存不足可以改小并发数比如make -j4。编译完成后安装到系统目录sudo make install sudo ldconfig这一步会把rs-enumerate-devices、rs-viewer、rs-sensor-control等工具安装到/usr/local/bin同时把动态链接库librealsense2.so安装到/usr/local/lib。3.3 配置udev规则让普通用户也能访问设备不配置udev规则D435i就只能用root权限访问。每次运行都要加sudo在ROS环境或者Python开发时会非常恶心。librealsense源码里提供了udev规则文件直接复制到系统目录并重载即可cd .. sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger规则文件生效后拔掉相机USB重新插入普通用户就能直接访问了。我建议插入时最好用USB 3.0口蓝色接口因为D435i的深度流数据量较大USB 2.0虽然能工作但帧率和稳定性都会受影响。3.4 验证安装使用rs-enumerate-devices和rs-viewer安装完成后先运行枚举命令确认设备能被正确识别rs-enumerate-devices如果输出中列出了D435i的详细信息包括相机型号、序列号、固件版本、支持的流等说明驱动安装成功。如果提示找不到设备大概率是udev规则没生效或者USB连接问题。接着运行图形化工具验证深度流rs-viewer打开后能看到相机的深度画面和彩色画面还可以开启IMU数据可视化。如果这些都没问题恭喜librealsense底层的安装已经大功告成。这里我补充一个小经验rs-viewer打开后如果画面是黑色的不要怀疑相机坏了先检查一下镜头保护膜是不是没有撕掉。D435i出厂时镜头上有一层透明的保护膜别问我怎么知道的。4. pyrealsense2环境配置Python接口与librealsense的无缝对接4.1 pip安装还是源码编译两条路线对比pyrealsense2的安装有两条路线一是直接用pip安装预编译的wheel包二是从源码编译Python绑定。两条路线各有优劣我整理了对比安装方式优点缺点适用场景pip install pyrealsense2快速、简单、无需编译版本可能和本地librealsense不匹配受限于Python版本快速验证、不需要修改底层源码编译Python绑定版本完全可控可调试底层编译耗时需要额外配置深度开发、二次封装、排障如果你只是用Python调API获取深度图直接pip安装是最省事的pip install pyrealsense2但要注意pip包自带了Python接口的C扩展它内部链接的是pip包自带或指定版本的librealsense动态库并不一定复用你刚编译安装的系统librealsense。这一点很多人不知道也是“明明librealsense装好了Python却报找不到设备”的常见原因之一。4.2 推荐方案源码编译Python绑定为了保证Python接口和系统librealsense版本严格一致我推荐走源码编译路线操作如下在librealsense源码根目录下重新配置CMake并开启Python绑定选项cd build cmake .. -DCMAKE_BUILD_TYPERelease -DFORCE_RSUSB_BACKENDtrue -DBUILD_PYTHON_BINDINGStrue -DPYTHON_EXECUTABLE$(which python3) make -j$(nproc)编译完成后在build/wrappers/python目录下会生成pyrealsense2的Python扩展模块。可以把它直接拷贝到你当前Python环境的site-packages目录或者通过PYTHONPATH环境变量指定路径。如果你想装到系统Python环境可以执行sudo make install编译生成的pyrealsense2模块会被安装到Python的dist-packages目录。随后验证python3 -c import pyrealsense2 as rs; print(rs.__version__)如果打印出来的版本号和你编译的librealsense版本一致说明Python接口已经正确关联。如果不一致说明Python加载了错误路径下的模块可以通过python3 -c import pyrealsense2; print(pyrealsense2.__file__)查一下实际加载的文件路径。4.3 虚拟环境管理建议使用conda或venv我强烈建议在虚拟环境里使用pyrealsense2而不是直接装系统Python。因为ROS、OpenCV、PyTorch等框架对Python版本和依赖有各自的要求混装容易起冲突。用venv创建虚拟环境python3 -m venv rs_env source rs_env/bin/activate pip install numpy opencv-python如果上一步是把pyrealsense2装到了系统Python里在虚拟环境中可能无法直接导入这时需要把编译好的pyrealsense2拷贝到虚拟环境的site-packages目录。或者更简单的方式是直接在虚拟环境里重新编译一次。用conda的话建议创建Python 3.8或3.10的环境这两个版本对pyrealsense2的兼容性最好。我平时主力用的是Python 3.10实测无论是pip包还是源码编译都能稳定运行。4.4 一个简单的Python读取示例配置好环境后写一个最简单的Python程序验证整个链路是否畅通import pyrealsense2 as rs import numpy as np 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.start(config) try: for i in range(30): frames pipeline.wait_for_frames() depth_frame frames.get_depth_frame() color_frame frames.get_color_frame() if not depth_frame or not color_frame: continue depth_image np.asanyarray(depth_frame.get_data()) color_image np.asanyarray(color_frame.get_data()) print(fFrame {i}: depth shape{depth_image.shape}, color shape{color_image.shape}) finally: pipeline.stop()运行这段代码如果能看到类似depth shape(480, 640), color shape(480, 640, 3)的输出说明pyrealsense2已经完全正常。如果报错大概率是设备权限、USB连接或版本不匹配的问题可以对照下一节的排查清单来定位。5. 实战中挖过的坑常见问题与排查技巧实录5.1 问题速查表从报错到解决方案对照我整理了实际开发中最高频的几类问题做成一张速查表遇到问题时可以直接对照问题现象可能原因解决方法rs-enumerate-devices找不到设备udev规则未生效 / USB接触不良重载udev规则更换USB 3.0口检查数据线Permission denied或Device busy权限不足 / 设备被占用确认udev规则已配置检查是否有其他进程占用相机Python导入pyrealsense2报错No module named虚拟环境中未正确安装模块将编译好的模块拷贝到虚拟环境site-packages或重新编译启动深度流时报Frame didnt arriveUSB带宽不足 / 固件过旧降低帧率或分辨率升级固件换USB 3.0接口彩色图正常但深度图为全黑深度模式配置错误 / 环境光线干扰检查depth stream格式调大激光功率增加环境光IMU数据无法获取未启用IMU流 / 固件不支持确认enable_stream中包含rs.stream.gyro和rs.stream.accel编译过程中报fatal error: libusb.h: No such file缺少libusb开发库执行sudo apt install libusb-1.0-0-devCMake版本过低系统软件源CMake旧版用Kitware官方源升级CMake5.2 深度流“卡帧”或“丢帧”别急先查USB带宽D435i的深度流在640x48030fps设置下数据量接近180MB/s超过了USB 2.0的480Mbps实际可用带宽。如果插在USB 2.0口上会出现深度图刷新率上不去、卡顿明显的问题。而且很多台式机的前置USB口实际上是USB 2.0虽然外观上看不出来。排查方法是运行rs-enumerate-devices查看设备连接信息其中会包含USB type字段。如果是3.0说明连接没问题。如果是2.x就得换一个USB 3.0接口。另外劣质USB延长线也会导致信号质量下降表现为间歇性断流。我自己就遇到过一根看起来很高档的延长线结果连上后深度流每过几秒就中断一次换直连后问题消失。如果确认USB 3.0后仍然丢帧可以尝试降低帧率到15fps或者把深度分辨率降到424x240这是D435i在USB 2.0下也能稳定跑通的配置虽然精度略降但稳定性优先。5.3 多相机同时使用同型号设备的“串台”问题在机器人或多视角采集场景下你可能需要同时接两个甚至更多D435i。这时候有个特别容易踩的坑如果多个相机都是默认配置它们会尝试用相同的USB带宽导致无法同时打开或帧率下降。解决办法有两个思路。第一个思路给每个相机指定不同的设备序列号。通过config.enable_device(serial_number)来区分其中序列号可以从rs-enumerate-devices的输出中获取。第二个思路如果主板没有足够的USB控制器可以考虑使用PCIe USB 3.0扩展卡让不同的相机走不同的USB控制器带宽隔离后稳定性会有明显提升。我在一个视觉抓取项目里就是靠扩展卡解决了两台D435i同帧率采集的问题。5.4 升级固件之后Python反而用不了版本锁定的教训这个问题特别典型。有一次画质异常我直接下载了官网最新的D435i固件刷了进去以为万事大吉结果原有版本的Python程序全部无法打开设备报Device is busy或者Unknown error。查了半天发现新固件改变了部分USB描述符的行为和旧版librealsense的驱动逻辑不再兼容。从那之后我的原则变成升级固件前先确认新固件和你当前librealsense版本的兼容性。尤其是在生产环境或者项目进行到一半时别图一时新鲜盲目升级。操作上先备份原有程序依赖的librealsense和pyrealsense2版本号如果升级后出现问题能用pip和git快速回滚。5.5 ROS环境下的权限与launch文件问题如果你在ROS中使用D435i除了要保证librealsense和pyrealsense2版本正确外还要注意realsense2_camera包的版本匹配。这个ROS功能包内部封装了librealsense如果功能包版本和底层SDK差异过大同样会出现各种问题。我习惯在launch文件中显式指定设备序列号避免多个相机时的设备选择混乱。launch文件中可以这样写launch node namecamera_node pkgrealsense2_camera typerealsense2_camera_node outputscreen param nameserial_no value你的设备序列号/ param namedepth_width value640/ param namedepth_height value480/ param namedepth_fps value30/ param nameenable_gyro valuetrue/ param nameenable_accel valuetrue/ /node /launch另外ROS节点访问设备时如果提示权限不足别忘了检查运行用户是否在realsense组或dialout组中。可以用sudo usermod -a -G dialout $USER把当前用户加入组里然后重新登录。6. 写在最后一套稳定方案的经验总结从librealsense编译到pyrealsense2跑通整个过程说难不难但细节非常多。按照我提供的流程走一遍大概率能一次成功核心就三点第一librealsense源码版本和pyrealsense2版本必须严格一致这是最容易忽略也最容易出问题的点。第二FORCE_RSUSB_BACKENDtrue能帮你绕过UVC内核模块的很多麻烦在Ubuntu 22.04上推荐默认开启。第三udev规则一定要配好不然权限问题会在ROS或者Python环境中反复折磨你。最后再分享一个小技巧如果你需要在多台电脑上重复部署可以先把编译好的librealsense2动态库、pyrealsense2模块、udev规则文件打包拷贝到目标机器后直接放到对应路径再执行sudo ldconfig和udevadm重载省去每台机器重新编译的时间。我自己就是在实验室三台机器上这么干的量产部署时这招特别管用。
