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

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

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

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

1.1支持的硬件芯片

RK平臺(tái)目前僅支持arm64位芯片，已驗(yàn)證的型號(hào)包括：

?RK356x系列（如RK3562、RK3568）

?RK3588系列

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

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

1.2匹配的Linux SDK與Docker鏡像

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

已驗(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等依賴(lài)到指定版本

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

RK平臺(tái)已實(shí)測(cè)通過(guò)4個(gè)ROS2版本，源碼可直接從GitHub下載，版本信息如下：

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

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

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

2.1 ROS官方方案的痛點(diǎn)

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

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

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

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

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

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

三、手把手適配流程：4步從0到ROS2運(yùn)行

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

3.1第一步：編譯RK SDK，集成ROS2依賴(lài)

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

步驟1.1檢查/添加ros2_dep.config

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

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

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

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

# 進(jìn)入SDK的buildroot目錄cdbuildroot# 打補(bǔ)丁（添加libasio依賴(lài)和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依賴(lài)配置）#include "ros2_dep.config"

步驟1.3完整編譯SDK的rootfs

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

# 進(jìn)入SDK根目錄cd/path/to/rk-linux-sdk# 編譯rootfs（根據(jù)芯片型號(hào)選擇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并配置用戶(hù)組

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

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

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

先確認(rèn)SDK編譯的Python版本，再導(dǎo)入對(duì)應(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對(duì)應(yīng)jammy-ros2-build）gunzip jammy-ros2-build.tar.gz # 解壓鏡像docker image load -i jammy-ros2-build.tar # 導(dǎo)入鏡像

步驟2.3啟動(dòng)Docker容器并掛載SDK輸出目錄

啟動(dòng)容器時(shí)，需將SDK的output目錄（含交叉工具鏈、rootfs）掛載到容器內(nèi)，確保編譯時(shí)能調(diào)用SDK資源：

# 啟動(dòng)容器，掛載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)用戶(hù)為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下會(huì)有cross-compile（交叉編譯配置）和各ROS2版本目錄ls/opt/ros # 輸出：cross-compile foxy galactic humble iron

步驟2.5修改腳本的Python版本號(hào)

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

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

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

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

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

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

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

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

關(guān)鍵問(wèn)題：處理TRY_RUN手動(dòng)配置

交叉編譯時(shí)，fastrtps和rosbag2_cpp會(huì)觸發(fā)TRY_RUN報(bào)錯(cuò)（因無(wú)法在PC端運(yùn)行arm64程序），需手動(dòng)在RK板端執(zhí)行程序并記錄結(jié)果。

案例1：fastrtps的TRY_RUN報(bào)錯(cuò)

報(bào)錯(cuò)信息：

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

解決步驟：

1.將容器內(nèi)的測(cè)試程序（如/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報(bào)錯(cuò)

類(lèi)似處理，在RK板端執(zhí)行測(cè)試程序后，填入結(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)

可選：?jiǎn)为?dú)編譯某個(gè)ROS2包

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

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

3.4第四步：打包rootfs，板端運(yùn)行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并運(yùn)行ROS2

將rootfs.img燒錄到RK板端（使用RK燒錄工具），啟動(dòng)后執(zhí)行以下命令運(yùn)行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)境# 驗(yàn)證ROS2環(huán)境（列出已安裝包）ros2 pkg list# 運(yùn)行Hello World（啟動(dòng)listener后臺(tái)進(jìn)程，再啟動(dòng)talker）ros2 run demo_nodes_cpp listener &ros2 run demo_nodes_cpp talker# 成功輸出（類(lèi)似以下內(nèi)容）[INFO] [1501839280.834017748] [talker]: Publishing:'Hello World: 1'[INFO] [1501839280.839280957] [listener]: I heard: [Hello World: 1]

四、避坑寶典：10個(gè)常見(jiàn)報(bào)錯(cuò)的解決方案

適配過(guò)程中難免遇到編譯或運(yùn)行報(bào)錯(cuò)，以下是RK官方已驗(yàn)證的10個(gè)高頻問(wèn)題及解決方案，按報(bào)錯(cuò)場(chǎng)景分類(lèi)。

4.1編譯環(huán)境類(lèi)報(bào)錯(cuò)

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

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

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

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

2. pkg-config找不到

?現(xiàn)象：編譯tracetools時(shí)報(bào)錯(cuò)“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板端運(yùn)行類(lèi)報(bào)錯(cuò)

3.板端報(bào)“GLIBCXX_3.4.30 not found”

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

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

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

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

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

?原因：pybind11交叉編譯時(shí)默認(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依賴(lài)與配置類(lèi)報(bào)錯(cuò)

5. CMake找不到exlibConfig.cmake

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

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

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

6. google_benchmark缺少limits頭文件

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

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

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

7. _FORTIFY_SOURCE編譯報(bào)錯(cuò)

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

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

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

8.需要設(shè)置CMAKE_INCLUDE_PATH

?現(xiàn)象：編譯orocos_kdl_vendor時(shí)，報(bào)錯(cuò)“EIGEN3_INCLUDE_DIR NOTFOUND”；

?原因：CMake無(wú)法找到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時(shí)，報(bào)錯(cuò)“cannot find -llttng-ust-common”；

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

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

10.交叉編譯時(shí)numpy路徑錯(cuò)誤

?現(xiàn)象：編譯action_msgs時(shí)，警告“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平臺(tái)的ROS2適配仍有2個(gè)待完善項(xiàng)，開(kāi)發(fā)者需注意：

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

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

六、總結(jié)與建議

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

給開(kāi)發(fā)者的3點(diǎn)實(shí)操建議：

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

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

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