rl_sar

中文文档

本仓库提供了一个用于机器人强化学习算法的仿真验证与物理部署框架，适用于四足机器人、轮式机器人和人形机器人。“sar”代表“simulation and real”。

同时支持 IsaacGym 和 IsaacSim

同时支持 ROS-Noetic 和 ROS2-Foxy/Humble

同时支持 libtorch 和 onnxruntime

同时支持 Linux 和 macOS（仅支持MuJoCo仿真）

同时支持 Gazebo 和 Mujoco（部分支持）

同时支持 运动 和 舞蹈

支持列表：

[!IMPORTANT] Python版本暂时停止维护，如有需要请使用v2.3，未来可能会重新发布。

[!NOTE] 如果您想使用IsaacLab(IsaacSim)训练策略，请使用robot_lab项目。

robot_lab配置文件joint_names中关节的顺序与本项目中xxx/robot_lab/config.yaml中定义的顺序一致。

欢迎在Github Discussion或Discord中讨论。

[!CAUTION] 免责声明：用户承认，因使用本代码而产生的所有风险及后果均由用户自行承担，作者对任何直接或间接损害不承担任何责任，在操作前必须采取适当的安全措施。

准备工作

克隆仓库

git clone --recursive --depth 1 https://github.com/fan-ziqi/rl_sar.git

更新时

git pull
git submodule update --init --recursive --recommend-shallow --progress

依赖项

安装所需软件包：

# Ubuntu
sudo apt install cmake g++ build-essential libyaml-cpp-dev libeigen3-dev libboost-all-dev libspdlog-dev libfmt-dev libtbb-dev liblcm-dev

# macOS
brew install boost lcm yaml-cpp tbb libomp pkg-config glfw

如果需要使用ROS，请安装以下依赖包：

# ros-noetic (Ubuntu20.04)
sudo apt install ros-noetic-teleop-twist-keyboard ros-noetic-controller-interface ros-noetic-gazebo-ros-control ros-noetic-joint-state-controller ros-noetic-effort-controllers ros-noetic-joint-trajectory-controller ros-noetic-joy ros-noetic-ros-control ros-noetic-ros-controllers ros-noetic-controller-manager

# ros2-foxy (Ubuntu20.04) / ros2-humble (Ubuntu22.04)
sudo apt install ros-$ROS_DISTRO-teleop-twist-keyboard ros-$ROS_DISTRO-ros2-control ros-$ROS_DISTRO-ros2-controllers ros-$ROS_DISTRO-control-toolbox ros-$ROS_DISTRO-robot-state-publisher ros-$ROS_DISTRO-joint-state-publisher-gui ros-$ROS_DISTRO-gazebo-ros2-control ros-$ROS_DISTRO-gazebo-ros-pkgs ros-$ROS_DISTRO-xacro

编译

在项目根目录下执行以下脚本以编译整个项目：

./build.sh

若需单独编译特定包，可追加包名：

./build.sh package1 package2

清理编译结果时，可使用以下命令。这将移除所有已编译的输出文件及创建的符号链接：

./build.sh -c  # 或 ./build.sh --clean

如无需仿真，仅在机器人上运行，可使用CMake进行编译，并禁用ROS（编译后的可执行文件位于cmake_build/bin，库文件位于cmake_build/lib）：

./build.sh -m  # 或 ./build.sh --cmake

如需使用Mujoco模拟器：

./build.sh -mj  # 或 ./build.sh --mujoco

有关详细使用说明，可通过./build.sh -h查看：

用法：./build.sh [选项] [包名...]

选项：
  -c, --clean    清理工作区（移除符号链接和构建产物）
  -m, --cmake    使用CMake构建（仅用于硬件部署）
  -mj,--mujoco   支持MuJoCo模拟器的构建（仅限CMake）
  -h, --help     显示此帮助信息

示例：
  ./build.sh                    # 构建所有ROS包
  ./build.sh package1 package2  # 构建特定ROS包
  ./build.sh -c                 # 清理所有符号链接和构建产物
  ./build.sh --clean package1   # 清理特定包及其构建产物
  ./build.sh -m                 # 使用CMake构建，用于硬件部署
  ./build.sh -mj                # 使用CMake构建，并支持MuJoCo模拟器

[!TIP] 若catkin构建报错：“无法找到可执行文件‘empy’或Python模块‘em’”，请在catkin build之前运行catkin config -DPYTHON_EXECUTABLE=/usr/bin/python3。

运行

在下文中，**<ROBOT>/<CONFIG>**用于表示不同环境，例如go2/himloco和go2w/robot_lab。

运行前，请将训练好的pt模型文件复制到rl_sar/src/rl_sar/policy/<ROBOT>/<CONFIG>，并配置<ROBOT>/<CONFIG>/config.yaml和<ROBOT>/base.yaml中的参数。

