-官方认证诚信至上 | 工业机器人及工控系统领军企业

随着具身智能技术爆发，机器人从工业场景向消费级、服务级领域快速渗透，小到家庭陪伴机器人，大到工业协作机器人，均对“边缘控制精度”与“生态协同能力”提出更高要求。据行业数据显示，一台中型服务机器人需集成10-15个传感器节点与8-12个执行器控制单元，而人形机器人的自由度关节更是突破20个，这类场景下，传统“MCU+简单控制程序”的模式已无法满足多节点协同需求——需同时实现实时电机控制、传感器数据预处理与云端/主机端数据交互，这也推动了“轻量化机器人操作系统（ROS）+高性能MCU”的技术组合成为行业主流。

作为ROS 2的轻量化分支，Micro-ROS凭借“资源适配性强”“生态兼容性高”“实时性优异”三大优势，已成为嵌入式机器人领域的核心(xīn)框(kuāng)架(jià)。其(qí)关键价(jià)值(zhí)在(zài)于(yú)打(dǎ)破(pò)资(zī)源(yuán)受(shòu)限(xiàn)设(shè)备(bèi)与(yǔ)ROS生(shēng)态(tài)的(de)壁(bì)垒(lěi)：仅(jǐn)需(xū)几(jǐ)十(shí)KB内(nèi)存(cún)即(jí)可(kě)在(zài)MCU端(duān)实(shí)现(xiàn)完(wán)整(zhěng)ROS 2通(tōng)信(xìn)能(néng)力(lì)（包(bāo)括(kuò)主题(tí)发(fā)布(bù)/订(dìng)阅(yuè)、服(fú)务(wu)调(diào)用(yòng)、参(cān)数(shù)管(guǎn)理(lǐ)等(děng)核(hé)心(xīn)功(gōng)能(néng)），且(qiě)能(néng)无(wú)缝(fèng)对(duì)接(jiē)Linux主机(jī)端(duān)的(de)ROS 2节(jié)点(diǎn)。在(zài)机(jī)器(qì)人(rén)实(shí)时(shí)电(diàn)机(jī)控制、智能传感器节点、边缘计算预处理等场景实现规模化应用，成为连接“边缘控制层”与“云端算力层”的关键桥梁。

兆易创新GD32H7系列MCU，凭借Cortex-M7内核，高达600MHz主频、1MB级SRAM（含512KB紧耦合内存）、多接口集成等硬件特性，完美匹配Micro-ROS的轻量化与实时性需求，成为国产MCU中适配Micro-ROS的优选方案。

本文将从开发板介绍、环境搭建、适配开发、测试验证四个维度，提供GD32H7系列MCU适配Micro-ROS的完整技术指南。

GD32H7系列MCU适配Micro-ROS的工程代码已在GitHub上开源，欢迎开发者下载使用。

Github仓库链接：

https://github.com/GigaDeviceSemiconductor/GD32H7-micro_ROS

Micro-ROS技术特性与架构

Micro-ROS是专为资源受限嵌入式设备设计的ROS 2轻量级实现框架，其核心特性可概括为七点：

优化的客户端API： 针对MCU资源特性优化，支持所有ROS 2核心概念（节点、话题、服务、参数等）；

无缝生态集成： 可直接与Linux主机ROS 2节点通信，无需额外协议转换；

轻量化中间件： 采用DDS-XRCE中间件，内存占用低至8KB，适配资源受限场景；

多RTOS支持： 兼容FreeRTOS、Zephyr、NuttX等主流实时操作系统，本文基于FreeRTOS开发；

宽松许可证： 基于Apache 2.0许可证，商用无限制；

活跃社区支持： 提供完善文档、示例代码与问题反馈渠道，生态持续迭代；

长期可维护性： 遵循ROS 2架构规范，确保与后续版本的兼容性。

△micro-ROS的系统架构

（图片来源：micro-ROS官方网站）

GD32H7开发板规格与接口定义

本文适配测试基于两款GD32H7系列开发板：GD32H759I-EVAL与GD32H75EY-EVAL，两者分别支持串口、USB、以太网与Micro-ROS Agent通信，核心规格与接口定义如下：

1GD32H759I-EVAL板

主控芯片：GD32H759IMK6（Cortex-M7内核，最高600MHz主频）；

供电方式：GD-Link Mini USB接口或DC-005连接器（5V）；

核心外设：Ethernet网口、USB HS0接口、3路CAN-FD、SDRAM、SPI-LCD、USARTx（多串口）等；

Micro-ROS关键接口定义：

打印串口：USART0（引脚PA9、PA10）；

串口通信（与Agent）：USART2（引脚PB10、PB11）；

以太网通信（与Agent）：ETH0网口（需将JP48、JP51、JP57、JP59、JP60、JP70跳帽接至ETH）；

USB通信（与Agent）：USB_HS0接口。

2GD32H75EY-EVAL板

