How yanjieze/twist works
Project Type and Purpose
• TWIST is a full-stack robotics imitation‐learning project. It includes:
• Offline training pipelines for “teacher” and “student” policies using reinforcement learning (RL) and behavior cloning.
• A simulation environment powered by NVIDIA Isaac Gym (via the legged_gym package).
• A pose‐retargeting library (pose/poselib).
• Deployment scripts to run the trained student policy in sim2sim (simulation) and sim2real (Unitree G1 robot) modes.
• A two‐layer control architecture: high‐level motion server (teleop or prerecorded motion) and low‐level controller server (the RL policy).
• Inter‐process communication via Redis.
File‐Structure Analysis
• Top‐level modules:
• assets/ — URDFs, XML robot descriptions, meshes, pretrained motion tracker.
• deploy_real/ — scripts for sim2sim and sim2real (high‐level and low‐level servers).
• legged_gym/ — the Isaac Gym RL environment and training scripts.
• pose/ — pose‐processing and retargeting library.
• rsl_rl/ — core RL algorithms (PPO, DAgger, RMA, etc.), network modules, runners, storage.
• shell scripts: training (train_teacher.sh, train_student.sh), export (to_jit.sh), play (play_student.sh, play_teacher.sh).
• unitree_g1.md — instructions specific to real‐robot deployment.
Key README Insights
• Two‐stage training: teacher (RL), then student (RL+BC).
• Two‐layer runtime:
a. High‐Level Motion Server (server_high_level_motion_lib.py) publishes motion targets via Redis.
b. Low‐Level Controller Server (server_low_level_g1_sim.py / server_low_level_g1_real.py) subscribes to Redis, runs the policy (JIT‐exported PyTorch model) in sim or real hardware.
• External dependencies: Redis[hiredis], Isaac Gym, MuJoCo, Unitree SDK, pyttsx3, flask, hydra-core, etc.
a. Main Components
1. Data & Assets
• Motion dataset (root path set in legged_gym/motion_data_configs/twist_dataset.yaml)
• URDF/XML & meshes (assets/)
• Pretrained motion tracker (assets/twist_general_motion_tracker.pt)
2. Training Pipeline
• RL Trainer (rsl_rl)
• Teacher RL
• Student RL+BC
• LeggedGym environments (legged_gym/envs/g1, base/legged_robot, etc.)
• Output: student policy checkpoint & JIT‐traced model
3. Pose Retargeting Library
• pose/poselib (core backend, skeleton, visualization)
• GMR as optional real‐time retargeting front end
4. Deployment Services (Microservices)
• High‐Level Motion Server
• Reads motion file or MOCAP stream (legacy OptiTrack or GMR)
• Publishes joint‐target commands to Redis
• Redis broker (pub/sub)
• Low‐Level Controller Server
• Subscribes to high‐level commands
• Loads JIT‐exported student policy (PyTorch)
• Drives either:
– Sim2sim: Isaac Gym simulator
– Sim2real: Unitree G1 via unitree_sdk2py
5. External Tools & Infrastructure
• NVIDIA GPU for training & simulation
• Redis server
• Unitree G1 hardware (Ethernet link, remote controller)
• Optional MoCap / GMR service for real‐time teleop
b. Relationships & Data Flows
• Offline: Motion Dataset → LeggedGym Env → RL Trainer → Policy Checkpoint → to_jit.sh → JIT Model
• Online Simulation: JIT Model + Isaac Gym → simulator → visualization
• Online Teleop/Real: MOCAP/GMR or prerecorded motion → High‐Level Server → Redis → Low‐Level Server → Simulator or Robot hardware
c. Architectural Patterns & Principles
• Layered Architecture: clear separation of offline training vs. runtime inference
• Microservices: high‐level and low‐level controllers as separate processes communicating via Redis
• Modular codebase: distinct packages for RL (rsl_rl), simulation (legged_gym), pose retarget (pose), deployment (deploy_real)
• Pluggable backends: supports both sim and real robot with minimal code changes
d. Key Technologies & Frameworks
• rsl_rl (PyTorch-based RL algorithms, on-policy runners)
• legged_gym (Isaac Gym wrapper, Hydra configs)
• pose/poselib (tensor utils, skeleton, visualization)
• Redis (pub/sub messaging)
• MuJoCo / mujoco-python-viewer
• Unitree SDK (unitree_sdk2py)
• Bash scripts & Hydra for experiment management