仿真

Gazebo

打开终端，启动Gazebo仿真环境：

# ROS1
source devel/setup.bash
roslaunch rl_sar gazebo.launch rname:=<ROBOT>

# ROS2
source install/setup.bash
ros2 launch rl_sar gazebo.launch.py rname:=<ROBOT>

再打开一个新终端，启动控制程序：

# ROS1
source devel/setup.bash
rosrun rl_sar rl_sim

# ROS2
source install/setup.bash
ros2 run rl_sar rl_sim

[!TIP] 重要提示： 启动 Gazebo 后，必须在另一个终端中启动 rl_sim 才能控制机器人。如果没有 rl_sim，机器人将无法被控制，并可能倒下。

如果在 Ubuntu 22.04 中启动 Gazebo 后看不到机器人，则说明机器人是在视野之外初始化的。启动 rl_sim 后，机器人的位置会自动重置。如果机器人在站立过程中倒下，可以使用键盘上的 R 键或游戏手柄上的 RB+Y 组合键来重置机器人。

如果首次启动 Gazebo 时无法打开，需要下载模型包：

git clone https://github.com/osrf/gazebo_models.git ~/.gazebo/models

Mujoco

./cmake_build/bin/rl_sim_mujoco <ROBOT> <SCENE>
# 示例：./cmake_build/bin/rl_sim_mujoco g1 scene_29dof

Docker

Docker 支持用于仿真和部署。详情请参阅 docker/README.md。

# 启动容器
xhost +local:docker  # 在主机上启用 X11
cd docker && docker compose up -d
docker compose exec rl_sar bash

# 容器内 - MuJoCo
./cmake_build/bin/rl_sim_mujoco g1 scene_29dof

# 容器内 - Gazebo
ros2 launch rl_sar gazebo.launch.py rname:=go2
# （新终端）ros2 run rl_sar rl_sim

# 容器内 - 实际机器人
./cmake_build/bin/rl_real_go2 <NETWORK_INTERFACE>

使用手机网页控制（实验性）

安装依赖项：

sudo apt install ros-${ROS_DISTRO}-rosbridge-suite
sudo apt install ros-${ROS_DISTRO}-web-video-server

# 如果您使用的不是 Humble、Jazz 和 Rolling 版本的 ROS2，需要从源代码构建 `web_video_server`
cd <your_ros2_workspace>/src
git clone https://github.com/RobotWebTools/web_video_server.git
cd <your_ros2_workspace>
colcon build --packages-select web_video_server

在机器人上运行 rosbridge 和 web_video_server：

# ROS1
roslaunch rosbridge_server rosbridge_websocket.launch
rosrun web_video_server web_video_server

# ROS2
ros2 launch rosbridge_server rosbridge_websocket_launch.xml
ros2 run web_video_server web_video_server

访问 http://robot.robotsfan.com/，填写 IP 地址和端口，检查右上角的设置页面，然后连接到机器人。进入控制页面后，将屏幕横过来并点击左上角的全屏按钮，即可通过手机浏览器控制机器人！

使用游戏手柄或键盘控制

实际机器人

# ROS1
source devel/setup.bash
rosrun rl_sar rl_real_a1

# ROS2
source install/setup.bash
ros2 run rl_sar rl_real_a1

# CMake
./cmake_build/bin/rl_real_a1

# ROS1
source devel/setup.bash
rosrun rl_sar rl_real_go2 <YOUR_NETWORK_INTERFACE> [wheel]

# ROS2
source install/setup.bash
ros2 run rl_sar rl_real_go2 <YOUR_NETWORK_INTERFACE> [wheel]

# CMake
./cmake_build/bin/rl_real_go2 <YOUR_NETWORK_INTERFACE> [wheel]

# ROS1
source devel/setup.bash
rosrun rl_sar rl_real_g1 <YOUR_NETWORK_INTERFACE>

# ROS2
source install/setup.bash
ros2 run rl_sar rl_real_g1 <YOUR_NETWORK_INTERFACE>

# CMake
./cmake_build/bin/rl_real_g1 <YOUR_NETWORK_INTERFACE>

ssh unitree@192.168.123.18

# Go2：
./cmake_build/bin/rl_real_go2 <YOUR_NETWORK_INTERFACE> [wheel]

# G1(29个自由度)：
./cmake_build/bin/rl_real_g1 <你的网络接口>

sudo touch /etc/systemd/system/rl_sar.service

[Unit]
Description=RL SAR Service
After=network.target

[Service]
Type=simple
User=unitree
WorkingDirectory=/home/unitree/rl_sar
ExecStart=/home/unitree/rl_sar/cmake_build/bin/rl_real_go2 eth0 wheel
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload

