在嵌入式機器人與智能硬件領域，瑞芯微（Rockchip）的RK356x、RK3588等arm64芯片憑借高性能、低功耗的優勢，成為眾多開發者的首選硬件平臺；而ROS2（Robot Operating System 2）作為新一代機器人操作系統，在分布式通信、實時性、多語言支持上的升級，更是嵌入式機器人開發的核心框架。

但不少開發者在將ROS2適配到RK平臺時，常會遇到“SDK與ROS2版本不兼容”“交叉編譯報錯”“板端運行缺失依賴”等問題。本文基于瑞芯微官方《Rockchip Linux SDK編譯ROS2說明》文檔，從適配邏輯、完整流程到避坑技巧，手把手教你搞定RK平臺的ROS2適配。

一、適配基礎：先搞懂“支持清單”

在開始適配前，必須先明確硬件、系統、ROS2版本的匹配關系，避免因版本不兼容走彎路。

1.1支持的硬件芯片

RK平臺目前僅支持arm64位芯片，已驗證的型號包括：

?RK356x系列（如RK3562、RK3568）

?RK3588系列

?其他同架構arm64芯片（內核版本無限制）

注意：32位arm芯片的rootfs暫未支持ROS2編譯，屬于待完善項。

1.2匹配的Linux SDK與Docker鏡像

RK Linux SDK基于Buildroot構建，ROS2的編譯依賴SDK提供的Python、bullet、opencv等基礎包，且需與Docker鏡像的Python版本嚴格一致（避免交叉編譯時庫版本沖突）。

已驗證的SDK與Docker匹配關系如下：

Linux SDK版本	Python版本	匹配Docker鏡像	額外要求
linux-5.10-stan-rkr1	3.10.5	jammy-ros2-build	需要添加ros2_dep.config補丁
linux-4.19-gen-rkr3	3.8.6	focal-ros2-build	需更新lttng-tools等依賴到指定版本

1.3已驗證的ROS2發行版

RK平臺已實測通過4個ROS2版本，源碼可直接從GitHub下載，版本信息如下：

ROS2發行版	版本號	下載鏈接（GitHub）
Foxy	ros2-release-foxy-20230620	https://github.com/ros2/ros2/releases/tag/release-foxy-20230620
Galactic	ros2-release-galactic-20221209	https://github.com/ros2/ros2/releases/tag/release-galactic-20221209
Humble	ros2-release-humble-20230724	https://github.com/ros2/ros2/releases/tag/release-humble-20230724
Iron	ros2-release-iron-20230912	https://github.com/ros2/ros2/releases/tag/release-iron-20230912

二、核心邏輯：為什么用“Docker+SDK”分離編譯？

很多開發者會疑惑：直接在RK SDK里編譯ROS2不行嗎？為什么要引入Docker？

這背后是RK團隊為降低維護成本、提升版本靈活性設計的適配邏輯：

2.1 ROS官方方案的痛點

ROS2官方雖提供了arm64交叉編譯的Docker鏡像（如Dockerfile_ubuntu_arm64_prebuilt），但僅支持Ubuntu 18.04（Bionic）系統，而RK Linux SDK的rootfs基于Buildroot定制，與Ubuntu 18.04的庫結構差異極大，直接使用會導致大量依賴沖突。

2.2 RK方案的優勢：解耦SDK與ROS2

RK采用“SDK提供依賴+ Docker編譯ROS2”的分離模式：

?RK Linux SDK：僅負責編譯ROS2所需的基礎依賴（如Python、Eigen、OpenCV），不直接編譯ROS2本體，避免SDK升級對ROS2的影響；

?Docker容器：提供統一的Ubuntu編譯環境，結合SDK的交叉工具鏈與Sysroot，確保ROS2編譯產物能適配RK的rootfs；

?最終通過“重新打包rootfs”將ROS2集成到RK板端，實現靈活升級（換ROS2版本只需換Docker編譯，無需重構SDK）。

三、手把手適配流程：4步從0到ROS2運行

接下來進入實操環節，全程基于“RK3562 + Linux 5.10 SDK + ROS2 Iron”示例，其他型號可參考適配。

3.1第一步：編譯RK SDK，集成ROS2依賴

先確保SDK已包含ROS2的基礎依賴，關鍵是配置ros2_dep.config文件。

步驟1.1檢查/添加ros2_dep.config

ros2_dep.config是ROS2依賴的配置文件，存放于buildroot/configs/rockchip/目錄下，包含LTTNG、Python等必需依賴的開關。

?若存在該文件：檢查是否包含LTTNG_TOOLS（ROS2 Iron必需），若缺失則手動添加：

# 編輯ros2_dep.configtail-f buildroot/configs/rockchip/ros2_dep.config# 添加以下內容（支持tracetools功能）BR2_PACKAGE_LTTNG_TOOLS=yBR2_PACKAGE_LTTNG_LIBUST=y

