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

方案定义：一体式「一机两用」环境

核心结论：RDK X5 机器人本体 = 开发机 + 目标运行机 硬件本体同时承载两大角色：

1. 开发机：预装完整 Ubuntu、ROS2 Humble、QT、Jupter、编译工具链、git、源码、调试工具，支持代码编写、编译、调试；
2. 目标机：所有 ROS 业务节点本地执行，整套机器人程序可脱离上位电脑独立运行。

Windows/PC 电脑仅充当远程终端显示器（VSCode Remote-SSH / MobaXterm SSH），PC 不部署 ROS2、不运行任何机器人业务节点。

一、整体软件栈架构

载体：RDK X5 ARM64 | Ubuntu 22.04 Jammy

plaintext

操作系统 Ubuntu22.04
├── 基础开发工具：git、cmake、gcc、python工具链、colcon编译系统
├── ROS2 Humble（兼容TogetheROS.Bot）
├── ROS全套调试工具：rqt、ros2 cli、jstest、串口调试工具
└── 机器人工作空间 ~/yahboomcar_ros2_ws
    ├─ src/ 完整源代码（可直接修改）
    └─ install/ 编译产出，机器人运行程序

二、三种工作模式，同一套硬件无缝切换

模式 1：开发学习模式（日常编码调试）

适用：学习 ROS2 架构、修改手柄映射、调整运动参数、调试链路故障

工作流程： PC 通过 VSCode 远程 SSH 连接 RDK → 直接在线修改源码 → 局部编译 colcon build --packages-select xxx → 加载环境变量，前台启动 launch → 使用 ros2 node list / ros2 topic echo /rqt 观测完整通信链路

整条遥控数据流（本地闭环，无跨主机网络）

plaintext

USB游戏手柄(RDK本地) → /dev/input/by-id固定设备
        ↓
joy_node → 发布话题 /joy
        ↓
yahboom_joy_M1（解析轴与按键）→ 发布 /cmd_vel
        ↓
Mcnamu_driver_M1（麦轮运动学逆解）→ 串口/CAN
        ↓
STM32底盘控制器 → 电机驱动

模式 2：集成测试模式（整机功能验证）

适用：长时间稳定性测试、场地实车移动测试、功能测试验收
特点： 代码冻结，极少重新编译；可降低日志打印等级减少资源占用； 完整保留调试工具，一旦出现小车异常，立刻 SSH 登录抓取话题数据、日志；

验证重点：手柄热插拔、连续运动、加减速、全向平移、避障联动。

模式 3：独立样机验证模式（模拟成品形态）

适用：检验机器人脱离上位机独立工作能力 配置 systemd 系统服务，上电自动启动整套 ROS 遥控程序； 断开电脑、断开 WiFi，仅依靠本地 USB 手柄控制小车；

⚠️关键区分：该模式依旧属于测试样机环境 ≠ 量产环境 镜像内置编译器、源码、大量开发组件，不能直接用于大规模商用出货。

三、「一机两用」方案核心优势

1. 运行环境 = 开发环境，消除兼容性坑 不存在交叉编译、x86→ARM 架构差异、ABI 不兼容问题。代码调试通过后，运行形态不会发生变化。
2. 学习门槛低，聚焦 ROS 核心思想 无需配置复杂 DDS 跨主机通信，不会出现经典问题：节点互相看不见、网络延迟、DomainID 冲突。 可以全身心理解：节点、话题、发布订阅分布式通信模型。
3. 外设接入简单直接 手柄、激光雷达、摄像头直接接入机器人板卡，不需要通过网络转发硬件原始数据流。
4. 测试不受线缆束缚 实车场地测试可以完全脱离电脑自由移动，适合户外、大范围场地验证。
5. 单人即可完成完整研发闭环：代码修改→编译→真机运行→实车测试。

四、方案固有的短板（明确边界）

1. RDK X5 ARM 平台算力有限，完整编译工作空间速度较慢； ✅对策：使用局部编译，不要每次全量编译 colcon build --packages-select yahboomcar_ctrl

2. 镜像附带源码、编译器、大量调试包，占用存储空间，开机后台进程更多； ✅对策：项目定型准备量产时，基于验证稳定的代码，重新制作最小运行时镜像，剔除所有开发组件。

3. 如果同时运行 SLAM、多目视觉 AI 推理等高负载任务，开发 + 运行程序叠加容易造成 CPU/BPU 满载； ✅对策：重型算法调试阶段，临时切换分布式方案；日常遥控调试维持一体式架构。

五、常见问题标准化解决方案

1. 新开终端执行 ros2 指令找不到节点 / 命令 根因：终端未加载环境 根治：将 ROS、工作空间环境变量写入~/.bashrc，终端自动加载。

2. 反复插拔手柄，设备从js0变成js1导致 joy_node 无法识别 优化 launch 文件，放弃硬编码/dev/input/js0，使用/dev/input/by-id/xxx固定符号链接。

3. 开发阶段日志过多，长期运行占用磁盘 增加环境变量区分运行模式： ROBOT_ENV=dev：全开调试日志；ROBOT_ENV=test：精简日志输出。

六、在项目全生命周期里的定位

1. 前期方案预研：PC Ubuntu + Gazebo 仿真，验证运动学、控制逻辑
2. 中期学习、真机迭代、功能验证：采用本方案【一体式一机两用】
3. 后期样机验收：开启开机自启动，模拟产品独立运行
4. 大规模商用量产：剥离开发环境，构建纯运行时最小镜像（删除源码、编译器、调试工具）

七、方案切换决策点

✅继续使用一机两用一体式：ROS 学习、小车遥控调试、小规模场地测试、算法真机验证

❌建议切换分布式架构：RDK 算力满载，需要运行大型 SLAM、大模型视觉推理

❌禁止直接使用该镜像量产：必须裁剪为轻量化运行环境