摘要本项目以 Renesas RA6M4 微控制器为核心平台在 Ubuntu VS Code 开发环境下完成 micro-ROS Client 的移植、底层硬件接口适配及 ROS 2 双向通信功能验证。系统采用 micro-ROS Client-Agent 架构RA6M4 作为 micro-ROS Client通过 UART 与运行于 Ubuntu 主机上的 micro-ROS Agent 建立通信并进一步接入 ROS 2 Jazzy 网络。项目首先完成 Ubuntu 下 Renesas 开发环境、Smart Configurator、CMake 编译系统及烧录调试流程的搭建随后完成 micro-ROS Agent、Client 静态库、CMake 链接以及 RA6M4 Transport、Allocator、Time 等平台相关接口的适配。在此基础上围绕实际 MCU 外设设计了多组功能测试包括 ROS 2 控制板载 LED、板载按键数据向 ROS 2 发布、MCU 系统状态监控以及通过 OLED 显示 ROS 2 动态文本、MCU 运行时间与 Agent 在线状态。最终系统形成一个统一的/ra6m4_node并通过 Publisher、Subscription、Timer 与 rclc Executor 将多个独立业务模块统一调度实现 ROS 2 与 MCU 之间的双向通信、板级外设控制和系统运行状态可视化。关键词Renesas RA6M4micro-ROSROS 2 JazzyUARTrclc ExecutorPublisherSubscriptionOLED嵌入式系统1. 项目背景与评测目标传统 ROS 2 系统主要运行于具有完整操作系统环境的 PC、工控机或嵌入式 Linux 平台而 MCU 的 RAM、Flash 和计算资源有限难以直接运行完整 ROS 2。micro-ROS 因此采用 Client-Agent 架构将轻量化 Client 部署到 MCU将 DDS 等较复杂的通信功能交由运行在上位机上的 Agent 完成。当前移植方案使用 Ubuntu ROS 2 Jazzy 作为上位机环境Renesas RA6M4 作为 MCU并采用 UART 建立 Client 与 Agent 之间的物理通信链路。本项目的评测目标不是仅证明“micro-ROS 能够编译”而是按照从工具链、协议栈到底层外设和实际业务的顺序验证以下完整技术链路在 Ubuntu VS Code 环境下建立可持续使用的 Renesas RA6M4 开发、编译、配置与调试环境将 micro-ROS Client 正确集成至 RA6M4 工程并完成平台接口适配建立 RA6M4 与 PC 端 micro-ROS Agent 的 UART 通信链路验证 ROS 2 → MCU 的控制消息链路验证 MCU → ROS 2 的传感/状态数据发布链路增加 MCU 自身运行状态监控能力使用 OLED 将 ROS 2 信息、MCU 本地状态与 Agent 状态集中显示对整个工程的模块划分、Executor 调度、消息类型和运行稳定性进行综合评测。2. 开发与评测环境项目配置MCURenesas RA6M4MCU 架构Arm Cortex-M33PC 操作系统UbuntuROS 2Jazzymicro-ROS 架构Client-AgentMCU ↔ Agent 通信UARTAgent 运行平台UbuntuIDEVisual Studio CodeRenesas 配置工具Renesas Platform Smart ConfiguratorMCU 工程构建系统CMakemicro-ROS MCU 库libmicroros.aUbuntu VS Code 开发文档已经覆盖 VS Code 安装、独立 Profile、Renesas Platform、Smart Configurator、CMake 用户源文件管理以及调试烧录流程并形成独立的开发环境搭建文档。micro-ROS 移植文档进一步覆盖了 ROS 2 workspace、micro_ros_setup、micro-ROS Agent、RA6M4 Client 静态库生成、ABI 参数匹配、CMake 集成以及底层 Transport 适配等过程。3. 最终工程架构3.1 软件分层当前工程已经按照“硬件总线层—设备驱动层—ROS 应用层—micro-ROS 平台层—系统入口层”进行组织主要结构如下src/ ├── asset/ │ ├── font.c │ └── font.h │ ├── bsp/ │ ├── bsp_i2c.c │ └── bsp_i2c.h │ ├── dev/ │ ├── dev_key.c │ ├── dev_key.h │ ├── dev_led.c │ ├── dev_led.h │ ├── dev_oled.c │ └── dev_oled.h │ ├── ros_app/ │ ├── ros_app_key.c │ ├── ros_app_key.h │ ├── ros_app_led.c │ ├── ros_app_led.h │ ├── ros_app_oled.c │ ├── ros_app_oled.h │ ├── ros_app_status.c │ └── ros_app_status.h │ ├── user_microros/ │ ├── microros_allocators.c/.h │ ├── microros_posix_compat.c │ ├── microros_time.c/.h │ ├── microros_transport_uart_adapter.c/.h │ └── uros_transport_uart.c/.h │ ├── hal_entry.c ├── hal_warmstart.c └── microros_app_entry.c这一结构避免将 ROS 2 业务、具体硬件驱动以及 micro-ROS 平台移植代码全部堆叠在hal_entry.c中。各层职责分别为层级职责BSP封装 I2C、UART 等通用板级总线能力Device封装 LED、KEY、OLED 等具体外设ros_app将硬件能力映射为 ROS Publisher、Subscription、Timeruser_microros完成 Transport、Allocator、Time 等平台适配microros_app_entry创建 ROS Context、Node、Executor 并统一装载应用模块hal_entry完成板级初始化并进入 micro-ROS 主业务4. micro-ROS 基础平台移植4.1 PC 端 AgentPC 端首先建立 ROS 2 Jazzy 与 micro-ROS workspace通过micro_ros_setup获取并编译 micro-ROS Agent。移植文档已经覆盖 workspace 创建、rosdep、colcon、Agent workspace 创建以及 Agent 可执行程序验证流程。最终通信关系为ROS 2 Nodes │ ▼ DDS / ROS Graph │ micro_ros_agent │ │ UART ▼ micro-ROS Client │ ▼ Renesas RA6M44.2 MCU 端 ClientRA6M4 端使用 Renesas 对应 micro-ROS 组件生成libmicroros.a并保证静态库的编译参数与 MCU 工程 ABI 一致。特别需要保证 Cortex-M33、Thumb、FPU 和 hard-float 等 ABI 参数相互匹配否则即使能够完成链接也可能因为函数参数传递规则不同而产生运行期异常。该问题以及libmicroros.a的生成过程已经在移植文档中进行了说明。随后通过 CMake 完成micro-ROS Headers │ ▼ target_include_directories() libmicroros.a │ ▼ add_library(... IMPORTED) │ ▼ target_link_libraries() 用户平台适配源码 │ ▼ target_sources() 最终生成 RA6M4 ELF 固件4.3 平台接口适配micro-ROS 为保持跨平台能力并不直接规定所有 MCU 上的数据收发、时间和内存机制而是通过抽象接口将这些平台相关操作交由开发者实现。移植文档中明确涉及 Transport、Allocator、Clock/Time 等平台相关能力并详细展开了自定义 Transport 的注册机制。本工程最终将其划分为micro-ROS │ ├── Allocator ──► microros_allocators │ ├── Time ──► microros_time │ └── Transport ──► microros_transport_uart_adapter │ ▼ uros_transport_uart │ ▼ Renesas FSP UART其中 UART Transport 最终向 micro-ROS 提供OpenCloseWriteRead四类操作使 XRCE-DDS 数据能够通过 RA6M4 UART 实际发送和接收。5. micro-ROS 主节点与 Executor所有应用最终统一挂载到/ra6m4_nodemicroros_app()的主要执行流程为等待 Agent │ ▼ rclc_support_init() │ ▼ 创建 /ra6m4_node │ ▼ 初始化 Executor │ ├── ros_app_led_init() ├── ros_app_key_init() ├── ros_app_status_init() └── ros_app_oled_init() │ ▼ while(true) │ ▼ rclc_executor_spin_some()最终代码中 Executor 容量定义为#define ROS_EXECUTOR_HANDLE_COUNT (8U)目前实际注册的 Executor Handle 为模块注册对象HandleLEDSubscription1KEYTimer1MCU StatusTimer1OLEDSubscription1OLEDTimer1实际总占用5Executor 配置容量8Publisher 本身由 Timer 回调主动调用因此不单独占用 Executor Handle。按键模块文档中也明确区分了 Publisher 与真正注册给 Executor 的 Timer。因此当前配置相当于使用 5 个 Handle、预留 3 个扩展位置可以继续为后续 Service、Subscription 或其他 Timer 提供空间。6. 评测项目一ROS 2 → MCU LED 控制6.1 测试目标验证 ROS 2 上位机发送的消息可以依次经过ROS 2 Publisher │ ▼ micro_ros_agent │ UART ▼ micro-ROS Client │ ▼ /led_topic Subscription │ ▼ dev_led_set() │ ▼ RA6M4 GPIO │ ▼ LED从而证明PC → Agent → UART → MCU → 外设的完整控制链路已经建立。LED 模块采用std_msgs/msg/Bool通过 Subscription 接收/led_topic消息并在回调函数中调用 LED 设备驱动。该实现及完整使用流程已经形成 LED 控制文档。6.2 ROS 资源项目内容Node/ra6m4_nodeTopic/led_topicMCU 角色SubscriberMessagestd_msgs/msg/BoolExecutor Handle1回调动作dev_led_set(msg-data)6.3 验证命令ros2 topic pub --once /led_topic std_msgs/msg/Bool {data: true}预期现象datatrue │ ▼ LED ON随后执行ros2 topic pub --once /led_topic std_msgs/msg/Bool {data: false}预期LED OFF6.4 验收标准/led_topic能在ros2 topic list中被发现发布true后 LED 状态发生对应变化发布false后 LED 恢复连续多次控制不存在明显漏响应。【插图ROS 2 发布命令】可以看到小灯正常亮了; 执行flase后小灯就正常熄灭了7. 评测项目二MCU → ROS 2 按键状态发布7.1 测试目标验证 MCU 获取的真实硬件事件能够上传至 ROS 2。完整路径为SW1 / SW2 │ ▼ RA6M4 外部中断 │ ▼ dev_key │ ▼ 按键累计计数 │ ▼ key_timer2000 ms │ ▼ rcl_publish() │ ▼ micro_ros_agent │ ▼ /sw1_topic /sw2_topic按键文档采用 SW1、SW2 外部中断累计按键次数由 2000 ms 定时器周期性读取并发布到 ROS 2因此设计发布频率为 0.5 Hz。7.2 ROS 资源Topic类型MCU 角色内容/sw1_topicstd_msgs/msg/UInt32PublisherSW1 累计按下次数/sw2_topicstd_msgs/msg/UInt32PublisherSW2 累计按下次数调度资源2 个 Publisher │ └──── 不直接占 Executor Handle 1 个 key_timer │ └──── 占用 1 个 Executor Handle7.3 测试方法监听 SW1ros2 topic echo /sw1_topic手动按下 SW1多次操作后应观察到类似data: 1 --- data: 2 --- data: 5 ---检查发布频率ros2 topic hz /sw1_topic理论设计值约 0.500 Hz该 0.5 Hz 对应代码中 2000 ms 的 Timer 周期。上传的按键评测文档也将ros2 topic hz作为周期验证方法。7.4 验收标准SW1/SW2 中断可正确计数/sw1_topic、/sw2_topic均能被 ROS 2 发现Topic 中的数据随实际按键操作变化实测发布频率与 0.5 Hz 设计值基本一致高频按键操作不会直接在中断中执行 ROS 发布避免 ISR 负担过重【插图ros2 topic echo /sw1_topic】【插图ros2 topic hz /sw1_topic】8. 评测项目三MCU 系统状态监控 Topic这是在基础消息收发之外新增的 MCU 自诊断模块由ros_app_status.c ros_app_status.h完成。8.1 设计目标普通 ROS Topic 只能证明“某项业务功能正在工作”但不能完整反映 MCU 自身是否健康。因此增加状态监控模块将 MCU 的关键运行信息主动发布到 ROS 2MCU │ ├── 运行时间 ├── UART RX Overflow └── Agent 心跳状态 │ ▼ status_timer 1000 ms │ ▼ ROS 2 Topics8.2 状态 TopicTopicMessage数据来源周期/mcu/uptime_msstd_msgs/msg/UInt64microros_uptime_ms()1 Hz/mcu/uart_rx_overflow_countstd_msgs/msg/UInt32uros_uart_rx_overflow_count_get()1 Hz/mcu/agent_onlinestd_msgs/msg/Boolrmw_uros_ping_agent(20, 1)1 Hz三个 Publisher 均由同一个status_timer周期触发因此 MCU Status 模块只消耗1 个 Executor Handle。8.3 MCU Uptime代码uptime_msg.data microros_uptime_ms();它反映 MCU 自本次启动以来持续运行的时间。验证ros2 topic echo /mcu/uptime_ms预期data: 1000 --- data: 2000 --- data: 3000 ...实际增量会受到调度时间影响但总体应持续单调递增。该指标可用于判断MCU 是否发生过异常复位固件是否持续稳定运行长时间稳定性测试已经运行多久。8.4 UART RX Overflow Count代码uart_overflow_msg.data uros_uart_rx_overflow_count_get();该 Topic 用于观察 micro-ROS UART 接收路径是否因数据处理不及时而发生缓冲区溢出。验证ros2 topic echo /mcu/uart_rx_overflow_count正常通信压力下理想状态应长期保持data: 0如果在高通信负载下持续增长则说明 UART RX 处理速度、缓冲区容量或者 Executor 业务执行时间需要进一步优化。因此这一指标能够直接用于后续的通信压力测试和稳定性评测。8.5 Agent Online状态判断agent_online_msg.data (rmw_uros_ping_agent(20, 1) RMW_RET_OK);验证ros2 topic echo /mcu/agent_online正常建立连接后应看到data: true这里存在一个需要在评测报告中明确说明的通信语义当 Agent 真正掉线后MCU 本身可以通过rmw_uros_ping_agent()判断其已经 OFFLINE但因为 ROS 数据本身也必须经过 Agent 才能传到 PC因此 PC 端无法在 Agent 已经完全断开的情况下实时收到false。因此/mcu/agent_online可用于正常通信期间的状态诊断OLED 等 MCU 本地界面可以真实显示 Agent OFFLINEAgent 完全离线期间不能依赖 ROS Topic 本身向 PC 报告“Agent 已离线”。这是由 Client-Agent 通信拓扑决定的正常现象而不是状态模块错误。9. 评测项目四ROS 2 → MCU OLED 动态文本与状态显示9.1 目标OLED 模块不仅验证一个普通 ROS Subscription还用于将多个系统状态集中到本地人机界面因此属于本项目的综合功能验证。OLED 文档设计了两个主要功能接收 PC 端/oled_text动态字符串按固定 2 Hz 刷新 OLED UI并显示 MCU Uptime 与 Agent 状态。最终界面---------------------- | PC: HELLO_ROS2 | |----------------------| | Up: xxx s | | Agent: ONLINE | ----------------------9.2 ROS 资源项目内容Topic/oled_textMessagestd_msgs/msg/StringMCU 角色SubscriberSubscription Handle1OLED Timer500 msTimer Handle1总 Handle2OLED 模块明确将文本接收与屏幕刷新分开处理。为了避免 MCU 上的动态内存碎片字符串接收使用预分配静态缓冲区同时 Subscription 回调只负责更新字符串不直接执行耗时的 I2C 刷屏。执行关系/oled_text │ ▼ Subscription Callback │ └── 仅更新 oled_display_text │ ▼ oled_timer 500 ms │ ├── MCU Uptime ├── Agent Ping ├── UI 排版 └── OLED_ShowFrame()这种设计避免将较慢的 I2C Transaction 放入消息接收回调是整个项目中比较重要的一项实时系统设计。9.3 动态字符串测试PCros2 topic pub --once /oled_text std_msgs/msg/String {data: HELLO_ROS2}预期 OLEDPC: HELLO_ROS2 Up: xxx s Agent: ONLINE上传的 OLED 测试文档已经记录了/oled_text、MCU 状态 Topic、SW1/SW2 和 LED Topic 同时存在于 ROS Graph 中并给出了动态字符串显示测试流程。【插图ros2 topic pub --once /oled_text std_msgs/msg/String {data: HELLO_ROS2} 】9.4 Agent 离线测试保持 MCU 继续运行在 PC 端停止micro_ros_agentOLED 本地执行rmw_uros_ping_agent(20, 1)因此应从Agent: ONLINE切换为Agent: OFFLINE这一测试证明 OLED 不仅是一个 ROS 消息显示器同时已经具备MCU 本地系统诊断界面的作用。OLED 文档给出的最终测试流程也明确包括停止 Agent 后观察 OLED 自动变为 OFFLINE。10. 最终 ROS Graph最终系统可以概括为PC / ROS 2 │ ┌─────────────┴──────────────┐ │ │ /led_topic /oled_text Bool String │ │ ▼ ▼ ros_app_led ros_app_oled │ │ ▼ ▼ LED OLED ▲ │ RA6M4 │ │ │ ┌───────┼──────────────┐ │ │ │ │ │ ▼ ▼ ▼ │ /sw1_topic /sw2_topic MCU Status ─────────┘ UInt32 UInt32 │ ├── /mcu/uptime_ms ├── /mcu/uart_rx_overflow_count └── /mcu/agent_online统一节点/ra6m4_node最终核心 Topic/led_topic /oled_text /sw1_topic /sw2_topic /mcu/uptime_ms /mcu/uart_rx_overflow_count /mcu/agent_online11. 综合评测计划总表编号完成任务涉及知识实际操作验收方法1Ubuntu VS Code 瑞萨环境GCC、CMake、FSP、Smart Configurator、Debugger建立 Renesas 开发 Profile、配置工程、编译烧录工程可正常 Build/Flash/Debug2micro-ROS AgentROS 2 workspace、colcon、Agent创建并编译 Agent workspaceAgent 能正常启动3micro-ROS Client交叉编译、ABI、静态库生成libmicroros.aRA6M4 工程链接成功4底层适配Transport、Allocator、TimeUART、内存、时钟适配rmw_uros_ping_agent()成功5Nodercl/rclc建立/ra6m4_noderos2 node list可见6LED 控制Subscription、Bool、GPIOPC 发布/led_topicLED 根据 Bool 变化7按键发布IRQ、Publisher、Timer发布/sw1_topic、/sw2_topicPC 实时得到按键计数8按键频率Executor、Timerros2 topic hz约 0.5 Hz9MCU Uptime系统时基、UInt64发布/mcu/uptime_ms数值持续递增10UART OverflowRing Buffer、UART RX发布 Overflow Count正常运行保持稳定11Agent 心跳Ping、链路诊断发布/mcu/agent_online在线时为 true12OLED 动态文字String、静态内存、SubscriptionPC 发布/oled_textOLED 显示发送内容13OLED 系统状态Timer、I2C、UI每 500 ms 刷新Uptime/Agent 状态正常14综合并发Executor所有模块同时加载所有 Topic 与外设同时工作15稳定性测试UART、Executor、内存连续运行【实测填写】分钟/小时无复位、无异常溢出12. 最终测试流程12.1 启动 Agentsource /opt/ros/jazzy/setup.bash source ~/Project/ROS2_Workspace/micro_ros/install/local_setup.bash ros2 run micro_ros_agent micro_ros_agent \ serial --dev /dev/ttyUSB0 -v6实际串口设备应按照测试电脑环境确定。12.2 检查 Noderos2 node list预期/ra6m4_node【插图node list】12.3 检查 Topicros2 topic list应至少观察到/led_topic /oled_text /sw1_topic /sw2_topic /mcu/uptime_ms /mcu/uart_rx_overflow_count /mcu/agent_online【插图topic list】12.4 LED# 打开 led 灯 ros2 topic pub --once /led_topic std_msgs/msg/Bool {data: true}以及# 关闭 led 灯 ros2 topic pub --once /led_topic std_msgs/msg/Bool {data: false}12.5 KEYros2 topic echo /sw1_topicros2 topic hz /sw1_topicSW2 同理。12.6 MCU Statusros2 topic echo /mcu/uptime_msros2 topic echo /mcu/uart_rx_overflow_countros2 topic echo /mcu/agent_online可增加ros2 topic hz /mcu/uptime_ms验证设计频率约为1 Hz12.7 OLEDros2 topic pub --once /oled_text std_msgs/msg/String {data: HELLO_ROS2}验证PC: HELLO_ROS2 Up: xxx s Agent: ONLINE随后关闭 Agent检查 OLEDAgent: OFFLINE13. 项目总结与评测结论本项目以 Renesas RA6M4 为嵌入式节点完成了 Ubuntu ROS 2 Jazzy 开发环境搭建、micro-ROS Client 移植、UART Transport、Allocator 与 Time 等底层接口适配并建立了完整的 Client-Agent 通信链路。在此基础上按照 BSP、Device、ROS Application 和 micro-ROS Porting 等层次完成工程重构实现了统一/ra6m4_node下多个业务模块的协同运行。功能评测覆盖 ROS 2 → MCU 与 MCU → ROS 2 两个通信方向通过/led_topic和/oled_text实现远程 LED 控制与 OLED 文本显示通过/sw1_topic、/sw2_topic实现板载按键数据上报并增加 MCU Uptime、UART RX Overflow 和 Agent 在线状态等运行监控信息。综合测试表明RA6M4 已能够稳定接入 ROS 2 网络并完成外设控制、数据采集、状态监测和本地信息显示等功能形成了一套较完整的 RA6M4 micro-ROS 应用与评测系统。14. 附件以下附件分别用于工程源码、开发环境搭建、micro-ROS 移植、设备通信以及系统状态监控等内容具体说明如下。14.1 工程完整代码(附带 oled 驱动)提供本项目的完整工程源代码包括 RA6M4 工程文件、micro-ROS 应用代码、UART 通信配置以及 OLED 驱动程序可用于复现和验证项目中的各项功能。项目完整代码14.2 基于 Ubuntu VS Code 搭建瑞萨开发环境说明文档介绍如何在 Ubuntu 系统中使用 VS Code 搭建 Renesas RA6M4 的开发环境包括相关工具的安装、工程配置、编译方法以及程序下载和调试流程。基于 Ubuntu VS Code 搭建瑞萨开发环境.pdf14.3 从零移植 micro-ROS 到 Renesas RA6M4说明文档详细说明将 micro-ROS 移植到 Renesas RA6M4 平台的完整过程涵盖底层接口适配、硬件抽象层配置、内存分配、时间接口以及编译部署等内容。从零移植 micro-ROS 到 Renesas RA6M4.zip14.4 在micro-ros上通过uart控制MCU外设 -- 以控制LED灯为例说明文档以 LED 控制为例介绍如何通过 UART 建立 ROS 2 与 RA6M4 MCU 之间的通信链路并实现 ROS 2 向 MCU 发送控制指令、MCU 根据指令控制外设的功能。在micro-ros上通过uart控制MCU外设 -- 以控制LED灯为例.pdf14.5 通过micro-ros 实现从 MCU - ROS2 的消息传递--以读取板子上的按键信息为例说明文档以板载按键数据采集为例说明 MCU 如何通过 micro-ROS 将硬件输入信息发布到 ROS 2 网络使上位机能够订阅并获取 RA6M4 的按键状态。通过micro-ros 实现从 MCU -_ ROS2 的消息传递--以读取板子上的按键信息为例.pdf14.6 通过 micro-ROS 实现 MCU 系统状态监控与上报 —— 以运行时间、串口溢出与 Agent 心跳为例介绍如何利用 micro-ROS 对 MCU 的运行状态进行监测和上报主要包括系统运行时间、UART 接收溢出次数以及 micro-ROS Agent 在线状态等信息通过 micro-ROS 实现 MCU 系统状态监控与上报 —— 以运行时间、串口溢出与 Agent 心跳为例.pdf14.7 通过 micro-ROS 实现从 ROS 2 - MCU 的消息传递 —— 以在 OLED 屏幕上显示动态文本与系统状态为例说明文档以 OLED 显示为例介绍 ROS 2 向 MCU 发送动态文本的方法并说明如何在 OLED 屏幕上显示接收到的消息、系统运行时间以及 Agent 在线状态等信息。通过 micro-ROS 实现从 ROS 2 -_ MCU 的消息传递 —— 以在 OLED 屏幕上显示动态文本与系统状态为例.pdf