主控芯片：GD32H75EYMJ6（Cortex-M7内核，最高600MHz主频）；

供电方式：GD-Link Mini USB接口或DC-005连接器（5V）；

核心外设：USB HS0接口、2路CAN-FD、SPI、I2C、USARTx（多串口）等；

Micro-ROS关键接口定义：

打印串口：USART2（引脚PB10、PB11）；

串口通信（与Agent）：USART0（引脚PB6、PB7）；

USB通信（与Agent）：USB_HS0接口。

1ROS 2与Micro-ROS开发环境搭建（Host：Ubuntu 22.04）

1.1ROS 2Humble环境安装

ROS 2是Micro-ROS的主机端核心依赖，本文选择稳定版Humble，安装步骤如下：

1.1.1 基础依赖安装

打开Ubuntu终端，执行以下命令安装系统依赖：

sudoapt update &&sudoapt install -y curl gnupg2 lsb-release

1.1.2 环境变量与源配置

确保系统支持UTF-8编码：

sudolocale-gen en_US en_US.UTF-8sudoupdate-locale LC_ALL=en_US.UTF-8LANG=en_US.UTF-8exportLANG=en_US.UTF-8

添加ROS 2 apt仓库密钥与源：

sudocurl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpgecho"deb [arch=$(dpkg --print-architecture)signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu$(lsb_release -cs)main"|sudotee/etc/apt/sources.list.d/ros2.list > /dev/null

1.1.3 ROS 2软件包安装

更新仓库缓存并安装桌面版：

sudoapt update &&sudoapt upgrade -ysudoapt install -y ros-humble-desktop# 可选：安装开发工具（编译依赖、调试工具）sudoapt install -y ros-humble-ros-base python3-colcon-common-extensions python3-rosdep

配置环境变量（每次打开终端需执行，或添加至～/.bashrc）：

source/opt/ros/humble/setup.bash

1.1.4 环境验证（Talker-Listener测试）

终端1：运行发布节点（talker）：

source/opt/ros/humble/setup.bashros2 run demo_nodes_cpp talker

终端2：运行订阅节点（listener）：

source/opt/ros/humble/setup.bashros2 run demo_nodes_cpp listener

若终端2能接收终端1发布的“Hello World”消息，则ROS 2环境安装成功。

1.2Micro-ROS构建系统安装

Micro-ROS依赖专属工具链实现固件编译与Agent通信，安装步骤如下：

1.2.1 工具链下载与依赖安装

加载ROS 2环境并创建Micro-ROS工作空间：

source/opt/ros/humble/setup.bashmkdir-p ~/micro_ros_ws/src &&cd~/micro_ros_wsgitclone-b humble https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

安装依赖（rosdep与pip）：

sudo rosdep init && rosdep updaterosdep install--from-pathssrc--ignore-src-ysudo apt install -ypython3-pippip3 install -U colcon-common-extensions

1.2.2 工具(jù)链(liàn)编(biān)译(yì)与(yǔ)环(huán)境(jìng)加(jiā)载(zài)

编(biān)译(yì)Micro-ROS工(gōng)具(jù)链(liàn)：

colcon build --packages-select micro_ros_setupsourceinstall/local_setup.bash

创(chuàng)建(jiàn)固(gù)件(jiàn)工(gōng)作(zuò)空(kōng)间(jiān)：

ros2run micro_ros_setup create_firmware_ws.sh host

执(zhí)行(xíng)后(hòu)将(jiāng)在(zài)~/micro_ros_ws/firmware目(mù)录(lù)下(xià)生(shēng)成(chéng)Micro-ROS工(gōng)程(chéng)结(jié)构(gòu)，包(bāo)含(hán)示(shì)例(lì)代(dài)码(mǎ)与(yǔ)编(biān)译(yì)脚(jiǎo)本(běn)。

1.2.3 Micro-ROS环(huán)境(jìng)验(yàn)证(zhèng)（Ubuntu主机(jī)端(duān)测(cè)试(shì)）

以(yǐ)“ping-pong”示(shì)例(lì)验(yàn)证(zhèng)环(huán)境(jìng)（主机(jī)端(duān)模(mó)拟(nǐ)MCU节(jié)点(diǎn)）：

编(biān)译(yì)ping-pong固(gù)件(jiàn)：

cd~/micro_ros_ws/firmwarecolcon build --packages-select micro_ros_demos_rclcsourceinstall/local_setup.bash

终(zhōng)端(duān)1：运(yùn)行(xíng)Micro-ROS Agent（UDP模(mó)式(shì)）：

ros2run micro_ros_agent micro_ros_agent udp4 --port8888

终(zhōng)端(duān)2：运(yùn)行(xíng)ping-pong节(jié)点(diǎn)：

source~/micro_ros_ws/firmware/install/local_setup.bashros2 run micro_ros_demos_rclc ping_pong

终(zhōng)端(duān)3：订(dìng)阅(yuè)ping话(huà)题(tí)验(yàn)证(zhèng)通(tōng)信(xìn)：

