`isaac_ros_unitree_g1_teleop_bringup`#

Source code available on GitHub.

Unitree G1 teleoperation with an XR headset

Overview#

Top-level launch file for Unitree G1 teleoperation combining AGILE locomotion, bimanual inverse kinematics, and finger control. Supports XR teleoperation through Isaac Teleop and RViz interactive markers.

Both simulation and real hardware are supported.

Tutorial: Unitree G1 XR Teleop#

This tutorial walks through running whole-body XR teleoperation on the Unitree G1 humanoid robot. The application combines AGILE locomotion, bimanual inverse kinematics, and finger control, all driven by an XR headset.

You will first run the application in MuJoCo simulation, then deploy on real hardware.

Prerequisites#

Note

This tutorial has been tested and qualified on Jetson AGX Thor and x86_64 for both simulation and real robot deployment.

PICO 4 Ultra or Meta Quest 3 headset (if no XR headset is available, the emulator provided by Isaac Teleop Core can be used instead)
A stable network connection meeting the CloudXR network requirements
Unitree G1 robot powered on and connected to the host machine through Ethernet

Set Up Development Environment#

Set up your development environment by following the instructions in getting started.
(Optional) Install dependencies for any sensors you want to use by following the sensor-specific guides.

Note

We strongly recommend installing all sensor dependencies before starting any quickstarts. Some sensor dependencies require restarting the development environment during installation, which will interrupt the quickstart process.

Set Up Hardware#

Set up the Intel RealSense camera by following the RealSense setup tutorial. For Docker environments, the RealSense setup tutorial adds the realsense Docker image key and rebuilds the Isaac ROS environment with isaac-ros activate --build-local.
Set up the Unitree G1 with the host machine connected to it by following these guides:
- Unitree G1 Developer Guide
- Unitree G1 Quick Development

Build `isaac_ros_unitree_g1_teleop_bringup`#

If your container was built with the gr00t_workflow Docker layer, you can skip step 1

Install and build isaac_ros_unitree_g1_teleop_bringup:

Activate the Isaac ROS environment:
```
isaac-ros activate
```

Install the prebuilt Debian package:

sudo apt-get update

sudo apt-get install -y ros-jazzy-isaac-ros-unitree-g1-teleop-bringup

Install mujoco_ros2_control:

sudo apt-get install -y ros-jazzy-mujoco-ros2-control
source /opt/ros/jazzy/setup.bash

Install Git LFS:

sudo apt-get install -y git-lfs && git lfs install

Clone this repository under ${ISAAC_ROS_WS}/src:

cd ${ISAAC_ROS_WS}/src && \
git clone -b release-4.5 https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_physical_ai.git isaac_ros_physical_ai

Activate the Isaac ROS environment:
```
isaac-ros activate
```

Use rosdep to install the package’s dependencies:

sudo apt-get update

rosdep update && rosdep install --from-paths ${ISAAC_ROS_WS}/src/isaac_ros_physical_ai/isaac_ros_unitree_g1_teleop_bringup --ignore-src -y

Build the package from source:

cd ${ISAAC_ROS_WS}/ && \
   colcon build --symlink-install --packages-up-to isaac_ros_unitree_g1_teleop_bringup --base-paths ${ISAAC_ROS_WS}/src/isaac_ros_physical_ai/isaac_ros_unitree_g1_teleop_bringup

Source the ROS workspace:

Note

Make sure to repeat this step in every terminal created inside the Isaac ROS environment. Because this package was built from source, the enclosing workspace must be sourced for ROS to be able to find the package’s contents.
```
source install/setup.bash
```

Run CloudXR Server#

Whitelist firewall ports for CloudXR.

CloudXR requires certain network ports to be open. Depending on your firewall configuration, you may need to open them manually. For Quest and PICO headsets (WebXR Client), at the minimum, the CloudXR runtime and WebSocket Secure proxy ports must be open. If ufw is enabled, run:
```
sudo ufw allow 47998/udp
sudo ufw allow 49100,48322/tcp
```
If you are running the WebXR client from source and ufw is enabled, also open the web server ports:
```
sudo ufw allow 8080,8443/tcp
```
Start the CloudXR runtime. Be sure to review and accept the EULA:
```
python3 -m isaacteleop.cloudxr
```
Tip

To accept the EULA prompt in non-interactive settings, pass the flag:
```
python3 -m isaacteleop.cloudxr --accept-eula
```
In a new terminal, activate the Isaac ROS environment:
```
isaac-ros activate
```
Activate the CloudXR environment:
```
source ~/.cloudxr/run/cloudxr.env
```
Connect the XR headset to the teleop server. In your headset’s browser, open the CloudXR web client and follow the headset connection guide.

Note

If the CloudXR runtime is running on Thor, make sure to set the Video Codec to H.264, otherwise the headset will fail to connect.

Warning

The world frame of the headset is defined as the position of the headset and controllers at the moment of connection. Stand still and face the robot before connecting to establish a consistent world frame. To reset the world frame, disconnect and reconnect the headset while stationary.

Launch the application#

Launch the teleop application:
ros2 launch isaac_ros_unitree_g1_teleop_bringup unitree_g1_teleop.launch.py \
    hardware_type:=mujoco input_mode:=teleop
This opens the MuJoCo viewer with the G1 robot. The virtual gantry holds the robot upright during startup. Press G to toggle the gantry on/off, and use [ / ] to shorten or lengthen the rope. It is recommended to disable the gantry once the robot is stable. The robot may oscillate at startup and will only stabilize once the controller is active.

Note

In simulation, blend_ratio defaults to 1.0 so the policy is active immediately.
With the controllers in your hands, start moving them. You should see the robot’s arms track your movements in the MuJoCo viewer.
Warning

