Ubuntu 20.04下ROS Noetic接入STM32超声波串口实践

简介supersonic.tar.gz 面向ROS与嵌入式控制学习者围绕STM32微控制器、串口通信和HC-SR04超声波传感器搭建一套可运行的测距与指令联动示例。压缩包共58个文件、约1.63MB以C源文件cc/cpp、头文件h/head、样例与测试数据sample、CMake/package.xml配置及工程文件为主兼顾ROS功能包组织、串口通信库和STM32端固件参考目录层级清晰便于按模块查阅与移植。已有396人学习下载说明其在机器人入门与课程实验场景中具有一定参考价值适合机器人操作系统入门、课程设计及小型移动平台调试时对照参考。读者可从中了解supersonic节点如何订阅距离话题、发布STM32控制指令以及超声波测距数据经串口在ROS主机与微控制器之间传递的完整链路同时可参考工程配置、样例数据和串口通信实现快速搭建避障、距离检测或LED联动实验的原型框架对理解ROS与STM32协同控制流程有直接帮助。1. 超声波接进 ROS先对版本再解压 supersonic.tar.gz手里有块 STM32 最小系统板、一个超声波模块想把测距数据接进 ROS 做避障或建图这套 ROS STM32 串口通信的组合几乎是绕不开的第一课。我第一次装 supersonic.tar.gz 是在一台 Ubuntu 18.04 的旧机器上ROS 装的却是 Noeticapt 装到一半就开始报依赖冲突硬着头皮 catkin_make 下去满屏红字里混着 serial 找不到、Python 解释器对不上折腾到半夜也没让话题出过一帧数据。换回 20.04 重装二十分钟就跑通了问题从来不在超声波测距那几行代码而在版本和权限这些前置条件上。这篇按我实际装过一遍的顺序写先对版本、再装依赖、编固件、配串口最后验证。刚上手 ROS 串口通信的新手能照着走已经在别的板子上跑通过、想换套现成工程复现的人也值得看。2. 环境准备Ubuntu 20.04 ROS Noetic 的三组依赖安装顺序这套工程横跨两边一边是跑在 STM32 上的固件一边是跑在 PC 上的 ROS 驱动包中间靠一根 USB 转串口线连着。所以“环境”不是一个东西是三层系统与 ROS 的版本匹配、PC 侧的串口依赖、以及交叉编译工具链。三层里任何一层装错后面看到的报错都会指向错误的方向这也是这类工程最劝退的地方。2.1 版本对照为什么我不建议在 22.04 上硬装先把这张表对一遍对不上就先别解压。组件我用的版本备选影响面操作系统Ubuntu 20.04 LTS18.04决定 ROS 大版本不能混搭ROSNoeticMelodic仅 18.04rospy 脚本跑 Python2 还是 Python3Python3.83.6Melodicpyserial 装到哪个解释器必须一致编译工具gcc / g 9—Noetic 的二进制包就在 9 上编的交叉工具链arm-none-eabi-gcc 10.39-2020-q2newlib 版本影响 printf 浮点输出烧录工具stlink-toolsst-flashopenocd / CubeProgrammer只影响烧录命令写法这里有个反直觉的点ROS 版本不是越新越好是跟着系统走。Noetic 官方只出 20.04 的 deb 包22.04 上根本没有对应的 apt 源硬装会一路缺依赖Melodic 同理只对 18.04 负责。我见过有人把 18.04 的机器装成 Noeticrosdep 去拉一堆 focal 才有的包最后卡在 Python 版本上两边都不认。如果你手上只有 22.04 的机器省事的做法是用虚拟机或者容器开一个 20.04别在原地死磕——这套包是 catkin 结构的换成 ROS2 等于重写不值当。工具链版本也不是随便选。arm-none-eabi-gcc 10 之后的 newlib 在 printf 浮点格式化上和 9 有差异固件里如果用了 printf 往串口打调试信息版本不一致时可能看到一串乱码或者干脆不输出。这不是玄学是 nano.specs 链接选项在作怪后面第三章会讲怎么在 Makefile 里确认。2.2 装 ROS 与串口依赖系统装好先做基础更新然后按顺序来。别跳步rosdep 那一步跳了后面 catkin_make 一样会报缺包。# 1) 添加 ROS 软件源focal 对应 Noetic别写成 jammy sudo sh -c echo deb http://packages.ros.org/ros/ubuntu focal main /etc/apt/sources.list.d/ros-latest.list # 2) 导入签名密钥地址以 ROS 官方当前提供的为准 sudo apt install -y curl gnupg curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - # 3) 装桌面完整版rviz 和 rqt 都在里面后面验证要用 sudo apt update sudo apt install -y ros-noetic-desktop-full # 4) 装构建工具与 rosdep sudo apt install -y python3-rosdep python3-rosinstall-generator python3-wstool build-essential sudo rosdep init rosdep update # 5) 串口相关C 驱动用 roscpp 的 serial 库Python 驱动用 pyserial sudo apt install -y ros-noetic-serial python3-serial这段命令的逻辑是“先给源、再给钥匙、然后批量装”。参数上focal这个代号写错是最常见的低级错误写成 bionic 会拉 18.04 的包装到一半就冲突desktop-full比ros-base多出 rviz、rqt 这些图形工具验证阶段没它们会很别扭ros-noetic-serial提供的是 roscpp 侧的串口封装如果你的驱动节点是 rospy 写的真正起作用的是python3-serial两个都装不亏几十兆的事。sudo rosdep init这一步在有些机器上会报 “already exists”说明之前装过 ROS 残留了配置直接跳过 init 只跑rosdep update就行不用删文件。rosdep update走网络偶尔超时重跑两三次一般能过实在不行换个时间段。装完记得把环境变量写进 shell 配置不写的话每开一个终端都要手动 source很容易忘echo source /opt/ros/noetic/setup.bash ~/.bashrc source ~/.bashrc # 验证能打印出 ROS 版本号就说明装好了 echo $ROS_DISTRO$ROS_DISTRO输出noetic才算过。这一步看着废话但我确实见过有人在没 source 的终端里编译报“找不到 catkin_make”然后去怀疑系统坏了。2.3 交叉编译工具链编固件那一半的依赖ROS 那半边装完只是能跑节点固件还得另外编。STM32 上跑的不是 x86 指令需要 arm 工具链# 交叉编译器与标准库 sudo apt install -y gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi # 烧录工具st-flash 用于 ST-Linkopenocd 作为备选 sudo apt install -y stlink-tools openocd # 版本自检重点看大版本号 arm-none-eabi-gcc -v st-flash --versionlibnewlib-arm-none-eabi是标准 C 库的 arm 版本缺了它链接阶段会报undefined reference to _printf_float之类的错误很误导人。stlink-tools装的是st-flash命令如果你用的是板载 DAP-Link 或者别的调试器就换 openocd两者烧同一份 bin 只是命令不同。工具链版本记一下arm-none-eabi-gcc -v输出里那行gcc version 10.3.1就是它后面 Makefile 里如果出现编译告警先确认是不是版本差异带来的。我一般会把这条输出顺手贴在工程目录的笔记里换机器时好对照省得再翻一遍。3. 固件侧落地在 supersonic 工程里编译并烧录 STM32先把顺序理清楚解压 → 看清目录 → 编固件 → 烧录 → 用串口工具确认板子在发数据。ROS 那边先不碰因为如果板子根本没在吐数据你在 ROS 里调一晚上参数都是白调。这个顺序能帮你把问题范围砍一半。3.1 解压位置与目录结构解压之前先看一眼包里有什么别直接铺到主目录# 只看列表不动文件先确认顶层目录名避免解出一堆散文件 tar -tzf supersonic.tar.gz | head -n 20 # 建个独立目录再解压-C 指定目标路径 mkdir -p ~/supersonic tar -zxvf supersonic.tar.gz -C ~/supersonic # 看两层目录结构心里有个数 cd ~/supersonic find . -maxdepth 2 -type d | sort参数说明-z走 gzip-x是解压-v打印过程-f后面接文件名这个必须紧挨文件名-C指定解到哪。-t是只列表不解压养成先看再解的习惯能避开不少坑比如包里带了绝对路径解出来直接覆盖系统目录。解出来以后工程通常分成两半固件那一半STM32 工程含 Makefile 或者 CubeMX 生成的目录结构和 ROS 那一半catkin 包含 package.xml 和 CMakeLists.txt。这里有个必须强调的点别把固件目录塞进 catkin 工作空间的 src 下。catkin_make 会去遍历 src 里所有带 CMakeLists.txt 的目录把 arm 工程当成 catkin 包来配然后报一堆“找不到 catkin”或者“未知的构建类型”。我一般是这样分开放的# 固件工程独立一个目录 ~/supersonic/firmware/ # ROS 工作空间另外建src 里只放 ROS 包 ~/supersonic_ws/src/这样两边互不干扰catkin_make也只扫该扫的地方。3.2 编译固件Makefile 里三个值得看的变量进固件目录先别急着 make把 Makefile 头部的 MCU 型号、时钟、优化等级扫一眼cd ~/supersonic/firmware # 清理旧产物换工具链之后必须 clean否则会链接到上次的 .o make clean # 四线程编译机器核少就用 -j2 make -j4 # 看产物.elf 用于调试.bin 用于烧录 ls -lh build/*.elf build/*.binMakefile 里通常有三个变量决定成败CPU-mcpucortex-m3这类M0/M3/M4 不能写错写错能编过但跑飞、C_DEFS宏定义比如USE_HAL_DRIVER、STM32F103xB芯片型号宏不对会直接卡在启动文件、OPT优化等级-Og便于调试-Os体积小量产后才考虑。如果make报arm-none-eabi-gcc: command not found不是没装是 PATH 没生效which arm-none-eabi-gcc确认一下或者重新开个终端。还有一种情况是链接阶段报region RAM overflowed那是内存放不下多半是开了浮点 printf 或者加了太大的缓冲区。常见做法是把-u _printf_float去掉或者把调试输出改成整数打印别硬加 RAM 长度。3.3 烧录与串口回环自检烧录前先把板子接上确认调试器认得到# 列出已连接的 ST-Link st-info --probe # 烧录到 Flash 起始地址STM32 一般是 0x8000000 st-flash --reset write build/supersonic.bin 0x80000000x8000000是 STM32 内部 Flash 的映射起点写错地址程序不会跑但烧录命令照样返回成功很容易误判。--reset让芯片烧完自动复位不加就得手动按复位键。如果你用的是别的芯片系列openocd 的写法要换 target 配置比如stm32f4x.cfg芯片系列对不上会报 “unknown device”。烧完先别开 ROS用最原始的方式确认板子在吐数据# 设定串口参数波特率必须和固件里 USART 初始化一致 sudo stty -F /dev/ttyUSB0 115200 raw -echo # 抓 64 字节看有没有帧头 timeout 2 cat /dev/ttyUSB0 | xxd -l 64stty那行是把串口设成原始模式关掉回显和行缓冲否则读出来的是被终端加工过的数据。timeout 2是防止cat挂住不退出。如果xxd输出里能看到固定的帧头字节这套工程用的是aa 55两字节帧头说明从超声波模块到 STM32、再到串口这条链路是通的可以往下走了。什么都读不到的话先查线序TX/RX 有没有交叉、再查波特率别急着怀疑代码。4. 串口通信配置驱动包参数、帧格式与固定设备名固件通了接下来是把数据接进 ROS。这一章的重点不是写代码是配参数——波特率、帧格式、设备名这三样里错一个话题就是空的而且报错信息往往指向别处。4.1 驱动包放进工作空间并编译catkin 的规矩是所有包必须在工作空间的src目录下编译产物在devel中间文件在build# 建工作空间 mkdir -p ~/supersonic_ws/src cd ~/supersonic_ws/src # 把 ROS 那一半的包拷进来注意拷的是包目录本身 cp -r ~/supersonic/ros_ws/src/supersonic_driver . # 回到工作空间根目录编译 cd ~/supersonic_ws catkin_make # 每次开新终端都要 source写进 .bashrc 一劳永逸 source devel/setup.bash echo source ~/supersonic_ws/devel/setup.bash ~/.bashrccatkin_make等价于在 build 目录里跑 cmake make第一次会慢一些。编译完用rospack find supersonic_driver验证能打印出路径就说明包被 ROS 认到了如果报 “package not found”八成是 source 没做或者包目录多套了一层src/supersonic_driver/supersonic_drivercatkin 不会递归去找。编译报Could not find a package configuration file provided by serial的话就是第二章那个ros-noetic-serial没装或者装了但当前终端没 source/opt/ros/noetic/setup.bash两者排查顺序别搞反。4.2 参数文件与帧格式波特率和校验必须两边一致驱动节点的参数一般放在包的config目录下用 yaml 加载# config/supersonic.yaml supersonic_node: port: /dev/supersonic # 固定设备名见 4.3 baudrate: 115200 # 必须与固件 USART 初始化完全一致 frame_id: supersonic_link # 写进消息 header做 TF 时要用 header0: 0xAA # 帧头第一字节 header1: 0x55 # 帧头第二字节 timeout_ms: 200 # 超过这个时间没收到完整帧就丢弃缓冲 publish_topic: /sonar/range scale: 0.001 # 固件发的是毫米转成米参数逐条说baudrate是重灾区固件里 USART 配的 115200yaml 写成 9600读出来全是乱码而且不会有任何报错提示scale决定发布出来的单位sensor_msgs/Range规定用米所以从毫米转过来要乘 0.001忘了乘就是几米量级的假数据timeout_ms控制断帧容忍度太小会在数据密集时频繁丢帧太大则板子掉线后节点还在发旧值。帧格式这边常见做法是三段式帧头 数据 校验。这套工程用的是定长 5 字节字节序号含义说明0帧头高字节固定 0xAA1帧头低字节固定 0x552距离低字节单位毫米小端3距离高字节与字节 2 组合成 16 位4校验前四字节逐字节异或小端序这点要注意STM32 是小端PC 也是小端所以直接拼(high 8) | low就对了如果哪天换成大端设备这里会整体偏移读出来的距离会莫名其妙变成几万。校验用异或是最省事的方案够用且不占算力比 CRC16 好在实现简单坏处是检错能力弱一些工业场景一般会换 CRC。launch 文件把参数和节点串起来launch !-- outputscreen 让 printf 和 ROS_INFO 都打到当前终端调试期必开 -- node pkgsupersonic_driver typesupersonic_node namesupersonic_node outputscreen rosparam file$(find supersonic_driver)/config/supersonic.yaml commandload/ !-- 命令行参数优先级高于 yaml临时换口不用改文件 -- param nameport value/dev/supersonic/ /node /launchcommandload表示把 yaml 里的键值对灌进参数服务器$(find ...)是 roslaunch 的路径替换比写绝对路径靠谱换机器不用改。param放在rosparam后面会覆盖同名项这是我调试时最常用的手法配置文件不动命令行临时改端口。4.3 udev 固定设备名与权限/dev/ttyUSB0这个编号是不稳定的插拔一次、或者同时插了别的串口设备编号就可能变成 USB1节点自然打不开。两个办法一起用最稳加 dialout 组解决权限写 udev 规则固定名字。# 1) 把当前用户加进 dialout 组重新登录后生效 sudo usermod -aG dialout $USER # 2) 查设备的厂商号、产品号和序列号 ls -l /dev/ttyUSB* udevadm info -a -n /dev/ttyUSB0 | grep -E idVendor|idProduct|serialusermod那条改的是组权限必须重新登录或者新开一个 session才生效改完立刻试还是 Permission denied 是正常的别以为没生效又去折腾别的。查出来的idVendor/idProduct是十六进制字符串写规则时要原样抄。# 规则文件按 99- 前缀命名数字越大越晚加载避免被系统规则覆盖 sudo tee /etc/udev/rules.d/99-supersonic.rules /dev/null EOF # 把 idVendor / idProduct 换成你上一条命令查到的值 SUBSYSTEMtty, ATTRS{idVendor}1a86, ATTRS{idProduct}7523, SYMLINKsupersonic, MODE0666 EOF # 重新加载规则并触发不用重启 sudo udevadm control --reload-rules sudo udevadm trigger # 验证应该能看到 /dev/supersonic 指向 ttyUSB* ls -l /dev/supersonicSYMLINKsupersonic是创建软链接节点里统一写/dev/supersonic插哪个 USB 口都不影响。MODE0666是图省事给所有用户读写权限严格点可以只给 0660 然后靠 dialout 组我自己的开发机用 0666 少踩权限坑产品机上会收回去。规则文件里那个1a86:7523是常见的 USB 转串口芯片你手上如果是别的型号一定要换成udevadm查出来的实际值照抄别人的规则是最典型的无用功。5. 排查清单串口链路上五个高频翻车点下面这几条是我自己踩过、也帮别人定位过的按“现象 → 原因 → 解决”记遇到问题直接对号入座比从头读日志快。5.1 串口打不开Permission denied 与设备名漂移现象节点一启动就报open port failed: Permission denied或者明明插着线/dev/ttyUSB0却不存在。原因两种可能。一是当前用户不在dialout组普通用户默认没有串口的读写权限二是设备名漂移上一次是ttyUSB0这次变成了ttyUSB1参数里写死的路径自然打不开。解决先ls -l /dev/ttyUSB*确认设备到底叫什么再groups看自己有没有在 dialout 里。加组之后一定要重新登录我最开始就是因为懒得注销以为是规则没写对白折腾了半小时。设备名用第四章的 udev 规则固定成/dev/supersonic这类问题基本就绝迹了。5.2 话题在但没有数据帧头对不上与校验失败现象rostopic list能看到/sonar/rangerostopic echo一片空白节点日志里偶尔刷“checksum error”或者干脆什么都不打。原因读到的是数据但拼不成完整帧。常见于三种情况波特率不一致固件 115200、yaml 9600、帧头字节写反0x55 0xAA当成了0xAA 0x55、固件那边发送间隔太长导致驱动端的超时先触发缓冲区被清空。解决先断开 ROS用timeout 2 cat /dev/ttyUSB0 | xxd -l 64直接看原始字节确认帧头真的是aa 55开头。这一步是分水岭原始字节就不对问题在固件或波特率原始字节对但 ROS 收不到问题在驱动的解析参数。校验失败还有个隐蔽原因——固件里发的距离是uint16_t驱动里按int8_t读了两个字节被拆开异或自然过不了。5.3 数值乱跳时间戳、量程与安装角度现象数据能出来但 rqt_plot 上是一条锯齿状的乱线静止的墙面也能测出 0.1 米和 4 米来回跳。原因超声波本身就有跳变但更多是配置问题。sensor_msgs/Range有min_range/max_range/field_of_view三个字段很多驱动包默认填 0下游的代价地图或者避障逻辑读到 0 会直接判定为无效另外时间戳用的是ros::Time::now()还是固件发上来的时间没统一导致 TF 查询时报 extrapolation 错误。解决把量程字段按模块实际能力填上常见的模块有效范围在 0.02 到 4 米这个量级field_of_view按波束角填个 15 度左右时间戳统一用收帧时刻的ros::Time::now()别用固件里的毫秒计数两边时钟不同源对不上。安装角度也要注意超声波对斜面和软质材料反射很差斜着装测出来的值会偏大很多这不是软件能修的。5.4 编译期报错serial 找不到与 CMake 版本现象catkin_make报Could not find a package configuration file provided by serial或者CMake Error: CMake 3.x or higher is required。原因前者是依赖没装或者当前终端没 source ROS 环境后者多见于从旧机器上拷过来的工程package.xml或者CMakeLists.txt里写死了低版本的 cmake 要求而 20.04 自带的是 3.16。解决sudo apt install ros-noetic-serial装上然后source /opt/ros/noetic/setup.bash再编。CMake 版本问题去CMakeLists.txt里把cmake_minimum_required改到 3.0.2 以上Noetic 官方要求别去降级系统 cmake那是给自己挖坑。还有一种报错是package.xml里build_depend写了包名但拼错rosdep 检查会直接跳过编译到一半才炸。5.5 烧完不跑BOOT 引脚、时钟配置与 printf 重定向现象st-flash提示烧录成功但板子毫无反应串口一个字节都不发。原因三种。BOOT0 被拉高进了 bootloader程序根本没执行时钟树配错USART 的波特率跟着整体偏移printf 没有重定向到串口你以为在打日志其实数据全丢了。解决先确认 BOOT0 接地、烧完按一下复位。时钟用 CubeMX 重新生成一遍别手改SystemClock_Config里的分频系数。printf 重定向要自己实现_write或者fputc并且 Makefile 的链接参数里加-u _printf_float要打浮点的话否则输出会被静默吞掉——这个坑最阴编译零告警运行零输出。6. 装完怎么验证从 echo 一帧到 rqt_plot 里那条稳定曲线装完不等于跑通我判断这套链路是否真的成了看四件事按顺序做每步都有明确的通过标准。第一步确认固件在发数据。板子单独上电不启 ROSsudo stty -F /dev/supersonic 115200 raw -echo timeout 2 cat /dev/supersonic | xxd -l 32看到aa 55开头的定长帧且手在传感器前面晃动时后面两个字节在变固件这半边就算过了。第二步确认节点在发消息roslaunch supersonic_driver supersonic.launch # 另开一个终端 rostopic echo -n 1 /sonar/range-n 1是只打印一条就退出避免刷屏。正常应该看到range在 0.02 到 4 之间、header.frame_id是supersonic_link、radiation_type为 0超声波。如果range恒为 0 或者一个很大的固定值回去看第五章 5.2 的字节序问题。第三步看频率稳不稳rostopic hz /sonar/range # 期望输出 average rate 接近固件的发送周期比如 20Hz 左右验证项命令通过标准固件出帧timeout 2 cat /dev/supersonic | xxd帧头aa 55数据随距离变化设备名固定ls -l /dev/supersonic软链接指向实际 ttyUSB消息内容rostopic echo -n 1 /sonar/range单位是米量程字段非 0发布频率rostopic hz /sonar/range与固件周期一致抖动不超过两成第四步看波形。rqt_plot里把/sonar/range/range加进去拿一本书在传感器前面慢慢靠近再拉远曲线应该跟着走不该出现垂直跳变。如果曲线在某个固定距离上反复横跳多半是量程字段没填或者传感器被安装支架挡住了盲区。提示验证阶段一定要把outputscreen打开驱动的调试日志是唯一的黑匣子出了问题只能靠它往回推。从那以后我每次装这类串口工程都强制走一遍“原始字节 → 单条消息 → 频率 → 波形”这四步不管多急都不跳。跳过任何一步后面出问题就要在四个环节里盲猜那才是真正耗时间的部分。希望这套顺序能帮你少走一段弯路把时间花在算法上而不是权限和波特率上。本文还有配套的精品资源点击获取