Skip to content

Feature/h2 integration - #2

Merged
modanesh merged 4 commits into
modanesh:mainfrom
kaidalisohaib:feature/h2-integration
Oct 6, 2026
Merged

modanesh merged 4 commits into
modanesh:mainfrom
kaidalisohaib:feature/h2-integration

Conversation

@kaidalisohaib

Copy link
Copy Markdown
Contributor

Description

This PR introduces full support and locomotion integration for the Unitree H2 humanoid robot (31 active DOFs) across both the Direct RL (HeteroHumanoidEnv) and Manager-Based frameworks.

It extends the heterogeneous humanoid mapping to support robots with a 3-axis active waist (waist_yaw, waist_roll, waist_pitch), resolves kinematic sign conventions for humanoid ankle roll, and introduces a smooth gait-symmetry regulation mechanism to ensure clean, limp-free bipedal walking.


Key Features & Technical Details

  • Unitree H2 Canonical Joint Alignment: Configured a full 31-DOF semantic joint layout in robot_configs.py covering:
    • 12 leg joints (hip pitch/roll/yaw, knee, ankle pitch/roll)
    • 3-axis torso/waist (waist_yaw, waist_roll, waist_pitch)
    • 8 arm joints (shoulder pitch/roll/yaw, elbow)
    • 6 wrist joints (wrist roll/pitch/yaw)
    • 2 head joints (head yaw/pitch)
  • Coherent Lateral Roll Alignment: Fixed a kinematic sign bug in hetero_humanoid_env.py where a generic substring match on "ankle" inadvertently flipped ankle_roll to -1.0 while hip_roll was +1.0. With and "roll" not in jname, both hip and ankle roll consistently share positive coordinate conventions ($+1.0$), ensuring stable lateral balance.
  • Gait Symmetry Regulation: Added feet_air_time_symmetry_biped to the heterogeneous reward pipeline with smooth yaw-command gating. This penalizes asymmetric air-time between the left and right foot during straight walking, eliminating the asymmetric "short-step / long-step" limp without hindering differential stepping during turns.
  • Anti-Exploit Posture Penalties: Expanded dof_pos_limits to actively cover knee hyperextension and waist pitch limits, combined with reinforced waist pitch ($-3.0$) and shoulder pitch ($-0.2$) penalties. This prevents policies from falling into local minima involving hyperextended knees, backward-leaning torsos, or outstretched counterweight arms.
  • Dual Environment Support:
    • Direct RL: Full integration into Isaac-Velocity-Flat-HeteroHumanoid-v0 enabling both single-robot training (--humanoids h2) and heterogeneous co-training alongside Cassie, Digit, G1, and H1.
    • Manager-Based: Complete single-robot baselines (Isaac-Velocity-Flat-H2-v0 and Isaac-Velocity-Rough-H2-v0) with natural-frequency-matched actuator constants and PPO configs.
  • Rough Terrain Infrastructure: Registered Isaac-Velocity-Rough-HeteroHumanoid-v0 with a 187-point raycast height scanner (h2_scanner on the pelvis) and procedural terrain curriculum. (Note: Environment registration and sensory infrastructure are complete; tuning policy convergence on rough terrain will be addressed in a dedicated follow-up).
  • Universal Multi-Robot Grid: Updated scripts/demos/visualize_all_robots.py to include H2, scaling the multi-robot showcase to 13 robots (8 quadrupeds + 5 humanoids).

File Overview

  • source/isaaclab_assets/isaaclab_assets/robots/unitree.py: Articulation configurations (H2_CFG, H2_MINIMAL_CFG) with natural-frequency actuator models and nominal standing pose.
  • source/isaaclab_tasks/isaaclab_tasks/direct/hetero_humanoid/robot_configs.py: Canonical 31-DOF joint slots, base link (pelvis), orientation limits, and illegal contact definitions for H2.
  • source/isaaclab_tasks/isaaclab_tasks/direct/hetero_humanoid/hetero_humanoid_env.py: Corrected roll sign logic, per-robot root height terminations, and height scanner support for H2.
  • source/isaaclab_tasks/isaaclab_tasks/direct/hetero_humanoid/hetero_humanoid_rewards.py: Scalable biped gait-symmetry reward function.
  • source/isaaclab_tasks/isaaclab_tasks/direct/hetero_humanoid/hetero_humanoid_velocity_env_cfg.py: Sensor configurations, action/observation dimension handling, and tuned H2 reward terms.
  • source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/config/h2/: Flat and rough manager-based environment configurations and PPO runner parameters.
  • scripts/tools/download_h2_assets.py: Asset helper to download and verify Unitree H2 USD assets.
  • scripts/demos/visualize_all_robots.py & cli_args.py: Updated visualization demo and CLI argument choices (--humanoids).

Visuals:

Screencast.from.2026-09-21.10-00-26.webm

How to Run

1. Direct RL Environment (Flat Terrain):

# Train Unitree H2 solo:
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
    --task=Isaac-Velocity-Flat-HeteroHumanoid-v0 \
    --humanoids h2 \
    --num_envs 4096 \
    --headless

# Playback / Visualize H2:
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/play.py \
    --task=Isaac-Velocity-Flat-HeteroHumanoid-Play-v0 \
    --humanoids h2 \
    --num_envs 16

2. Manager-Based Environment (Flat Terrain):

# Train:
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
    --task=Isaac-Velocity-Flat-H2-v0 \
    --num_envs 4096 \
    --headless

# Playback / Visualize:
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/play.py \
    --task=Isaac-Velocity-Flat-H2-Play-v0 \
    --num_envs 16

3. Universal Multi-Robot Visualization:

./isaaclab.sh -p scripts/demos/visualize_all_robots.py

Type of change

  • New feature (non-breaking change which adds functionality)

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests/evaluations that prove my fix is effective or that my feature works
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

@github-actions github-actions Bot added documentation Improvements or additions to documentation enhancement New feature or request asset labels Sep 21, 2026
@modanesh
modanesh merged commit 526ffad into modanesh:main Oct 6, 2026
4 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

asset documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants