本文档面向首次接触 ATOM01 部署框架的开发者，系统梳理从裸机到可编译状态的完整环境准备流程。内容涵盖系统平台要求、ROS2 Humble 安装、系统依赖库、C++ 与 Python 构建依赖、实时内核升级以及工作空间编译验证。完成本章后，你将拥有一个可成功执行 colcon build 并通过 start_robot.sh 启动机器人的完整开发环境。

Sources: README_CN.md

硬件与系统平台要求

ATOM01 部署框架当前在以下两款主控板上经过充分验证，二者均基于 Ubuntu 22.04 LTS，但在内核版本与实时内核获取方式上存在差异。初学者请根据实际持有的硬件选择对应配置路径。

Sources: README_CN.md

依赖全景与层级关系

本项目的依赖体系可分为四个层级：系统平台层提供操作系统与内核支持；ROS2 中间件层提供通信与构建工具；系统库层提供 fmt、spdlog、Eigen3 等基础 C++ 库以及 pybind11 绑定支持；项目内部层则包含三个功能包（roboto_imu、roboto_motors、roboto_inference）及其内嵌第三方库（ONNX Runtime、cnpy、yaml-cpp）。理解这一层级有助于在编译报错时快速定位缺失依赖的归属。

graph TD
    A[系统平台层<br>Ubuntu 22.04 / 实时内核] --> B[ROS2 中间件层<br>Humble / ament_cmake / colcon]
    B --> C[系统库层<br>fmt / spdlog / Eigen3 / Boost / pybind11]
    C --> D[项目功能包]
    D --> D1[roboto_imu]
    D --> D2[roboto_motors]
    D --> D3[roboto_inference]
    D3 --> E1[内嵌 ONNX Runtime]
    D3 --> E2[内嵌 cnpy]
    D3 --> E3[内嵌 yaml-cpp]
    D2 --> F1[CAN / CANFD 驱动库]
    D1 --> F2[HiPNUC IMU 协议库]

Sources: src/imu/CMakeLists.txt, src/motors/CMakeLists.txt, src/inference/CMakeLists.txt

环境配置总流程

对于初学者，建议严格按照以下顺序执行配置步骤。其中步骤六（实时内核）仅 Orange Pi 5 Plus 用户需要执行，RDK X5 用户可跳过。

flowchart TD
    A[确认硬件平台] --> B[安装 ROS2 Humble]
    B --> C[安装系统依赖库]
    C --> D[安装 ROS2 joy 包与 Python 依赖]
    D --> E[克隆代码并更新子模块]
    E --> F{主控板类型?}
    F -->|Orange Pi 5 Plus| G[安装 5.10 实时内核]
    F -->|RDK X5| H[跳过内核步骤]
    G --> I[配置用户实时优先级权限]
    H --> I
    I --> J[重启设备]
    J --> K[验证 ulimit -r 输出 98]
    K --> L[colcon build 编译工作空间]
    L --> M[source install/setup.bash]
    M --> N[环境就绪]

Sources: README_CN.md

ROS2 Humble 安装

ATOM01 采用 ROS2 Humble 作为中间件，这是整个软件栈的通信基石。请参照 ROS 官方安装指南 完成安装。由于主控板均为 ARM64 架构，请选择 Ubuntu (Debian packages) 路径中的 aarch64 版本进行安装。安装完成后，请确保以下基础命令可正常执行：

source /opt/ros/humble/setup.bash
ros2 --version
colcon --version

若 colcon 命令不存在，说明 ROS2 开发工具未安装，需补充执行 sudo apt install python3-colcon-common-extensions。start_robot.sh 启动脚本会在运行时显式检查 colcon 与 ros2 命令是否存在，缺少任一都会直接报错退出。

Sources: README_CN.md, tools/start_robot.sh

系统工具与 C++ 库安装

部署框架的编译与运行依赖若干系统级工具和 C++ 库。以下命令一次性安装编译工具链、缓存加速、日志库、矩阵运算库以及后台会话管理工具：

sudo apt update && sudo apt install -y \
    build-essential cmake ccache \
    libfmt-dev libspdlog-dev libeigen3-dev \
    libboost-system-dev screen can-utils

各依赖的作用与在项目中的使用位置如下表所示。

Sources: src/imu/package.xml, src/motors/package.xml, src/inference/CMakeLists.txt, src/motors/.github/workflows/build-deb.yml

ROS2 功能包与 Python 依赖

若计划使用手柄控制机器人，需安装 ROS2 的 joy 驱动包。该包负责将游戏手柄的输入转换为 ROS2 的 sensor_msgs/Joy 消息，供推理节点订阅处理。

