🤖 roboto_origin_03 Wiki
首页 / 项目根 / 快速开始与仓库结构

本文档面向首次接触 ROBOTO_ORIGIN 的开发者，旨在帮助你理解仓库的组织方式、各模块的职责边界，以及如何以最快速度将代码拿到手并定位到需要的内容。萝博头原型机的代码库采用快照聚合仓库的设计：你当前所在的 roboto_origin 主仓库每日自动拉取各子仓库的最新代码，因此只需一次 git clone 即可获得完整研发资源，无需手动初始化子模块。

Sources: README_cn.md CONTRIBUTING_CN.md

仓库定位：快照聚合机制

roboto_origin 本身不直接接受代码贡献。它扮演的角色是“每日快照相机”——内部包含 modules/ 目录，分别对应五个独立维护的子仓库。这种设计的优势在于：新手无需理解复杂的 Git 子模块操作，克隆后即可获得开箱即用的完整代码集；而各模块的 Issue、PR 与版本迭代则在其对应的独立仓库中进行。如果你计划提交代码改进，请务必前往对应子仓库操作；主仓库会自动同步这些变更。

Sources: README_cn.md CONTRIBUTING_CN.md

五大模块总览与架构关系

整个项目围绕硬件设计 → 运动学描述 → 强化学习训练 → 固件支持 → ROS2 部署这一完整链路展开。下表汇总了各模块的技术栈与核心职责，帮助你根据目标快速定位入口。

模块名称 目录路径 核心技术栈 核心职责 独立仓库
Atom01_hardware modules/Atom01_hardware 机械 CAD、PCB Gerber 机械结构图纸、电路板设计、V1.0/V2.0 迭代 Atom01_hardware
atom01_description modules/atom01_description URDF、MJCF、STL 机器人运动学与动力学描述、仿真用网格与碰撞体 atom01_description
atom01_train modules/atom01_train IsaacLab、rsl_rl、MuJoCo 足式机器人强化学习训练、Sim2Sim 迁移 atom01_train
atom01_firmware modules/atom01_firmware Zephyr、Linux 内核构建 USB2CAN 适配器固件、OrangePi/RDK X5 镜像构建 atom01_firmware
atom01_deploy modules/atom01_deploy ROS2 Humble、C++17、ONNX 推理节点、电机/IMU 驱动、手柄控制、Python SDK atom01_deploy

Sources: README_cn.md README_cn.md

架构关系图

从数据流视角看，五大模块并非简单并列，而是构成了一条“从设计到落地”的链路。硬件与描述文件是训练和部署的物理与数字基础；训练产出的策略模型最终通过部署框架烧录到主控板运行；固件则为底层通信和板卡系统提供支撑。下图展示了模块间的协作关系：

flowchart TB
    subgraph 设计层
        HW[Atom01_hardware<br/>机械与电路设计]
        DESC[atom01_description<br/>URDF/MJCF 模型]
    end

    subgraph 算法层
        TRAIN[atom01_train<br/>IsaacLab 强化学习训练]
    end

    subgraph 嵌入式层
        FIRM[atom01_firmware<br/>USB2CAN / 镜像构建]
    end

    subgraph  runtime层
        DEP[atom01_deploy<br/>ROS2 推理与驱动]
    end

    HW --> DESC
    DESC --> TRAIN
    TRAIN -->|策略模型 .pt / .onnx| DEP
    FIRM -->|CAN 通信 / 系统镜像| DEP
    HW -->|实物硬件| DEP

Sources: README_cn.md modules/atom01_deploy/README_CN.md modules/atom01_train/README_CN.md

物理目录结构详解

克隆仓库后，你的本地目录将与下文结构一致。其中 modules/ 内的五个目录为核心研发资产；assets/ 存放了 BOM 表、演示图片与二维码等资源。各模块内部通常包含中英文双语 README，建议优先阅读 README_cn.md（或 README_CN.md）以获取最贴合中文用户的指引。

