自述文件

英语 | 中文

简介

AgiBot X1 是一款由 AgiBot 开发并开源的高自由度模块化人形机器人。它基于 AgiBot 的开源框架 AimRT 作为中间件，并采用强化学习进行运动控制。

本项目是 AgiBot X1 的配套软件，包含模型推理、平台驱动和软件仿真等多个功能模块。

有关 AimRT 框架的详细教程，请访问 AimRT 官方网站。

软件架构图

有关各模块的详细说明，请参阅 开发指南。

目录结构

.
├── build.sh              # 构建脚本
├── cmake                 # 用于构建依赖项的 CMake 脚本
│   ├── GetAimRT.cmake
│   ├── GetGTest.cmake
│   └── NamespaceTool.cmake
├── CMakeLists.txt        # 顶级 CMakeLists.txt
├── format.sh             # 格式化脚本
├── README.md             # 自述文件
├── doc                   # 开发指南目录
├── src                   # 源代码目录
│   ├── CMakeLists.txt    # 源代码目录的 CMakeLists.txt
│   ├── assistant         # ROS2 仿真及示例项目目录
│   ├── install           # 配置脚本目录
│   ├── module            # 模块目录
│   ├── pkg               # 部署目录
│   └── protocols         # 协议目录
└── test.sh               # 测试脚本

运行说明

启动准备

• 安装 GCC-13。

• 安装 cmake（版本 3.26 或以上）。

• 安装 ONNX Runtime。

sudo apt update
sudo apt install -y build-essential cmake git libprotobuf-dev protobuf-compiler

git clone --recursive https://github.com/microsoft/onnxruntime

cd onnxruntime
./build.sh --config Release --build_shared_lib --parallel

cd build/Linux/Release/
sudo make install

• 安装 ROS2 Humble 并配置环境变量。详细步骤请参考 ROS2 官方网站。

• 安装仿真环境所需的依赖项。

sudo apt install jstest-gtk libglfw3-dev libdart-external-lodepng-dev

• 如果需要对真实机器人进行调试，请安装 Linux 实时内核补丁。

从默认源下载 AimRT 的大量依赖项可能会非常缓慢甚至失败。因此，我们提供了基于 Gitee 源的环境变量 DOWNLOAD_FLAGS，位于 url_gitee.bashrc 中。只需在运行 build.sh 前先执行 source url_gitee.bashrc，并添加 Gitee 源的环境变量参数即可。

完成上述步骤后，在终端中执行以下命令：

source /opt/ros/humble/setup.bash
source url_gitee.bashrc

# 构建
./build.sh $DOWNLOAD_FLAGS

# 测试
./test.sh $DOWNLOAD_FLAGS

启动仿真

启动前，需要连接手柄接收器。

cd build/
./run_sim.sh

在真实机器人上启动

首先导出库路径，只需执行一次。

# 以 root 权限打开 "/etc/ld.so.conf"
sudo vi /etc/ld.so.conf

# 将以下路径添加到 "/etc/ld.so.conf" 的末尾
/opt/ros/humble/lib
{YourProjectSource}/build/install/lib

# 刷新系统环境
sudo ldconfig

准备就绪后，即可启动。

cd build/
./run.sh

操纵杆控制

具体控制说明请参阅 操纵杆控制模块。

许可协议

本项目提供的代码运行在 AimRT 框架之上。这是一份研究性代码，可能会频繁更新，无法适用于所有特定用途。源代码采用 MULAN 许可协议发布。

使用说明

如果您对该仓库有任何疑问或问题，请使用 Issues 功能。

请勿通过电子邮件联系我们，因为我们可能无法及时回复。如果您希望贡献代码，可以直接 fork 该仓库（或作为协作者创建分支），进行修改后向我们提交 pull request。

AgiBot X1 推理工具快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Ubuntu (推荐用于 ROS2 Humble 的版本)
• 编译器: GCC-13
• 构建工具: CMake 3.26 或更高版本
• 中间件: ROS2 Humble
• 推理引擎: ONNX Runtime
• 实时性: 若需在真机调试，需安装 Linux 实时内核补丁 (Preempt-RT)

安装步骤

1. 安装基础依赖与编译工具

sudo apt update
sudo apt install -y build-essential cmake git libprotobuf-dev protobuf-compiler

2. 编译并安装 ONNX Runtime

git clone --recursive https://github.com/microsoft/onnxruntime

cd onnxruntime
./build.sh --config Release --build_shared_lib --parallel

cd build/Linux/Release/
sudo make install

3. 安装 ROS2 Humble 及仿真依赖

请参考 ROS2 官方文档 安装 ROS2 Humble 并配置环境变量。

随后安装仿真环境所需的额外依赖：

sudo apt install jstest-gtk libglfw3-dev libdart-external-lodepng-dev

4. 配置国内镜像源加速（推荐）

由于 AimRT 依赖较多，直接从默认源下载可能缓慢或失败。项目提供了基于 Gitee 源的加速脚本。

在使用构建脚本前，请先加载环境变量配置：

source url_gitee.bashrc

5. 编译项目

加载 ROS2 环境和加速配置后，执行构建和测试：

source /opt/ros/humble/setup.bash
source url_gitee.bashrc

# 构建项目
./build.sh $DOWNLOAD_FLAGS

# 运行测试
./test.sh $DOWNLOAD_FLAGS

基本使用

启动仿真环境

在启动仿真前，请确保已连接手柄接收器。

cd build/
./run_sim.sh

在真机上运行

首次运行前，需将库路径添加到系统动态链接库配置中（仅需执行一次）：

1. 编辑配置文件：

   sudo vi /etc/ld.so.conf
   

2. 在文件末尾添加以下两行路径（请将 {YourProjectSource} 替换为您的实际项目源码路径）：

   /opt/ros/humble/lib
   {YourProjectSource}/build/install/lib
   

3. 刷新系统环境：

   sudo ldconfig
   

完成配置后，启动真机程序：

cd build/
./run.sh

提示：关于手柄控制的具体操作说明，请参阅项目文档中的 doc/joy_stick_module/joy_stick_module.md。