RDK X5机器人开发环境搭建：Ubuntu 20.04与ROS 2 Humble实战指南

1. 为什么选择RDK X5搭建机器人开发环境

1.1 这块板子到底适合谁

RDK X5 是地瓜机器人推出的一款面向智能机器人场景的开发板，核心卖点是算力够用、接口丰富、官方软件栈相对完整。我拿到这块板子的第一反应是：它不像某些开发板那样“买回来先折腾三天系统”，官方给的 Ubuntu 20.04 镜像烧录完基本就能跑，这对刚入门的开发者来说省了太多事。

如果你属于以下几类人，这套环境搭建方案会非常适合你：一是刚接触机器人开发、想找一个软硬件都相对友好的平台入门的；二是做 SLAM、导航、视觉识别这类需要一定算力但预算有限的；三是已经在用 ROS 2 做项目，想找一个能直接跑 Humble 的嵌入式平台做验证的。RDK X5 官方适配的就是 Ubuntu 20.04 + ROS 2 Humble 这套组合，版本匹配度高，踩坑概率比你自己乱配要低得多。

1.2 为什么是 Ubuntu 20.04 而不是 22.04

这个问题我被问过很多次。ROS 2 Humble 官方支持的 Ubuntu 版本就是 20.04（Focal），虽然 22.04 也能装，但很多依赖包的版本对不上，尤其是涉及到硬件加速、BPU 推理库这些和板子底层强相关的东西，官方只在 20.04 上做了完整验证。你硬上 22.04，可能编译能过，但跑起来各种奇怪的段错误，排查成本极高。

另一个现实原因是 RDK X5 的官方镜像就是基于 Ubuntu 20.04 定制的，里面已经预置了 BPU 驱动、多媒体库、GPIO 控制库这些底层组件。你自己装一个纯净版 20.04 再补驱动，工作量比直接用官方镜像大得多，而且容易漏掉某些隐藏依赖。所以我的建议很明确：直接用官方镜像，不要自己从零装系统。

1.3 ROS 2 Humble 在机器人开发中的位置

ROS 2 Humble 是 2022 年发布的 LTS 版本，支持到 2027 年，生命周期长，社区资料多。相比 ROS 1，它在实时性、多机通信、安全机制上都有明显改进。对于机器人开发来说，Humble 目前是性价比最高的选择——既不像 Foxy 那样太老，也不像 Rolling 那样天天变。

RDK X5 上跑 Humble 的意义在于：你可以把 PC 上开发好的节点直接移植过来，话题、服务、动作的接口基本不用改。我实测过一个在 PC 上跑的激光雷达建图节点，交叉编译后放到板子上，除了 CPU 占用高一点，功能完全正常。这种“开发在 PC、部署在板子”的流程，是嵌入式机器人开发最舒服的模式。

2. 环境搭建前的硬件与软件准备

2.1 硬件清单与选型理由

先把要用的东西列清楚，免得做到一半发现少东西。

电源这块我要多说一句。很多人随便找个手机充电器就上，结果板子跑高负载任务时电压跌落，系统直接挂掉。RDK X5 的峰值功耗不低，尤其是 BPU 满载的时候，5V/3A 是底线，能上 4A 更稳。我一开始用了个 2A 的，编译 ROS 包的时候随机重启，换了电源后再没出现过。

2.2 软件工具准备

软件方面需要准备的东西不多，但每一样都要装对版本。

• 镜像烧录工具：官方推荐的 balenaEtcher 或者 Rufus 都行，我用的是 balenaEtcher，界面简单，烧录完会自动校验。
• 官方系统镜像：去地瓜机器人官网下载 RDK X5 对应的 Ubuntu 20.04 镜像，注意看版本号，选最新的稳定版。
• 串口终端工具：Windows 下用 MobaXterm 或 PuTTY，Linux/Mac 下直接用 screen 或 minicom。
• SSH 客户端：配置好网络后基本都用 SSH，推荐 Windows Terminal 或者 VS Code 的 Remote-SSH 插件。

提示：下载镜像时务必核对文件哈希值，我遇到过一次下载不完整导致烧录后无法启动的情况，重新下载才解决。

2.3 网络环境规划

RDK X5 首次启动后需要联网才能更新软件源、安装 ROS 2。有两种方式：有线直连路由器，或者通过串口配置 WiFi。我建议首次配置用有线，因为串口配 WiFi 要敲一堆命令，容易出错。

