部署架构与实时内核配置是足式机器人从仿真环境迁移到物理样机的关键桥梁。本页面向已完成主控板镜像烧录的开发者，系统梳理基于 ROS2 Humble 的模块化软件部署架构，并详细说明 Orange Pi 5 Plus 与 RDK X5 双平台的实时内核配置、DDS 通信调优及硬件自动绑定策略，确保推理控制环路具备毫秒级确定性。Sources: README_CN.md

部署架构总览

整个部署框架采用三层解耦设计：最底层为 Orange Pi 5 Plus 或 RDK X5 主控及其外设，中间层以 ROS2 Humble 作为通信中间件承载 joy_node 与 inference_node，底层驱动则由 roboto_imu 和 roboto_motors 两个独立功能包分别封装 IMU 串口协议与 CAN 总线电机协议。inference_node 内部维护独立的推理线程 inference_thread_ 与控制线程 control_thread_，前者负责 ONNX Runtime 模型前向计算，后者负责将策略输出转换为电机 MIT 指令并通过 RobotInterface 下发。Sources: inference_node.hpp

roboto_imu 与 roboto_motors 均基于 ament_cmake 构建，除了提供 C++ 原生接口外，还通过 pybind11 向外暴露 Python 绑定模块 imu_py 与 motors_py，两者进一步被 robot_py 封装为统一机器人接口。这种设计使得上层既可以用 C++ 节点进行高性能闭环控制，也可以用 Python 脚本完成硬件调试与数据采集。Sources: imu/package.xml, motors/package.xml

下图展示了从物理外设到 ROS2 节点再到驱动库的完整数据链路。inference_node 订阅 /joy 手柄话题或 /cmd_vel 速度指令，经 ONNX Runtime 模型计算后生成关节目标，通过 RobotInterface 调用 roboto_motors 与 roboto_imu 完成电机使能、状态刷新与 IMU 数据读取，同时向外发布 /joint_states 与 /imu 话题。joy_node 则负责将蓝牙或 USB 手柄事件转换为 ROS2 标准 sensor_msgs/Joy 消息。Sources: inference_node.hpp, README_CN.md

graph TB
    subgraph HW ["硬件层"]
        A[Orange Pi 5 Plus / RDK X5]
        B[USB2CAN x4]
        C[HIPNUC IMU]
        D[Gamepad]
    end

    subgraph ROS2 ["ROS2 中间件层"]
        E[joy_node]
        F[inference_node<br/>ONNX Runtime]
        G[RobotInterface]
    end

    subgraph DRV ["驱动库层"]
        H[roboto_motors<br/>CAN总线]
        I[roboto_imu<br/>串口]
    end

    subgraph SDK ["SDK层"]
        J[robot_py]
        K[motors_py]
        L[imu_py]
    end

    A -->|USB 3.0| B
    A -->|USB 2.0| C
    A -->|USB/BT| D
    B -->|can0~can3| H
    C -->|/dev/ttyUSB0| I
    D -->|/joy| E
    E --> F
    F --> G
    G --> H
    G --> I
    H --> K
    I --> L
    G --> J

主控平台适配与实时内核安装

部署框架针对两款主控板进行了充分验证，两者在操作系统版本上一致，但内核版本与实时化方式存在差异。Orange Pi 5 Plus 运行 Ubuntu 22.04 与 5.10 内核，需要手动安装仓库预编译的实时内核 deb 包；RDK X5 同样运行 Ubuntu 22.04，但内核版本为 6.1.83，且官方已提供预装实时内核的镜像，烧录后无需额外操作。Sources: README_CN.md

