# rl_deploy_python

**Repository Path**: nanhaibei/rl_deploy_python

## Basic Information

- **Project Name**: rl_deploy_python
- **Description**: 使用python+ROS2编写的强化学习推理框架
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-06-12
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rl_deploy_python

## 📖 介绍

`rl_deploy_python` 是一个基于 **Python + ROS2 Humble** 的强化学习策略部署框架，专为腿足机器人设计。该框架支持将训练好的强化学习策略（ONNX格式）快速部署到真实机器人或仿真环境中，提供了统一的接口和丰富的工具支持。



### ✨ 主要特性

- 🤖 **多机器人支持**：支持人形机器人（G1, S3）和四足机器人（Go2, L1, Pegasus, ZSL1）
- 🔌 **统一接口**：使用 MIT Cheetah 风格的统一控制接口
- 🚀 **ONNX推理**：高效的 ONNX Runtime 推理引擎
- 🎮 **状态机管理**：灵活的 FSM（有限状态机）控制
- 🛠️ **丰富工具**：包含调试、日志记录、信号测试等实用工具
- 🗺️ **高程图支持**：支持基于高程图的地形感知控制
- ⚙️ **易于配置**：基于 YAML 的参数配置系统

## 📦 支持的机器人平台

### 人形机器人
- ✅ **Unitree G1** - 支持标准控制、高程图控制、AMP控制等多种模式
- ✅ **启灵机器人 S3** - 支持标准控制和 EstNet 控制

### 四足机器人  
- ✅ **Unitree Go2** - 标准四足控制
- ✅ **启灵机器人 L1** - 标准四足控制
- ✅ **智身机器人 ZSL1** - 标准四足控制

## 🔧 安装

### 系统依赖

```bash
# 安装 TOML 解析库
sudo apt-get install python3-tomli

# 安装 ROS 2 Foxglove Bridge（用于可视化）
sudo apt install ros-humble-foxglove-bridge
```

### Python 依赖

```bash
# 安装必要的 Python 包
pip install tabulate onnxruntime numpy
```

### 安装 ROS2 Humble

推荐使用鱼香ROS一键安装脚本：

```bash
wget http://fishros.com/install -O fishros && . fishros
```

### 构建工作空间

#### 📝 依赖包说明

根据您的使用场景，需要克隆不同的包：

| 使用场景 | 必需的包 | 说明 |
|---------|---------|------|
| **🎮 仅运行仿真** | `rl_deploy_python`<br>`mujoco_simulator`<br>`robot_description`<br>`communicate_interface` | 包含控制器、MuJoCo 仿真器、机器人模型描述和消息定义 |
| **🤖 运行实物机器人** | `rl_deploy_python`<br>`communicate_interface` | 仅需控制器和通信接口包（消息定义和话题转换器） |

#### 🎮 仅运行仿真

如果您只想在仿真环境中测试控制器，执行以下步骤：

```bash
# 1. 创建工作空间
mkdir -p ~/rl_das_ws/src
cd ~/rl_das_ws/src

# 2. 克隆必需的仿真包
# 克隆本仓库（强化学习控制器）
git clone https://gitee.com/nanhaibei/rl_deploy_python.git

# 克隆 MuJoCo 仿真器
git clone https://github.com/NanHaibei/mujoco_simulator.git

# 克隆机器人描述文件
git clone https://gitee.com/coralab/robot_description.git

# 克隆通信接口包（消息定义）
git clone https://gitee.com/nanhaibei/communicate_interface.git

# 3. 安装 Python 包（开发模式）
cd rl_deploy_python
pip install -e .
cd ../..

# 4. 编译工作空间
sudo apt install ros-humble-rosidl-generator-dds-idl
colcon build --symlink-install
source install/setup.bash
```

#### 🤖 运行实物机器人

如果您需要在真实机器人上部署，只需要以下 2 个包：