Before operating on real hardware:

Ensure the working area is free of any persons or other potential hazards.

Always start with blend_ratio at 0.0. You can increase from 0.0 to 1.0 in a single step since the ratio is smoothed internally.

Ensure the waist yaw joint is close to zero before launching. It is uncontrolled and will be held at its current position, so a rotated torso can degrade balance.

Have the disable command ready (refer to the disable step below).
Set up the network — clone isaac_ros_robots and run the setup script outside the docker container on the host machine:
cd ${ISAAC_ROS_WS}/src && \
 git clone -b release-4.5 https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_robots.git isaac_ros_robots
Run the network setup script:
${ISAAC_ROS_WS}/src/isaac_ros_robots/isaac_ros_robots_tools/scripts/setup_network.py
The script will interactively guide you through the network setup. Make sure to select the network interface that is physically connected to the G1 robot.
Launch the application:
ros2 launch isaac_ros_unitree_g1_teleop_bringup unitree_g1_teleop.launch.py \
    hardware_type:=real \
    input_mode:=teleop \
    network_interface:=<your_interface>
Replace <your_interface> with the network interface you selected in the previous step.
Note
The application starts but the robot will not move because blend_ratio defaults to 0.0 on real hardware.
To verify that XR commands are reaching the controller:
ros2 topic echo /xr_teleop/ee_poses
ros2 topic echo /xr_teleop/root_twist
To disable the robot, set the blend ratio back to zero:
ros2 param set /safety_controller blend_ratio 0.0
Keep this command in your shell history so you can execute it quickly if something goes wrong.
Enable the robot by setting the blend ratio:
ros2 param set /safety_controller blend_ratio 1.0
The robot will start tracking your hand movements.

Note

After several minutes of operation, the G1 hands may lower due to temperature limits. Allow the robot to cool down before resuming

Warning

When operating real robot hardware, ensure the robot is stopped (blend_ratio set to 0.0) before disconnecting the teleop application.

Controller Reference#

The PICO 4 Ultra headset and Meta Quest 3 include two handheld controllers. The following table summarizes what each input does during teleoperation:

Input	Action
Left joystick	Move the robot: up = forward, down = backward, left = strafe left, right = strafe right
Right joystick — left / right	Rotate the robot in place (yaw)
Controller motion (6-DOF)	The end-effector pose tracks the physical controller; moving and rotating the controller moves the robot’s hand correspondingly
Triggers (each controller has two)	Open and close the finger joints of the tri-finger hand

API#

Usage#

ros2 launch isaac_ros_unitree_g1_teleop_bringup unitree_g1_teleop.launch.py

Launch Arguments#

Launch Argument	Type	Default	Description
`hardware_type`	`string`	`mujoco`	Hardware platform. Options: `mujoco` (simulation), `real` (physical robot).
`input_mode`	`string`	`teleop`	Input source. Options: `teleop` (XR device through CloudXR), `markers` (RViz interactive markers).
`network_interface`	`string`	`eno1`	Network interface for G1 communication. Only used when `hardware_type:=real`.
`enable_viewer`	`bool`	`true`	Enable MuJoCo GUI viewer. Only used when `hardware_type:=mujoco`.
`use_rviz`	`bool`	`false`	Enable RViz visualization. Automatically set to `true` when `input_mode:=markers`.
`use_foxglove`	`bool`	`false`	Start Foxglove bridge for remote monitoring.

ROS Topics#

Topics depend on the input_mode launch argument. In teleop mode:

ROS Topic	Interface	Description
`/xr_teleop/ee_poses`	`geometry_msgs/PoseArray`	End-effector (wrist) poses from XR headset
`/xr_teleop/root_twist`	`geometry_msgs/TwistStamped`	Root velocity command from XR headset
`/xr_teleop/finger_joints`	`sensor_msgs/JointState`	Retargeted finger joint angles from XR hand tracking
`/xr_teleop/controller_data`	`std_msgs/ByteMultiArray`	Raw controller state encoded as msgpack (button, trigger, thumbstick, and pose data)

In markers mode:

ROS Topic	Interface	Description
`/ik_controller/reference_pose`	`geometry_msgs/PoseArray`	End-effector poses published by the RViz interactive marker node

ROS Parameters#

Parameter	Node	Type	Default	Description
`blend_ratio`	`/safety_controller`	`double`	`0.0` (real), `1.0` (sim)	Policy activation level (0.0–1.0). Dynamically adjustable at runtime.

Troubleshooting#

Test Without an XR Headset (Interactive Markers Mode)#

If the XR headset is unavailable or you want to isolate whether an issue is with XR or the robot itself, launch with input_mode:=markers:

ros2 launch isaac_ros_unitree_g1_teleop_bringup unitree_g1_teleop.launch.py \
    input_mode:=markers

RViz opens automatically with 6-DOF interactive markers for each wrist. The /ik_controller/reference_pose topic replaces the /xr_teleop/ee_poses topic in this mode.

Publish to /cmd_vel to start the controller:

ros2 topic pub --rate 10 /cmd_vel geometry_msgs/msg/Twist \
    "{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

In the RViz Displays panel, find the IK Target Marker display and set its Interactive Markers Namespace to /ik_controller_marker. You can then drag the wrist markers to command the arms.

Remote Monitoring with Foxglove#

If visualization through Foxglove is desired, add use_foxglove:=true to any launch command to start the Foxglove bridge:

ros2 launch isaac_ros_unitree_g1_teleop_bringup unitree_g1_teleop.launch.py \
    use_foxglove:=true

Refer to Foxglove Setup for instructions on connecting Foxglove Studio.

isaac_ros_unitree_g1_teleop_bringup#