项目概览 · 部署

本文档为初学者提供 ATOM01 部署框架的全景式介绍。你将了解这个项目「是什么」「能做什么」以及「由哪些部分组成」，从而建立对整套系统的初步认知，为后续动手实践打下基础。

本仓库是面向 ATOM01 机器人的 ROS2 Humble 部署框架，采用模块化架构，将强化学习策略推理、电机驱动与 IMU 姿态感知解耦为独立的功能包，既支持开箱即用的预训练策略部署，也支持通过 Python SDK 和配置文件进行二次开发。代码已在 Orange Pi 5 Plus 与 RDK X5 主控平台上完成充分验证。

Sources: README_CN.md

系统架构总览

整个系统以 ROS2 作为中间件，在实时内核之上运行。核心数据流遵循「感知 → 推理 → 执行」的闭环：IMU 与关节编码器提供状态观测，推理节点加载 ONNX 策略模型计算动作指令，再通过 CAN/CANFD 总线将 MIT 控制帧下发到 23 个关节电机。手柄信号或 /cmd_vel 速度指令作为高层控制输入，可随时切换策略、启停推理或重置关节。

flowchart TB
    subgraph INPUT["🎮 控制输入"]
        JOY[手柄 Joy 节点]
        CMD["/cmd_vel 指令"]
    end

    subgraph CORE["🧠 推理层 (inference)"]
        INF["推理节点<br/>inference_node"]
        ONNX["ONNX Runtime<br/>策略模型"]
        OBS["观测堆叠<br/>obs_manager"]
    end

    subgraph HAL["⚙️ 硬件抽象层"]
        RI["RobotInterface"]
    end

    subgraph HW["🔧 硬件驱动层"]
        IMU_DRV["IMU 驱动<br/>(HIPNUC 串口)"]
        MOT_DRV["电机驱动<br/>(CAN/CANFD)<br/>DM / EVO / LRO"]
    end

    subgraph ACT["🤖 执行机构"]
        MOT["23 关节电机"]
        IMU_DEV["IMU 传感器"]
    end

    JOY -->|/joy| INF
    CMD -->|/cmd_vel| INF
    INF <-->|状态 / 动作| RI
    RI --> IMU_DRV
    RI --> MOT_DRV
    IMU_DRV --> IMU_DEV
    MOT_DRV --> MOT
    IMU_DEV -->|四元数 / 角速度| RI
    MOT -->|位置 / 速度 / 力矩| RI
    INF <-->|观测 / 动作向量| ONNX
    INF <-->|时序堆叠| OBS

上图展示了系统的三层结构：控制输入层负责接收人为指令；推理与硬件抽象层是系统的决策中枢，其中 RobotInterface 向上提供统一的机器人状态接口，向下屏蔽不同电机与 IMU 的通信细节；硬件驱动层则直接操作总线与物理设备。这种分层设计意味着，如果你只想更换电机型号或接入新的 IMU，通常只需修改驱动层而无需触碰推理逻辑。

Sources: robot_interface.hpp, inference_node.hpp, README_CN.md

项目目录结构

仓库采用「ROS2 Workspace」风格组织。src/ 下包含三个核心功能包，scripts/ 提供标定与辅助脚本，tools/ 包含启动脚本与 WiFi 热点工具，assets/ 存放内核包与 DDS 优化配置。

atom01_deploy/
├── src/                          # ROS2 工作空间源码
│   ├── imu/                      # IMU 驱动包 (roboto_imu)
│   │   ├── src/                  # 协议解析与驱动实现
│   │   ├── include/              # C++ 头文件
│   │   └── ...
│   ├── motors/                   # 电机驱动包 (roboto_motors)
│   │   ├── src/drivers/          # 各品牌电机驱动 (DM/EVO/LRO)
│   │   ├── src/protocol/         # CAN/CANFD 协议层
│   │   └── ...
│   └── inference/                # 推理主包 (roboto_inference)
│       ├── src/                  # 推理节点、RobotInterface、ROS 接口
│       ├── config/               # 机器人参数与策略配置 YAML
│       ├── models/               # ONNX 策略模型
│       ├── motions/              # 预录动作序列 (.npz)
│       └── launch/               # ROS2 启动文件
├── scripts/                      # 辅助 Python 脚本
│   ├── set_zero.py               # 电机零点标定
│   └── motion_player.py          # 动作序列播放
├── tools/
│   ├── start_robot.sh            # 一键启动机器人
│   └── create_ap/                # WiFi 热点配置工具
└── assets/
    ├── *.deb                     # 实时内核包 (Orange Pi)
    └── rt_fastdds_profile.xml    # Fast DDS 优化配置

