ROSMASTER-M1（RDK X5 + M1 麦轮底盘）

一体式「一机两用」完整方案文档

一、方案背景

传统 ROS2 机器人开发主流两套模式，存在明显痛点：

1. 分布式分离方案（PC 开发机 + 机器人目标机） PC (X86) 负责代码编译开发，ARM 机器人仅运行程序。

   • 必须掌握 ROS2 DDS 跨主机通信；极易出现 DomainID、防火墙、组播问题，频繁发生 “节点互相看不见”；
   • X86 编译产物在 ARM 平台容易出现库版本、ABI 兼容性异常；
   • 手柄、雷达、相机挂载机器人，上位机难以直接抓取底层设备原始数据；
   • 小车测试依赖网络，断开 WiFi / 网线无法独立运行。

2. 交叉编译量产方案 PC 搭建 ARM 交叉编译链，编译后将程序上传机器人运行。

   • 工具链部署复杂，学习门槛极高；
   • 缺少真机即时调试链路，不适合教学、科研快速原型验证。

3. 用户群体诉求（亚博产品定位人群） ROS 初学者、高校科研团队、单人小型研发团队；需求：一套硬件完成代码编写→编译→真机调试→场地独立实测，尽量减少环境配置、网络通信等无关障碍。

4. 硬件条件成熟 RDK X5 具备 8 核 A55、充足内存、SSD 高速存储，ARM64 Ubuntu22.04 完整系统，算力可以支撑本地编译 ROS2 功能包，不再像低性能开发板只能纯跑程序。

基于以上痛点，亚博原厂镜像采用一体式一机两用架构。

二、方案定位

单台机器人本体（RDK X5）同时承担【开发机】+【目标运行机】双重角色

• RDK X5：代码编辑、本地编译、业务程序运行、硬件驱动访问；
• Windows/X86 PC：仅作为远程终端显示器（VSCode Remote-SSH / MobaXterm），PC 可以不安装 ROS2、不运行任何机器人业务节点；
• 适用阶段：ROS 学习、算法原型开发、真机功能调试、样机场地验证；
• 边界说明：属于研发 / 样机环境，不可直接作为大规模商用量产固件；项目定型后，需要剥离开发工具，制作最小化纯运行镜像。

三、选择一体式「一机两用」方案的核心原因

优势

1. 开发环境 = 运行环境，消除架构兼容风险 代码在 ARM 本机编译、本机运行，不存在 x86→ARM 跨架构编译带来的依赖库、ABI 不兼容问题；调试通过的程序，直接等同于样机运行版本。
2. 大幅降低 ROS2 入门门槛 所有 ROS 节点本地运行，通信闭环在板卡内部。开发者专注学习节点、话题、发布订阅核心模型，不必花费大量精力调试 DDS 跨机网络故障。
3. 硬件外设调试直观便捷 USB 手柄、激光雷达、MIPI 相机直接接入 RDK，程序直接读写/dev/input、串口设备；无需网络转发硬件原始数据流，延迟低、稳定性高。
4. 机器人支持完全脱离 PC 独立运行 调试完成后，断开电脑、断开无线网络，依靠本地 USB 手柄自主工作，支持室内、户外大范围移动实测。
5. 单人可实现完整研发闭环 不需要两台主机、无需搭建复杂局域网分布式环境；单台小车即可完成编码、编译、实车验证全流程。
6. 软件运行架构与小批量样机形态完全一致 研发阶段不需要修改通信架构，后期向样机交付平滑过渡。

客观短板（方案边界）

1. ARM 平台本地编译速度弱于 X86 台式计算机；
2. 镜像预装编译器、源码、全套调试工具，占用存储空间，后台进程更多；
3. 同时运行 SLAM、多目 AI 推理等高负载任务时，容易触发算力瓶颈；

应对：高负载算法调试阶段可临时切换分布式架构。

四、技术基础（软硬件底层支撑）

硬件基础

• 主控：RDK X5 ARM64 8 核 A55，支持本地编译；
• 外设接口：USB3.0（手柄）、UART/CAN（通信 STM32 底盘）、MIPI 相机、雷达接口；
• 底盘：M1 麦轮底盘 + STM32 运动控制板，负责底层电机闭环驱动。

软件基础

