# dyumanaditya/quad-stack architecture

> Architecture diagram of the GitHub repository dyumanaditya/quad-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dyumanaditya/quad-stack
- Repository: https://github.com/dyumanaditya/quad-stack

## Overview

##### Project type and purpose
- QuadStack is a ROS 2-based software stack for quadruped robots (MAB Silver/Honey Badger and Unitree A1/Go1/Go2).
- It integrates neural locomotion, visual‐inertial‐kinematic odometry, SLAM, navigation/planning/exploration, simulation (Gazebo), and teleoperation.

##### File structure
- Top–level workspace containing:
- legged_kinematics_odometry (pure C++ ROS 2 package publishing odometry from leg kinematics)
- mab_ros (several ROS 2 packages: hb40_commons, mab_control, mab_locomotion, mab_utils)
- quad_stack (the core bringup, gazebo, contact, keyboard teleop, localization, navigation, stand, utils packages)
- robots (URDF/Xacro descriptions for supported robots)
- unitree_ros (control, locomotion, utils for Unitree robots)
- Each package has its own CMakeLists.xml / package.xml, source code (C++ or Python), launch files, message/service definitions, and resources (meshes, models, configuration YAML).

##### README for insights
- The README describes four major functional pillars:
a. Neural locomotion
b. Visual-Inertial-Kinematic Aided Odometry (VIO)
c. Velocity-constrained SLAM
d. Navigation, planning & exploration
- It also walks through launching each subsystem via ROS 2 launch files under quad_stack_bringup.

##### Elements
- Blue for perception (VIO, kinematics odometry, SLAM)
- Green for motion (locomotion, control, teleop)
- Orange for planning (navigation, exploration)
- Gray for simulation/hardware (Gazebo, URDF)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware / Simulation Layer
    subgraph "Hardware / Simulation"
        USim["URDF/Xacro Descriptions"]:::hardware
        Gazebo["Gazebo Simulator & Worlds"]:::hardware
    end

    %% Sensor Interfaces Layer
    subgraph "Sensor Interfaces"
        Plugins["RealSense Gazebo Plugin"]:::perception
        IMUFake["fake_imu.py"]:::perception
        CameraStab["camera_frame_stabilizer.py"]:::perception
        DepthConv["depth_to_laser.launch.py"]:::perception
    end

    %% Perception Layer
    subgraph "Perception"
        KinOdo["Kinematic Odometry"]:::perception
        VIO["Visual-Inertial Odometry"]:::perception
    end

    %% Mapping Layer
    subgraph "Mapping"
        SLAM["SLAM Node"]:::perception
        MapStorage[(Map Storage)]:::data
    end

    %% Planning Layer
    subgraph "Planning"
        Planner["Global Planner"]:::planning
        Explorer["Frontier Exploration"]:::planning
    end

    %% Control & Locomotion Layer
    subgraph "Control & Locomotion"
        Neuro["Neural Locomotion Controller"]:::control
        Teleop["Teleoperation Interface"]:::control
        CtrlPlugin["Control Plugins & Actuation"]:::control
    end

    %% Visualization & Logging Layer
    subgraph "Visualization & Logging"
        RViz["RViz"]:::external
        Rosbag[(rosbag)]:::data
    end

    %% Data Flows
    USim -->|"/joint_states,/imu/data,/camera/image"/Gazebo| Plugins
    Gazebo --> Plugins
    Plugins --> KinOdo
    Plugins --> VIO
    IMUFake --> VIO
    CameraStab --> VIO
    DepthConv --> VIO

    KinOdo -->|"/odom_kinematic"| SLAM
    VIO -->|"/odom_vo"| SLAM
    SLAM -->|"/map,/tf"| MapStorage
    SLAM --> Planner
    MapStorage --> Planner
    Planner --> Explorer
    Planner --> Neuro
    Teleop --> Planner
    Teleop --> Neuro
    Neuro --> CtrlPlugin
    CtrlPlugin --> Gazebo

    RViz --> Rosbag

    %% Click events
    click USim "https://github.com/dyumanaditya/quad-stack/tree/main/robots/"
    click Gazebo "https://github.com/dyumanaditya/quad-stack/tree/main/quad_stack/quadstack_gazebo"
    click Plugins "https://github.com/dyumanaditya/quad-stack/tree/main/quad_stack/realsense_gazebo_plugin"
    click IMUFake "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_utils/quadstack_utils/fake_imu.py"
    click CameraStab "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_utils/quadstack_utils/camera_frame_stabilizer.py"
    click DepthConv "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_utils/launch/depth_to_laser.launch.py"
    click KinOdo "https://github.com/dyumanaditya/quad-stack/blob/main/legged_kinematics_odometry/src/kinematics_odometry.cpp"
    click VIO "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_localization/launch/visual_odometry.launch.py"
    click SLAM "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_localization/launch/slam.launch.py"
    click Neuro "https://github.com/dyumanaditya/quad-stack/blob/main/mab_ros/mab_locomotion/mab_locomotion/policy.py"
    click Neuro "https://github.com/dyumanaditya/quad-stack/blob/main/unitree_ros/unitree_locomotion/unitree_locomotion/policy.py"
    click Planner "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_navigation/launch/navigation.launch.py"
    click Teleop "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_keyboard_teleop/quadstack_keyboard_teleop/teleop_node.py"
    click CtrlPlugin "https://github.com/dyumanaditya/quad-stack/blob/main/mab_ros/mab_control/src/mab_gazebo_control_plugin.cpp"
    click CtrlPlugin "https://github.com/dyumanaditya/quad-stack/blob/main/unitree_ros/unitree_control/src/unitree_gazebo_control_plugin.cpp"
    click RViz "https://github.com/dyumanaditya/quad-stack/blob/main/quad_stack/quadstack_bringup/rviz/quadstack_nav.rviz"
    click Rosbag "https://github.com/dyumanaditya/quad-stack/tree/main/quad_stack/quadstack_bringup/launch/"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef perception fill:#85C1E9,stroke:#333,stroke-width:1px;
    classDef planning fill:#F5B041,stroke:#333,stroke-width:1px;
    classDef control fill:#82E0AA,stroke:#333,stroke-width:1px;
    classDef data fill:#D7BDE2,stroke:#333,stroke-width:1px;
    classDef external fill:#FAD7A0,stroke:#333,stroke-width:1px;
```