?若不存在該文件：需給SDK打2個補?。ㄑa丁文件可從RK官方鏈接下載）：

# 進入SDK的buildroot目錄cdbuildroot# 打補?。ㄌ砑觢ibasio依賴和ros2_dep.config）patch -p1 < ../linux-sdk-patches/buildroot/0001-package-add-libasio.patchpatch -p1 < ../linux-sdk-patches/buildroot/0002-configs-rockchip-add-ros2-build-dependencies.patch

步驟1.2將ros2_dep.config集成到SDK編譯

修改SDK的defconfig文件（如RK356x機器人方案的rockchip_rk356x_robot_defconfig），引入ros2_dep.config：

# 編輯defconfigvim buildroot/configs/rockchip/rockchip_rk356x_robot_defconfig# 在文件中添加一行（引入ROS2依賴配置）#include "ros2_dep.config"

步驟1.3完整編譯SDK的rootfs

執行SDK編譯命令，生成包含ROS2依賴的rootfs：

# 進入SDK根目錄cd/path/to/rk-linux-sdk# 編譯rootfs（根據芯片型號選擇defconfig）./build.sh rockchip_rk356x_robot_defconfig# 編譯完成后，rootfs輸出在buildroot/output/rockchip_rk356x_robot/

3.2第二步：搭建Docker編譯環境

基于匹配的Docker鏡像，搭建ROS2的交叉編譯環境。

步驟2.1安裝Docker并配置用戶組

在Ubuntu PC（建議20.04及以上）上安裝Docker，避免每次執行需sudo：

# 安裝Dockersudoapt install docker.io# 將當前用戶加入docker組（無需sudo）sudo usermod -aG docker$USERnewgrp docker # 生效用戶組

步驟2.2導入匹配的Docker鏡像

先確認SDK編譯的Python版本，再導入對應Docker鏡像（鏡像從RK官方鏈接下載）：

# 查看SDK的Python版本（示例輸出：Python 3.10.5）./buildroot/output/rockchip_rk356x_robot/host/bin/python --version# 導入匹配的鏡像（Python 3.10.5對應jammy-ros2-build）gunzip jammy-ros2-build.tar.gz # 解壓鏡像docker image load -i jammy-ros2-build.tar # 導入鏡像

步驟2.3啟動Docker容器并掛載SDK輸出目錄

啟動容器時，需將SDK的output目錄（含交叉工具鏈、rootfs）掛載到容器內，確保編譯時能調用SDK資源：

# 啟動容器，掛載SDK的output目錄（source替換為你的SDK output路徑）docker run -it --mounttype=bind,source=/home/yourname/rk-sdk/buildroot/output/rockchip_rk356x_robot/,target=/buildroot jammy-ros2-build# 進入容器后，默認用戶為builder，密碼：rockchip

步驟2.4拷貝編譯腳本與ROS2源碼到容器

從RK官方鏈接下載ros2-build-scripts.tar.gz（編譯腳本）和ros2-sources.tar.gz（ROS2源碼），拷貝到容器內并解壓：

# 1. 在Ubuntu PC端，查找容器ID（示例容器ID：c519d9d668f9）docker containerls# 2. 拷貝文件到容器的/tmp目錄docker containercpros2-build-scripts.tar.gz c519d9d668f9:/tmp/docker containercpros2-sources.tar.gz c519d9d668f9:/tmp/# 3. 在容器內解壓文件到/opt/ros目錄tar zxf /tmp/ros2-build-scripts.tar.gz -C /tar zxf /tmp/ros2-sources.tar.gz -C /# 解壓后，/opt/ros下會有cross-compile（交叉編譯配置）和各ROS2版本目錄ls/opt/ros # 輸出：cross-compile foxy galactic humble iron

步驟2.5修改腳本的Python版本號

確保編譯腳本的Python版本與SDK一致（示例SDK為3.10.5，無需修改；若為3.8.6則需將“310”改為“38”）：

#編輯交叉編譯配置文件vim /opt/ros/cross-compile/cross-compile.mixin#檢查Python版本相關配置（如3.10對應310）#示例：將所有"3.10"改為"3.8"（若SDK為Python 3.8.6）

3.3第三步：編譯ROS2，解決交叉編譯關鍵問題

進入ROS2版本目錄（如Iron），執行編譯腳本，重點處理“TRY_RUN手動配置”問題。

步驟3.1執行編譯前準備

# 進入ROS2 Iron目錄cd/opt/ros/iron# 準備源碼（腳本會檢查源碼完整性）./prepare-source.sh

步驟3.2執行編譯腳本

