ESP32+micro-ROS接入ROS2：自制可巡逻遥控小车全攻略

先交代一下我做了什么把一块吃灰挺久的ESP32 NodeMCU-32S翻出来配了个亚克力小车底盘、两个TT马达、一个TB6612FNG驱动板再加一节18650电池组花了一个周末把这堆东西变成了一个能接入ROS2生态的遥控小车。这里说的接入不是用串口转发之类的野路子而是让ESP32在ROS2里成为一个正式节点。小车端跑micro-ROS通过WiFi连到电脑上的micro-ROS Agent再由Agent桥接到ROS2的DDS网络。这样一来我可以用ROS2的话题给小车轮速指令用Action给小车派发“巡逻一圈”这种带进度的任务还能通过参数服务器在运行时改电机最大速度不用重新烧固件。这个项目最大的价值在于它把“嵌入式MCU实时控制”和“ROS2生态工具链”完整地串在了一起。对刚学完ROS2小乌龟、想往实体硬件上迁移的初学者非常合适对已经熟悉ROS2、想给自家车/机械臂加一个低成本无线节点的老玩家也是一个可以直接抄作业的模板。我会把整个从选型、环境搭建、代码实现到调试避坑的过程都写清楚尤其是Action和参数服务器这两块在真机上的坑网上讲得真的不多。1. 先把项目掰开揉碎1.1 为什么选ESP32而不是树莓派或STM32一说到“让小车接入ROS2”很多人的第一反应是直接用树莓派。树莓派能跑完整的Ubuntu和ROS2python、rviz2随便装确实省心。但代价也很明显一块树莓派4的价格能买好几块ESP32而且树莓派扩展板的体积和功耗对一辆十几厘米长的小车来说有点比例失衡。那STM32呢STM32在实时性和生态上都很强但做无线通信基本要外挂ESP8266或者以太网模块链路变长调试难度也跟着上来。最常见的情况是STM32负责电机控制再通过串口和树莓派通信绕来绕去最后还是得有一台Linux主机在中间。ESP32的优势在这里就体现出来了芯片自带WiFi和蓝牙双核240MHz跑micro-ROS的节点逻辑绰绰有余。更关键的是Arduino和ESP-IDF生态有现成的micro-ROS库初始化WiFi连接之后ESP32在网络层面就是个标准UDP客户端直接和micro-ROS Agent通信省掉了串口转接这一层。对遥控小车这种场景ESP32属于“一块芯片干了树莓派和STM32俩人的活”的典型选择。1.2 Action和参数服务器在遥控小车里的角色ROS2的通信方式主要是话题、服务、Action三件套。遥控小车最基础的“给速度”用话题就够了/cmd_vel一发小车就跑起来频率高、延迟低适合连续性指令。但如果你想给小车上层任务比如“沿着当前方向前进1米然后停下”纯用话题就很别扭——话题无状态你不知道任务到底执行完没有成功了还是失败了。这时Action就是正确解法。Action有三个阶段goal目标、feedback反馈、result结果客户端发一个目标过去服务端执行过程中持续回报进度最后返回执行结果。这种天然的任务语义非常契合“巡逻一圈”“转90度”“前进2米”这类一次性任务。我在这个项目里就用Action给小车下发了一个“绕圈巡逻”的指令小车轮子每走一段就发一次feedback走完全程返回result整个过程和用ROS2自带Action的感觉完全一致。参数服务器则是另一条独立链路。小车电机的最大速度、转向比例、加减速曲线这些参数如果每次调都要改代码重新烧录那调试体验会非常糟糕。ROS2的参数服务器可以在节点运行期间在线修改参数值micro-ROS在ESP32端也实现了对应的参数API我用它在运行的时候动态修改PWM上限实测下来效果很理想。1.3 整条数据链路的组成把整个系统拆开看数据流大致是这样的ESP32端跑micro-ROS节点节点里初始化三类通信资源订阅/cmd_vel话题用来接收遥控速度创建一个Action客户端用于向ROS2端发送巡逻任务严格说任务执行逻辑在ESP32Action服务端应该在ESP32我这里为了演示和调试方便把目标生成放在电脑端执行和反馈在ESP32端再创建一个参数服务器存放max_speed这类可调参数。ESP32通过WiFi把数据包发给电脑或树莓派上的micro-ROS Agent进程。Agent是micro-ROS体系里的关键角色它在UDP端口上接收ESP32上送的micro-ROS协议数据再转换为标准DDS报文注入ROS2节点网络。反过来ROS2节点发出来的DDS消息也由Agent转换成ESP32能识别的格式再从UDP发回去。所以从ROS2侧看ESP32和普通ROS2节点几乎没有区别ros2 node list能看到它ros2 param set能改它的参数ros2 action send_goal能给它下发任务。这是整个方案最舒服的地方——上层工具一个不少底层逻辑全在MCU上实时跑。2. 环境准备与工具链搭建2.1 ROS2环境与micro-ROS Agent安装ROS2这边我建议直接用Ubuntu 22.04 ROS2 Humble这也是目前资料最多、兼容性最好的组合。装ROS2的方法网上已经非常成熟新手可以跟着官方二进制包安装或者用社区的一键安装脚本几分钟就能把ROS2核心和常用工具拉起来。如果你还没跑过小乌龟强烈建议先把turtlesim跑一遍再继续至少要知道ros2 topic list、ros2 action list这些命令长什么样。micro-ROS Agent是连接ESP32和ROS2的桥梁它其实就是一个普通ROS2功能包编译运行起来很简单。我最常用的方式是直接用Docker跑官方镜像docker run -it --rm --nethost microros/micro-ros-agent:humble udp4 --port 8888如果你不想用Docker也可以源码编译micro-ROS-Agentgit clone https://github.com/micro-ROS/micro-ROS-Agent.git cd micro-ROS-Agent colcon build source install/setup.bash ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888Agent跑起来后会打印等待连接的日志这时候它就在UDP 8888端口上等ESP32来敲门了。需要提醒一句Agent跑在哪个机器上ESP32里的IP地址就要填哪个机器的局域网IP别填localhost除非你ESP32和Agent在同一台设备上。2.2 ESP32开发环境与烧录方式ESP32端的开发环境我在Arduino IDE和PlatformIO之间纠结了一阵最后选了PlatformIO。原因很简单真实项目里多个源文件、库依赖、编译选项用PlatformIO管理更顺手而且它能方便地指定开发板型号和烧录端口。Arduino IDE对纯新手更友好如果之前只用过Arduino IDE直接用也没问题核心代码都是一样的。在PlatformIO里新建一个ESP32项目platform选择espressif32然后在platformio.ini里加上对micro-ROS库的依赖。micro-ROS Arduino库在库管理器里可以直接搜到也可以在项目里通过lib_deps拉取。这里要留意micro-ROS库版本和ROS2版本要对上Humble对应的是micro-ROS Humble分支别混用。烧录方面ESP32 NodeMCU-32S通常是通过USB转串口芯片常见CP2102或CH340连接电脑。第一次插上如果电脑没识别需要先装对应驱动。烧录的时候如果提示串口占用检查是不是Arduino IDE的串口监视器开着如果老是连接不上按住开发板上的BOOT键再点烧录一般就能搞定。2.3 连接方式WiFi优先LAN8720作为备选对遥控小车来说WiFi是最省事的通信方式ESP32自带的WiFi模块已经够用。我在代码里用的就是WiFi UDP连接ESP32连上路由器Agent在电脑上监听同一个路由器的局域网端口两者通过UDP交换数据。实测下来在家里路由器信号正常的情况下控制指令延迟在十几毫秒量级对遥控小车完全够用。不过也有一种情况要提前考虑如果你所在环境WiFi干扰很大或者路由器配置了AP隔离设备间通信被禁止TCP/UDP包可能传不过去。这时候可以考虑走有线以太网。ESP32外接LAN8720以太网模块是一种成熟方案但引脚多、容易踩坑我单独整理了一份避坑清单放在后面第5.4节接线和常见问题都有真要用到的时候可以直接参考。另外一个小建议如果走WiFi尽量把ESP32的蓝牙关掉。ESP32的天线是共用的WiFi和蓝牙同时开会导致吞吐率下降尤其是micro-ROS这种长连接的UDP流很容易出现掉包。反正小车用不上蓝牙关了省心很多。3. 小车端代码实现micro-ROS节点、Action客户端与参数服务器3.1 初始化micro-ROS节点与WiFi传输在Arduino环境里写micro-ROS节点第一步是设置传输层。我用的是WiFi UDP方式代码里直接调用set_microros_wifi_transports#include micro_ros_arduino.h #include WiFi.h #include rcl/rcl.h #include rclc/rclc.h #include rclc/executor.h const char* ssid 你的WiFi名; const char* psk 你的WiFi密码; const char* agent_ip 192.168.1.100; // 电脑的局域网IP const int agent_port 8888; rcl_node_t node; rcl_allocator_t allocator; rclc_support_t support; rclc_executor_t executor; void setup() { Serial.begin(115200); set_microros_wifi_transports(ssid, psk, agent_ip, agent_port); delay(2000); allocator rcl_get_default_allocator(); rclc_support_init(support, 0, NULL, allocator); rclc_node_init_default(node, esp32_car, , support); // 后面扩展的订阅、Action、参数服务器都挂到executor上 rclc_executor_init(executor, support.context, 4, allocator); rclc_executor_spin_period(executor, 1000); // 1ms周期轮询 } void loop() { delay(10); rclc_executor_spin_some(executor, RCL_MS_TO_NS(100)); }这里最关键的是agent_ip一定不要写错写错的话ESP32会一直处于“已连接WiFi但micro-ROS握手失败”的状态。另一个细节是rclc_executor_init的第三个参数它表示executor最多能挂多少个句柄包括订阅、动作客户端、参数服务器等后面新增通信资源时要记得把这个数字加大否则运行时会出现句柄不足的错误。3.2 用Action实现“巡逻”任务这次演示我选用的是系统自带的example_interfaces/action/Fibonacci用它是为了绕开自定义Action接口在Arduino端生成麻烦的问题。跑通链路之后再换成你自己的Action思路完全一样。micro-ROS在Arduino环境下的Action支持需要rclc_action库初始化逻辑比普通订阅多几个步骤#include rclc_action/rclc_action.h #include example_interfaces/action/fibonacci.h rclc_action_client_t action_client; example_interfaces__action__Fibonacci_SendGoal_Request goal_req; example_interfaces__action__Fibonacci_SendGoal_Response goal_resp; example_interfaces__action__Fibonacci_FeedbackMessage feedback_msg; example_interfaces__action__Fibonacci_GetResult_Request result_req; example_interfaces__action__Fibonacci_GetResult_Response result_resp; void action_goal_response_cb(void* ctx, const rcl_action_goal_handle_t* goal_handle, bool accepted) { if (accepted) { Serial.println(Goal accepted); } else { Serial.println(Goal rejected); } } void action_feedback_cb(void* ctx, const example_interfaces__action__Fibonacci_FeedbackMessage* msg) { Serial.print(Feedback: ); for (size_t i 0; i msg-feedback.sequence.size; i) { Serial.print(msg-feedback.sequence.data[i]); Serial.print( ); } Serial.println(); } void action_result_cb(void* ctx, const example_interfaces__action__Fibonacci_GetResult_Response* msg) { if (msg-status 1) { Serial.println(Goal succeeded); } else { Serial.println(Goal failed); } }初始化时把Action客户端挂进executorrclc_action_client_init_default( action_client, node, ROSIDL_GET_ACTION_TYPE_SUPPORT(example_interfaces, action, Fibonacci), /patrol ); rclc_executor_add_action_client( executor, action_client, goal_resp, action_goal_response_cb, action_feedback_cb, action_result_cb );注意不同micro-ROS版本的rclc_action函数签名可能略有差异我这份是基于我用的Humble分支如果你编译报错优先查一下官方example里的头文件和回调格式。在loop循环里检测到某个条件时比如收到一个特定字符就发送一个goalif (Serial.available()) { char cmd Serial.read(); if (cmd s) { goal_req.goal.order 6; // 让小车“巡逻”6步 rclc_action_send_goal_request(action_client, goal_req, goal_resp); } }我在这辆小车上实际跑的时候把Fibonacci的sequence计算替换成了电机转动的步数记录每走完一步就在feedback里上报当前累积里程这样在电脑端能看到小车“走了一步、两步、三步……”直到目标步数完成。这种“目标-反馈-结果”的交互方式如果只用话题或服务做实现起来要自己造一套状态机Action直接给你把框架铺好了。3.3 用参数服务器动态调整电机参数参数服务器这头我用的是micro-ROS的rclc_parameter实现。创建参数服务器的代码很简洁#include rclc_parameter/rclc_parameter.h rclc_parameter_server_t param_server; int32_t max_speed 150; void param_cb(const rclc_parameter_t* param) { if (strcmp(param-name.data, max_speed) 0) { max_speed param-value.integer_value; Serial.print(Updated max_speed to ); Serial.println(max_speed); } } rclc_parameter_server_init_default(param_server, node); rclc_parameter_add_param_int(param_server, max_speed, max_speed); rclc_parameter_server_set_callback(param_server, param_cb); rclc_executor_add_parameter_server(executor, param_server);之后在上位机执行ros2 param get /esp32_car max_speed ros2 param set /esp32_car max_speed 220就能看到ESP32串口打印出“Updated max_speed to 220”PWM输出上限也随之改变。这里有个细节参数回调函数的执行必须依赖executor周期运转如果你的loop里忘了调用rclc_executor_spin_some或者executor句柄数量不够参数请求到了ESP32也不会被处理表现为“上位机显示set成功但电机没变化”。这个在调试时特别容易忽略。3.4 接收/cmd_vel话题并驱动电机Action负责“任务层”而日常遥控还是要靠话题。我订阅了标准的速度话题/cmd_vel接收geometry_msgs/Twist然后换算成左右轮速度通过TB6612驱动电机。#include geometry_msgs/msg/twist.h rcl_subscription_t sub_cmd_vel; geometry_msgs__msg__Twist cmd_vel_msg; void cmd_vel_cb(const void* msgin) { const geometry_msgs__msg__Twist* msg (const geometry_msgs__msg__Twist*)msgin; float linear msg-linear.x; float angular msg-angular.z; // 简单差速模型 float left_speed linear - angular * WHEEL_BASE / 2.0; float right_speed linear angular * WHEEL_BASE / 2.0; // 限幅到参数服务器的max_speed left_speed constrain(left_speed, -max_speed, max_speed); right_speed constrain(right_speed, -max_speed, max_speed); set_motor_speed(LEFT_MOTOR, left_speed); set_motor_speed(RIGHT_MOTOR, right_speed); } void setup() { // ... rclc_subscription_init_default( sub_cmd_vel, node, ROSIDL_GET_MSG_TYPE_SUPPORT(geometry_msgs, msg, Twist), /cmd_vel ); rclc_executor_add_subscription( executor, sub_cmd_vel, cmd_vel_msg, cmd_vel_cb, ON_NEW_DATA ); }set_motor_speed函数里用ESP32的LEDC外设输出PWM。TB6612的接线这里不细展开关键是AIN1/AIN2和BIN1/BIN2控制旋转方向PWMA/PWMB控制速度。注意别把PWM频率设太低我用的5kHz既能避免电机啸叫也不会浪费LEDC的精度。实际跑起来键盘遥控和Action任务是可以共存的。你正常用teleop_twist_keyboard发速度小车就手动跑一旦用Action下发巡逻目标底层逻辑在接收目标期间可以暂停/接管电机控制。我在Action反馈回调里维护了一个flag在“巡逻中”自动屏蔽外部cmd_vel输入任务结束再恢复手动控制这样两种控制模式不会打架。4. 上位机调试从agent日志到rqt、参数修改4.1 验证节点与Action链路硬件烧好、Agent跑起来后第一步是确认ESP32节点成功注册到ROS2网络。在电脑终端执行ros2 node list如果看到/esp32_car说明micro-ROS链路已经通了。接着看看这个节点上有什么资源ros2 node info /esp32_car正常情况下会列出它订阅了/cmd_vel提供/patrol这个Action还维护着一组参数。看到这些就说明ESP32在ROS2眼中已经是一个“正常公民”了。Action链路可以用命令行直接测ros2 action send_goal /patrol example_interfaces/action/Fibonacci {order: 5} --feedback这个命令会打印Action的目标接收情况、反馈和最终结果。如果feedback能一路刷过来说明ESP32端的Action客户端工作正常。注意micro-ROS的Action链路对Agent版本和固件版本都有要求如果这里卡住优先看Agent的终端日志它会打印比较明确的报错信息。4.2 键盘遥控与参数动态修改装一个键盘遥控包就能在小车上验证/cmd_vel了sudo apt install ros-humble-teleop-twist-keyboard ros2 run teleop_twist_keyboard teleop_twist_keyboard按i前进逗号后退j/l左右转小车应该跟着你的按键动起来。如果方向反了改电机方向引脚或者把cmd_vel回调里的符号取反即可。参数服务器这边前面提过的ros2 param get和param set是常用命令但如果你想可视化地观察参数变化趋势可以打开rqt:ros2 run rqt_gui rqt_gui在Plugins菜单里找到Configuration Dynamic Reconfigure或者直接用Parameter窗口能看到/esp32_car的max_speed参数拖动滑块就能实时改变小车最大速度。我实测时把max_speed从150拉到255小车明显从慢吞吞变成起飞姿态这种“不烧固件就能调参”的体验确实比改代码重新上传舒服太多。4.3 一个完整的调试工作流给新手一个推荐调试顺序第一先不接电机只跑micro-ROS节点确认WiFi连接、Agent注册、topic订阅输出正常第二用ros2 topic echo /cmd_vel发一个固定速度确认ESP32能收到并能解析出值第三接上电机用手转动轮子观察方向对不对第四测Action先发一个简单的Fibonacci目标确认feedback和result链路通最后测参数服务器set一个数值看是否实时生效。整个流程下来一旦有问题能很快定位在哪一层是网络层没通还是驱动层没通还是ROS2接口层没通。别一开始就全堆上去出了问题排查起来会非常头疼。5. 常见问题与排查技巧实录5.1 Agent找不到节点这是最常碰到的问题。ESP32串口打印显示WiFi已连接但Agent那边就是看不到节点。优先检查四件事一是agent_ip是否写成了localhost这是最多新手犯的错二是电脑防火墙是否拦截了UDP 8888端口Windows和Ubuntu都可能拦直接在防火墙放行UDP 8888即可三是ESP32和电脑是否真的在同一网段有些路由器开了访客网络隔离两个设备看似连同一个WiFi实际不通四是Agent启动时用的udp端口和代码里写的端口是否一致默认8888但你如果改过就要两边对齐。5.2 Action没反馈或请求超时Action链路比话题复杂出问题的地方也更多。我踩过的一个典型坑是Action的goal请求发出去了电脑端显示“accepted”但feedback死活不回来。后来排查发现是executor的句柄数量不够Action客户端的回调没有被executor轮询到。处理方法很简单把rclc_executor_init里的句柄数量调大并且确认每次loop循环都在执行rclc_executor_spin_some。还有一个容易忽略的点Action callback的类型和顺序最好严格按照官方example里rclc_executor_add_action_client的参数顺序来回调函数签名对不上编译能过但运行时会出诡异问题。5.3 参数更新不生效参数服务器这边最典型的症状是上位机ros2 param set显示成功但小车速度没变化。先查参数回调函数有没有触发在回调里加一行串口打印是最直接的判断。如果压根没打印说明参数请求没到ESP32原因可能是Agent和ESP32之间的参数同步周期没到或者executor句柄不够。如果打印了但电机行为没变检查回调里是否真的更新了全局变量以及电机驱动代码里是否真的引用了这个全局变量。有时候命名空间写错改的是“/esp32_car/max_speed”但代码里读的是另一个参数名那就尴尬了。5.4 补充避坑ESP32接LAN8720以太网模块时的三个坑如果你不打算用WiFi而是想给ESP32接LAN8720以太网模块提高稳定性那我得说三个我实测过的坑照着能少走很多弯路第一PHY地址和ETH_CLK引脚。ESP32连接LAN8720时PHY地址默认是0但如果你的模块或者某个GPIO配置把PHY_ADDR改成了1初始化会一直失败。另外ETH_CLK引脚要保证是GPIO0并且模块需要外部提供50MHz时钟源很多坑都是因为时钟没起来。第二RST引脚必须接对。LAN8720的复位引脚不能悬空我一开始用的模块上RST没接MCU导致模块上电时序不对经常出现随机无法link up。后来把RST接到ESP32的一个GPIO并在初始化时延时200ms再拉高复位问题才解决。第三供电要干净。LAN8720是3.3V供电但很多模块板载了稳压如果直接用5V给模块供电然后指望它输出3.3V逻辑给ESP32电平不匹配就很容易丢包。最好统一用3.3V供电并且共地。完整的LAN8720接线图网上有不少这里不贴图了但核心就一句话电源、PHY_ADDR、ETH_CLK、RST、RX/TX这五组信号每一组都不能想当然。5.5 烧录失败与串口问题ESP32烧录失败也是高频问题。常见的现象是“A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header”。解决方法是按住开发板BOOT键不放点烧录看到Connecting字样后再松开BOOT键。如果还是不行检查串口驱动是否正常尤其CH340在Windows下容易掉驱动重新插拔USB或者换一根数据线有些线只能充电不能传数据往往能解决。串口监视器和烧录端口冲突也是老问题PlatformIO烧录时一定要关掉串口监视器否则端口被占用会一直报错。写在最后这个小车项目做到现在最大的感受是micro-ROS把“MCU接入ROS2”的门槛拉得非常低但它毕竟不是完整的DDS实现调试思路和纯ROS2节点还是有点区别。我的经验是遇到问题先看Agent日志再看ESP32串口打印最后才去翻上位机的报错按这条线查基本都能定位到问题。最后再分享一个小技巧给ESP32端的micro-ROS节点加一个看门狗重连逻辑。WiFi环境不稳时UDP连接很容易断但ESP32自己并不知道Agent已经失联。我写了一个定时器如果超过10秒没有收到Agent的任何数据就主动重启WiFi传输层并重新初始化节点。这个做法让小车在路由器重启、电脑休眠唤醒后都能自动恢复连接实测非常稳。这套框架跑通之后后面可玩的东西非常多。比如给小车加上编码器和IMU用micro-ROS发布odom话题再配一个激光雷达就能直接往ROS2导航栈上靠了。ESP32作为低成本、低功耗的智能节点在ROS2生态里的想象力要比一辆遥控小车大得多。