```bash
# 1. 创建工作空间
mkdir -p ~/rl_das_ws/src
cd ~/rl_das_ws/src

# 2. 克隆必需的包
# 克隆本仓库（强化学习控制器）
git clone https://gitee.com/nanhaibei/rl_deploy_python.git

# ⭐ 克隆通信接口包（实物部署必需）
git clone https://gitee.com/nanhaibei/communicate_interface.git

# 3. 安装 Python 包（开发模式）
cd rl_deploy_python
pip install -e .
cd ../..

# 4. 编译工作空间
colcon build --symlink-install
source install/setup.bash
```

> **💡 提示**：
> - **仿真环境**：需要 `mujoco_simulator` 和 `robot_description` 来运行仿真器和加载机器人模型
> - **实物机器人**：不需要仿真器和模型文件，只需控制器和通信接口
> - `communicate_interface` 包含了各机器人的 ROS2 消息定义和话题转换器，仿真和实物都需要

## 🚀 快速开始

### 1. 配置控制器参数

打开 `config/` 目录，每个控制器都有对应的配置文件。以 `G1_controller` 为例：

```yaml
# config/G1/G1_controller_config.yaml
parameters:
  # ONNX 模型路径（相对于 onnx/ 目录）
  onnx_path: "G1/your_policy.onnx"
  
  # 状态机参数
  # 0: 仅行走状态（推荐仿真调试）
  # 1: 根据命令值确定状态（实物部署）
  FSMFlag: 0
  
  # CPU 核心绑定（-1 表示不绑定）
  CPUCore: 6
  
  # 话题名称
  lowStateTopic: "/low_state"
  jointCommandsTopic: "/low_command"
  twistTopic: "/rl_cmd_vel"
  
  # PD 控制参数
  kp: [40.18, 99.10, ...]  # 位置增益
  kd: [2.56, 6.31, ...]    # 速度增益
  
  # 默认关节位置
  defaultPos: [-0.312, 0.00, ...]
```

⚠️ **重要提示**：实物部署前请检查 `FSMFlag` 参数，避免危险发生！

### 2. 启动控制器

#### 方法 1：直接运行节点

```bash
# 启动 G1 控制器
ros2 run rl_deploy_python G1_controller

# 启动 Go2 控制器
ros2 run rl_deploy_python Go2_controller

# 启动 S3 控制器
ros2 run rl_deploy_python S3_controller
```

#### 方法 2：使用 Launch 文件（推荐）

```bash
# 启动 G1 控制器（包含话题转换器）
ros2 launch rl_deploy_python G1_controller.launch.py

# 启动 G1 高程图控制器
ros2 launch rl_deploy_python G1_elevation_controller.launch.py

# 启动 Go2 控制器
ros2 launch rl_deploy_python Go2_controller.launch.py
```


## 🎮 控制器类型说明

### G1 控制器

| 控制器 | 说明 | Launch 文件 |
|--------|------|------------|
| `G1_controller` | 标准强化学习控制器 | `G1_controller.launch.py` |
| `G1_elevation_controller` | 基于高程图的地形感知控制器 | `G1_elevation_controller.launch.py` |
| `G1_amp_controller` | AMP（Adversarial Motion Priors）控制器 | `G1_amp_controller.launch.py` |
| `G1_mix_controller` | 混合控制器 | - |
| `G1_EstNet_DWAQ_controller` | EstNet DWAQ 控制器 | `G1_EstNet_DWAQ_controller.launch.py` |

### S3 控制器

| 控制器 | 说明 | Launch 文件 |
|--------|------|------------|
| `S3_controller` | 标准强化学习控制器 | `S3_controller.launch.py` |
| `S3_controller_real` | 实物机器人控制器 | `S3_controller_real.launch.py` |
| `S3_EstNet_controller` | EstNet 控制器 | `S3_EstNet_controller.launch.py` |
| `S3_slw_controller` | SLW 控制器 | `S3_slw_controller.launch.py` |

### 四足机器人控制器

| 机器人 | 控制器 | Launch 文件 |
|--------|--------|------------|
| Go2 | `Go2_controller` | `Go2_controller.launch.py` |
| L1 | `L1_controller` | `L1_controller.launch.py` |
| Pegasus | `Pegasus_controller` | `Pegasus_controller.launch.py` |
| ZSL1 | `zsl1_controller` | `zsl1_controller.launch.py` |

