cyy/RoboGauge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.1.1-rc2; add README

Browse Source
This commit is contained in:
wty-yy
2026-01-27 20:52:01 +08:00
parent 777f688cfe
commit f98b75bdf9
3 changed files with 409 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
README.md
View File

@@ -1,19 +1,49 @@
# Robot Gauge
本仓库提供一系列**强化学习训练的运动控制模型指标**, 目标是衡量模型的以下信息, 以衡量Sim2Real间隙:
- 鲁棒性: 随机变化地形, 地面类型(环境摩擦、弹性系数), 模型是否能继续稳定控制
- 稳定性: 电机出力是否合理, 长时间运行是否导致电机过热, 是否出现极端关节位置
- 控制稳定性及准确性: 对于速度追踪指令, 能否准确追踪; 对于目标点指令, 到达误差大小
<div align="center">
<h1 align="center">RoboGauge</h1>
<p align="center">
<span>🌎 English</span> | <a href="README_zh.md">🇨🇳 中文</a>
</p>
</div>
能间接地衡量模型部署在真机上的效果, 该流程使用Mujoco进行自动化指标评测, 全部代码基于Python实现.
This repository provides a suite of **motion-control evaluation for reinforcement-learning locomotion policies**. The goal is to measure the following aspects of a policy, so we can partially predict Sim2Real performance and reduce the risk of damaging real hardware:
## 支持机器人
| 机器人型号 | 机器人类型 | 速度追踪指令 |
- **Robustness**: Under randomized terrains and ground types (e.g., friction / restitution), can the policy keep controlling stably?
- **Stability**: Are motor outputs reasonable? Does long-horizon execution risk motor overheating? Does it reach extreme joint positions?
- **Control stability & accuracy**: For velocity-tracking commands, can it track accurately? For target-point commands, how large is the final tracking error?
The evaluation is automated with MuJoCo and implemented fully in Python.
Demo of the evaluation process (4 terrains, 2 difficulty levels):
<table style="width: 100%; text-align: center;">
<tr>
<td><b>Wave</b></td>
<td><b>Slope</b></td>
</tr>
<tr>
<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_wave.gif" width="100%"></td>
<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_slope.gif" width="100%"></td>
</tr>
<tr>
<td><b>Stairs</b></td>
<td><b>Obstacles</b></td>
</tr>
<tr>
<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_stairs.gif" width="100%"></td>
<td><img src="https://raw.githubusercontent.com/robogauge/picture-bed/refs/heads/main/robogague/robogauge_obstaces.gif" width="100%"></td>
</tr>
</table>
## Supported Robots
| Robot | Type | Velocity Tracking |
| - | - | - |
| Unitree go2 | 四足 | ✅ |
| Unitree go2 | Quadruped | ✅ |
## 安装
推荐安装`python=3.8`, 参考[PyTorch官网](https://pytorch.org/get-started/locally/)安装2.0以上任意版本, 安装本仓库
## Installation
Recommended environment: `python=3.8`. Install any PyTorch version >= 2.0 following the [official PyTorch guide](https://pytorch.org/get-started/locally/), then install this repo:
```bash
git clone https://github.com/wty-yy/RoboGauge.git
@@ -21,92 +51,177 @@ cd RoboGauge
pip install -e .
```
## 目录结构
- `robogauge/scripts`: 启动指标测试程序
- `robogauge/tasks`: 定义测试任务
- `robogauge/utils`: 常用工具
## Usage
## 指标/目标/地形
指标的计算方法是通过在环境中发送固定指令及持续时长, 通过Mujoco获取所需参数并计算.
### Run evaluations directly
### 环境参数
#### 域随机化
所有的评测指标都会先配置相应的域随机化参数, 在随机参数下进行评测, 以下为常用的域随机化参数
We provide four evaluation modes: **Single Pipeline**, **Multi Pipeline**, **Level Pipeline**, and **Stress Pipeline**. Compute cost increases gradually, and parallel execution is supported to speed up evaluation. See examples in [CMD.md](./CMD.md).
| 参数名称 | 变量名 | 范围 |
### Asynchronous evaluation during training
Start the evaluation server:
```bash
python robogauge/scripts/server.py
```
Key arguments:
- `--port`: server port (default: `9973`)
- `--num-processes`: total number of evaluation processes (default: `30`)
The client `robogauge/scripts/client.py` submits evaluation requests to the server and returns results. Example:
```python
from robogauge.scripts.client import RoboGaugeClient
# Create client and submit a test task
client = RoboGaugeClient(f"http://127.0.0.1:9973")
task_id = client.submit_task(
model_path=test_payload["model_path"],
step=test_payload["step"],
task_name=test_payload["task_name"],
experiment_name=test_payload["experiment_name"],
wait_for_server=True
)
# Monitor task status and get results
while True:
client.monitor_tasks()
for task_id, resp in client.response_data.items():
scores = resp['results']['scores']
print("[RoboGaugeClient]📊 Scores:")
print(json.dumps(scores, indent=2, ensure_ascii=False))
client.response_data.clear()
time.sleep(5)
```
Example integration: `update_robogauge` in [`go2_rl_gym - on_policy_runner.py`](https://github.com/wty-yy/go2_rl_gym/blob/f9024e807758d497445857a21dce3b266876f375/rsl_rl/rsl_rl/runners/on_policy_runner.py#L252)
> You can launch training with evaluation enabled via `python legged_gym/scripts/train.py --task=xxx --robogauge`. The trainer waits for the evaluation client to be available. Results are saved under `logs/{experiment_name}` and visualized in TensorBoard.
## Metrics / Goals / Terrains
Metrics are computed by sending fixed commands to the environment for a fixed duration, reading required signals from MuJoCo, and aggregating them.
### Environment Parameters
#### Domain Randomization
All evaluations are run with configured domain randomization (DR). Below are commonly used DR parameters:
| Parameter | Variable | Range |
| - | - | - |
| 电机动作执行随机延迟 | `action delay` | `<= RL控制间隔` |
| base负重 | `base mass` | `-1, 0, 1, 2, 3 kg` |
| 地面摩擦力 | `friction` | `0.4, 0.7, 1.0, 1.3, 1.6` |
| Random action execution delay | `action delay` | `<= RL control interval` |
| Base payload mass | `base mass` | `-1, 0, 1, 2, 3 kg` |
| Ground friction | `friction` | `0.4, 0.7, 1.0, 1.3, 1.6` |
#### 地形
1. 支持legged_gym中的部分地形, 包括: `wave, slope, stairs up, stairs down, obstacles, flat`, 除`flat`地形外其他地形可进行难度系数提升
2. 地面类型 (影响接触摩擦系数, 弹性摩擦系数), 包括: 橡胶地, 木地板, 瓷砖地
#### Terrains
### 指标
目前在每个`env.step`后可度量的指标, 所有指标均要求**越大越好**, 目前支持:
1. Supports a subset of terrains from `legged_gym`, including: `wave, slope, stairs up, stairs down, obstacles, flat`. All terrains except `flat` can be evaluated with increasing difficulty levels.
2. Ground material types (affecting contact friction / restitution) include: rubber, wooden floor, tile.
| # | 指标名称 Metrics | 描述 | 包含的超参数 | 归一化系数 | 变化 |
### Metrics
Supported per-step metrics (measured after each `env.step`). **All metrics are normalized so that higher is better**:
| # | Metric | Description | Hyper-parameters | Normalization | Transform |
| - | - | - | - | - | - |
| 1 | `dof_limits` | 关节超出软关节范围的大小 | 软关节范围阈值 | 总关节变化范围 | `1-x` |
| 2 | `lin_vel_err` | 线速度L2误差 | NA | 总线速度指令范围 | `1-x` |
| 3 | `ang_vel_err` | 角速度L2误差 | NA | 总角速度指令范围 | `1-x` |
| 4 | `dof_power` | 电机耗能 | 缩放系数 | 100 | `1-x` |
| 5 | `orientation_stability` | 机身姿态稳定性 (Roll) | NA | NA | `1-x` |
| 6 | `torque_smoothness` | 力矩平滑度 | 缩放系数 | 30 | `1-x` |
| 1 | `dof_limits` | Magnitude of joint excursions beyond soft limits | Soft-limit threshold | Total joint range | `1-x` |
| 2 | `lin_vel_err` | L2 error of linear velocity tracking | NA | Total commanded linear-velocity range | `1-x` |
| 3 | `ang_vel_err` | L2 error of angular velocity tracking | NA | Total commanded angular-velocity range | `1-x` |
| 4 | `dof_power` | Motor energy consumption | Scaling factor | 100 | `1-x` |
| 5 | `orientation_stability` | Body orientation stability (Roll) | NA | NA | `1-x` |
| 6 | `torque_smoothness` | Torque smoothness | Scaling factor | 30 | `1-x` |
### 速度追踪目标
针对在虚实迁移中发现的问题, 整理指标 (metrics) 内容如下:
### Velocity-Tracking Targets
| # | 描述 | 标准化范围 | 对应真机问题 | 地形 |
Based on common issues observed in Sim2Real transfer, we organize metrics and their corresponding real-robot risks as follows:
| # | Description | Normalization | Real-robot issue | Terrain |
| - | - | - | - | - |
| 1 | 关节出现极端值的比例 | 关节范围 | 移动时发生危险的高抬腿行为 | Any |
| 2 | 线速度与指令速度的L2误差 | 最大线速度指令 | 移动时可能无法达到指定速度 | Any |
| 3 | 角速度与指令速度的L2误差 | 最大角速度指令 | 移动时可能无法达到指定速度 | Any |
| 4 | 高速移动/速度对角突变base高度变化 | 固定高度 | 高速移动时机身存在趴低问题, 速度发生对角突变时无法平衡 | 平地 |
| 5 | 高速移动急停稳定性 | 固定用时 | 楼梯上静止时, 关节不稳定 | Any |
| 1 | Ratio of extreme joint values | Joint range | Dangerous high-stepping behavior during motion | Any |
| 2 | L2 error between linear velocity and command | Max linear command | Might fail to reach the requested speed | Any |
| 3 | L2 error between angular velocity and command | Max angular command | Might fail to reach the requested yaw rate | Any |
| 4 | Base-height variation at high speed / diagonal command jumps | Fixed height | Body crouches at high speed; loses balance when diagonal command flips | Flat |
| 5 | Stability after emergency stop at high speed | Fixed duration | Joints become unstable when standing still (e.g., on stairs) | Any |
总结速度最总目标 (goals) 如下:
Summary of velocity-related goals:
| # | 目标名称 Goals | 描述 | reset条件 | 最大reset次数 |
| # | Goal | Description | Reset condition | Max resets |
| - | - | - | - | - |
| 1 | `max_velocity` | 单一维度的最大线/角速度 | 每次执行一个方向的指令, 再急停 | 6 |
| 2 | `diagonal_velocity` | 对角线速度变化 | 每次执行一对对角指令 | 8 |
| 3 | `target_pos_velocity` | 比例差分控制到达目标位置 | 到达目标位置或超时 | 1 |
| 1 | `max_velocity` | Maximum linear / angular speed along a single axis | Run one-direction command then hard stop | 6 |
| 2 | `diagonal_velocity` | Diagonal velocity changes | Execute a pair of diagonal commands | 8 |
| 3 | `target_pos_velocity` | Reach a target position via PD control | Target reached or timeout | 1 |
## 创建新任务
评测任务注册在[`tasks/__init__.py`](./robogauge/tasks/__init__.py)中完成, 包含四个部分:
- BasePipline: 标准Pipline一般无需修改
- MujocoConfig: 仿真器配置文件, 一般无需修改
- BaseGaugeConfig: 指标配置文件, 参考下文创建新指标
- RobotConfig: 机器人配置文件, 参考下文创建新机器人
### 新指标
在`robogauge/tasks/gauge`下创建新的场景、评估指标
### 新机器人
在`robogauge/tasks/robots`下创建新机器人、配置控制模型, 参考`go2`配置
- [go2.py](./robogauge/tasks/robots/go2/go2.py)控制模型, 包含观测构建和动作输出两个函数, 继承`BaseRobot`
- [go2_config.py](./robogauge/tasks/robots/go2/go2_config.py)配置文件, 包含机器人模型xml路径, 控制模型路径, 观测构建参数, 关节映射顺序, 各类缩放系数, 控制频率等
## Create a New Task
## 注意事项
### 导入新机器人/控制模型
1. 在Robot中创建新的机器人xml文件时, 需包含力矩控制`actuator`, 传感器`sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer)`, 参考[`go2.xml`](resources/robots/go2/go2.xml), **注意: actuator的顺序需要和joint顺序一致, 该顺序称为mujoco关节顺序**
2. 控制模型相关位置位于[`RobotConfig.control`](robogauge/tasks/robots/base_robot_config.py)中, 不同仿真中关节顺序可能不同, 需保证`mj2model_dof_indices`从mujoco映射到模型训练的关节次序配置正确 (IsaacGym次序和Mujoco相同), 其他模型配置需保持一致
Tasks are registered in [robogauge/tasks/__init__.py](./robogauge/tasks/__init__.py). A evaluation task consists of four parts:
## 代码架构
### Pipeline逻辑
- **BasePipeline**: the standard pipeline (usually no changes needed)
- **MujocoConfig**: simulator configuration (usually no changes needed)
- **BaseGaugeConfig**: metric configuration (see below to add new metrics)
- **RobotConfig**: robot configuration (see below to add a new robot)
[BasePipeline](./robogauge/tasks/pipeline/base_pipeline.py)用于管理仿真`sim`, 度量器(控制指令, 指标计算)`gauge`, 机器人运控模型`robot`三者的调度, 并包含异常处理, 域随机化, 观测噪声的添加.
### Add a New Metric
Create a new scenario / metric implementation under `robogauge/tasks/gauge`.
### Add a New Robot
Create a new robot implementation and control-model configuration under `robogauge/tasks/robots`. See the `go2` example:
- [go2.py](./robogauge/tasks/robots/go2/go2.py): control wrapper (inherits `BaseRobot`), implements observation construction and action output
- [go2_config.py](./robogauge/tasks/robots/go2/go2_config.py): config including robot XML path, control-model path, observation params, joint mapping order, scaling factors, control rate, etc.
## Notes
### Importing a New Robot / Control Model
1. When creating a new robot XML, it must include torque-control `actuator` and sensors: `sensor - jointpos, jointvel, imu (framequat, gyro, accelerometer)`. See [resources/robots/go2/go2.xml](resources/robots/go2/go2.xml). **Important**: actuator order must match joint order (this is referred to as the MuJoCo joint order).
2. Control-model related configuration is in [robogauge/tasks/robots/base_robot_config.py](robogauge/tasks/robots/base_robot_config.py) under `RobotConfig.control`. Joint orders may differ across simulators; ensure `mj2model_dof_indices` correctly maps MuJoCo joint order to the joint order used during training (IsaacGym uses the same order as MuJoCo). Keep other model configs consistent.
## Code Architecture
## Directory Structure
- `robogauge/`: core Python package
- `robogauge/scripts/`: runnable entry scripts (run evaluation / start server)
- `robogauge/tasks/`: task system (sim config + metrics/scenes + robot + scheduling)
- `robogauge/tasks/pipeline/`: scheduling & execution layer (lifecycle, DR, parallel seeds, aggregation)
- `robogauge/tasks/gauge/`: gauge layer (command generation, metric computation, result aggregation)
- `robogauge/tasks/robots/`: robot adapters (obs/action, joint mapping, model loading, control rate)
- `robogauge/tasks/simulator/`: simulator wrappers / environment interfaces (MuJoCo integration, stepping, state access)
- `robogauge/tasks/custom/`: project-specific extensions and custom tasks
- `robogauge/utils/`: utilities (logging, config/file helpers, stats, math)
- `resources/`: simulation static assets
- `resources/robots/`: robot assets (XML / meshes / textures), organized by robot type
- `resources/terrains/`: terrain assets (e.g., `flat.xml`, slope/stairs/wave/obstacle variants)
- `resources/models/`: policy/model resources
- `assets/`: documentation assets
- `scripts/`: helper shell scripts for running experiments
### Pipeline Logic
[BasePipeline](./robogauge/tasks/pipeline/base_pipeline.py) manages scheduling among the simulator `sim`, the gauge (command generation + metric computation) `gauge`, and the locomotion policy wrapper `robot`. It also includes exception handling, domain randomization, and observation noise.
![robogauge_basepipeline](./assets/robogauge_basepipeline.png)
[MultiPipeline](./robogauge/tasks/pipeline/multi_pipeline.py)用于多进程启动不同seed, 域随机化参数下的`BasePipeline`, 并合并结果文件.
[MultiPipeline](./robogauge/tasks/pipeline/multi_pipeline.py) launches `BasePipeline` in multiple processes across different seeds and DR parameter sets, then merges result files.
[LevelPipeline](./robogauge/tasks/pipeline/level_pipeline.py)对于当前的环境配置, 找到环境地形下模型能稳定通过(三个seed均通过)的最高地形难度.
[LevelPipeline](./robogauge/tasks/pipeline/level_pipeline.py) searches, for the current environment configuration, the highest terrain difficulty that the policy can stably pass (all three seeds pass).
![robogauge_levelpipeline](./assets/robogauge_levelpipeline.png)
## 可能的报错
### Mujoco OpenGL Context Error
## Common Errors
### MuJoCo OpenGL Context Error
```mujoco.FatalError: an OpenGL platform library has not been loaded into this process, this most likely means that a valid OpenGL context has not been created before mjr_makeContext was called```
问题原因: Mujoco在无头模式下无法创建OpenGL上下文
解决方案: 在`robogauge/scripts/run.py`和`robogauge/scripts/server.py`中, 将`os.environ['MUJOCO_GL']`设置为`egl`(GPU)或`osmesa`(CPU, 慢)
Cause: MuJoCo cannot create an OpenGL context in headless mode.
Fix: In `robogauge/scripts/run.py` and `robogauge/scripts/server.py`, set `os.environ['MUJOCO_GL']` to `egl` (GPU) or `osmesa` (CPU, slower).
## Thanks
Thanks to [@windigal](https://github.com/windigal) for editing the videos.