Skip to content

README.md

Latest commit

 

History

History
118 lines (98 loc) · 5.64 KB

README.md

File metadata and controls

118 lines (98 loc) · 5.64 KB

GentleHumanoid: Whole body Motion Tracking with Compliance - Inference and Deploy

Home Page arXiv Video Online Demo

This is an official implementation of GentleHumanoid, more details please check our Project page.

This repo provides the codebase for deploying GentleHumanoid policies on both simulation and real robots. For training code and data, please check here.

GentleHumanoid learns a universal whole-body motion control policy with upper-body compliance and adjustable force limits, allowing smooth, stable, and safe interactions with humans and objects.

Key Features:

  1. Compliance: Coordinated responses across the shoulder, elbow, and wrist for adaptive motion.
  2. Unified interaction modeling: Handles both resistive and human-guided contact forces.
  3. Safety-aware control: Supports tunable force thresholds to ensure safe human–robot interaction.
  4. Universal and Robust: Demonstrated in simulation and on the Unitree G1, generalizing across diverse motions and interactions.

Try Our Online Demo

online_demo.mp4

TODO

  • Release sim2sim, sim2real code
  • Release pretrained model, that can deploy customized motions to G1
  • Release training code and data
  • Release full pipeline from RGB video to G1 deployment
  • Release locomotion and motion-tracking switching module
  • More upon request

Getting Started

Clone the repo:

git clone https://github.com/Axellwppr/gentle-humanoid
cd gentle-humanoid

Install

  • Create conda environment 
    conda create -n gentle python=3.10
conda activate gentle
  • Install the Unitree SDK2 Python bindings in virtual environment (follow the official Unitree guide)
  • Install Python deps: 
    pip install -r requirements.txt

Tested on Ubuntu 22.04 with Python 3.10

Run Sim2Sim

  1. Start the simulator (state publisher + keyboard bridge): 
    python3 src/sim2sim.py --xml_path assets/g1/g1.xml
    Leave the terminal focused so the keyboard mapping works.
  2. In another terminal launch the high-level controller: 
    python3 src/deploy.py --net lo --sim2sim
  3. Flow:
    • Controller waits in zero-torque mode until it receives the simulated state.
    • Press s in the sim terminal to let the robot move to the default pose.
    • Press a in the sim terminal to start tracking policy
    • See Motion Switching to replay different motions.
    • Use u and d to increase/decrease the force threshold (default 10N).
    • Press x to exit gracefully.

You can double-click a link in the simulation window and Ctrl + right-drag to apply an external force to that link.

sim2sim.mp4

Run Sim2Real

Please read official document before you work on G1.

  1. Power on G1 and connect to your PC.
  2. Turn on Controller, press L2+R2 for debugging mode. Run Sim2Real: 
    python3 src/deploy.py --net <robot_iface> --real
  3. The state machine matches Sim2Sim but with physical remote controller input
    • Zero torque
    • (Press start) → move to default pose
    • Place robot on the ground
    • (Press A) → run the active policy
    • See Motion Switching to replay different motions.
    • Use up and down buttons to increase/decrease the force threshold (default 10N).
    • (Press select) → exit gracefully

⚠️ Please always test motions in Sim2Sim before deploying to real robot.
⚠️ Please do not blindly trust the RL policy. Always have emergency stop (select) ready.

Motion Switching

  • The tracking policy accepts motion change commands while it is active.
  • Open a terminal and run the motion selector: 
    python3 src/motion_select.py
  • Usage tips:
    • Type the motion name or its index (list prints the menu). Press Enter with an empty line to resend the previous choice.
    • r reloads the YAML file if you edit it; q exits the selector.
  • Selection rules:
    • The policy only starts a new motion when the current clip has finished and the robot is in the default clip (or you explicitly request default).
    • Sending default always fades back to the idle pose.
selection.mp4

Acknowledgments