roboto_origin/
├── assets/                         # 公共资源：BOM、演示 GIF、二维码
├── modules/
│   ├── Atom01_hardware/            # 硬件设计
│   │   ├── V1.0/                   # 早期机械与分立电路设计（老用户维护）
│   │   └── V2.0/                   # 当前推荐版本：结构强化、单板集成
│   ├── atom01_description/         # 机器人描述文件
│   │   ├── meshes/                 # 视觉与碰撞网格（STL）
│   │   ├── urdf/                   # URDF 运动学描述
│   │   └── mjcf/                   # MuJoCo 仿真配置
│   ├── atom01_train/               # 强化学习训练
│   │   ├── robolab/                # IsaacLab 环境扩展与训练脚本
│   │   └── rsl_rl/                 # 强化学习算法库（rsl_rl 分支）
│   ├── atom01_firmware/            # 固件与镜像
│   │   ├── roboto_usb2can/         # USB 转 CAN 适配器固件
│   │   ├── orangepi-build/         # Orange Pi 5 Plus 镜像构建
│   │   └── x5-rdk-gen/             # RDK X5 镜像构建
│   └── atom01_deploy/              # ROS2 部署框架
│       ├── src/
│       │   ├── imu/                # IMU 驱动包
│       │   ├── motors/             # 电机驱动包
│       │   └── inference/          # 策略推理节点
│       ├── scripts/                # Python 工具脚本（标零、示例）
│       └── tools/                  # 启动脚本、AP 热点配置
├── README_cn.md                    # 中文总览
├── CONTRIBUTING_CN.md              # 贡献指南（快照仓库说明）
├── CODE_OF_CONDUCT_CN.md           # 行为准则
└── LICENSE                         # GPLv3 许可证

Sources: get_dir_structure 输出 get_dir_structure 输出 get_dir_structure 输出 get_dir_structure 输出 get_dir_structure 输出

快速克隆与更新

如果你只想浏览代码或跟随文档进行学习，主仓库已经为你打包好了全部资源。在终端执行以下命令即可：

# 克隆完整仓库（无需额外子模块操作）
git clone https://github.com/Roboparty/roboto_origin.git

# 进入仓库
cd roboto_origin

# 后续每日更新
git pull

进入 modules/ 下对应模块后，请优先阅读该模块内的 README 文件。例如，准备进行强化学习训练时，应阅读 modules/atom01_train/README_CN.md；准备部署到真机时，应阅读 modules/atom01_deploy/README_CN.md。

Sources: README_cn.md

子模块注意事项

虽然主仓库是“开箱即用”的快照，但部分模块内部仍然保留了 Git 子模块结构，以便独立仓库的维护者进行版本管理。具体来说：

对于普通使用者：由于主仓库已经将这些子模块的代码内容合并进快照，通常你不需要执行 git submodule update。但如果你直接克隆了某个独立子仓库（而非 roboto_origin 主仓库），则必须执行以下命令以拉取完整依赖：

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

同理适用于 atom01_train。这一区别在提交 Issue 或 PR 时尤为重要：先确认自己操作的是独立仓库还是主快照仓库。

Sources: modules/atom01_deploy/.gitmodules modules/atom01_train/.gitmodules CONTRIBUTING_CN.md

推荐的阅读路径

萝博头原型机的研发链路较长，初学者无需一次性吃透所有模块。根据大多数社区成员的上手经验，我们推荐以下渐进式路径：

阶段 目标 推荐阅读
阶段 1：了解全貌 建立项目整体认知 项目概览与开源理念 → 本文档
阶段 2：采购与组装 确定硬件版本、采购物料、完成机械组装 BOM清单与采购指南
阶段 3：安全与标定 掌握安全规范、完成电机零位标定 安全操作与零位标定
阶段 4：硬件深化 理解机械结构、电路设计与执行器选型 V2.0机械结构与装配工艺、电路板设计与电气集成
阶段 5：仿真与训练 搭建 IsaacLab 环境、训练 Locomotion 策略 IsaacLab环境搭建与训练流程、基础Locomotion策略训练
阶段 6：真机部署 烧录镜像、配置 ROS2、加载 ONNX 策略 部署架构与实时内核配置、推理节点与ONNX策略部署

如果你已有 ROS2 或强化学习背景，可以跳过熟悉阶段，直接从对应模块深入。

Sources: README_cn.md CONTRIBUTING_CN.md

下一步

现在你已经对仓库结构有了整体认知。根据大多数用户的路径，接下来有两个高频选择：

如果在克隆或目录定位过程中遇到问题，欢迎通过 README 中提供的 QQ 群（1078670917）或各子仓库的 GitHub Issues 进行反馈。

Generated from zread wikis · roboto_origin_03