如果你只有笔记本没有路由器，可以用网线直连笔记本，然后在笔记本上开网络共享。Windows 下在“网络适配器”里把有线网卡和无线网卡桥接，Ubuntu 下用 nmcli 配置共享。这个方式稍微麻烦一点，但应急可用。

3. 系统镜像烧录与首次启动

3.1 镜像烧录的完整步骤

烧录本身不复杂，但有几个细节容易翻车。

1. 把 MicroSD 卡插入读卡器，接到电脑上。注意备份卡里原有数据，烧录会全盘覆盖。
2. 打开 balenaEtcher，选择下载好的 RDK X5 镜像文件。
3. 选择目标磁盘，一定要确认选的是 SD 卡而不是你的移动硬盘，我见过有人选错盘把资料全格了的。
4. 点击 Flash，等待烧录和校验完成。32GB 的卡大概需要 10-15 分钟，取决于卡的速度。
5. 烧录完成后，把 SD 卡拔出，插入 RDK X5 的卡槽。

注意：烧录完成后 Windows 可能会提示“需要格式化磁盘”，千万别点格式化，那是 Linux 分区 Windows 识别不了，点取消就行。

3.2 首次上电与串口登录

板子插好 SD 卡、接好电源和网线，上电。首次启动会比较慢，因为要初始化文件系统和扩展分区，大概等 1-2 分钟。

如果你接了串口模块，可以在终端里看到启动日志。串口参数是115200-8-N-1，登录用户名和密码看官方文档，通常是 root/root 或者 sunrise/sunrise。串口登录的好处是即使网络没配好也能进去操作，是救砖的最后手段。

首次启动后建议先做两件事：一是用df -h看一下根分区有没有自动扩展，二是用free -h确认内存识别正常。如果根分区没扩展，手动执行sudo resize2fs /dev/mmcblk0p2扩展一下。

3.3 网络配置与 SSH 打通

有线网络一般插上就能用，用ip addr看一下有没有拿到 IP。如果没有，检查网线和水晶头，或者用sudo dhclient eth0手动获取。

拿到 IP 后，在 PC 上ping一下确认连通，然后ssh sunrise@<板子IP>登录。第一次登录会提示确认指纹，输入 yes 即可。登录成功后，建议立刻改密码，并把 SSH 配置成密钥登录，方便后续用 VS Code Remote 开发。

WiFi 配置用nmcli命令：

sudo nmcli dev wifi connect "你的WiFi名" password "你的密码"

连上后用nmcli connection show确认，再用ip addr看 wlan0 有没有 IP。

4. 系统初始化与基础环境配置

4.1 软件源更新与依赖安装

官方镜像的软件源可能指向的是默认的 Ubuntu 源，国内访问速度慢。建议换成国内镜像源，具体换源方法参考官方文档，这里不展开。换完源后执行：

sudo apt update sudo apt upgrade -y

这一步会更新所有已安装的包，时间比较长，建议挂着跑。更新完后安装一些基础工具：

sudo apt install -y build-essential cmake git wget curl vim htop net-tools

这些工具后面编译 ROS 包、调试网络都会用到，一次性装好省事。

4.2 中文输入法与显示环境

如果你打算在板子上直接接显示器用，中文输入法得配一下。Ubuntu 20.04 下推荐 fcitx + 搜狗输入法，或者直接用 ibus + 拼音。安装命令：

sudo apt install -y fcitx fcitx-pinyin fcitx-config-gtk

装完后在“语言支持”里把键盘输入法系统切成 fcitx，重启生效。不过说实话，板子上直接敲中文的场景不多，大部分时候是 SSH 过去在 PC 上开发，这个配置属于锦上添花。

显示环境方面，RDK X5 支持 HDMI 输出，接显示器就能用桌面。但如果你做的是无头机器人，桌面环境其实可以关掉，省内存和 CPU。用sudo systemctl set-default multi-user.target可以切到命令行模式，需要时再切回来。

4.3 时间同步与区域设置

时间不对会导致 ROS 2 的 TF 变换、日志时间戳全乱套。先确认时区：

sudo timedatectl set-timezone Asia/Shanghai

然后装 NTP 服务同步时间：