# 開始編譯ROS2（耗時約15-30分鐘，取決于PC性能）./build-ros2.sh# 編譯成功的標志：輸出類似以下內容Summary: 317 packages finished [15min 37s]build ros quit & cleanup

關鍵問題：處理TRY_RUN手動配置

交叉編譯時，fastrtps和rosbag2_cpp會觸發TRY_RUN報錯（因無法在PC端運行arm64程序），需手動在RK板端執行程序并記錄結果。

案例1：fastrtps的TRY_RUN報錯

報錯信息：

CMake Error: TRY_RUN() invokedincross-compiling mode, pleasesetSM_RUN_RESULTandSM_RUN_RESULT__TRYRUN_OUTPUT

解決步驟：

1.將容器內的測試程序（如/buildroot/build/ros/fastrtps/cmTC_4f573）拷貝到RK板端；

2.在RK板端執行程序，記錄輸出：

# RK板端執行/tmp/cmTC_4f573-SM_RUN_RESULT # 輸出：PTHREAD_RWLOCK_PREFER_READER_NP

1.在容器內編輯TryRunResults.cmake，填入結果：

vim/buildroot/build/ros/fastrtps/TryRunResults.cmake# 添加以下內容set(SM_RUN_RESULT"0"CACHESTRING"PTHREAD_RWLOCK_PREFER_READER_NP"FORCE)set(SM_RUN_RESULT__TRYRUN_OUTPUT"0"CACHESTRING"PTHREAD_RWLOCK_PREFER_READER_NP"FORCE)

案例2：rosbag2_cpp的TRY_RUN報錯

類似處理，在RK板端執行測試程序后，填入結果（示例輸出為缺失liblsan.so）：

vim/buildroot/build/ros/rosbag2_cpp/TryRunResults.cmakeset(HAVE_SANITIZERS_EXITCODE"127"CACHESTRING"error while loading shared libraries: liblsan.so.0"FORCE)set(HAVE_SANITIZERS_EXITCODE__TRYRUN_OUTPUT"127"CACHESTRING"error while loading shared libraries: liblsan.so.0"FORCE)

可選：單獨編譯某個ROS2包

若只需編譯特定包（如demo_nodes_cpp），可使用colcon build --packages-select：

# 單獨編譯demo_nodes_cppcolconbuild --packages-selectdemo_nodes_cpp --cmake-args -DCMAKE_TOOLCHAIN_FILE=/buildroot/share/buildroot/toolchainfile.cmake

3.4第四步：打包rootfs，板端運行ROS2

編譯完成后，ROS2產物已存放在/buildroot/target/opt/ros目錄，需重新打包rootfs并燒錄到RK板端。

步驟4.1重新打包rootfs

在Ubuntu PC的SDK根目錄，執行打包命令：

# 進入SDK根目錄cd/path/to/rk-linux-sdk# 重新打包rootfs（生成rootfs.img）./build.sh rootfs

步驟4.2燒錄rootfs并運行ROS2

將rootfs.img燒錄到RK板端（使用RK燒錄工具），啟動后執行以下命令運行ROS2 Hello World：

# 進入ROS2目錄cd/opt/ros/iron# 設置環境變量（指定ROS2路徑和工作目錄）exportCOLCON_CURRENT_PREFIX=/opt/ros/ironexportROS_HOME=/userdata/source./local_setup.sh # 加載ROS2環境# 驗證ROS2環境（列出已安裝包）ros2 pkg list# 運行Hello World（啟動listener后臺進程，再啟動talker）ros2 run demo_nodes_cpp listener &ros2 run demo_nodes_cpp talker# 成功輸出（類似以下內容）[INFO] [1501839280.834017748] [talker]: Publishing:'Hello World: 1'[INFO] [1501839280.839280957] [listener]: I heard: [Hello World: 1]

四、避坑寶典：10個常見報錯的解決方案

適配過程中難免遇到編譯或運行報錯，以下是RK官方已驗證的10個高頻問題及解決方案，按報錯場景分類。

4.1編譯環境類報錯

1.編譯主機內存不足

?現象：編譯中途卡頓或報錯“out of memory”；

?解決方案：開啟zram交換空間（示例分配12G）：

sudo -i sumodprobe zramecho12G > /sys/block/zram0/disksizemkswap /dev/zram0swapon /dev/zram0free -h # 驗證交換空間已生效

2. pkg-config找不到

?現象：編譯tracetools時報錯“Could NOT find PkgConfig”；

?原因：Docker中未安裝pkgconf（非pkg-config），或SDK的host-pkgconf與Docker版本沖突；

?解決方案：在Docker中安裝pkgconf，并指定SDK的pkgconfig路徑：

# Docker中安裝pkgconfsudo apt install pkgconf# 設置PKG_CONFIG_PATH（指向SDK的sysroot）exportPKG_CONFIG_PATH=/buildroot/host/aarch64-buildroot-linux-gnu/sysroot/usr/lib/pkgconfig

