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

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

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

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

1.1支持的硬件芯片

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

?RK356x系列（如RK3562、RK3568）

?RK3588系列

?其他同架構(gòu)arm64芯片（內(nèi)核版本無限制）

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

1.2匹配的Linux SDK與Docker鏡像

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

已驗證的SDK與Docker匹配關(guān)系如下：

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

1.3已驗證的ROS2發(fā)行版

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

ROS2發(fā)行版	版本號	下載鏈接（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”分離編譯？

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

這背后是RK團(tuán)隊為降低維護(hù)成本、提升版本靈活性設(shè)計的適配邏輯：

2.1 ROS官方方案的痛點

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

2.2 RK方案的優(yōu)勢：解耦SDK與ROS2

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

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

?Docker容器：提供統(tǒng)一的Ubuntu編譯環(huán)境，結(jié)合SDK的交叉工具鏈與Sysroot，確保ROS2編譯產(chǎn)物能適配RK的rootfs；

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

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

接下來進(jìn)入實操環(huán)節(jié)，全程基于“RK3562 + Linux 5.10 SDK + ROS2 Iron”示例，其他型號可參考適配。

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

先確保SDK已包含ROS2的基礎(chǔ)依賴，關(guān)鍵是配置ros2_dep.config文件。

步驟1.1檢查/添加ros2_dep.config

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

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

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

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

# 進(jìn)入SDK的buildroot目錄cdbuildroot# 打補(bǔ)?。ㄌ砑觢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機(jī)器人方案的rockchip_rk356x_robot_defconfig），引入ros2_dep.config：

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

步驟1.3完整編譯SDK的rootfs

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

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

3.2第二步：搭建Docker編譯環(huán)境

基于匹配的Docker鏡像，搭建ROS2的交叉編譯環(huán)境。

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

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

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

步驟2.2導(dǎo)入匹配的Docker鏡像

先確認(rèn)SDK編譯的Python版本，再導(dǎo)入對應(yīng)Docker鏡像（鏡像從RK官方鏈接下載）：

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

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

啟動容器時，需將SDK的output目錄（含交叉工具鏈、rootfs）掛載到容器內(nèi)，確保編譯時能調(diào)用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# 進(jìn)入容器后，默認(rèn)用戶為builder，密碼：rockchip

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

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

# 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. 在容器內(nèi)解壓文件到/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版本相關(guān)配置（如3.10對應(yīng)310）#示例：將所有"3.10"改為"3.8"（若SDK為Python 3.8.6）

3.3第三步：編譯ROS2，解決交叉編譯關(guān)鍵問題

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

步驟3.1執(zhí)行編譯前準(zhǔn)備

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

步驟3.2執(zhí)行編譯腳本

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

關(guān)鍵問題：處理TRY_RUN手動配置

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

案例1：fastrtps的TRY_RUN報錯

報錯信息：

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

解決步驟：

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

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

# RK板端執(zhí)行/tmp/cmTC_4f573-SM_RUN_RESULT # 輸出：PTHREAD_RWLOCK_PREFER_READER_NP

1.在容器內(nèi)編輯TryRunResults.cmake，填入結(jié)果：

vim/buildroot/build/ros/fastrtps/TryRunResults.cmake# 添加以下內(nèi)容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板端執(zhí)行測試程序后，填入結(jié)果（示例輸出為缺失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產(chǎn)物已存放在/buildroot/target/opt/ros目錄，需重新打包rootfs并燒錄到RK板端。

步驟4.1重新打包rootfs

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

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

步驟4.2燒錄rootfs并運行ROS2

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

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

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

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

4.1編譯環(huán)境類報錯

1.編譯主機(jī)內(nèi)存不足

?現(xiàn)象：編譯中途卡頓或報錯“out of memory”；

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

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

2. pkg-config找不到

?現(xiàn)象：編譯tracetools時報錯“Could NOT find PkgConfig”；

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

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

# Docker中安裝pkgconfsudo apt install pkgconf# 設(shè)置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”

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

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

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

4.編譯結(jié)果出現(xiàn)x86_64動態(tài)庫

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

?原因：pybind11交叉編譯時默認(rèn)使用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中添加相同參數(shù)

4.3依賴與配置類報錯

5. CMake找不到exlibConfig.cmake

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

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

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

6. google_benchmark缺少limits頭文件

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

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

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

7. _FORTIFY_SOURCE編譯報錯

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

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

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

8.需要設(shè)置CMAKE_INCLUDE_PATH

?現(xiàn)象：編譯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

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

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

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

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

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

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

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

五、待完善方向：這些功能還在優(yōu)化中

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

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

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

六、總結(jié)與建議

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

給開發(fā)者的3點實操建議：

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

2.交叉編譯多檢查：編譯后通過file命令驗證產(chǎn)物架構(gòu)（如file _rclpy_pybind11.so應(yīng)顯示“aarch64”）；

通過這套流程，你可以快速在RK356x、RK3588等芯片上跑通ROS2，為嵌入式機(jī)器人開發(fā)打下基礎(chǔ)。后續(xù)可基于此擴(kuò)展激光SLAM、運動控制等功能，充分發(fā)揮RK芯片的硬件性能與ROS2的軟件生態(tài)優(yōu)勢。