## 🛠️ 实用工具

### GUI 速度控制器
```bash
ros2 run rl_deploy_python cmd_vel_gui_controller
```

### 手柄转换器
```bash
ros2 run rl_deploy_python js0_converter
```

### 传感器数据记录器
```bash
ros2 run rl_deploy_python sensor_logger
```

### 高程图发布节点
```bash
ros2 run rl_deploy_python elevation_map_publish_node
```

### 扭矩延迟测试
```bash
ros2 run rl_deploy_python torque_delay_test
```

### Chirp 信号生成器
```bash
ros2 run rl_deploy_python chirp_signal
```

## 🎯 部署场景

### 🎮 仿真部署

仿真环境需要以下 **4 个包**：
- ✅ `rl_deploy_python` - 强化学习控制器
- ✅ `mujoco_simulator` - MuJoCo 仿真器
- ✅ `robot_description` - 机器人 URDF/MJCF 模型
- ✅ `communicate_interface` - 消息定义和接口

#### 启动仿真

```bash
# 1. 启动 MuJoCo 仿真器
ros2 launch mujoco_simulator_python simulate.launch.py

# 2. 启动控制器
ros2 launch rl_deploy_python G1_controller.launch.py
```

> **📦 包说明**：
> - `mujoco_simulator` 提供物理仿真环境
> - `robot_description` 包含机器人的 URDF 和 MJCF 模型文件
> - `communicate_interface` 提供统一的消息定义（MIT 风格接口）

### 🤖 实物部署

实物机器人只需要以下 **2 个包**：
- ✅ `rl_deploy_python` - 强化学习控制器
- ⭐ `communicate_interface` - **消息定义和话题转换器（实物必需）**

#### 启动实物机器人

```bash
# 启动控制器（launch 文件会自动启动话题转换器）
ros2 launch rl_deploy_python G1_controller.launch.py
```

> **⚠️ 重要提示**：
> - 实物部署前请在仿真中充分测试
> - 确保 `FSMFlag` 参数设置正确
> - 检查 PD 增益参数是否适合实物
> - 准备好紧急停止措施
> 
> **💡 为什么实物不需要仿真包？**
> - 实物机器人有自己的硬件驱动和状态反馈
> - 不需要 `mujoco_simulator`（仿真器）和 `robot_description`（模型文件）
> - `communicate_interface` 的话题转换器将硬件消息转换为控制器所需的格式

### 🖥️ Foxglove 可视化

```bash
# 启动 Foxglove Bridge
ros2 launch foxglove_bridge foxglove_bridge_launch.xml

# 在浏览器中打开 https://foxglove.dev/studio
# 连接到 ws://localhost:8765
```

## 📁 项目结构

```
rl_deploy_python/
├── config/                    # 配置文件目录
│   ├── G1/                   # G1 机器人配置
│   ├── Go2/                  # Go2 机器人配置
│   ├── S3/                   # S3 机器人配置
│   ├── L1/                   # L1 机器人配置
│   └── ...
├── launch/                    # Launch 文件目录
│   ├── G1/                   # G1 launch 文件
│   ├── Go2/                  # Go2 launch 文件
│   └── ...
├── onnx/                      # ONNX 模型文件目录
│   ├── G1/                   # G1 模型
│   ├── Go2/                  # Go2 模型
│   └── ...
├── rl_deploy_python/          # Python 包源代码
│   ├── base_controller.py    # 基础控制器类
│   ├── FSM.py                # 状态机实现
│   ├── humanoid/             # 人形机器人控制器
│   │   ├── G1/              # G1 控制器实现
│   │   └── S3/              # S3 控制器实现
│   ├── quadruped/            # 四足机器人控制器
│   │   ├── Go2/             # Go2 控制器实现
│   │   ├── L1/              # L1 控制器实现
│   │   ├── Pegasus/         # Pegasus 控制器实现
│   │   └── ZSL/             # ZSL1 控制器实现
│   └── utils/                # 工具函数和辅助节点
│       ├── cmd_vel_gui_controller.py
│       ├── elevation_map_publish_node.py
│       ├── sensor_logger.py
│       └── ...
├── setup.py                   # Python 包安装配置
├── package.xml               # ROS2 包配置
└── README.md                 # 本文件
```