sudo apt install -y ntpdate sudo ntpdate ntp.aliyun.com

如果板子长期联网，可以装 chrony 做持续同步。时间同步这事看着小，但多机通信时时间不一致会引发各种诡异问题，我踩过这个坑，排查了半天才发现是时间差了 8 小时。

5. ROS 2 Humble 安装与验证

5.1 安装 ROS 2 Humble 的两种方式

RDK X5 上装 ROS 2 Humble 有两条路：一是用 apt 装官方二进制包，二是用官方提供的预编译包。我推荐优先用官方预编译包，因为地瓜的镜像里可能已经预置了部分 ROS 2 组件，或者提供了针对 BPU 优化的版本。

如果官方没有预编译包，那就走标准 apt 安装流程：

sudo apt install -y software-properties-common sudo add-apt-repository universe sudo apt update && sudo apt install -y curl sudo curl -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 $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null sudo apt update sudo apt install -y ros-humble-desktop

ros-humble-desktop包含了 RViz、rqt 这些图形工具，如果板子存储紧张，可以装ros-humble-ros-base，只装核心库。

5.2 环境变量配置与验证

装完后要把 ROS 2 的环境变量加到 bashrc 里：

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc source ~/.bashrc

验证安装是否成功，开两个终端，一个跑 talker，一个跑 listener：

# 终端1 ros2 run demo_nodes_cpp talker # 终端2 ros2 run demo_nodes_cpp listener

如果 listener 能收到 talker 发的消息，说明 ROS 2 核心功能正常。再用ros2 topic list看一下话题列表，应该能看到/chatter。

5.3 工作空间创建与 colcon 编译

ROS 2 用 colcon 替代了 ROS 1 的 catkin。创建一个标准工作空间：

mkdir -p ~/ros2_ws/src cd ~/ros2_ws colcon build source install/setup.bash

colcon build第一次跑会编译一些基础包，时间较长。编译完成后，install目录里就是你的工作空间产物。后续自己写包，放到src下，再colcon build即可。

实操心得：colcon 编译时如果报内存不足，可以用--parallel-workers 1限制并行编译数。RDK X5 内存有限，同时编译多个大包容易 OOM。

6. 机器人开发常用工具链配置

6.1 VS Code Remote 开发环境

在板子上直接写代码体验很差，推荐用 VS Code 的 Remote-SSH 插件，在 PC 上编辑，代码实际存在板子上。配置步骤：

1. PC 上装 VS Code，安装 Remote-SSH 插件。
2. 按 F1，输入Remote-SSH: Connect to Host，填sunrise@<板子IP>。
3. 连上后，在板子上装 C++、Python、ROS 插件。
4. 打开~/ros2_ws目录，就可以在 PC 上享受智能补全和调试了。

这个方式的好处是编译在板子上跑，编辑在 PC 上做，两边优势都占了。我现在的机器人项目基本都是这个模式，效率比纯 SSH 高太多。

6.2 micro-ROS 与单片机通信

如果你的机器人有 STM32 或 ESP32 这类单片机做底层控制，micro-ROS 是绕不开的。RDK X5 上装 micro-ROS 的 agent：

sudo apt install -y ros-humble-micro-ros-agent

然后单片机端跑 micro-ROS 客户端，通过串口或 UDP 和 agent 通信。这样单片机上的话题就能直接出现在 ROS 2 网络里，上层导航、规划节点不用关心底层是啥。

配置时注意串口权限，把用户加到 dialout 组：

sudo usermod -aG dialout $USER

重新登录生效。不然 agent 打不开串口，会报 permission denied。

6.3 常用调试工具安装

机器人开发离不开调试工具，这几个建议都装上：

• rqt：图形化调试工具集，看话题、调参数、画曲线都靠它。
• rviz2：3D 可视化，看激光雷达点云、机器人模型、TF 树。
• ros2 bag：录包回放，复现问题必备。
• foxglove：网页版可视化，比 rviz 轻量，远程看数据方便。

安装命令：

sudo apt install -y ros-humble-rqt* ros-humble-rviz2 ros-humble-ros2bag

foxglove 需要单独下载，官网有 Linux 版。

7. 常见问题与排查实录

7.1 系统启动类问题

电源问题我再说一遍，这是最常见的坑。板子跑轻负载没事，一编译就重启，十有八九是电源不行。

