robot_lab

Overview

robot_lab is a RL extension library for robots, based on IsaacLab. It allows you to develop in an isolated environment, outside of the core Isaac Lab repository.

The table below lists all available environments:

Category	Robot Model	Environment Name ()	Screenshot
Quadruped	Anymal D	RobotLab-Isaac-Velocity-Rough-Anymal-D-v0
	Unitree Go2	RobotLab-Isaac-Velocity-Rough-Unitree-Go2-v0
	Unitree B2	RobotLab-Isaac-Velocity-Rough-Unitree-B2-v0
	Unitree A1	RobotLab-Isaac-Velocity-Rough-Unitree-A1-v0
	Deeprobotics Lite3	RobotLab-Isaac-Velocity-Rough-Deeprobotics-Lite3-v0
	Zsibot ZSL1	RobotLab-Isaac-Velocity-Rough-Zsibot-ZSL1-v0
	Magiclab MagicDog	RobotLab-Isaac-Velocity-Rough-MagicLab-Dog-v0
Wheeled	Unitree Go2W	RobotLab-Isaac-Velocity-Rough-Unitree-Go2W-v0
	Unitree B2W	RobotLab-Isaac-Velocity-Rough-Unitree-B2W-v0
	Deeprobotics M20	RobotLab-Isaac-Velocity-Rough-Deeprobotics-M20-v0
	DDTRobot Tita	RobotLab-Isaac-Velocity-Rough-DDTRobot-Tita-v0
	Zsibot ZSL1W	RobotLab-Isaac-Velocity-Rough-Zsibot-ZSL1W-v0
	Magiclab MagicDog-W	RobotLab-Isaac-Velocity-Rough-MagicLab-Dog-W-v0
Humanoid	Unitree G1	RobotLab-Isaac-Velocity-Rough-Unitree-G1-v0
	Unitree H1	RobotLab-Isaac-Velocity-Rough-Unitree-H1-v0
	FFTAI GR1T1	RobotLab-Isaac-Velocity-Rough-FFTAI-GR1T1-v0
	FFTAI GR1T2	RobotLab-Isaac-Velocity-Rough-FFTAI-GR1T2-v0
	Booster T1	RobotLab-Isaac-Velocity-Rough-Booster-T1-v0
	RobotEra Xbot	RobotLab-Isaac-Velocity-Rough-RobotEra-Xbot-v0
	Openloong Loong	RobotLab-Isaac-Velocity-Rough-Openloong-Loong-v0
	RoboParty ATOM01	RobotLab-Isaac-Velocity-Rough-RoboParty-ATOM01-v0
	Magiclab MagicBot-Gen1	RobotLab-Isaac-Velocity-Rough-MagicLab-Bot-Gen1-v0
	Magiclab MagicBot-Z1	RobotLab-Isaac-Velocity-Rough-MagicLab-Bot-Z1-v0

[!NOTE] If you want to run policy in gazebo or real robot, please use rl_sar project.

Discuss in Github Discussion or Discord.

Version Dependency

Installation

• Install Isaac Lab by following the installation guide. We recommend using the conda installation as it simplifies calling Python scripts from the terminal.

• Clone this repository separately from the Isaac Lab installation (i.e. outside the IsaacLab directory):

bash git clone https://github.com/fan-ziqi/robot_lab.git

• Using a python interpreter that has Isaac Lab installed, install the library

bash python -m pip install -e source/robot_lab

• Verify that the extension is correctly installed by running the following command to print all the available environments in the extension:

bash python scripts/tools/list_envs.py

Set up IDE (Optional, click to expand)

To setup the IDE, please follow these instructions:

• Run VSCode Tasks, by pressing Ctrl+Shift+P, selecting Tasks: Run Task and running the setup_python_env in the drop down menu. When running this task, you will be prompted to add the absolute path to your Isaac Sim installation.

If everything executes correctly, it should create a file .python.env in the .vscode directory. The file contains the python paths to all the extensions provided by Isaac Sim and Omniverse. This helps in indexing all the python modules for intelligent suggestions while writing code.

Setup as Omniverse Extension (Optional, click to expand)

We provide an example UI extension that will load upon enabling your extension defined in source/robot_lab/robot_lab/ui_extension_example.py.

To enable your extension, follow these steps:

1. Add the search path of your repository to the extension manager:

   • Navigate to the extension manager using Window -> Extensions.
   • Click on the Hamburger Icon (☰), then go to Settings.
   • In the Extension Search Paths, enter the absolute path to robot_lab/source
   • If not already present, in the Extension Search Paths, enter the path that leads to Isaac Lab's extension directory directory (IsaacLab/source)
   • Click on the Hamburger Icon (☰), then click Refresh.