4.2板端運行類報錯

3.板端報“GLIBCXX_3.4.30 not found”

?現象：運行ros2命令時，提示libstdc++.so.6: version 'GLIBCXX_3.4.30' not found；

?原因：ROS2編譯使用的工具鏈與SDK的工具鏈版本不匹配；

?解決方案：必須使用RK Linux SDK自帶的交叉工具鏈編譯ROS2（Docker掛載的/buildroot目錄已包含該工具鏈）。

4.編譯結果出現x86_64動態庫

?現象：ROS2的Python庫（如_rclpy_pybind11.cpython-310-x86_64-linux-gnu.so）是x86架構，無法在arm64板端運行；

?原因：pybind11交叉編譯時默認使用PC的Python路徑；

?解決方案：修改pybind11配置，指定arm64的Python模塊后綴：

# 1. 在pybind11_vendor/CMakeLists.txt中添加list(APPEND extra_cmake_args"-DPYBIND11_PYTHONLIBS_OVERWRITE=OFF")list(APPEND extra_cmake_args"-DPYTHON_MODULE_EXTENSION=.cpython-310-aarch64-linux-gnu.so")# 2. 在cross-compile.mixin中添加相同參數

4.3依賴與配置類報錯

5. CMake找不到exlibConfig.cmake

?現象：編譯ament_cmake_vendor_package時，報錯“Could not find exlibConfig.cmake”；

?原因：交叉工具鏈路徑與CMAKE_PREFIX_PATH沖突；

?解決方案：編譯時不指定CMAKE_TOOLCHAIN_FILE（依賴Docker與SDK掛載的環境自動識別）。

6. google_benchmark缺少limits頭文件

?現象：編譯foxy版本時，報錯“‘numeric_limits’ is not a member of ‘std’”；

?原因：benchmark_register.h缺失頭文件；

?解決方案：在該頭文件中添加#include，或使用RK提供的補丁包。

7. _FORTIFY_SOURCE編譯報錯

?現象：編譯mimick_vendor時，報錯“_FORTIFY_SOURCE requires compiling with optimization (-O)”；

?原因：SDK工具鏈定義了_FORTIFY_SOURCE，但未開啟編譯優化；

?解決方案：刪除工具鏈中的_FORTIFY_SOURCE定義，或在編譯時添加-O2優化參數。

8.需要設置CMAKE_INCLUDE_PATH

?現象：編譯orocos_kdl_vendor時，報錯“EIGEN3_INCLUDE_DIR NOTFOUND”；

?原因：CMake無法找到SDK中的Eigen頭文件；

?解決方案：指定CMAKE_INCLUDE_PATH指向SDK的sysroot：

exportCMAKE_INCLUDE_PATH='/buildroot/host/aarch64-buildroot-linux-gnu/sysroot/usr/include/'

9. tracetools找不到lttng-ust

?現象：編譯tracetools時，報錯“cannot find -llttng-ust-common”；

?原因：pkg-config找到了Docker的lttng，而非SDK的lttng；

?解決方案：設置PKG_CONFIG_PATH指向SDK的pkgconfig目錄（同問題2的解決方案）。

10.交叉編譯時numpy路徑錯誤

?現象：編譯action_msgs時，警告“unsafe header path: /usr/local/lib/python3.10/dist-packages/numpy/core/include”；

?原因：Python使用PC端的numpy路徑；

?解決方案：在cross-compile.mixin中預設numpy的include路徑（指向SDK的sysroot）。

五、待完善方向：這些功能還在優化中

目前RK平臺的ROS2適配仍有2個待完善項，開發者需注意：

1.刪除不必要的安裝文件：編譯后的ROS2目錄包含cmake、頭文件、靜態庫等冗余文件，未來可優化為僅保留運行必需的動態庫和腳本；

2.arm32位rootfs支持：當前僅支持arm64，32位芯片（如RK3288）的適配仍在開發中。

六、總結與建議

RK平臺的ROS2適配核心是“SDK提供依賴+ Docker編譯+ rootfs集成”，既解決了官方ROS2鏡像與RK系統的兼容性問題，又實現了SDK與ROS2的解耦維護。

給開發者的3點實操建議：

1.版本匹配是前提：務必確保SDK的Python版本、Docker鏡像、ROS2版本三者對應，避免版本沖突；

2.交叉編譯多檢查：編譯后通過file命令驗證產物架構（如file _rclpy_pybind11.so應顯示“aarch64”）；

通過這套流程，你可以快速在RK356x、RK3588等芯片上跑通ROS2，為嵌入式機器人開發打下基礎。后續可基于此擴展激光SLAM、運動控制等功能，充分發揮RK芯片的硬件性能與ROS2的軟件生態優勢。