树莓派加 STM32 做 ROS2 小车听起来是个非常标准的入门项目但真正动手之后你会发现问题从来不在“能不能转起来”而在“转起来之后怎么让它听话”。如果只是拼硬件半天就能把轮子点亮可一旦进入里程计、导航、rviz2 显示这些环节你立刻会意识到这个项目的真正难点不是单片机编程也不是 ROS2 的某个具体功能而是两套完全不同的开发范式怎么在一条串口线上达成协作。这篇文章想分享的不是又一个“从零装机教程”而是我在把一个树莓派 ROS2 小车从能跑到能用、从手搓到可调试的过程中沉淀下来的一套判断框架。里面涉及环境搭建、STM32 固件职责、通信协议设计、ROS2 控制链路的搭建顺序以及那些最容易让人卡住一整天的细节。如果你正打算做同类型项目或者已经在做但总觉得哪里不对劲可以沿着下面几个阶段对照自己的进度。1. 先搞清楚这辆小车的“驾驶舱”到底在哪里很多人会把“树莓派 ROS2 控制 STM32 小车”理解成一件主从关系明确的事树莓派是大脑STM32 是手脚。这个说法方向不错但落地时容易产生一个认知偏差——把树莓派当成无所不能的控制中心把所有希望寄托在 ROS2 节点上。1.1 树莓派处理不了实时性这才是双芯片架构的底层原因ROS2 本身运行在 Linux 之上树莓派跑的是完整的 Ubuntu 系统进程调度、内存管理、网络协议栈都会引入不确定性。你可以给某个节点设置很高的优先级但 Linux 不是实时操作系统重要的 PWM 输出、编码器计数、堵转保护这些任务如果都交给树莓派一旦系统负载升高轮子响应就会出现几十毫秒的抖动。对建图导航来说几十毫秒的延迟足以让里程计数据产生可见误差。STM32 在这里要承担的是那些对时间敏感的工作读取编码器、生成 PWM、检测 IO 状态、执行简单的闭环控制。这些任务的特点是循环周期固定、中断频率确定、单次计算量小。它们不该被 Linux 的调度器随意打断。所以更准确的一层理解是树莓派负责的是“该往哪走、走多远”STM32 负责的是“电机实际怎么转、转了多少”。前者是决策层后者是执行与反馈层。1.2 职责边界清晰之后代码结构才不会乱这个项目里最容易出现的失控局面是两边代码都写得太多、交叉太多。比如有人在 STM32 上写了一个完整的 PID 调速又在树莓派上写了一套同样的逻辑有人让 STM32 直接处理激光雷达数据或者让树莓派去读电机编码器引脚。我的建议很明确STM32 侧只做三件事。接收上层下发的目标速度或目标位置。根据编码器反馈执行闭环控制。回传当前转速、方向、状态、电压等必要信息。而路径规划、建图、避障、视觉识别这些任务一律留在树莓派的 ROS2 环境里。每一层只处理自己职责内的逻辑调试的时候才能按层排查。建议动手焊板子之前先拿一张纸把数据流从头到尾画一遍。从“ROS2 节点发出 cmd_vel”一直到“车轮转起来编码器产生计数”中间经过哪些接口、哪些线程、哪些协议帧全部标出来。这张图就是后面所有工作的蓝图。2. 树莓派端环境搭建比安装命令更重要的是版本匹配思维树莓派端的核心任务是先让 Ubuntu、ROS2、通信串口都处于一个可控状态。很多人在这一步还没踩到真正的坑反而先被环境问题劝退了。热搜词里频繁出现“树莓派5 清华源 ubuntu22.04”“ros2 humble”“ubuntu24.04 安装 ros2”说明大家确实都在这一带摸索。2.1 镜像和 ROS2 版本要锁在一起考虑不要先装完系统再想版本ROS2 的每个发行版都绑定特定 Ubuntu 版本的官方支持。Humble 对应 Ubuntu 22.04如果树莓派已经刷了 Ubuntu 24.04再从源码或者第三方源编译安装 ROS2成本会显著上升。选择开发板系统镜像时就要先想清楚最终想用哪个 ROS2 发行版而不是拿到板子后先装一个最新系统再去外网找兼容方案。以树莓派 5 搭配 ROS2 Humble 为例常见的路径是选择 Ubuntu Server 22.04 镜像。注意尽量选 Server 而不是 Desktop 版本原因有两个一是桌面环境对树莓派的内存和 SD 卡 IO 压力较大二是机器人开发场景里图形界面大多通过 VNC、rviz2 远程显示或后续单独配置没必要让板卡本地跑一个完整桌面。如果你手头是新一些的树莓派型号比如 5 代更要注意不同型号的内核外设支持和启动固件差异可能影响 CSI 摄像头、GPIO、串口设备节点的表现。OS 镜像的厂商适配程度往往比博通的芯片型号本身更能决定你能否顺利跑通 ROS2。2.2 换源不是复制粘贴就结束要验证 GPG 和源文件生效对于国内网络环境树莓派换源几乎是必经之路。常见的清华源、阿里源都提供 Ubuntu 和 ROS2 的镜像帮助文档。很多人照着文档操作后仍然报错多数原因是 GPG key 没导入成功或者只换了 apt 源而没换 ROS2 的源。我建议按这条链路操作并逐步验证备份原始源文件保留回滚能力。修改 Ubuntu 源时注意 codename22.04 是 jammy24.04 是 noble。ROS2 源配置文件路径是/etc/apt/sources.list.d/ros2.list内容要和系统版本匹配。每次换源后执行sudo apt update时注意看是否出现 GPG 错误或 404 提示。安装 ros-humble-desktop 前先确认ros2 --version对应的环境变量可以正常加载。这里有一个常被忽略的操作ROS2 安装完成后需要执行source /opt/ros/humble/setup.bash。如果你把这一行写进~/.bashrc后续打开新终端会自动生效。可如果你同时在多个终端里工作且有的终端在source之前执行了命令就会遇到ros2: command not found它不是安装问题而是环境变量未生效。2.3 树莓派端还要提前准备串口权限树莓派和 STM32 通过 UART 通信时Linux 下访问串口设备需要权限。当前用户不在dialout组中程序打开/dev/ttyAMA0或/dev/ttyUSB0时会提示 Permission denied。建议系统装好后立刻执行sudo usermod -aG dialout $USER添加完组后先注销再登录或者重启一次否则当前会话可能不生效。这个操作虽然不起眼但它会直接影响后面所有串口通信节点的运行。3. STM32 侧固件的核心不是“让电机转”而是“怎么描述电机状态”STM32 在 ROS2 小车里的职责是要给上层提供一个可靠的执行接口。你不会让 STM32 去理解 ROS2 的 DDS 协议也不应该让它去处理复杂的数据帧解析之外的业务逻辑。它要做的是一个忠实的“执行器”。3.1 开发环境选择HAL 库和标准外设库都不是银弹ST 官方提供的开发方式一直在演进从早期的标准外设库到现在的 HAL 库、LL 库再到各种图形化配置工具。对于 ROS2 小车这种中等复杂度项目我一般用 STM32CubeMX 生成初始化代码然后基于 HAL 库编写控制逻辑。原因是 CubeMX 能快速完成时钟树、GPIO、定时器、串口和 DMA 的图形化配置你不需要把时间浪费在翻阅参考手册配置寄存器上。但也有反面教训CubeMX 生成代码可以跑不代表它就是最优解。你在配置 TIM 输出 PWM 时要注意通道映射和定时器时钟源不同定时器挂在不同总线上APB1 和 APB2 的时钟频率可能不同。如果 PWM 频率不符合预期先查时钟树再查预分频和自动重装值。// HAL 库中 TIM 输出 PWM 的常见初始化框架 TIM_OC_InitTypeDef sConfigOC {0}; sConfigOC.OCMode TIM_OCMODE_PWM1; sConfigOC.Pulse 0; sConfigOC.OCPolarity TIM_OCPOLARITY_HIGH; sConfigOC.OCFastMode TIM_OCFAST_DISABLE; HAL_TIM_PWM_ConfigChannel(htim1, sConfigOC, TIM_CHANNEL_1); HAL_TIM_PWM_Start(htim1, TIM_CHANNEL_1);这个例子是工程写法不是完整程序。关键是你要理解 Pulse 值对应的是比较寄存器修改它就能在中断之外改变占空比。3.2 定时器不只是输出 PWM还要去读编码器STM32 驱动直流电机小车常用的带编码器电机需要同时输出 PWM 和读取 AB 相脉冲。STM32 的高级定时器和通用定时器可以从外部引脚输入编码器信号并自动完成计数。这里有一个很容易误判的逻辑编码器计数不是“看当前转速”而是“统计一段时间内的脉冲变化量”。你在上层计算速度时通常会对差值做换算。STM32 如果配置了编码器接口模式不需要在中断里频繁计数硬件会自动把脉冲累计到计数寄存器里。你只需要按固定周期读取该寄存器再换算成转速。如果出现电机在转但速度读数为零排查顺序通常是编码器线序是否接反或接触不良。定时器的编码器模式配置是否正确。读取计数器的周期是否太长导致计数溢出被忽略。换算系数是否写错脉冲数与轮子转圈数对应不上。3.3 串口中断与 DMA 的选择会直接影响通信稳定性STM32 与树莓派通过 UART 通信时最简单的方式是串口接收中断加环形缓冲区。每个字节到达时触发中断把数据写入环形缓冲主循环里再做帧解析。这种方式代码直观但在高波特率或持续大量数据收发时可能因为频繁进中断而占掉过多 CPU。另一种常见做法是 DMA 空闲中断DMA 把串口接收到的数据连续搬运到内存缓冲区当检测到串口空闲时再处理这一整段数据。这种方式的优势是降低 CPU 中断频率更适合小车上传感器数据持续上行、控制指令持续下行的场景。但要注意DMA 收发协议对帧格式更敏感。如果使用变长帧你必须在协议层设计明确的帧头、长度、校验、帧尾否则 DMA 很难判断一帧数据在哪里结束。4. 通信链路桥接两端的不是一根杜邦线而是一套状态约定如果把树莓派和 STM32 分成两个“国家”ROS2 消息和单片机报文就是两种完全不同的语言。中间需要翻译和约定而这一层恰恰是这个项目里最容易出“玄学问题”的地方。4.1 物理层选择UART 直连和 USB 转串口的权衡树莓派 GPIO 上的 UART例如/dev/ttyAMA0或/dev/serial0与 STM32 的 UART 直连接线少、成本低但会占用 GPIO且电平匹配、地线连接必须谨慎。树莓派 GPIO 的 UART 电平是 3.3V很多 STM32 板子也是 3.3V 逻辑可以直连但如果你用的是带 5V 电平的 MCU 板或其他模块就需要确认电平兼容否则可能损坏引脚。USB 转串口方案则更灵活给 STM32 板子配上 USB 转 TTL 模块以虚拟串口的方式接到树莓派 USB 口设备节点通常是/dev/ttyUSB0。它的好处是方便插拔和调试但偶尔会有 USB 转串口芯片在树莓派休眠或重启后失去响应的问题需要检查权限和重新枚举设备。选择哪种方案取决于你小车的硬件布局和长期使用的稳定性要求。我的经验是前期验证时用 USB 转串口比较省事如果要做成较稳定的整机建议用树莓派的硬件 UART 与 STM32 直连减少一个 USB 转换环节出现异常的可能。4.2 协议设计的核心是“状态可预期”不是把 JSON 搬到单片机很多初学者会想树莓派上跑的是 ROS2能不能直接把数据组个 JSON 然后发给 STM32对于资源充足的 Linux 系统这没问题但 STM32 解析变长 JSON 需要额外的内存和串口缓冲。更常见的做法是自定义二进制帧协议。一份简明的帧结构大致是帧头(2字节) | 数据长度(1字节) | 数据域(n字节) | 校验(1字节或2字节)数据域里可以打包目标线速度、目标角速度或传感器状态、电池电压、编码器累计值等字段。帧头建议用两个固定的非 ASCII 字节比如 0xAA 0x55减少误触发校验字段用 CRC8 或简单的累加校验都能起到基本作用。协议这块最重要的不是格式多漂亮而是两边对“数据域里每个字段的字节序、单位、范围”要有一份精确约定。比如速度用的是 mm/s 还是 m/s是 int16 还是 float是低字节在前还是高字节在前任何一处不匹配都会造成轮子转速和指令之间出现莫名其妙的倍数关系。4.3 在 ROS2 和 STM32 之间你还需要一个“翻译节点”ROS2 的cmd_vel消息类型是geometry_msgs/msg/Twist它包含线速度和角速度。这个结构不能直接通过串口发给 STM32。你需要在树莓派侧写一个 ROS2 节点订阅/cmd_vel将其中的线速度和角速度按照你的运动学模型换算成左右轮目标速度然后打包成自定义二进制帧通过串口发送给 STM32。同样STM32 回传的编码器数据需要在这个节点里被解析成 ROS2 的里程计消息/odom并发布出来后续才能在 rviz2 里看到机器人模型运动。所以整个链路是/cmd_vel - 节点解析 - 二进制帧 - UART - STM32控制电机 STM32编码器 - UART - 节点解析 - /odom - rviz2 / nav2这个中间节点通常会被称为“机器人驱动节点”或“底层桥接节点”。它决定了两套系统的耦合程度。如果你把协议解析逻辑写得太分散后续修改字段或调参数会非常痛苦。5. ROS2 控制链路的搭建不要一开始就上 nav2先让一个轮子“可信”很多人搜索“ros2 树莓派 stm32 小车”时心里其实想的是让小车最终能导航在 rviz2 里看到地图。但如果你一开始就奔着导航去可能一周后还在跟 TF 树和 costmap 较劲。反过来如果按照“先让指令到轮子、再让轮子变数据、最后让数据驱动地图”的顺序搭建每一步的排查边界都会非常清晰。5.1 第一阶段从cmd_vel话题到电机转动的“单向链路”第一个应该跑通的目标非常窄在树莓派终端发布一条速度指令小车能按照预期方向转动对应轮子。ros2 topic pub /cmd_vel geometry_msgs/msg/Twist {linear: {x: 0.2}, angular: {z: 0.0}}这个阶段里你不需要 rviz2、不需要建图甚至不需要里程计。你需要确认的是话题是否发布、驱动节点是否订阅到、串口是否发送成功、STM32 是否收到合法帧、PWM 波形是否按指令输出。这条链路上任何一个环节断了都能通过分阶段排查快速定位。可以先测试固定占空比在 STM32 代码里写死一个 PWM 值确认电机可以转动同时确认方向和预期一致。然后去掉写死值让 STM32 根据串口指令计算占空比再输出。这样做的好处是当轮子不转时你能区分是执行器问题还是通信问题。5.2 第二阶段编码器回传里程计让小车“知道自己走了多远”当速度指令可控之后再让 STM32 周期性发送编码器累计值。树莓派上的驱动节点将这些值换算成左右轮速度再通过运动学模型计算机器人的位姿变化发布/odom。在这个阶段用 rviz2 显示 TF 树和模型走向“在可视化界面里看到小车动了”正是很多人第一次感到“这个项目活了”的时刻。实际上这一阶段要花时间处理的是单位换算和坐标定义。轮距、轮径、编码器每圈脉冲数、减速比任何一个参数不准确都会让模型要么转着转着漂移要么在原地打转。用 rviz2 检查时要注意固定坐标系建议设为odom。机器人 base_link 与 odom 之间的 TF 必须由里程计节点发布。如果机器人模型没出现先查 URDF/Xacro 和 robot_state_publisher。如果模型在动但方向不对先检查 STM32 端返回的符号和树莓派端符号是否一致。5.3 第三阶段激光雷达、nav2、地图都在基础闭环之后接进来只有当下发速度和读取里程计构成一个“可信闭环”之后再接入激光雷达和 nav2才有意义。导航框架默认依赖一个准确的odom如果你在里程计都有误差的前提下直接跑 nav2地图会看起来“扭曲”路径规划也会反复失败。导航场景下建议先用遥控或手动控制让小车在室内转一圈用 SLAM 工具建一张简单地图观察地图轮廓是否和真实环境一致。如果地图出现明显错位大概率不是 nav2 参数问题而是里程计或激光雷达的 TF 有误。提醒把“导航跑不好”等同于 nav2 参数没调好是新手最常见的误判。先检查底层反馈的准确性再到上层找原因会省掉大量无效调参时间。6. 真正让人崩溃的细节串口、波形和日志开发到中后期最常见的卡住不是某个概念不懂而是一些工程细节反复消耗时间。以下四个问题是我在高频搜索词、社区问答和自己项目中反复看到的值得单独列出。6.1 STM32 的 delay 卡死不一定是程序 bug很多人遇到过HAL_Delay()或自定义延时函数卡住不返回。这种情况多数和中断优先级、SysTick 配置有关。HAL 库的默认HAL_Delay()依赖于 SysTick 中断如果你在某个中断里调用了延时函数并且这个中断优先级比 SysTick 更高或存在冲突就可能出现死等。建议优先避免在中断回调中调用延时函数。如果必须在中断服务里等待某个电平变化可以改用状态机或定时器轮询方式。另一个容易触发类似问题的是在串口接收中断里做复杂解析并调用HAL_Delay()这会拖慢中断返回造成其他中断被阻塞表象上也是“程序卡住”。6.2 树莓派 GPIO 和摄像头问题要先分层观察如果你给小车加了摄像头或要控制 GPIO会比较常在树莓派这层遇到问题。摄像头驱动不上先检查libcamera-hello能否正常出图GPIO 不可控先确认当前用户的权限和引脚编号再检查是否有其他服务占用该引脚。树莓派 5 等新硬件的摄像头排线和引脚定义和老型号有一些差异接线前一定找到对应型号的官方引脚图和摄像头适配说明不能靠老经验直接套。比如 CSI 摄像头接口位置和排线方向错了会识别不到设备。6.3 USB 转串口的“消失”问题不是换一根线就能解决调试时用 USB 转串口连接跑了一会儿设备节点消失了或者波特率对不上出现乱码。先不要急着怀疑线坏了按照下面的路径检查dmesg | tail -20查看内核日志中有没有 USB disconnect 事件。ls -l /dev/ttyUSB*确认设备节点是否还在。重新插拔后对比设备节点是否变化。如果换了 USB 口导致设备名从/dev/ttyUSB0变成/dev/ttyUSB1检查你的节点和脚本用的是不是固定设备路径最稳的方法是配置 udev 规则按串口芯片序列号生成固定软链接。6.4 日志能力是 ROS2 小车长期优化最重要的基础设施样车阶段你可能觉得打印 log 是在浪费时间等到里程计不准、偶然丢帧、速度指令偶发无响应时才发现没有日志记录根本无法复盘。建议在驱动节点上保留双层日志一层是 ROS2 标准输出打印关键状态和时间戳一层是文件日志记录一段时间内收发的关键帧内容方便后续分析偶发问题。网上热门搜索词里出现的“ros2 八叉树地图导航”“rviz2 安装使用”其实都属于后期能力。在这些能力之前数据链路日志的规范化才是真正决定你后续能否进行长期调试的分水岭。7. 这类小车方案的适用边界与长期演进文章最后回到一个未必让人舒服的事实树莓派 STM32 的 ROS2 小车是一个很棒的“学习平台”和“原型平台”但它不一定适合所有场景。理解它的边界比能把它搭起来更重要。7.1 适合的场景学习、验证、教学和二次开发如果你在接触 ROS2、机器人学、嵌入式控制这套组合几乎是性价比最高的实验环境。它让你能同时接触到 Linux 系统、DDS 通信、嵌入式外设编程、运动学模型、传感器融合和可视化工具并且每一层都有大量参考资源。从学习价值来看它的最大收益是“理解多层系统如何协同”而不是“做出一个产品”。7.2 不适合的场景要求高实时性、高可靠性和低成本量产的项目树莓派加外置 MCU 的功耗、体积、成本、启动时间和故障恢复能力都不适合工业级量产产品。工业机器人控制更多会走向一体化控制器、FPGA 或实时 Linux、专用运动控制板等方案。如果你只是需要一个“能自动跑的底盘”市面上也有大量集成度更高的轮式机器人开发套件底层细节已经封装完成让你能把精力集中在导航和业务逻辑上。7.3 长期演进时最值得投入的三个方向如果你搭完基础功能后不想停在原地我认为优先投入以下三个方向设计更可靠的底盘通信协议包括帧超时重传、心跳检测、错误码定义而不是只保证“大概率能通”。引入仿真环境把上层算法先在 Gazebo 或 Webots 里验证等逻辑稳定后再下放到实体车。建立参数化配置体系把轮距、轮径、PID 参数、串口波特率都做成可配置项而不是散落在代码里的魔法数字。这三个方向都会让项目的复杂度上升但也正是从“实验品”走向“可维护系统”的关键路径。这个项目真正教给你的并不是某个开发板的用法。它让你看清一层一层系统之间如何通过明确的接口协作Linux 与单片机的边界、ROS2 与自定义协议的边界、上层规划与底层执行的边界。把这些边界管理好换什么板子、用什么算法你都能快速迁移。如果你现在只是刚刚准备开始我给你的建议是先别急着焊电机和调 PID。先把树莓派和 STM32 之间的串口打通用两根线、一个串口助手、一条自定义指令完成最小系统验证。这个“最小通信闭环”一旦建立后面的路就会顺畅得多。
树莓派+STM32 ROS2小车开发：从串口通信到导航的调试框架
树莓派加 STM32 做 ROS2 小车听起来是个非常标准的入门项目但真正动手之后你会发现问题从来不在“能不能转起来”而在“转起来之后怎么让它听话”。如果只是拼硬件半天就能把轮子点亮可一旦进入里程计、导航、rviz2 显示这些环节你立刻会意识到这个项目的真正难点不是单片机编程也不是 ROS2 的某个具体功能而是两套完全不同的开发范式怎么在一条串口线上达成协作。这篇文章想分享的不是又一个“从零装机教程”而是我在把一个树莓派 ROS2 小车从能跑到能用、从手搓到可调试的过程中沉淀下来的一套判断框架。里面涉及环境搭建、STM32 固件职责、通信协议设计、ROS2 控制链路的搭建顺序以及那些最容易让人卡住一整天的细节。如果你正打算做同类型项目或者已经在做但总觉得哪里不对劲可以沿着下面几个阶段对照自己的进度。1. 先搞清楚这辆小车的“驾驶舱”到底在哪里很多人会把“树莓派 ROS2 控制 STM32 小车”理解成一件主从关系明确的事树莓派是大脑STM32 是手脚。这个说法方向不错但落地时容易产生一个认知偏差——把树莓派当成无所不能的控制中心把所有希望寄托在 ROS2 节点上。1.1 树莓派处理不了实时性这才是双芯片架构的底层原因ROS2 本身运行在 Linux 之上树莓派跑的是完整的 Ubuntu 系统进程调度、内存管理、网络协议栈都会引入不确定性。你可以给某个节点设置很高的优先级但 Linux 不是实时操作系统重要的 PWM 输出、编码器计数、堵转保护这些任务如果都交给树莓派一旦系统负载升高轮子响应就会出现几十毫秒的抖动。对建图导航来说几十毫秒的延迟足以让里程计数据产生可见误差。STM32 在这里要承担的是那些对时间敏感的工作读取编码器、生成 PWM、检测 IO 状态、执行简单的闭环控制。这些任务的特点是循环周期固定、中断频率确定、单次计算量小。它们不该被 Linux 的调度器随意打断。所以更准确的一层理解是树莓派负责的是“该往哪走、走多远”STM32 负责的是“电机实际怎么转、转了多少”。前者是决策层后者是执行与反馈层。1.2 职责边界清晰之后代码结构才不会乱这个项目里最容易出现的失控局面是两边代码都写得太多、交叉太多。比如有人在 STM32 上写了一个完整的 PID 调速又在树莓派上写了一套同样的逻辑有人让 STM32 直接处理激光雷达数据或者让树莓派去读电机编码器引脚。我的建议很明确STM32 侧只做三件事。接收上层下发的目标速度或目标位置。根据编码器反馈执行闭环控制。回传当前转速、方向、状态、电压等必要信息。而路径规划、建图、避障、视觉识别这些任务一律留在树莓派的 ROS2 环境里。每一层只处理自己职责内的逻辑调试的时候才能按层排查。建议动手焊板子之前先拿一张纸把数据流从头到尾画一遍。从“ROS2 节点发出 cmd_vel”一直到“车轮转起来编码器产生计数”中间经过哪些接口、哪些线程、哪些协议帧全部标出来。这张图就是后面所有工作的蓝图。2. 树莓派端环境搭建比安装命令更重要的是版本匹配思维树莓派端的核心任务是先让 Ubuntu、ROS2、通信串口都处于一个可控状态。很多人在这一步还没踩到真正的坑反而先被环境问题劝退了。热搜词里频繁出现“树莓派5 清华源 ubuntu22.04”“ros2 humble”“ubuntu24.04 安装 ros2”说明大家确实都在这一带摸索。2.1 镜像和 ROS2 版本要锁在一起考虑不要先装完系统再想版本ROS2 的每个发行版都绑定特定 Ubuntu 版本的官方支持。Humble 对应 Ubuntu 22.04如果树莓派已经刷了 Ubuntu 24.04再从源码或者第三方源编译安装 ROS2成本会显著上升。选择开发板系统镜像时就要先想清楚最终想用哪个 ROS2 发行版而不是拿到板子后先装一个最新系统再去外网找兼容方案。以树莓派 5 搭配 ROS2 Humble 为例常见的路径是选择 Ubuntu Server 22.04 镜像。注意尽量选 Server 而不是 Desktop 版本原因有两个一是桌面环境对树莓派的内存和 SD 卡 IO 压力较大二是机器人开发场景里图形界面大多通过 VNC、rviz2 远程显示或后续单独配置没必要让板卡本地跑一个完整桌面。如果你手头是新一些的树莓派型号比如 5 代更要注意不同型号的内核外设支持和启动固件差异可能影响 CSI 摄像头、GPIO、串口设备节点的表现。OS 镜像的厂商适配程度往往比博通的芯片型号本身更能决定你能否顺利跑通 ROS2。2.2 换源不是复制粘贴就结束要验证 GPG 和源文件生效对于国内网络环境树莓派换源几乎是必经之路。常见的清华源、阿里源都提供 Ubuntu 和 ROS2 的镜像帮助文档。很多人照着文档操作后仍然报错多数原因是 GPG key 没导入成功或者只换了 apt 源而没换 ROS2 的源。我建议按这条链路操作并逐步验证备份原始源文件保留回滚能力。修改 Ubuntu 源时注意 codename22.04 是 jammy24.04 是 noble。ROS2 源配置文件路径是/etc/apt/sources.list.d/ros2.list内容要和系统版本匹配。每次换源后执行sudo apt update时注意看是否出现 GPG 错误或 404 提示。安装 ros-humble-desktop 前先确认ros2 --version对应的环境变量可以正常加载。这里有一个常被忽略的操作ROS2 安装完成后需要执行source /opt/ros/humble/setup.bash。如果你把这一行写进~/.bashrc后续打开新终端会自动生效。可如果你同时在多个终端里工作且有的终端在source之前执行了命令就会遇到ros2: command not found它不是安装问题而是环境变量未生效。2.3 树莓派端还要提前准备串口权限树莓派和 STM32 通过 UART 通信时Linux 下访问串口设备需要权限。当前用户不在dialout组中程序打开/dev/ttyAMA0或/dev/ttyUSB0时会提示 Permission denied。建议系统装好后立刻执行sudo usermod -aG dialout $USER添加完组后先注销再登录或者重启一次否则当前会话可能不生效。这个操作虽然不起眼但它会直接影响后面所有串口通信节点的运行。3. STM32 侧固件的核心不是“让电机转”而是“怎么描述电机状态”STM32 在 ROS2 小车里的职责是要给上层提供一个可靠的执行接口。你不会让 STM32 去理解 ROS2 的 DDS 协议也不应该让它去处理复杂的数据帧解析之外的业务逻辑。它要做的是一个忠实的“执行器”。3.1 开发环境选择HAL 库和标准外设库都不是银弹ST 官方提供的开发方式一直在演进从早期的标准外设库到现在的 HAL 库、LL 库再到各种图形化配置工具。对于 ROS2 小车这种中等复杂度项目我一般用 STM32CubeMX 生成初始化代码然后基于 HAL 库编写控制逻辑。原因是 CubeMX 能快速完成时钟树、GPIO、定时器、串口和 DMA 的图形化配置你不需要把时间浪费在翻阅参考手册配置寄存器上。但也有反面教训CubeMX 生成代码可以跑不代表它就是最优解。你在配置 TIM 输出 PWM 时要注意通道映射和定时器时钟源不同定时器挂在不同总线上APB1 和 APB2 的时钟频率可能不同。如果 PWM 频率不符合预期先查时钟树再查预分频和自动重装值。// HAL 库中 TIM 输出 PWM 的常见初始化框架 TIM_OC_InitTypeDef sConfigOC {0}; sConfigOC.OCMode TIM_OCMODE_PWM1; sConfigOC.Pulse 0; sConfigOC.OCPolarity TIM_OCPOLARITY_HIGH; sConfigOC.OCFastMode TIM_OCFAST_DISABLE; HAL_TIM_PWM_ConfigChannel(htim1, sConfigOC, TIM_CHANNEL_1); HAL_TIM_PWM_Start(htim1, TIM_CHANNEL_1);这个例子是工程写法不是完整程序。关键是你要理解 Pulse 值对应的是比较寄存器修改它就能在中断之外改变占空比。3.2 定时器不只是输出 PWM还要去读编码器STM32 驱动直流电机小车常用的带编码器电机需要同时输出 PWM 和读取 AB 相脉冲。STM32 的高级定时器和通用定时器可以从外部引脚输入编码器信号并自动完成计数。这里有一个很容易误判的逻辑编码器计数不是“看当前转速”而是“统计一段时间内的脉冲变化量”。你在上层计算速度时通常会对差值做换算。STM32 如果配置了编码器接口模式不需要在中断里频繁计数硬件会自动把脉冲累计到计数寄存器里。你只需要按固定周期读取该寄存器再换算成转速。如果出现电机在转但速度读数为零排查顺序通常是编码器线序是否接反或接触不良。定时器的编码器模式配置是否正确。读取计数器的周期是否太长导致计数溢出被忽略。换算系数是否写错脉冲数与轮子转圈数对应不上。3.3 串口中断与 DMA 的选择会直接影响通信稳定性STM32 与树莓派通过 UART 通信时最简单的方式是串口接收中断加环形缓冲区。每个字节到达时触发中断把数据写入环形缓冲主循环里再做帧解析。这种方式代码直观但在高波特率或持续大量数据收发时可能因为频繁进中断而占掉过多 CPU。另一种常见做法是 DMA 空闲中断DMA 把串口接收到的数据连续搬运到内存缓冲区当检测到串口空闲时再处理这一整段数据。这种方式的优势是降低 CPU 中断频率更适合小车上传感器数据持续上行、控制指令持续下行的场景。但要注意DMA 收发协议对帧格式更敏感。如果使用变长帧你必须在协议层设计明确的帧头、长度、校验、帧尾否则 DMA 很难判断一帧数据在哪里结束。4. 通信链路桥接两端的不是一根杜邦线而是一套状态约定如果把树莓派和 STM32 分成两个“国家”ROS2 消息和单片机报文就是两种完全不同的语言。中间需要翻译和约定而这一层恰恰是这个项目里最容易出“玄学问题”的地方。4.1 物理层选择UART 直连和 USB 转串口的权衡树莓派 GPIO 上的 UART例如/dev/ttyAMA0或/dev/serial0与 STM32 的 UART 直连接线少、成本低但会占用 GPIO且电平匹配、地线连接必须谨慎。树莓派 GPIO 的 UART 电平是 3.3V很多 STM32 板子也是 3.3V 逻辑可以直连但如果你用的是带 5V 电平的 MCU 板或其他模块就需要确认电平兼容否则可能损坏引脚。USB 转串口方案则更灵活给 STM32 板子配上 USB 转 TTL 模块以虚拟串口的方式接到树莓派 USB 口设备节点通常是/dev/ttyUSB0。它的好处是方便插拔和调试但偶尔会有 USB 转串口芯片在树莓派休眠或重启后失去响应的问题需要检查权限和重新枚举设备。选择哪种方案取决于你小车的硬件布局和长期使用的稳定性要求。我的经验是前期验证时用 USB 转串口比较省事如果要做成较稳定的整机建议用树莓派的硬件 UART 与 STM32 直连减少一个 USB 转换环节出现异常的可能。4.2 协议设计的核心是“状态可预期”不是把 JSON 搬到单片机很多初学者会想树莓派上跑的是 ROS2能不能直接把数据组个 JSON 然后发给 STM32对于资源充足的 Linux 系统这没问题但 STM32 解析变长 JSON 需要额外的内存和串口缓冲。更常见的做法是自定义二进制帧协议。一份简明的帧结构大致是帧头(2字节) | 数据长度(1字节) | 数据域(n字节) | 校验(1字节或2字节)数据域里可以打包目标线速度、目标角速度或传感器状态、电池电压、编码器累计值等字段。帧头建议用两个固定的非 ASCII 字节比如 0xAA 0x55减少误触发校验字段用 CRC8 或简单的累加校验都能起到基本作用。协议这块最重要的不是格式多漂亮而是两边对“数据域里每个字段的字节序、单位、范围”要有一份精确约定。比如速度用的是 mm/s 还是 m/s是 int16 还是 float是低字节在前还是高字节在前任何一处不匹配都会造成轮子转速和指令之间出现莫名其妙的倍数关系。4.3 在 ROS2 和 STM32 之间你还需要一个“翻译节点”ROS2 的cmd_vel消息类型是geometry_msgs/msg/Twist它包含线速度和角速度。这个结构不能直接通过串口发给 STM32。你需要在树莓派侧写一个 ROS2 节点订阅/cmd_vel将其中的线速度和角速度按照你的运动学模型换算成左右轮目标速度然后打包成自定义二进制帧通过串口发送给 STM32。同样STM32 回传的编码器数据需要在这个节点里被解析成 ROS2 的里程计消息/odom并发布出来后续才能在 rviz2 里看到机器人模型运动。所以整个链路是/cmd_vel - 节点解析 - 二进制帧 - UART - STM32控制电机 STM32编码器 - UART - 节点解析 - /odom - rviz2 / nav2这个中间节点通常会被称为“机器人驱动节点”或“底层桥接节点”。它决定了两套系统的耦合程度。如果你把协议解析逻辑写得太分散后续修改字段或调参数会非常痛苦。5. ROS2 控制链路的搭建不要一开始就上 nav2先让一个轮子“可信”很多人搜索“ros2 树莓派 stm32 小车”时心里其实想的是让小车最终能导航在 rviz2 里看到地图。但如果你一开始就奔着导航去可能一周后还在跟 TF 树和 costmap 较劲。反过来如果按照“先让指令到轮子、再让轮子变数据、最后让数据驱动地图”的顺序搭建每一步的排查边界都会非常清晰。5.1 第一阶段从cmd_vel话题到电机转动的“单向链路”第一个应该跑通的目标非常窄在树莓派终端发布一条速度指令小车能按照预期方向转动对应轮子。ros2 topic pub /cmd_vel geometry_msgs/msg/Twist {linear: {x: 0.2}, angular: {z: 0.0}}这个阶段里你不需要 rviz2、不需要建图甚至不需要里程计。你需要确认的是话题是否发布、驱动节点是否订阅到、串口是否发送成功、STM32 是否收到合法帧、PWM 波形是否按指令输出。这条链路上任何一个环节断了都能通过分阶段排查快速定位。可以先测试固定占空比在 STM32 代码里写死一个 PWM 值确认电机可以转动同时确认方向和预期一致。然后去掉写死值让 STM32 根据串口指令计算占空比再输出。这样做的好处是当轮子不转时你能区分是执行器问题还是通信问题。5.2 第二阶段编码器回传里程计让小车“知道自己走了多远”当速度指令可控之后再让 STM32 周期性发送编码器累计值。树莓派上的驱动节点将这些值换算成左右轮速度再通过运动学模型计算机器人的位姿变化发布/odom。在这个阶段用 rviz2 显示 TF 树和模型走向“在可视化界面里看到小车动了”正是很多人第一次感到“这个项目活了”的时刻。实际上这一阶段要花时间处理的是单位换算和坐标定义。轮距、轮径、编码器每圈脉冲数、减速比任何一个参数不准确都会让模型要么转着转着漂移要么在原地打转。用 rviz2 检查时要注意固定坐标系建议设为odom。机器人 base_link 与 odom 之间的 TF 必须由里程计节点发布。如果机器人模型没出现先查 URDF/Xacro 和 robot_state_publisher。如果模型在动但方向不对先检查 STM32 端返回的符号和树莓派端符号是否一致。5.3 第三阶段激光雷达、nav2、地图都在基础闭环之后接进来只有当下发速度和读取里程计构成一个“可信闭环”之后再接入激光雷达和 nav2才有意义。导航框架默认依赖一个准确的odom如果你在里程计都有误差的前提下直接跑 nav2地图会看起来“扭曲”路径规划也会反复失败。导航场景下建议先用遥控或手动控制让小车在室内转一圈用 SLAM 工具建一张简单地图观察地图轮廓是否和真实环境一致。如果地图出现明显错位大概率不是 nav2 参数问题而是里程计或激光雷达的 TF 有误。提醒把“导航跑不好”等同于 nav2 参数没调好是新手最常见的误判。先检查底层反馈的准确性再到上层找原因会省掉大量无效调参时间。6. 真正让人崩溃的细节串口、波形和日志开发到中后期最常见的卡住不是某个概念不懂而是一些工程细节反复消耗时间。以下四个问题是我在高频搜索词、社区问答和自己项目中反复看到的值得单独列出。6.1 STM32 的 delay 卡死不一定是程序 bug很多人遇到过HAL_Delay()或自定义延时函数卡住不返回。这种情况多数和中断优先级、SysTick 配置有关。HAL 库的默认HAL_Delay()依赖于 SysTick 中断如果你在某个中断里调用了延时函数并且这个中断优先级比 SysTick 更高或存在冲突就可能出现死等。建议优先避免在中断回调中调用延时函数。如果必须在中断服务里等待某个电平变化可以改用状态机或定时器轮询方式。另一个容易触发类似问题的是在串口接收中断里做复杂解析并调用HAL_Delay()这会拖慢中断返回造成其他中断被阻塞表象上也是“程序卡住”。6.2 树莓派 GPIO 和摄像头问题要先分层观察如果你给小车加了摄像头或要控制 GPIO会比较常在树莓派这层遇到问题。摄像头驱动不上先检查libcamera-hello能否正常出图GPIO 不可控先确认当前用户的权限和引脚编号再检查是否有其他服务占用该引脚。树莓派 5 等新硬件的摄像头排线和引脚定义和老型号有一些差异接线前一定找到对应型号的官方引脚图和摄像头适配说明不能靠老经验直接套。比如 CSI 摄像头接口位置和排线方向错了会识别不到设备。6.3 USB 转串口的“消失”问题不是换一根线就能解决调试时用 USB 转串口连接跑了一会儿设备节点消失了或者波特率对不上出现乱码。先不要急着怀疑线坏了按照下面的路径检查dmesg | tail -20查看内核日志中有没有 USB disconnect 事件。ls -l /dev/ttyUSB*确认设备节点是否还在。重新插拔后对比设备节点是否变化。如果换了 USB 口导致设备名从/dev/ttyUSB0变成/dev/ttyUSB1检查你的节点和脚本用的是不是固定设备路径最稳的方法是配置 udev 规则按串口芯片序列号生成固定软链接。6.4 日志能力是 ROS2 小车长期优化最重要的基础设施样车阶段你可能觉得打印 log 是在浪费时间等到里程计不准、偶然丢帧、速度指令偶发无响应时才发现没有日志记录根本无法复盘。建议在驱动节点上保留双层日志一层是 ROS2 标准输出打印关键状态和时间戳一层是文件日志记录一段时间内收发的关键帧内容方便后续分析偶发问题。网上热门搜索词里出现的“ros2 八叉树地图导航”“rviz2 安装使用”其实都属于后期能力。在这些能力之前数据链路日志的规范化才是真正决定你后续能否进行长期调试的分水岭。7. 这类小车方案的适用边界与长期演进文章最后回到一个未必让人舒服的事实树莓派 STM32 的 ROS2 小车是一个很棒的“学习平台”和“原型平台”但它不一定适合所有场景。理解它的边界比能把它搭起来更重要。7.1 适合的场景学习、验证、教学和二次开发如果你在接触 ROS2、机器人学、嵌入式控制这套组合几乎是性价比最高的实验环境。它让你能同时接触到 Linux 系统、DDS 通信、嵌入式外设编程、运动学模型、传感器融合和可视化工具并且每一层都有大量参考资源。从学习价值来看它的最大收益是“理解多层系统如何协同”而不是“做出一个产品”。7.2 不适合的场景要求高实时性、高可靠性和低成本量产的项目树莓派加外置 MCU 的功耗、体积、成本、启动时间和故障恢复能力都不适合工业级量产产品。工业机器人控制更多会走向一体化控制器、FPGA 或实时 Linux、专用运动控制板等方案。如果你只是需要一个“能自动跑的底盘”市面上也有大量集成度更高的轮式机器人开发套件底层细节已经封装完成让你能把精力集中在导航和业务逻辑上。7.3 长期演进时最值得投入的三个方向如果你搭完基础功能后不想停在原地我认为优先投入以下三个方向设计更可靠的底盘通信协议包括帧超时重传、心跳检测、错误码定义而不是只保证“大概率能通”。引入仿真环境把上层算法先在 Gazebo 或 Webots 里验证等逻辑稳定后再下放到实体车。建立参数化配置体系把轮距、轮径、PID 参数、串口波特率都做成可配置项而不是散落在代码里的魔法数字。这三个方向都会让项目的复杂度上升但也正是从“实验品”走向“可维护系统”的关键路径。这个项目真正教给你的并不是某个开发板的用法。它让你看清一层一层系统之间如何通过明确的接口协作Linux 与单片机的边界、ROS2 与自定义协议的边界、上层规划与底层执行的边界。把这些边界管理好换什么板子、用什么算法你都能快速迁移。如果你现在只是刚刚准备开始我给你的建议是先别急着焊电机和调 PID。先把树莓派和 STM32 之间的串口打通用两根线、一个串口助手、一条自定义指令完成最小系统验证。这个“最小通信闭环”一旦建立后面的路就会顺畅得多。