2. Search and enable your extension:

   • Find your extension under the Third Party category.
   • Toggle it to enable your extension.

Docker setup

Click to expand

Building Isaac Lab Base Image

Currently, we don't have the Docker for Isaac Lab publicly available. Hence, you'd need to build the docker image for Isaac Lab locally by following the steps here.

Once you have built the base Isaac Lab image, you can check it exists by doing:

docker images

# Output should look something like:
#
# REPOSITORY                       TAG       IMAGE ID       CREATED          SIZE
# isaac-lab-base                   latest    28be62af627e   32 minutes ago   18.9GB

Building robot_lab Image

Following above, you can build the docker container for this project. It is called robot-lab. However, you can modify this name inside the docker/docker-compose.yaml.

cd docker
docker compose --env-file .env.base --file docker-compose.yaml build robot-lab

You can verify the image is built successfully using the same command as earlier:

docker images

# Output should look something like:
#
# REPOSITORY                       TAG       IMAGE ID       CREATED             SIZE
# robot-lab                        latest    00b00b647e1b   2 minutes ago       18.9GB
# isaac-lab-base                   latest    892938acb55c   About an hour ago   18.9GB

Running the container

After building, the usual next step is to start the containers associated with your services. You can do this with:

docker compose --env-file .env.base --file docker-compose.yaml up

This will start the services defined in your docker-compose.yaml file, including robot-lab.

If you want to run it in detached mode (in the background), use:

docker compose --env-file .env.base --file docker-compose.yaml up -d

Interacting with a running container

If you want to run commands inside the running container, you can use the exec command:

docker exec --interactive --tty -e DISPLAY=${DISPLAY} robot-lab /bin/bash

Shutting down the container

When you are done or want to stop the running containers, you can bring down the services:

docker compose --env-file .env.base --file docker-compose.yaml down

This stops and removes the containers, but keeps the images.

Try examples

You can use the following commands to run all environments:

RSL-RL:

# Train
python scripts/reinforcement_learning/rsl_rl/train.py --task=<TASK_NAME> --headless

# Play
python scripts/reinforcement_learning/rsl_rl/play.py --task=<TASK_NAME>

CusRL (Experimental):

# Train
python scripts/reinforcement_learning/cusrl/train.py --task=<TASK_NAME> --headless

# Play
python scripts/reinforcement_learning/cusrl/play.py --task=<TASK_NAME>

Running a task with dummy agents (These include dummy agents that output zero or random agents. They are useful to ensure that the environments are configured correctly):

# Zero-action agent
python scripts/tools/zero_agent.py --task=<TASK_NAME>
# Random-action agent
python scripts/tools/random_agent.py --task=<TASK_NAME>

BeyondMimic for Unitree G1:

• Gather the reference motion datasets (please follow the original licenses), we use the same convention as .csv of Unitree's dataset

• Unitree-retargeted LAFAN1 Dataset is available on HuggingFace

• Sidekicks are from KungfuBot
• Christiano Ronaldo celebration is from ASAP.

• Balance motions are from HuB

• Convert retargeted motions to include the maximum coordinates information (body pose, body velocity, and body acceleration) via forward kinematics

bash python scripts/tools/beyondmimic/csv_to_npz.py -f path_to_input.csv --input_fps 60 --headless

• Replaying the motion in Isaac Sim:

bash python scripts/tools/beyondmimic/replay_npz.py -f path_to_motion.npz

• Training and Evaluation

```bash # Train python scripts/reinforcement_learning/rsl_rl/train.py --task=RobotLab-Isaac-BeyondMimic-Flat-Unitree-G1-v0 --headless

# Play python scripts/reinforcement_learning/rsl_rl/play.py --task=RobotLab-Isaac-BeyondMimic-Flat-Unitree-G1-v0 --num_envs 2 ```

Others (Experimental)

• Train AMP Dance for Unitree G1

```bash # Train python scripts/reinforcement_learning/skrl/train.py --task=RobotLab-Isaac-G1-AMP-Dance-Direct-v0 --algorithm AMP --headless

# Play python scripts/reinforcement_learning/skrl/play.py --task=RobotLab-Isaac-G1-AMP-Dance-Direct-v0 --algorithm AMP --num_envs=32 ```

• Train Handstand for Unitree A1

```bash # Train python scripts/reinforcement_learning/rsl_rl/train.py --task=RobotLab-Isaac-Velocity-Flat-HandStand-Unitree-A1-v0 --headless

# Play python scripts/reinforcement_learning/rsl_rl/play.py --task=RobotLab-Isaac-Velocity-Flat-HandStand-Unitree-A1-v0 ```