# teddy-liao/walk-these-ways-go2 architecture

> Architecture diagram of the GitHub repository teddy-liao/walk-these-ways-go2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teddy-liao/walk-these-ways-go2
- Repository: https://github.com/teddy-liao/walk-these-ways-go2

## Overview

##### Project Type and Purpose
- This is a full‐stack Sim‑to‑Real robotics framework for the Unitree Go2 quadruped. It comprises three domains:
a. Simulation & environment (`go2_gym`)
b. Reinforcement‑learning training (`go2_gym_learn` + `scripts/train.py`)
c. Real‑robot deployment (`go2_gym_deploy` + C++ LCM ↔ Unitree SDK2 interface)

##### High‑Level Component Breakdown
A. Simulation & Environment Layer
- Python “Gym” wrappers in `go2_gym/envs/...` use Isaac Gym and URDF/DAE robot models in `resources/robots/...`.
- Base classes (`legged_robot.py`, `base_task.py`) define physics interface, curriculum, reward functions.
B. Training & Learning Layer
- PPO implementations under `go2_gym_learn/ppo` (and variant `ppo_cse`), plus vectorized env support in `go2_gym_learn/env/vec_env.py`.
- Utility modules for metrics, data logging, domain randomization in `go2_gym_learn/eval_metrics`.
- Training entry point `scripts/train.py`, experiment logs/checkpoints saved under `runs/`.
C. Deployment Layer
- C++ executable `lcm_position_go2` built via CMake in `go2_gym_deploy`, linking Unitree SDK2 library.
- LCM message definitions in `go2_gym_deploy/lcm_types/*_(lcmt).lcm/py/hpp`.
- Python deploy script `go2_gym_deploy/scripts/deploy_policy.py` publishes policy commands over LCM.
- Hardware SDK (`unitree_sdk2`) integrated as a third‑party library under `go2_gym_deploy/unitree_sdk2_bin`.

##### Component Interactions & Data Flow
1. During Training:
[Python PPO Agent] → samples actions →
[go2_gym Env Wrappers] ←– state from Isaac Gym simulation & URDF models
↳ reward/curriculum → PPO update → checkpoints in `runs/`
2. During Deployment:
[Python deploy_policy.py] ← loads trained weights →
publishes LCM command messages →
[lcm_position_go2 C++ Service] ← subscribes to LCM → translates to Unitree SDK2 calls →
[Unitree Go2 Robot Hardware]
in parallel, [Unitree SDK2] → sensor feedback → publishes LCM state messages →
[Python cheetah_state_estimator.py] → state estimation → feed to deploy_policy

##### Architectural Patterns & Principles
- Modular separation: Simulation vs. Training vs. Deployment
- Clear “message bus” abstraction via LCM decouples Python and C++ layers
- Configuration injection: Robot parameters in `go2_config.py` vs. base configs
- Reusable base classes and inheritance in `go2_gym/envs/base`
- Experiment reproducibility: deterministic seed, curriculum saved in `runs/.../curriculum`

##### Technologies & Frameworks
- Python 3 + PyTorch + Isaac Gym
- OpenAI‑style Gym API
- Reinforcement Learning: PPO algorithm
- Build & Deployment: CMake, C++17, Unitree SDK2
- Message passing: LCM (Lightweight Communications and Marshalling)
- URDF/DAE robot models, conda environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation & Environment Layer"
        URDF["URDF/DAE Resources"]:::python
        Gym["Gym Wrappers"]:::python
        Base["Base Classes"]:::python
        Config["Robot Config"]:::python
        Rewards["Reward Functions"]:::python
        History["History Wrapper"]:::python
        URDF -->|“robot models”| Gym
        Config -->|“parameters”| Gym
        Rewards -->|“reward signals”| Gym
        History -->|“state history”| Gym
        Gym -->|“environment interface”| Base
    end

    subgraph "Training & Learning Layer"
        PPO["PPO Agent"]:::python
        VecEnv["Vectorized Env"]:::python
        Metrics["Domain Rand & Metrics"]:::python
        TrainScript["Training Entry Point"]:::python
        Runs["Experiment Outputs"]:::python
        Gym -->|“states & rewards”| PPO
        PPO -->|“actions”| Gym
        PPO -->|“checkpoints”| Runs
        VecEnv -->|“env multiplexing”| PPO
        Metrics -->|“logging/randomization”| PPO
        TrainScript -->|“launch training”| PPO
    end

    LCMBus["LCM Message Bus"]:::lcm

    subgraph "Deployment Service"
        DeployPy["Deploy Script"]:::python
        CppSvc["lcm_position_go2 (C++)"]:::cpp
        SDK2["Unitree SDK2 Library"]:::cpp
        Robot["Unitree Go2 Robot"]:::hw
        Estimator["State Estimator"]:::python
        DeployPy -->|“/MotorCmd_lcmt”| LCMBus
        LCMBus -->|“/MotorCmd_lcmt”| CppSvc
        CppSvc -->|“SDK calls”| SDK2
        SDK2 -->|“hardware actuation”| Robot
        Robot -->|“/RobotState_lcmt”| LCMBus
        LCMBus -->|“/RobotState_lcmt”| Estimator
        Estimator -->|“state input”| DeployPy
    end

    classDef python fill:#D0E6F8,stroke:#0366D6,stroke-width:1px
    classDef cpp fill:#FFE5B4,stroke:#CC6600,stroke-width:1px
    classDef hw fill:#E0E0E0,stroke:#606060,stroke-width:1px
    classDef lcm fill:#D4F1BE,stroke:#4F8A10,stroke-width:1px

    click Gym "https://github.com/teddy-liao/walk-these-ways-go2/tree/main/go2_gym/envs/"
    click Base "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym/envs/base/base_task.py"
    click Base "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym/envs/base/legged_robot.py"
    click Config "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym/envs/go2/go2_config.py"
    click Rewards "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym/envs/rewards/corl_rewards.py"
    click History "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym/envs/wrappers/history_wrapper.py"
    click URDF "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/resources/robots/go2/urdf/go2.urdf"
    click URDF "https://github.com/teddy-liao/walk-these-ways-go2/tree/main/resources/robots/go2/dae/"
    click PPO "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/ppo/ppo.py"
    click PPO "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/ppo/actor_critic.py"
    click PPO "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/ppo/rollout_storage.py"
    click VecEnv "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/env/vec_env.py"
    click Metrics "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/eval_metrics/domain_randomization.py"
    click Metrics "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_learn/eval_metrics/metrics.py"
    click TrainScript "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/scripts/train.py"
    click Runs "https://github.com/teddy-liao/walk-these-ways-go2/tree/main/runs/"
    click DeployPy "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_deploy/scripts/deploy_policy.py"
    click CppSvc "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_deploy/unitree_sdk2_bin/lcm_position_go2.cpp"
    click SDK2 "https://github.com/teddy-liao/walk-these-ways-go2/tree/main/go2_gym_deploy/unitree_sdk2_bin/library/unitree_sdk2"
    click Estimator "https://github.com/teddy-liao/walk-these-ways-go2/blob/main/go2_gym_deploy/utils/cheetah_state_estimator.py"
```