sudo systemctl enable rl_sar.service

sudo systemctl disable rl_sar.service

sudo systemctl start rl_sar.service

sudo systemctl stop rl_sar.service

sudo systemctl restart rl_sar.service

sudo journalctl -u rl_sar.service -f

# ROS1
source devel/setup.bash
rosrun rl_sar rl_real_lite3

# ROS2
source install/setup.bash
ros2 run rl_sar rl_real_lite3

# CMake
./cmake_build/bin/rl_real_lite3

ssh firefly@192.168.234.1  # 密码：firefly

vim /opt/export/config/sdk_config.yaml

# ROS1
source devel/setup.bash
rosrun rl_sar rl_real_d1 [本地IP] [机器人IP]

# ROS2
source install/setup.bash
ros2 run rl_sar rl_real_d1 [本地IP] [机器人IP]

# CMake
./cmake_build/bin/rl_real_d1 [本地IP] [机器人IP]

# 示例（使用默认IP）
./cmake_build/bin/rl_real_d1 192.168.234.2 192.168.234.1

训练执行器网络

以下以 A1 为例

1. 在 rl_real_a1.hpp 的顶部取消注释 #define CSV_LOGGER。你也可以修改仿真程序中的相应部分，收集仿真数据用于测试训练过程。
2. 运行控制程序，程序会将所有数据记录到 src/rl_sar/policy/<ROBOT>/motor.csv。
3. 停止控制程序，开始训练执行器网络。请注意，以下路径中省略了 rl_sar/src/rl_sar/policy/。

   rosrun rl_sar actuator_net.py --mode train --data a1/motor.csv --output a1/motor.pt
   

4. 验证训练好的执行器网络。

   rosrun rl_sar actuator_net.py --mode play --data a1/motor.csv --output a1/motor.pt
   

添加你的机器人

以下使用 <ROBOT>/<CONFIG> 来表示你的机器人环境。你只需创建或修改以下文件，且文件名必须与所示完全一致。（可以参考 go2w 中的对应文件作为示例。）

# 你的机器人描述
rl_sar/src/rl_sar_zoo/<ROBOT>_description/CMakeLists.txt
rl_sar/src/rl_sar_zoo/<ROBOT>_description/package.ros1.xml
rl_sar/src/rl_sar_zoo/<ROBOT>_description/package.ros2.xml
rl_sar/src/rl_sar_zoo/<ROBOT>_description/xacro/robot.xacro
rl_sar/src/rl_sar_zoo/<ROBOT>_description/xacro/gazebo.xacro
rl_sar/src/rl_sar_zoo/<ROBOT>_description/config/robot_control.yaml
rl_sar/src/rl_sar_zoo/<ROBOT>_description/config/robot_control_ros2.yaml

# 你的策略
policy/<ROBOT>/base.yaml  # 此文件必须按照物理机器人的关节顺序编写
policy/<ROBOT>/<CONFIG>/config.yaml
policy/<ROBOT>/<CONFIG>/<POLICY>.pt  # 适用于 libtorch，注意需要导出 JIT 格式
policy/<ROBOT>/<CONFIG>/<POLICY>.onnx  # 适用于 onnxruntime

# 机器人状态机
src/rl_sar/fsm_robot/fsm_<ROBOT>.hpp
src/rl_sar/fsm_robot/fsm_all.hpp

# 你的真实机器人代码
rl_sar/src/rl_sar/src/rl_real_<ROBOT>.cpp  # 你可以根据需要自定义 forward() 函数，以适配你的策略

贡献

我们诚挚欢迎社区的贡献，以使这个框架更加成熟并惠及所有人。这些贡献可以是 bug 报告、功能请求或代码提交。

贡献者列表

引用

如果你使用了本代码或其中的部分内容，请引用以下信息：