对于 Orange Pi 5 Plus，实时内核的安装流程为：进入 assets 目录后执行 sudo apt install ./*.deb，即可一次性完成镜像、头文件与设备树的替换；RDK X5 用户则可直接跳过内核安装步骤。无论哪种平台，安装完成后都必须为当前用户在 /etc/security/limits.conf 中追加 rtprio 98 与 memlock unlimited 两项限制，以允许推理节点设置实时调度策略并锁定内存。Sources: README_CN.md

flowchart TD
    A[选择主控板] -->|Orange Pi 5 Plus| B[安装 assets/*.deb<br/>linux-image / headers / dtb]
    A -->|RDK X5| C[烧录预装实时内核的镜像]
    B --> D[配置 /etc/security/limits.conf<br/>rtprio 98 & memlock unlimited]
    C --> D
    D --> E[重启并验证 ulimit -r 输出 98]
    E --> F[导出 DDS 环境变量]
    F --> G[运行 start_robot.sh 启动节点]

配置生效后，重启主控并通过 ulimit -r 验证实时优先级上限。若输出为 98，则表明用户进程已具备申请 SCHED_FIFO 实时调度的权限，这是后续 inference_node 稳定运行在 1 kHz 控制频率的前提。Sources: README_CN.md

DDS 实时通信调优

在 ROS2 默认配置下，DDS 发现与内存动态分配可能引入不可预测的通信抖动。为了将节点间延迟压制在毫秒以内，仓库提供了一份经过裁剪的 Fast DDS 配置文件 rt_fastdds_profile.xml，并通过 start_robot.sh 在启动时注入相关环境变量，确保推理节点与手柄节点始终使用同一套 QoS 与传输策略。Sources: README_CN.md, start_robot.sh

该配置文件的核心策略包括：启用共享内存 SHM 传输以降低同机节点间延迟，保留 UDPv4 作为跨进程回退；通过 interfaceWhiteList 将 DDS 绑定在 127.0.0.1、192.168.13.1 与 192.168.127.10 三个地址，避免多网卡环境下冗余发现带来的抖动；历史内存策略采用 PREALLOCATED_WITH_REALLOC，发布模式设为 SYNCHRONOUS，QoS 选用 BEST_EFFORT 与 VOLATILE，从而在确定性与吞吐量之间取得平衡。Sources: rt_fastdds_profile.xml

硬件自动绑定与现场部署辅助

现场部署时，四路 USB-CAN 适配器与 IMU 的插入顺序直接影响 can0 到 can3 的映射。为避免人工记忆插槽顺序，仓库为 Orange Pi 5 Plus 与 RDK X5 分别提供了 99-auto-up-devs-orangepi.rules 与 99-auto-up-devs-sunrise.rules，通过匹配 USB 拓扑中的 KERNELS 属性将物理接口固定为逻辑接口名，并在设备接入时自动执行 ip link set up 与波特率配置。IMU 串口则通过 SYMLINK+="ttyUSB0" 与 MODE="0666" 统一权限。Sources: 99-auto-up-devs-orangepi.rules, 99-auto-up-devs-sunrise.rules

在无显示器或网线的现场调试场景中，可启用 tools/create_ap 中的热点服务。该工具根据主控板型号选择对应的配置文件，将 WiFi 接口桥接到有线接口，默认 SSID 为 atom，密码为 jujujuju。部署为 systemd 服务后即可实现开机自启，方便开发者通过无线 SSH 登录主控进行远程监控。Sources: README_CN.md, create_ap_orangepi.conf

启动流程与运行验证

tools/start_robot.sh 是整个部署流程的入口脚本。它首先导出 RMW_IMPLEMENTATION=rmw_fastrtps_cpp 等 DDS 环境变量，随后执行 colcon build --symlink-install 编译工作空间，并在两个独立的 screen 会话中分别后台启动 inference_node 与 joy_node。脚本还内嵌了 DDS 配置有效性校验逻辑，通过检查进程环境变量、共享内存文件及节点发现延迟，确保实时通信链路在后台启动前已正确建立。Sources: start_robot.sh

下一步

完成部署架构与实时内核配置后，建议按照以下顺序深入后续章节：IMU驱动与传感器集成 介绍 HIPNUC IMU 的串口驱动与话题发布机制；电机驱动与CAN总线通信 说明达妙电机的 CAN 协议封装与 MIT 控制模式；推理节点与ONNX策略部署 则详细讲解如何将训练好的策略模型转换为 ONNX 并加载到 inference_node 中运行。