sudo apt install -y ros-humble-joy

仓库中的 Python 脚本（如 scripts/set_zero.py、scripts/motion_player.py）依赖 yaml 与 numpy，请通过系统包管理器安装：

sudo apt install -y python3-yaml python3-numpy

需要注意的是，scripts/set_zero.py 与 scripts/motion_player.py 在运行时还会加载编译生成的 Python 扩展模块（motors_py、robot_py）。这些模块并非通过 pip 安装，而是 colcon build 之后由 pybind11 生成的 .so 文件，因此必须在编译完成并 source install/setup.bash 后方可正常导入。

Sources: README_CN.md, scripts/set_zero.py, scripts/motion_player.py

代码仓库获取与子模块更新

本项目包含 src/imu 与 src/motors 两个子模块（通过 .gitmodules 管理），因此在克隆后必须执行递归初始化，否则这两个目录将为空，导致后续编译失败。

git clone https://github.com/Roboparty/atom01_deploy.git
cd atom01_deploy
git submodule update --init --recursive

执行完毕后，请检查 src/imu/src 与 src/motors/src 目录下是否已有源文件。若子模块拉取失败（常见于网络受限环境），可尝试手动进入对应目录执行 git submodule update --init，或配置代理后重试。

Sources: README_CN.md

实时内核安装与权限配置

实时性能是机器人控制的关键。本项目推理节点以 200Hz 频率运行，要求操作系统具备实时调度能力。

Orange Pi 5 Plus 用户：仓库 assets 目录下提供了三个预编译的 Debian 包，用于将内核升级为 5.10 实时内核。请在项目根目录执行以下命令：

cd assets
sudo apt install ./*.deb
cd ..

RDK X5 用户：无需执行上述步骤。请直接烧录官方提供的、已预装实时内核的系统镜像。

内核安装完成后，还需为当前用户授予设置实时优先级的权限。使用 sudo nano /etc/security/limits.conf 编辑文件，在末尾追加以下两行。务必将 orangepi 替换为你的实际用户名（RDK X5 默认用户为 sunrise）：

orangepi   -   rtprio   98
orangepi   -   memlock  unlimited

保存后重启设备，执行 ulimit -r 验证。若输出为 98，则代表实时权限配置成功。start_robot.sh 脚本虽未在启动时显式检查 ulimit，但若配置不正确，推理节点在尝试设置实时线程优先级时会失败，导致控制周期抖动。

Sources: README_CN.md, assets/linux-image-legacy-rockchip-rk3588_1.2.0_arm64.deb

工作空间编译

完成前述所有步骤后，即可在工作空间根目录执行编译。--symlink-install 参数使得 Python 脚本与配置文件的修改无需重新编译即可生效，这对调试非常友好。

colcon build --symlink-install

编译成功后，必须 source 当前工作空间的安装环境，否则 ROS2 无法发现本项目的功能包，Python 也无法找到 motors_py、imu_py、robot_py 等扩展模块：

source install/setup.bash

首次完整编译可能需要 5–15 分钟，视主控板性能而定。ccache 会在后续编译中显著缩短时间。若编译过程中出现 ament_cmake 或 rclcpp 未找到的错误，请检查 ROS2 Humble 是否已正确 source。

Sources: README_CN.md, tools/start_robot.sh

安装验证清单

为确保环境配置完整无误，建议在继续后续操作前逐项核对以下检查点。

Sources: tools/start_robot.sh

内嵌第三方库说明

本项目在 src/inference/thirdparty/ 目录下内嵌了三个关键第三方库，无需用户手动安装或通过网络下载：

• ONNX Runtime 1.21.0：用于神经网络推理，提供 x64 与 aarch64 两个预编译版本，CMake 会根据 CMAKE_SYSTEM_PROCESSOR 自动选择。
• cnpy：用于加载 .npy 格式的运动序列文件。
• yaml-cpp 0.8.0：用于解析推理与机器人配置文件。

这种内嵌方式确保了离线环境下的可编译性，同时也锁定了库版本，避免了因上游更新导致的接口不兼容问题。

Sources: src/inference/CMakeLists.txt, src/inference/thirdparty/

下一步

完成环境配置并通过编译后，你已经具备了运行机器人软件的基础条件。建议按照以下顺序继续阅读：

1. 若尚未连接硬件，请前往 硬件连接与 CAN/IMU 映射 了解接线与 udev 规则配置。
2. 若硬件已就绪，请阅读 电机零点标定 完成首次上机前的关键校准步骤。
3. 若希望脱离显示器与网线进行调试，可参考 WiFi 热点与远程调试 开启主控板热点功能。