@software{fan-ziqi2024rl_sar,
  author = {fan-ziqi},
  title = {rl_sar：机器人强化学习算法的仿真验证与物理部署},
  url = {https://github.com/fan-ziqi/rl_sar},
  year = {2024}
}

致谢

本项目使用了以下开源代码仓库中的部分代码：

• unitreerobotics/unitree_sdk2-2.0.0
• unitreerobotics/unitree_legged_sdk-v3.2
• unitreerobotics/unitree_guide
• unitreerobotics/unitree_mujoco
• google-deepmind/mujoco-3.2.7
• mertgungor/unitree_model_control
• Improbable-AI/walk-these-ways
• ccrpRepo/RoboMimic_Deploy
• Deeprobotics/Lite3_Motion_SDK
• chengyangkj/ROS_Flutter_Gui_App

rl_sar 快速上手指南

rl_sar 是一个用于机器人强化学习算法仿真验证与真机部署的框架，支持四足、轮式及人形机器人。"sar"代表 "simulation and real"（仿真与真机）。

1. 环境准备

系统要求

• 推荐系统: Ubuntu 20.04 / 22.04
• 实验性支持: macOS (仅支持 MuJoCo 仿真)
• ROS 版本: ROS Noetic 或 ROS2 Foxy/Humble
• 仿真器: Gazebo Classic 或 MuJoCo (3.2.7+)
• 注意: Python 版本目前暂停维护，如需使用请参考 v2.3 版本。

安装前置依赖

Ubuntu 用户:

sudo apt update
sudo apt install cmake g++ build-essential libyaml-cpp-dev libeigen3-dev libboost-all-dev libspdlog-dev libfmt-dev libtbb-dev liblcm-dev

macOS 用户:

brew install boost lcm yaml-cpp tbb libomp pkg-config glfw

ROS 相关依赖 (根据选择的 ROS 版本执行):

ROS1 Noetic (Ubuntu 20.04):

sudo apt install ros-noetic-teleop-twist-keyboard ros-noetic-controller-interface ros-noetic-gazebo-ros-control ros-noetic-joint-state-controller ros-noetic-effort-controllers ros-noetic-joint-trajectory-controller ros-noetic-joy ros-noetic-ros-control ros-noetic-ros-controllers ros-noetic-controller-manager

ROS2 Foxy/Humble:

# 请确保已设置 $ROS_DISTRO 环境变量 (foxy 或 humble)
sudo apt install ros-$ROS_DISTRO-teleop-twist-keyboard ros-$ROS_DISTRO-ros2-control ros-$ROS_DISTRO-ros2-controllers ros-$ROS_DISTRO-control-toolbox ros-$ROS_DISTRO-robot-state-publisher ros-$ROS_DISTRO-joint-state-publisher-gui ros-$ROS_DISTRO-gazebo-ros2-control ros-$ROS_DISTRO-gazebo-ros-pkgs ros-$ROS_DISTRO-xacro

2. 安装步骤

克隆项目

建议使用递归克隆以获取子模块：

git clone --recursive --depth 1 https://github.com/fan-ziqi/rl_sar.git
cd rl_sar

若后续需要更新代码：

git pull
git submodule update --init --recursive --recommend-shallow --progress

编译项目

在项目根目录执行编译脚本：

全量编译 (默认 ROS 模式):

./build.sh

仅编译特定包:

./build.sh package1 package2

仅用于真机部署 (禁用 ROS，使用 CMake):

./build.sh -m

启用 MuJoCo 仿真支持:

./build.sh -mj

提示: 如果 catkin build 报错 Unable to find either executable 'empy' or Python module 'em'，请先运行 catkin config -DPYTHON_EXECUTABLE=/usr/bin/python3。

3. 基本使用

在使用前，请将训练好的 .pt 模型文件复制到对应目录： rl_sar/src/rl_sar/policy/<ROBOT>/<CONFIG> 并配置 <ROBOT>/<CONFIG>/config.yaml 和 <ROBOT>/base.yaml 中的参数。

以下以 Unitree Go2 机器人配合 Gazebo 仿真为例：

步骤一：启动仿真环境

打开终端，加载环境并启动 Gazebo：

ROS1:

source devel/setup.bash
roslaunch rl_sar gazebo.launch rname:=go2

ROS2:

source install/setup.bash
ros2 launch rl_sar gazebo.launch.py rname:=go2

步骤二：启动控制节点

重要：必须在新开的终端中启动控制程序，否则机器人无法保持平衡。

ROS1:

source devel/setup.bash
rosrun rl_sar rl_sim

ROS2:

source install/setup.bash
ros2 run rl_sar rl_sim

启动后，机器人将自动复位。若机器人摔倒，可按键盘 R 或手柄 RB+Y 重置。

简易控制方式

• 键盘控制:
  • W/S: 前进/后退
  • A/D: 左移/右移
  • Q/E: 旋转
  • Num1-8: 切换不同技能策略 (如基础行走、舞蹈等)
  • Space: 停止所有运动指令
• 手柄控制: 支持 Xbox/PS 系列手柄，映射关系详见项目文档。

真机部署简述

对于真机（如 Unitree A1/Go2），确保电脑与机器人通过网线或 WiFi 连接在同一网段，然后运行对应的可执行文件：

# ROS2 示例
source install/setup.bash
ros2 run rl_sar rl_real_go2 <网络接口名>

# 或 CMake 编译后的直接运行
./cmake_build/bin/rl_real_go2 <网络接口名>

安全警告: 真机操作存在风险，请务必在开阔安全区域测试，并做好急停准备。作者不对因使用代码造成的任何损坏负责。