1. 为什么树莓派5跑ROS2值得单独写一篇避坑指南树莓派5这块板子刚出来的时候我第一时间就搞了一块8GB版本。原因很简单ROS2 Humble对算力的胃口比ROS1大了不止一个量级而树莓派4B跑Nav2导航栈的时候光是一个代价地图更新就能让CPU飙到七八十度降频。树莓派5的Cortex-A76四核2.4GHz加上VideoCore VII理论上单核性能比树莓派4B提升了接近两到三倍这对ROS2这种大量依赖DDS通信和TF变换的框架来说是实打实的体验升级。但问题也来了。ROS2 Humble官方支持的Ubuntu 22.04在arm64架构上的镜像跟树莓派5的硬件适配并不是“烧录即用”那么顺滑。我自己前前后后装了不下十遍从系统镜像选择、源配置、依赖冲突到DDS中间件调优踩过的坑能写满一张A4纸。网上很多教程要么是树莓派4B时代的旧内容要么是x86虚拟机里的操作直接照搬到了树莓派5上就各种报错。这篇内容就是把我自己反复折腾出来的经验整理出来面向的是手里有一块树莓派5、想跑ROS2 Humble但不想在环境配置上浪费太多时间的开发者。不管你是刚接触ROS2的新手还是从ROS1转过来的老手只要按照这里的步骤走基本可以避开90%以上的常见问题。我会从系统选型开始讲一直讲到DDS调优和实际节点测试中间穿插大量“为什么这么做”的解释和踩坑记录。2. 系统镜像与基础环境选对了就成功了一半2.1 Ubuntu 22.04 arm64镜像的选择逻辑树莓派5的官方系统是Raspberry Pi OS基于Debian Bookworm。但ROS2 Humble的官方二进制包只针对Ubuntu 22.04 Jammy Jellyfish的amd64和arm64架构发布。虽然理论上可以在Debian上从源码编译ROS2但那个工作量对于大多数人来说完全不划算——光是编译整个ROS2基础包就要好几个小时而且中间各种依赖版本冲突能让人崩溃。所以结论很明确直接上Ubuntu 22.04 Server arm64。这里有个关键点树莓派5用的是BCM2712芯片arm64架构没问题但要注意Ubuntu官方为树莓派提供的镜像和通用arm64镜像不是一回事。你需要的是Ubuntu专门为Raspberry Pi定制的镜像在Ubuntu官网的Raspberry Pi页面可以找到。截至我写这篇内容的时候Ubuntu 22.04.4 LTS for Raspberry Pi的镜像已经比较成熟了对树莓派5的支持也基本稳定。注意不要用Ubuntu 24.04去装ROS2 Humble。Humble的官方支持到2027年但它的二进制包只针对22.04编译。在24.04上强行装Humble会遇到大量libc版本不兼容的问题比如libstdc的GLIBCXX版本要求对不上报错信息还特别隐晦。如果你手头只有一张TF卡建议至少用32GB Class 10以上的卡最好是A2级别的。ROS2的日志和bag文件增长很快16GB的卡装完系统加ROS2基本就剩不下多少空间了。有条件的话直接上NVMe SSD加M.2 HAT树莓派5的PCIe接口虽然只跑Gen2 x1但比起TF卡的随机读写还是快太多了编译和启动节点的时候体感差异非常明显。2.2 烧录与首次启动的实操细节烧录工具我用的是Raspberry Pi Imager这个工具的好处是可以在烧录前就配置好WiFi、SSH和用户名密码省去了第一次启动还要接显示器的麻烦。具体操作是在Imager里选择“Choose OS” - “Other general-purpose OS” - “Ubuntu” - “Ubuntu Server 22.04.4 LTS (Raspberry Pi) 64-bit”然后选好存储卡点击齿轮图标进入高级设置。高级设置里几个关键项Enable SSH勾选选择“Use password authentication”设置好用户名和密码。用户名不要用默认的“ubuntu”自己起一个避免一些脚本里的硬编码冲突。Configure wireless LAN填好WiFi的SSID和密码注意树莓派5只支持2.4GHz和5GHz的WiFi不支持6GHz。国家代码填CN。Set locale settings时区选Asia/Shanghai键盘布局选us。烧录完成后把卡插进树莓派5上电。第一次启动会比较慢因为要扩展文件系统和初始化。等个两三分钟然后在路由器后台找到树莓派的IP或者直接用ping raspberrypi.local试试。如果能ping通就ssh 用户名IP连上去。首次登录会强制要求改密码改完之后第一件事是更新系统sudo apt update sudo apt full-upgrade -y这个步骤在树莓派5上可能要跑十几分钟取决于你的网络和存储卡速度。更新完之后重启一次。实操心得如果你用的是NVMe SSD通过M.2 HAT启动需要在烧录前先更新树莓派5的bootloader固件否则可能无法从NVMe启动。具体方法是用TF卡启动后执行sudo rpi-eeprom-update -a然后重启再在raspi-config里把启动顺序改成NVMe优先。2.3 系统层面的必要调优Ubuntu Server默认没有图形界面这对ROS2来说其实是好事省资源。但有几个系统参数需要调整否则后面跑ROS2的时候会遇到莫名其妙的延迟和丢包。首先是交换空间。树莓派5的8GB内存跑ROS2基本够用但如果你要同时跑Gazebo或者编译大型包swap还是需要的。Ubuntu默认的swapfile是2GB建议改成4GBsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab然后是CPU调度器。树莓派5默认用的是ondemand调度器在ROS2这种需要实时响应的场景下建议改成performance模式让CPU始终跑在最高频率echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor这个设置重启后会失效可以写个systemd service或者加到rc.local里。不过要注意散热树莓派5满载的时候发热不小官方主动散热器基本是必须的否则performance模式下很容易触发温度墙降频。网络方面ROS2的DDS默认走UDP多播在WiFi环境下有时候会不稳定。如果你打算用有线网络直接插网线就行。如果用WiFi建议在路由器里把树莓派的IP固定下来避免DHCP租约变化导致节点发现失败。3. ROS2 Humble安装apt方式与常见报错处理3.1 添加ROS2 apt源的正确姿势ROS2 Humble在arm64上的安装官方推荐的就是apt二进制安装。步骤本身不复杂但有几个地方容易出错。第一步是设置locale确保支持UTF-8sudo apt update sudo apt install locales -y sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 export LANGen_US.UTF-8这一步不做的话后面ros2 run的时候可能会报编码相关的警告虽然不影响运行但看着烦。第二步是添加ROS2的apt源。这里有个坑网上很多教程让你直接echo deb [arch$(dpkg --print-architecture)] ...但在树莓派5上dpkg --print-architecture返回的是arm64这个没问题。问题在于ROS2的源服务器在国内访问速度很不稳定经常超时。我的做法是先用官方源把GPG key加上然后把源地址换成国内镜像。sudo apt install software-properties-common curl -y sudo add-apt-repository universe sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg如果curl那个raw.githubusercontent.com连不上可以先用ping测试一下或者直接用wget试试。实在不行就手动下载key文件然后拷贝进去。然后添加源我习惯用清华的镜像echo deb [archarm64 signed-by/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu jammy main | sudo tee /etc/apt/sources.list.d/ros2.list /dev/null注意源地址里的jammy对应的是Ubuntu 22.04的代号不要写成focal或者noble。写错了的话apt update会报404。3.2 安装ROS2基础包与开发工具源配好之后先sudo apt update然后安装sudo apt install ros-humble-ros-base ros-dev-tools -y这里我选择的是ros-base而不是desktop。原因很简单desktop版本包含了RViz2、Gazebo等图形化工具在树莓派5这种没有显示器的Server系统上装了也是白装还占空间。如果你后面确实需要RViz2可以单独装ros-humble-rviz2但说实话在树莓派5上跑RViz2的体验并不好帧率很低建议还是在PC上远程可视化。ros-dev-tools包含了colcon、rosdep等开发工具这个是必须的。安装完成后source一下环境source /opt/ros/humble/setup.bash echo source /opt/ros/humble/setup.bash ~/.bashrc然后测试一下ros2 run demo_nodes_cpp talker如果能看到[INFO] [talker]: Publishing: Hello World: 1这样的输出说明安装成功了。另开一个终端跑ros2 run demo_nodes_py listener能看到接收消息就说明DDS通信正常。3.3 安装过程中最常见的三个报错报错一E: Unable to locate package ros-humble-ros-base这个基本就是源没配好。检查/etc/apt/sources.list.d/ros2.list里的内容确认架构是arm64代号是jammy。另外确认GPG key文件存在且权限正确。报错二The following packages have unmet dependencies: ros-humble-... : Depends: lib... but it is not going to be installed这种依赖问题通常是因为系统的apt源不完整。检查/etc/apt/sources.list里有没有universe和multiverse仓库。Ubuntu Server默认可能只开了main需要手动加上sudo add-apt-repository universe sudo add-apt-repository multiverse sudo apt update报错三dpkg: error processing archive ... (--unpack): trying to overwrite ...这是文件冲突通常是因为之前装过ROS1或者手动编译过某些库。用sudo apt install -f修复如果还不行用dpkg -S找到冲突的文件属于哪个包然后决定是删除还是用--force-overwrite强制覆盖。不过强制覆盖有风险能不用就不用。4. DDS中间件调优与网络配置4.1 为什么默认的Fast DDS在树莓派5上需要调ROS2 Humble默认用的DDS是Fast DDS以前叫FastRTPS。这个中间件在x86上表现不错但在树莓派5这种arm64平台上默认配置有几个问题一是共享内存传输在某些内核配置下不工作导致所有通信都走网络回环延迟增加二是多播发现机制在WiFi环境下容易丢包节点发现慢三是默认的缓冲区大小偏小传大消息比如点云或者图像的时候容易丢帧。我实测下来默认配置下两个节点在同一块树莓派5上通信延迟大概在2-3毫秒看起来还行。但如果你跑的是Nav2这种需要高频TF变换的场景累积延迟就很明显了。调优之后可以降到1毫秒以内。4.2 Fast DDS配置文件的编写与生效Fast DDS支持通过XML文件配置。在树莓派5上我建议创建一个配置文件放在~/.ros/fastdds.xml内容如下?xml version1.0 encodingUTF-8? profiles xmlnshttp://www.eprosima.com/XMLSchemas/fastRTPS_Profiles transport_descriptors transport_descriptor transport_idUdpTransport/transport_id typeUDPv4/type sendBufferSize1048576/sendBufferSize receiveBufferSize1048576/receiveBufferSize /transport_descriptor /transport_descriptors participant profile_nameparticipant_profile is_default_profiletrue rtps userTransports transport_idUdpTransport/transport_id /userTransports useBuiltinTransportsfalse/useBuiltinTransports /rtps /participant /profiles然后在~/.bashrc里加上export FASTRTPS_DEFAULT_PROFILES_FILE~/.ros/fastdds.xml这个配置的核心改动是把UDP的发送和接收缓冲区都调到1MB并且显式指定使用UDPv4传输。共享内存传输在树莓派5上我试过有时候会因为/dev/shm的大小限制出问题索性关掉统一走UDP回环反而更稳定。实操心得如果你需要跨设备通信比如树莓派5和PC上的ROS2节点互相发现确保两台机器的ROS_DOMAIN_ID一致并且防火墙允许UDP多播。Ubuntu默认的ufw会拦截多播需要手动放行或者直接关掉ufw。4.3 网络环境对DDS发现的影响ROS2的节点发现默认走多播这在同一个局域网里没问题。但如果你在办公室或者实验室环境网络里有很多设备多播包可能会被交换机限制。表现就是ros2 node list看不到另一台机器上的节点。解决办法有两个一是配置单播发现在Fast DDS的XML里指定对方的IP地址二是用ROS_STATIC_PEERS环境变量。我一般用后者简单直接export ROS_STATIC_PEERS192.168.1.100多个IP用分号隔开。这个变量告诉DDS除了多播之外还向这些IP发送发现信息。另外如果你在树莓派5上同时跑多个ROS2节点建议把ROS_DOMAIN_ID设成一个固定的值不要用默认的0。因为0域在多机组网的时候容易冲突。我一般用ROS_DOMAIN_ID42这个数字随便选只要同一网络里所有机器一致就行。5. 实际节点测试与性能验证5.1 用小乌龟仿真验证基础环境装完ROS2之后最经典的验证方式就是跑小乌龟。但树莓派5是Server系统没有图形界面turtlesim跑不起来。不过我们可以用turtlesim的无头模式来测试节点通信ros2 run turtlesim turtlesim_node这个命令在没有X11的情况下会报错退出。替代方案是用demo_nodes_cpp和demo_nodes_py来测试前面已经说过了。如果你确实想跑小乌龟可以在PC上跑turtlesim_node然后在树莓派5上跑turtle_teleop_key通过ROS2的网络通信来控制。这其实是个很好的跨设备通信测试。5.2 用ros2 topic hz测试消息频率环境验证通过之后我习惯用ros2 topic hz来测一下实际的消息频率。比如跑一个talker然后ros2 topic hz /chatter在树莓派5上默认配置下talker的发布频率是10Hzros2 topic hz显示的数值应该稳定在10左右波动不超过0.5。如果波动很大比如在8到12之间跳说明DDS的调度有问题可能是CPU降频了或者网络缓冲区不够。我实测的数据是默认配置下平均10.02Hz标准差0.3调优之后平均10.00Hz标准差0.1。这个差异在跑控制算法的时候体感很明显。5.3 编译一个自定义包测试colcon性能最后一步是编译一个自定义的ROS2包验证colcon工具链是否正常。创建一个简单的包mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src ros2 pkg create --build-type ament_cmake my_test_pkg --dependencies rclcpp std_msgs然后在src目录下写一个简单的发布者节点编译cd ~/ros2_ws colcon build --symlink-install在树莓派5上编译一个简单的C包大概需要十几秒到几十秒取决于包的复杂度。如果编译过程中报virtual memory exhausted说明内存不够需要减小并行编译的线程数colcon build --symlink-install --parallel-workers 2树莓派5的8GB内存在编译大型包比如Nav2的时候可能会吃紧建议加上--parallel-workers 2或者--executor sequential。6. 常见问题速查与避坑经验汇总6.1 安装与配置阶段的高频问题问题现象可能原因解决方法apt update报404源地址代号写错确认是jammy不是focal或nobleros2 run报找不到包环境没source执行source /opt/ros/humble/setup.bash节点之间无法发现多播被拦截或域ID不一致检查ROS_DOMAIN_ID配置ROS_STATIC_PEERS编译时报内存不足并行编译线程过多加--parallel-workers 2ros2 topic hz频率不稳CPU降频或DDS缓冲区小设置performance调度器调大DDS缓冲区SSH连接超时WiFi休眠或IP变化关闭WiFi电源管理固定IP6.2 那些教程里不会写的坑第一个坑是TF变换的时间戳问题。树莓派5的系统时钟在没有RTC的情况下每次断电重启时间都会重置。ROS2的TF变换严重依赖时间戳如果系统时间不对tf2会报LookupException。解决办法是装一个RTC模块或者确保树莓派5每次启动都能通过NTP同步时间。Ubuntu Server默认开了systemd-timesyncd但需要网络连通才能同步。如果启动时网络还没准备好时间就是错的。我一般会在/etc/rc.local里加一个延迟同步的脚本。第二个坑是串口权限。如果你要接串口设备比如STM32或者ArduinoUbuntu默认的dialout组权限可能不够。需要把用户加到dialout组sudo usermod -a -G dialout $USER然后重新登录。另外树莓派5的GPIO串口默认是给蓝牙用的需要在/boot/firmware/config.txt里加上enable_uart1和dtoverlaydisable-bt才能把/dev/ttyAMA0释放出来给外部设备用。第三个坑是WiFi和蓝牙的共存干扰。树莓派5的无线模块同时支持WiFi和蓝牙但两者共用天线在2.4GHz频段会互相干扰。如果你用WiFi连接ROS2网络同时又在用蓝牙手柄或者蓝牙串口可能会遇到丢包。解决办法是尽量用5GHz WiFi或者用有线网络。6.3 性能优化的几个实用技巧如果你要在树莓派5上跑视觉相关的ROS2节点比如USB摄像头或者CSI摄像头有几个优化点用v4l2_camera包而不是usb_cam前者对arm64的优化更好。图像分辨率不要超过640x480帧率不要超过30fps否则CPU占用会很高。如果要做图像处理尽量用OpenCV的硬件加速树莓派5的VideoCore VII支持OpenCL但需要手动编译OpenCV并开启WITH_OPENCLON。对于导航相关的应用建议把代价地图的分辨率从默认的0.05米降到0.1米这样计算量会小很多而实际导航效果差别不大。另外把controller_frequency从20Hz降到10Hz也能显著降低CPU负载。最后分享一个小技巧如果你在树莓派5上跑ROS2的时候发现CPU占用莫名其妙很高先用top看看是哪个进程。很多时候是ros2 daemon在后台跑这个守护进程用于加速命令行工具的响应但在资源紧张的设备上反而拖后腿。可以用ros2 daemon stop停掉它需要的时候再启动。7. 从零到跑通一个SLAM节点的完整流程7.1 硬件准备与连接检查假设你手头有一个激光雷达比如RPLIDAR A1和一个树莓派5想跑一个SLAM建图。首先确认硬件连接激光雷达通过USB转串口接到树莓派5的USB口然后ls /dev/ttyUSB*应该能看到设备。如果没有检查dmesg | grep tty看看内核有没有识别到。然后安装雷达的ROS2驱动。以RPLIDAR为例sudo apt install ros-humble-rplidar-ros -y启动雷达节点ros2 run rplidar_ros rplidar_node --ros-args -p serial_port:/dev/ttyUSB0 -p serial_baudrate:115200 -p frame_id:laser如果一切正常ros2 topic list应该能看到/scan话题。用ros2 topic echo /scan --once检查一下有没有数据。7.2 SLAM Toolbox的配置与启动SLAM Toolbox是ROS2里比较成熟的SLAM包安装sudo apt install ros-humble-slam-toolbox -y启动之前需要确认TF树。SLAM Toolbox需要odom到base_link的变换以及base_link到laser的变换。如果你没有轮式里程计可以用ros2 run tf2_ros static_transform_publisher发布一个静态变换来临时替代ros2 run tf2_ros static_transform_publisher 0 0 0 0 0 0 base_link laser然后启动SLAM Toolboxros2 launch slam_toolbox online_async_launch.py在PC上用RViz2订阅/map话题应该能看到地图在逐渐构建。如果地图不动检查/scan的频率和TF变换的时间戳。7.3 保存地图与后续导航建图完成后保存地图ros2 run nav2_map_server map_saver_cli -f ~/my_map这会生成my_map.pgm和my_map.yaml两个文件。后续用Nav2做导航的时候在nav2_params.yaml里指定这个地图文件就行。整个流程在树莓派5上跑下来CPU占用大概在40%到60%之间内存占用1GB左右。如果同时跑Nav2的完整导航栈CPU会到80%以上建议加散热风扇。8. 我个人在实际操作中的几点体会树莓派5跑ROS2 Humble这件事说难不难说简单也不简单。硬件性能是够的但软件生态的适配还需要一些手动调整。我最大的体会是不要迷信一键安装脚本。网上有些脚本号称能一键搞定但树莓派5的硬件版本和系统版本差异很大脚本里的硬编码路径和版本号很容易出问题。自己一步步来虽然慢一点但出了问题知道去哪里找。另外散热真的不能省。我一开始用的是一个便宜的铝制散热片跑SLAM的时候温度直接上85度降频TF变换的延迟从1毫秒飙到十几毫秒地图直接飘了。换了官方主动散热器之后温度稳定在60度左右一切正常。最后如果你打算长期在树莓派5上跑ROS2建议把系统装到NVMe SSD上然后用TF卡只做bootloader。这样系统的稳定性和响应速度都会有质的提升。我现在的配置是8GB树莓派5 256GB NVMe SSD 官方散热器跑SLAM和Nav2都很流畅日常开发完全够用。