7.2 ROS 2 相关故障

问题一：ros2 run 报找不到包

先确认source /opt/ros/humble/setup.bash执行了，再确认包名拼写正确。用ros2 pkg list | grep 包名查一下。

问题二：话题能发不能收

检查 ROS_DOMAIN_ID 是否一致，多机通信时域 ID 不同会导致互相看不见。用echo $ROS_DOMAIN_ID确认。

问题三：colcon build 内存不足

限制并行编译数：colcon build --parallel-workers 1。或者加 swap 分区。

问题四：TF 变换报时间戳错误

检查系统时间是否同步，多机时所有机器时间要一致。用date命令对比。

7.3 网络与远程访问问题

SSH 连不上，先 ping 一下看通不通。通但 SSH 拒绝，检查 sshd 服务是否运行：sudo systemctl status ssh。不通的话检查网线、IP 配置、防火墙。

VS Code Remote 连接慢，通常是板子上没装好 vscode-server。删掉~/.vscode-server重新连一次，会自动重装。

避坑技巧：板子长期跑机器人，建议配静态 IP，不然路由器重新分配 IP 后，你所有脚本里的地址都得改。在/etc/netplan/下配置静态 IP，具体方法参考 Ubuntu 网络配置文档。

8. 环境验证与第一个机器人节点

8.1 用 turtlesim 验证 ROS 2 图形功能

turtlesim 是 ROS 2 的经典入门示例，能验证图形显示和话题通信：

ros2 run turtlesim turtlesim_node ros2 run turtlesim turtle_teleop_key

如果板子接了显示器，能看到小乌龟；如果无头，可以用ros2 topic echo /turtle1/pose看位姿数据。这个例子虽小，但涵盖了节点、话题、服务的基本用法，适合验证环境完整性。

8.2 写一个简单的发布订阅节点

自己写个 Python 节点，验证开发流程：

# publisher.py import rclpy from rclpy.node import Node from std_msgs.msg import String class Publisher(Node): def __init__(self): super().__init__('publisher') self.pub = self.create_publisher(String, 'hello', 10) self.timer = self.create_timer(1.0, self.callback) def callback(self): msg = String() msg.data = 'Hello RDK X5' self.pub.publish(msg) self.get_logger().info('Published: %s' % msg.data) def main(): rclpy.init() rclpy.spin(Publisher()) rclpy.shutdown() if __name__ == '__main__': main()

放到ros2_ws/src下，配好setup.py，colcon build后ros2 run跑起来。再用ros2 topic echo /hello看消息。这个流程走通，说明你的开发环境完全可用了。

8.3 性能与资源占用观察

跑起来后用htop看 CPU 和内存占用，用sudo tegrastats（如果支持）看更详细的硬件状态。RDK X5 跑纯 ROS 2 节点时 CPU 占用不高，但跑 BPU 推理时会明显上升。建议在跑重负载任务前，先用stress压测一下，确认散热和电源扛得住。

我实测下来，跑一个激光雷达建图节点加一个导航节点，CPU 占用大概 40%-60%，内存占用 1.5GB 左右。这个负载对 RDK X5 来说很轻松，还有余量跑视觉推理。

9. 后续扩展与个人经验

环境搭好只是第一步，后面还有一堆事要做：接传感器、标定、建图、导航、调参。但基础环境稳了，后面就是按部就班的事。

我个人在实际操作中的体会是，不要急着上复杂功能，先把基础环境验证透。我见过太多人环境还没跑通就开始搞 SLAM，结果出了问题分不清是环境问题还是算法问题，排查起来极其痛苦。先把 talker/listener 跑通，再把 turtlesim 跑通，再写个自己的节点跑通，这三步走完，你对整个工具链就有感觉了。

最后分享一个小技巧：把常用的环境配置、启动命令写成脚本，比如setup_env.sh，每次开机 source 一下。机器人开发涉及的环境变量、工作空间、设备权限很多，手动敲容易漏，脚本化之后省心很多。我现在板子上有十几个这样的脚本，按场景分类，用哪个跑哪个，效率提升明显。

这个环境后续还可以这样扩展：接入真实传感器做数据采集，用 ros2 bag 录包后在 PC 上离线分析；或者把 PC 上的仿真环境通过 DDS 和板子打通，做硬件在环测试。路子很多，关键是基础打牢。