隨著具身智能技術爆發，機器人從工業場景向消費級、服務級領域快速滲透，小到家庭陪伴機器人，大到工業協作機器人，均對“邊緣控制精度”與“生態協同能力”提出更高要求。據行業數據顯示，一臺中型服務機器人需集成10-15個傳感器節點與8-12個執行器控制單元，而人形機器人的自由度關節更是突破20個，這類場景下，傳統“MCU+簡單控制程序”的模式已無法滿足多節點協同需求——需同時實現實時電機控制、傳感器數據預處理與云端/主機端數據交互，這也推動了“輕量化機器人操作系統（ROS）+高性能MCU”的技術組合成為行業主流。

作為ROS 2的輕量化分支，Micro-ROS憑借“資源適配性強”“生態兼容性高”“實時性優異”三大優勢，已成為嵌入式機器人領域的核心框架。其關鍵價值在于打破資源受限設備與ROS生態的壁壘：僅需幾十KB內存即可在MCU端實現完整ROS 2通信能力（包括主題發布/訂閱、服務調用、參數管理等核心功能），且能無縫對接Linux主機端的ROS 2節點。在機器人實時電機控制、智能傳感器節點、邊緣計算預處理等場景實現規模化應用，成為連接“邊緣控制層”與“云端算力層”的關鍵橋梁。

兆易創新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-8
sudoupdate-locale LC_ALL=en_US.UTF-8LANG=en_US.UTF-8
exportLANG=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.gpg
echo"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 -y
sudoapt 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.bash
ros2 run demo_nodes_cpp talker

終端2：運行訂閱節點（listener）：

source/opt/ros/humble/setup.bash
ros2 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.bash
mkdir-p ~/micro_ros_ws/src &&cd~/micro_ros_ws
gitclone-b humble https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

安裝依賴（rosdep與pip）：

sudo rosdep init && rosdep update
rosdep install--from-pathssrc--ignore-src-y
sudo apt install -ypython3-pip
pip3 install -U colcon-common-extensions

1.2.2 工具鏈編譯與環境加載

編譯Micro-ROS工具鏈：

colcon build --packages-select micro_ros_setup
sourceinstall/local_setup.bash

創建固件工作空間：

ros2run micro_ros_setup create_firmware_ws.sh host

執行后將在~/micro_ros_ws/firmware目錄下生成Micro-ROS工程結構，包含示例代碼與編譯腳本。

1.2.3 Micro-ROS環境驗證（Ubuntu主機端測試）

以“ping-pong”示例驗證環境（主機端模擬MCU節點）：

編譯ping-pong固件：

cd~/micro_ros_ws/firmware
colcon build --packages-select micro_ros_demos_rclc
sourceinstall/local_setup.bash

終端1：運行Micro-ROS Agent（UDP模式）：

ros2run micro_ros_agent micro_ros_agent udp4 --port8888

終端2：運行ping-pong節點：

source~/micro_ros_ws/firmware/install/local_setup.bash
ros2 run micro_ros_demos_rclc ping_pong

終端3：訂閱ping話題驗證通信：

source/opt/ros/humble/setup.bash
ros2 topicecho/ping

若終端3能接收ping消息，則Micro-ROS環境搭建成功。

2GD32H7系列MCU適配Micro-ROS開發

2.1核心適配邏輯：靜態庫集成

由于GD32H7基于FreeRTOS開發，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/），本文已提供預編譯完成的靜態庫（包含libmicroros.a及相關頭文件），直接導入工程即可使用。

2.2工程導入與編譯（基于GD32 Embedded Builder）

GD32 Embedded Builder是GD32系列MCU的專屬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.bash
ros2 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.bash
ros2 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*
# 啟動Agent
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyACM0 -b 115200