## 🔌 话题接口

### 订阅的话题

| 话题名 | 消息类型 | 说明 |
|--------|---------|------|
| `/low_state` | `unitree_go/LowState` 或 `unitree_hg/LowState` | 机器人低层状态（关节、IMU等） |
| `/rl_cmd_vel` | `geometry_msgs/Twist` | 速度命令 |
| `/elevation_map` | `sensor_msgs/PointCloud2` | 高程图数据（仅高程图控制器） |

### 发布的话题

| 话题名 | 消息类型 | 说明 |
|--------|---------|------|
| `/low_command` | `unitree_go/LowCmd` 或 `unitree_hg/LowCmd` | 关节控制命令 |
| `/mit_low_state` | `mit_msgs/MITLowState` | MIT 风格的状态反馈 |

## ⚙️ 参数说明

### 关键参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `onnx_path` | string | - | ONNX 模型文件相对路径 |
| `FSMFlag` | int | 0 | 状态机模式（0: 仅行走, 1: 多状态） |
| `CPUCore` | int | -1 | CPU 核心绑定（-1: 不绑定） |
| `ShowLog` | int | 1 | 是否显示日志 |
| `defaultPos` | array | - | 默认关节位置 |
| `kp` | array | - | PD 控制位置增益 |
| `kd` | array | - | PD 控制速度增益 |
| `scale` | array | - | 输出缩放因子 |

## 🐛 常见问题

### 1. 找不到 ONNX 文件

**问题**：控制器启动时报错 "ONNX file not found"

**解决方法**：
- 检查 `config/*.yaml` 中的 `onnx_path` 是否正确
- 确保 ONNX 文件存在于 `onnx/` 目录下
- 使用相对路径，例如 `"G1/policy.onnx"`

### 2. 话题连接问题

**问题**：控制器启动后无法接收或发送消息

**解决方法**：
- 使用 `ros2 topic list` 检查话题是否存在
- 使用 `ros2 topic echo` 检查消息内容
- 确认话题转换器已正确启动
- 检查话题名称是否与配置文件一致

### 3. 机器人抖动或不稳定

**问题**：机器人在运行时出现抖动

**解决方法**：
- 检查 PD 增益参数（`kp`, `kd`）是否合适
- 降低输出缩放因子（`scale`）
- 检查默认关节位置（`defaultPos`）是否合理
- 在仿真中先测试，确认稳定后再部署到实物

### 4. CPU 占用过高

**问题**：控制器运行时 CPU 占用率过高

**解决方法**：
- 绑定 CPU 核心：设置 `CPUCore` 参数
- 优化 ONNX 模型：减少模型复杂度
- 使用 GPU 推理（需要安装 `onnxruntime-gpu`）

## 📝 开发指南

### 添加新的机器人支持

1. 在 `rl_deploy_python/humanoid/` 或 `quadruped/` 下创建新的文件夹
2. 创建控制器类，继承自 `BaseController`
3. 在 `config/` 下创建对应的配置文件
4. 在 `launch/` 下创建对应的 launch 文件
5. 在 `setup.py` 中添加入口点
6. 在 `onnx/` 下放置训练好的模型

### 自定义控制器

```python
from rl_deploy_python.base_controller import BaseController

class MyController(BaseController):
    def __init__(self):
        super().__init__('my_controller')
        # 初始化代码
    
    def control_loop(self):
        # 控制循环逻辑
        pass
    
    def inference(self, obs):
        # 推理逻辑
        return action

def main():
    controller = MyController()
    controller.run()
```

## 🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

请查看具体项目的许可证要求。

## 📮 联系方式

- 维护者: nanhaibei
- Email: 371743175@qq.com
- 相关项目：
  - [MuJoCo Simulator](https://github.com/NanHaibei/mujoco_simulator)
  - [Communicate Interface](../communicate_interface)

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！