Sources: README_CN.md

核心功能模块

系统由三个 ROS2 功能包和一个顶层推理节点构成，每个包均可独立编译、独立导出为 Debian 包，也可作为纯 C++ 库在非 ROS 环境下使用。

模块名称	包名	核心职责	关键特性
IMU 驱动	`roboto_imu`	串口通信、IMU 数据解析与姿态输出	当前支持 HiPNUC 系列，波特率默认 `921600`，频率 `500Hz`；通过 `imu_py` 暴露 Python 接口
电机驱动	`roboto_motors`	CAN/CANFD 通信、电机控制指令下发与状态回读	支持 DM、EVO、LRO 三大品牌电机；支持 MIT、位置、速度三种控制模式；通过 `motors_py` 暴露 Python 接口
推理节点	`roboto_inference`	ONNX 模型加载、观测堆叠、实时推理、ROS2 话题与服务	支持多策略切换、动作序列混合、观测时序堆叠；内置 `RobotInterface` 统一封装电机与 IMU
启动脚本	—	编译、配置 DDS、后台启动推理与手柄节点	自动设置 Fast DDS 共享内存传输，使用 `screen` 管理后台会话

三个功能包之间存在明确的依赖关系：roboto_inference 依赖 roboto_motors 与 roboto_imu，而 roboto_motors 与 roboto_imu 彼此独立。这种设计允许你在不编译推理包的情况下，单独使用 Python SDK 控制硬件。

Sources: src/imu/package.xml, src/motors/package.xml, src/inference/package.xml, src/motors/src/motor_driver.cpp, src/imu/src/imu_driver.cpp

硬件平台与机器人配置

本框架面向 ATOM01 机器人平台，具备 23 个关节（6+7+5+5 分布，分别对应左腿、右腿加腰、左手、右手），并采用 4 路 USB-to-CAN 接口连接电机驱动器。默认 CAN 映射关系如下：

CAN 接口	负责部位	电机数量
`can0`	左腿	6
`can1`	右腿 + 腰部	7
`can2`	左手	5
`can3`	右手	5

IMU 通过串口 /dev/ttyUSB0 连接，默认配置为 921600 波特率、500Hz 输出频率。主控平台方面，系统已针对 Orange Pi 5 Plus（内核 5.10）与 RDK X5（内核 6.1）完成适配，推荐使用预装的实时内核镜像以获得稳定的推理时序。

Sources: src/inference/config/robot.yaml, README_CN.md

关键软件特性

除了基础的策略推理与电机控制，框架还内置了多项面向落地部署的高级特性，帮助开发者快速实现稳定运行。

多策略切换与动作序列：推理节点支持同时加载多个 ONNX 策略模型（如行走、起身、舞蹈、受扰恢复），并通过手柄按键或 ROS2 服务进行热切换。motions/ 目录中的 .npz 文件可用于加载预录动作序列，实现模仿学习或混合控制。

观测堆叠与时序建模：obs_manager 负责将历史观测按帧堆叠（默认 frame_stack=10），满足需要时序输入的策略网络（如带注意力编码器的策略）。

Python SDK 三层封装：系统提供 imu_py、motors_py、robot_py 三个 Python 模块。前两者允许单独调试传感器与电机；robot_py.RobotInterface 则通过读取 YAML 配置文件自动初始化整机的电机与 IMU，一行代码即可开始发送动作。

DDS 传输优化：启动脚本 tools/start_robot.sh 自动加载 assets/rt_fastdds_profile.xml，启用 Fast DDS 的共享内存传输与 QoS 配置，显著降低同机节点间的通信延迟，满足实时控制对低抖动的要求。

Sources: src/inference/config/inference.yaml, tools/start_robot.sh, README_CN.md

系统架构总览

项目目录结构

核心功能模块

硬件平台与机器人配置

关键软件特性

推荐阅读路径