source/opt/ros/humble/setup.bashros2 topicecho/ping

若(ruò)终(zhōng)端(duān)3能(néng)接(jiē)收(shōu)ping消(xiāo)息(xi)，则(zé)Micro-ROS环(huán)境(jìng)搭(dā)建(jiàn)成(chéng)功(gōng)。

2GD32H7系(xì)列(liè)MCU适(shì)配(pèi)Micro-ROS开(kāi)发(fā)

2.1核(hé)心(xīn)适(shì)配(pèi)逻(luó)辑(ji)：静(jìng)态(tài)库(kù)集成(chéng)

由(yóu)于(yú)GD32H7基(jī)于(yú)FreeRTOS开(kāi)发，Micro-ROS适配采用“静态库集成”方案：先在Ubuntu主机端编译生成适配Cortex-M7内核的Micro-ROS静态库（含核心API、中间件、通信适配层），再将静态库与头文件导入GD32 Embedded Builder工程，配合底层驱动（串口、USB、以太网）实现通信。

静态库编译参考Micro-ROS官方教程（https://micro.ros.org/docs/tutorials/advanced/create_custom_static_library/），本(běn)文已(yǐ)提(tí)供(gōng)预(yù)编(biān)译(yì)完(wán)成(chéng)的(de)静(jìng)态(tài)库(kù)（包(bāo)含(hán)libmicroros.a及(jí)相(xiāng)关头(tóu)文件(jiàn)），直(zhí)接(jiē)导(dǎo)入(rù)工(gōng)程(chéng)即(jí)可(kě)使(shǐ)用(yòng)。

2.2工(gōng)程(chéng)导(dǎo)入(rù)与(yǔ)编(biān)译(yì)（基(jī)于(yú)GD32 Embedded Builder）

GD32 Embedded Builder是(shì)GD32系(xì)列(liè)MCU的(de)专(zhuān)属IDE，支持工程管理、编译、下载，适配步骤如下：

2.2.1 工程结构与静态库导入

下载GD32H7 Micro-ROS工程包（含GD32H759I_Eval_FreeRTOS_MicroROS与 GD32H75E_MicroROS两个工程）；

打开GD32 Embedded Builder，导入目标工程（如 GD32H759I_Eval_FreeRTOS_MicroROS）；

将Micro-ROS静态库（libmicroros.a）放入工程Lib目录，头文件放入Inc/microros目录，并在IDE中配置库路径与头文件路径。

2.2.2 不同通信接口的工程编译

GD32H759I-EVAL支持串口（中断/DMA）、USB CDC、以太网UDP三种通信方式，

GD32H75EY-EVAL支持串口（中断/DMA）、USB CDC两种方式，编译时需选择对应目标：

以GD32H759I-EVAL的串口（中断）为例，编译步骤：

右击工程→Build Configuration→Set Active→选择gd32h7_microros_usart_it；

点击“Build”按钮，编译完成后生成.elf与.hex文件；

其他通信方式的编译步骤类似，仅需切换目标工程即可。

3GD32H7 Micro-ROS功能测试

3.1测试准备

硬件：GD32H7开发板、GD-Link调试器、串口线（USB-TTL）、以太网网线（仅GD32H759I-EVAL）、12V电源；

软件：Ubuntu 22.04（已装ROS 2与Micro-ROS Agent）、串口调试助手（如SSCOM）。

3.2分接口测试步骤

3.2.1 串口通信测试（以GD32H759I-EVAL为例）

硬件连接：

打印串口：USART0（PA9→TX，PA10→RX）接USB-TTL，用于查看调试信息；

通信串口：USART2（PB10→TX，PB11→RX）接另一USB-TTL，连接Ubuntu主机。

Agent启动（Ubuntu终端）：

source/opt/ros/humble/setup.bashros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -b 115200

（注：/dev/ttyUSB0为Ubuntu识别的串口设备，可通过ls/dev/ttyUSB*查看）

固件下载：

在GD32 Embedded Builder中选择gd32h7_microros_usart_it工程，点击“Download”下载固件；

打开串口调试助手（波特率115200），可看到开发板打印的初始化信息。

功能验证：

打开新Ubuntu终端，订阅Micro-ROS节点发布的/gd32h7_microros_publisher话题：

source/opt/ros/humble/setup.bashros2 topicecho/gd32h7_microros_publisher

若能接收32位整数数据，则串口通信测试成功。

3.2.2 USB CDC通信测试（以GD32H759I-EVAL为例）

硬件连接：

打印串口：USART0接USB-TTL（查看调试信息）；

USB通信：开发板USB_HS0接口接Ubuntu主机。

Agent启动（Ubuntu终端）：

source/opt/ros/humble/setup.bash# 查看USB CDC设备（通常为/dev/ttyACM0）ls/dev/ttyACM*# 启动Agentros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyACM0 -b 115200