本页面向首次接触 ATOM01 部署框架的开发者，提供从代码获取到机器人动起来的最小完整路径。阅读完本页后，你将理解项目的模块划分、掌握一键启动流程，并知道在每一步遇到困难时应深入阅读哪一篇文档。如果你已熟悉 ROS2 与嵌入式开发，按照本页流程可在 30 分钟内完成首次上电运行。
Sources: README_CN.md
系统一览
ATOM01 部署框架以 ROS2 Humble 为中间件，采用三模块分离架构：推理节点负责加载 ONNX 策略模型并实时计算关节目标；电机驱动包通过 SocketCAN 与达妙（DM）等电机通信；IMU 驱动包读取机身姿态。三者通过 robot.yaml 统一配置，由 start_robot.sh 一键编译并后台启动。
graph LR
A[手柄 / 指令] -->|ROS2 Topic| B(inference_node<br/>推理节点)
B -->|MIT 控制指令| C[RobotInterface<br/>硬件抽象层]
C --> D[motors 包<br/>CAN 总线]
C --> E[imu 包<br/>串口/CAN]
D --> F[23 个关节电机]
E --> G[HiPNUC IMU]
B --> H[ONNX<br/>策略模型]
上图中，推理节点是中枢神经：它以固定频率（默认 250 Hz）采集 IMU 角速度、机身姿态四元数、关节位置与速度，经观测堆叠后送入 ONNX 模型，输出 23 维动作指令；RobotInterface 将动作映射为 MIT 阻抗控制参数，通过 can0~can3 下发给左腿、右腿+腰、左手、右手四组电机。整个数据流在编译型 C++ 中完成，保证实时性。
Sources: inference_node.cpp, robot_interface.cpp, robot.yaml
项目结构速查
仓库根目录按功能做了清晰隔离。对初学者而言，重点关注以下路径即可：
| 目录 | 作用 | 入门关键文件 |
|---|---|---|
src/inference/ |
推理节点与硬件抽象 | config/robot.yaml（整机配置）、launch/inference.launch.py（启动描述） |
src/motors/ |
电机驱动 C++/Python SDK | README_CN.md（API 速查） |
src/imu/ |
IMU 驱动 C++/Python SDK | README_CN.md（API 速查） |
tools/ |
一键启动与辅助工具 | start_robot.sh（核心启动脚本） |
scripts/ |
Python 示例与标定脚本 | set_zero.py（零点标定）、motion_player.py（动作序列） |
assets/ |
内核包、udev 规则、DDS 配置 | rt_fastdds_profile.xml（实时 DDS 优化） |
graph TD
Root[atom01_deploy] --> Src[src]
Root --> Scripts[scripts]
Root --> Tools[tools]
Root --> Assets[assets]
Src --> Inf[src/inference]
Src --> Mot[src/motors]
Src --> Imu[src/imu]
Inf --> InfConfig[config/robot.yaml]
Inf --> InfLaunch[launch/inference.launch.py]
Tools --> Start[start_robot.sh]
Scripts --> Zero[set_zero.py]
Sources: start_robot.sh, inference.launch.py
快速启动五步走
以下流程假设你已完成主控板（Orange Pi 5 Plus 或 RDK X5）的系统烧录与基础联网。若尚未配置 ROS2 环境或依赖，请先阅读 环境配置与依赖安装。
flowchart TD
A[1. 获取代码并编译] --> B[2. 确认硬件连接]
B --> C[3. 电机零点标定]
C --> D[4. 启动机器人软件]
D --> E[5. 手柄使能与推理]
E --> F{运行正常?}
F -->|是| G[开始探索]
F -->|否| H[查看排查技巧]
H --> I[常见问题排查与调试技巧]
第一步：获取代码并编译
在项目根目录执行以下命令，拉取完整代码（含子模块）并进行首次编译：
git clone https://github.com/Roboparty/atom01_deploy.git
cd atom01_deploy
git submodule update --init --recursive
colcon build --symlink-install
source install/setup.bash
--symlink-install 选项让你在修改 src/ 下的 Python 脚本或配置后无需重新编译即可生效，对调试非常友好。编译成功后，install/ 目录下会生成 setup.bash 以及 Python 扩展模块 imu_py、motors_py、robot_py。
Sources: README_CN.md, start_robot.sh
第二步：确认硬件连接
ATOM01 默认使用 4 路 CAN 总线分别控制四肢，IMU 通过串口连接。首次上电前，请确认：
- 4 个 USB-CAN 适配器已插入主控 USB 3.0 接口，走线顺序决定
can0~can3映射； - IMU 与手柄接收器插在 USB 2.0 接口即可；
- 电机 ID 与
robot.yaml中的motor_id列表一致； - IMU 波特率为
921600，输出频率不低于200 Hz。
为免除“按顺序插拔”的麻烦，推荐部署 udev 规则自动绑定 USB 物理接口与 CAN/串口设备。若你使用 Orange Pi 5 Plus，执行：
sudo cp assets/99-auto-up-devs-orangepi.rules /etc/udev/rules.d/
sudo udevadm control --reload
sudo udevadm trigger
重启后输入 ip a 应能看到 can0~can3 全部处于 UP 状态。更详细的接线图、电机 ID 定义与 udev 规则定制方法，请参考 硬件连接与 CAN/IMU 映射。
Sources: README_CN.md, 99-auto-up-devs-orangepi.rules
第三步：电机零点标定（首次必需）
电机零点标定只需在首次使用或更换/维修电机后执行一次。仓库提供两种标定方式：软件服务标定适合批量写入，脚本标定适合逐关节人工摆位。对初学者推荐后者，更直观且不易出错。
先确认 scripts/config/set_zero.yaml 中的电机 ID、CAN 接口与实际硬件一致，然后执行：
source /opt/ros/humble/setup.bash
source install/setup.bash
python3 scripts/set_zero.py
脚本会依次将每个电机切换到阻尼模式，你只需手动将关节转到机械零位，按 Enter 确认即可；按 空格 跳过当前电机。全部完成后，零点即写入电机 Flash。
注意：
src/inference/config/robot.yaml中的motor_zero_offset第 13 个值（腰部 yaw）默认为2.093。若你是将腰部 yaw 转至限位块处标定，保留该值；若使用打印件固定腰部 yaw 标定，请将其改为0.0。
Sources: set_zero.py, set_zero.yaml, robot.yaml, README_CN.md
第四步：启动机器人软件
一切准备就绪后，在项目根目录执行：
./tools/start_robot.sh
该脚本会自动完成以下操作：
- 设置 Fast DDS 环境变量，加载
assets/rt_fastdds_profile.xml以优化实时通信； - 自动
sourceROS2 环境并执行colcon build --symlink-install； - 在后台
screen会话中启动推理节点inference_node； - 在后台
screen会话中启动手柄节点joy_node； - 验证 DDS 配置与节点发现状态，输出启动报告。
启动成功后，终端会打印绿色成功信息。你可以通过以下命令查看实时日志：
screen -r inference_session # 查看推理节点输出
screen -r joy_session # 查看手柄节点输出
按 Ctrl+A 再按 D 即可 detach 会话，回到原终端。停止所有后台组件：
screen -S inference_session -X quit
screen -S joy_session -X quit
Sources: start_robot.sh
第五步：使能电机与开始推理
软件启动后，机器人处于待机状态。拿起手柄，按以下顺序操作：
| 按键 | 功能 | 时机 |
|---|---|---|
| X | 使能 / 失能电机 | 首次上电必须先按 X 使能 |
| A | 复位电机到默认角度 | 若姿态异常，按 A 恢复站姿 |
| B | 开始 / 暂停推理 | 确认站稳后按 B 启动策略 |
| 右摇杆 | 前后左右移动 | 推理运行中控制平移 |
| LT / RT | 左右旋转 | 推理运行中控制转向 |
推理启动后，机器人会根据 ONNX 策略自主保持平衡并响应手柄速度指令。若需切换策略（如从默认行走切换为 beyondmimic 或 interrupt 模式），修改 src/inference/launch/inference.launch.py 中加载的 YAML 文件名后重新运行 ./tools/start_robot.sh 即可。
Sources: README_CN.md, start_robot.sh, inference.launch.py
首次启动检查清单
在点击启动前，建议逐条核对下表，可显著减少首次上电的报错概率：
| 检查项 | 期望结果 | 验证命令 / 方法 |
|---|---|---|
| ROS2 Humble 已安装 | ros2 --version 有输出 |
ros2 --version |
| 依赖库已安装 | colcon、screen、libeigen3-dev 可用 |
`dpkg -l |
| 工作空间已编译 | install/setup.bash 存在 |
ls install/setup.bash |
| CAN 接口已 UP | can0~can3 显示 state UP |
ip a | grep can |
| IMU 串口可访问 | /dev/ttyUSB0 存在且权限正确 |
ls -l /dev/ttyUSB0 |
| 电机零点已写入 | 各关节机械零位与软件零位一致 | 运行 set_zero.py 并确认 |
robot.yaml 零点偏移正确 |
腰部 yaw 偏移值与标定方式匹配 | 检查 motor_zero_offset 第 13 项 |
| 实时优先级已配置 | ulimit -r 返回 98 |
ulimit -r |
Sources: README_CN.md
常用命令速查
以下命令覆盖了日常调试中最频繁使用的操作，建议保存备查：
| 目的 | 命令 |
|---|---|
| 启动整机软件 | ./tools/start_robot.sh |
| 进入推理日志 | screen -r inference_session |
| 停止推理节点 | screen -S inference_session -X quit |
| 初始化所有电机 | ros2 service call /init_motors std_srvs/srv/Trigger |
| 开始策略推理 | ros2 service call /start_inference std_srvs/srv/Trigger |
| 停止策略推理 | ros2 service call /stop_inference std_srvs/srv/Trigger |
| 清除电机错误 | ros2 service call /clear_errors std_srvs/srv/Trigger |
| 复位关节到默认角度 | ros2 service call /reset_joints std_srvs/srv/Trigger |
Sources: README_CN.md, start_robot.sh
下一步阅读建议
完成首次启动并让机器人动起来后，建议按照以下顺序深入阅读，逐步建立对系统的完整理解：
- 若你尚未完成环境配置或想了解依赖细节 → 环境配置与依赖安装
- 若需重新接线、修改 udev 规则或更换 IMU 波特率 → 硬件连接与 CAN/IMU 映射
- 若对零点标定的两种方法仍有疑问 → 电机零点标定
- 若希望脱离网线、通过 WiFi 热点远程调试 → WiFi 热点与远程调试
- 若想深入理解启动脚本、DDS 配置与推理节点的线程模型 → 启动机器人与推理节点
- 若需查看手柄按键的完整映射与组合操作 → 手柄控制说明
- 若计划通过 ROS2 服务或 Topic 进行二次开发 → ROS2 服务接口调用
- 若倾向使用 Python 快速验证算法或控制单电机 → Python SDK 快速上手
- 若启动后电机无响应、推理闪退或 CAN 报错 → 常见问题排查与调试技巧