1. OS：Ubuntu 22.04 Jammy ARM64（Desktop 完整版）
2. ROS2：Humble Hawksbill（兼容 TogetheROS.Bot），同时完整安装开发包 + 运行时包
3. 完整 ARM 原生工具链：gcc/g++、python、git、cmake、colcon
4. 调试工具栈：rqt 套件、ros2 cli 命令、jstest、串口调试工具
5. 硬件驱动适配：预先适配手柄、雷达、IMU、麦轮底盘通信协议
6. 统一工作空间规范：~/yahboomcar_ros2_ws，分离源码目录与编译产物

五、如何实现一机两用（工程实现机制）

1. 镜像预构建双环境

亚博预制镜像内置两套环境共存：

✅【开发组件】赋予开发机能力：编译器、git、colcon、rqt、源代码

✅【运行组件】赋予目标机能力：ROS2 运行库、底盘驱动、launch 启动脚本

2. 统一工作空间架构（核心设计）

plaintext

~/yahboomcar_ros2_ws
├── src         # 源代码目录（开发阶段修改代码）
├── build       # 编译中间文件
├── install     # 编译产出（ROS运行时加载程序）
└── log

工作流：修改 src 源码 → colcon build本地编译 → install 目录生成可执行文件 → ROS 加载运行。 同一目录同时支撑代码开发和程序运行。

3. 三种运行模式无缝切换（同一硬件、同一套源码）

模式① 开发学习模式（启用完整开发能力）

PC 远程 SSH 连接 RDK，在线编辑源码 → 局部编译 → 前台启动 launch； 全开调试日志，使用ros2 topic、rqt 监控整条通信链路； 标准遥控数据流： USB 手柄 → /dev/input → joy_node → /joy → yahboom_joy_M1 → /cmd_vel → Mcnamu_driver_M1 → STM32 底盘电机

模式② 集成测试模式（开发工具保留，专注整机验证）

代码冻结，极少重新编译；按需降低日志等级；保留调试工具，异常时快速抓取话题数据、日志；用于长时间稳定性、场地实车测试。

模式③ 独立样机验证模式（偏向纯目标机形态）

配置 systemd 系统服务，上电自动启动整套 ROS 遥控程序；断开电脑、WiFi，机器人独立运行。

注意：依旧保留开发工具，属于测试样机，不等同量产产品。

4. 配套标准化工程规范规避常见问题

1. 环境变量自动化：~/.bashrc自动加载 ROS 与工作空间环境，新开终端无需重复 source；
2. 硬件路径固化：launch 文件使用/dev/input/by-id/固定手柄符号链接，防止插拔后 js 编号漂移；
3. 编译优化：强制使用局部编译，缓解 ARM 编译慢问题 colcon build --packages-select yahboomcar_ctrl
4. 环境分级控制：通过环境变量ROBOT_MODE=dev/test控制日志、调试开关；开发模式开启打印，测试模式精简输出。

六、整体系统分层架构

【硬件层】

RDK X5 主控 ├─ 输入外设：USB 游戏手柄、激光雷达、MIPI 摄像头、IMU └─ 输出链路：UART/CAN 总线 → STM32 底盘控制器 → 四个麦轮电机

【操作系统层】

Ubuntu22.04 ARM64 Linux ├─ Linux 内核设备驱动：HID 手柄驱动、串口驱动、USB 驱动 ├─ 系统工具链（开发能力）：gcc、cmake、git、python、colcon └─ 系统服务：网络、权限管理、systemd 自启动管理

【中间件层】

ROS2 Humble（DDS 通信）

• 提供节点通信、话题、参数、日志框架
• 所有节点本地进程通信，不走外部网络 DDS 组播

【业务应用层（一体式双能力）】

开发能力模块

源码目录管理、在线修改、本地编译、调试工具（rqt、ros2 cli）

机器人运行业务节点

1. /joy_node：读取手柄，发布 /joy
2. /yahboom_joy_M1：摇杆解析，发布 /cmd_vel
3. /Mcnamu_driver_M1：麦轮运动学逆解，下发指令到底盘
4. 可选：雷达驱动、IMU 驱动、视觉 AI 节点、SLAM 导航节点

【远程交互层】

PC（Windows/Ubuntu）仅 SSH 远程登录，作为终端显示器，不参与运算。

七、研发全生命周期流转建议

1. 前期预研：PC Ubuntu + Gazebo 仿真，验证运动学、控制逻辑
2. 中期学习、真机迭代、功能验证：一体式一机两用方案（当前方案）
3. 后期样机验收：开启开机自启动，模拟产品独立运行
4. 大规模商用量产：环境分离 基于验证稳定源码，构建最小化纯运行镜像：删除源码、编译器、调试工具；仅保留业务程序、运行依赖，关闭多余账户与调试功能。