# skywoodsz/qm_control architecture

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

- Interactive diagram: https://gitdiagram.com/skywoodsz/qm_control
- Repository: https://github.com/skywoodsz/qm_control

## Overview

##### Project type and purpose
- From the README and file tree, qm_control is a robotics software stack implemented as a ROS1 (Noetic) Catkin workspace.
- It provides a Model Predictive Control (MPC) + Whole-Body Control (WBC) framework for a quadruped manipulator, along with simulation support in Gazebo.
- The key use cases: whole-body planning, end-effector motion tracking, disturbance-robust control, compliance control, and real-hardware deployment.

##### File structure
Top-level organization:
– LICENSE, README.md, docs
– A Catkin workspace with multiple ROS packages, each in its own subfolder:
· qm_common: shared data structures and hardware interface abstractions
· qm_control: the core controller logic (MPC + WBC orchestrator)
· qm_controllers: ROS controller plugins and nodes
· qm_description: URDF/Xacro robot models, meshes, and RViz configs
· qm_estimation: state estimation interfaces and implementations
· qm_gazebo: Gazebo hardware simulation plugin and launch files
· qm_interface: the “API” layer to the OCS2 solver and visualization
· qm_msgs: custom ROS message definitions
· qm_wbc: WBC algorithms (hierarchical QP solvers, tasks)
· qpoases_catkin: catkinized external dependency (qpOASES QP solver)

Notice patterns:
- MVC-like layering: qm_msgs ↔ controllers (qm_controllers) ↔ core logic (qm_control + qm_interface + qm_wbc) ↔ hardware/sim (qm_gazebo, actual hardware).
- ROS-centric micro-services: each package is a node or plugin with its own CMakeLists/package.xml.
- Clear separation of concerns: description (URDF), simulation (Gazebo), estimation, control, interface, and shared utilities.

##### README insights
- Depends on ROS1-Noetic & OCS2 (external MPC solver).
- Two modes: “MPC with WBC” and “MPC only.”
- Launch sequence: gazebo world → load controllers → start controller manager → send commands via ROS topics/services or GUI (rqt).
- Uses ROS launch files (qm_gazebo/launch, qm_controllers/launch, qm_description/launch).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        QMHWSim["QMHWSim (Gazebo Plugin)"]:::sim
        RobotDesc["Robot Description (URDF/Xacro + Meshes)"]:::sim
    end

    %% ROS Infrastructure
    subgraph "ROS Infrastructure"
        direction TB
        ROSMaster["ROS Master"]:::infra
        Topics["Topics/Services\n(/base_state, /ee_state,\ncontroller_manager, commands)"]:::infra
    end

    %% Estimation Layer
    subgraph "Perception & Estimation"
        direction TB
        Estimation["qm_estimation\n(StateEstimateBase, FromTopicEstimate)"]:::est
    end

    %% Planning Layer
    subgraph "Control & Planning"
        direction TB
        MPCInterface["qm_interface\n(MPC Interface to OCS2)"]:::plan
        WBC["qm_wbc\n(Whole-Body Control Algorithms)"]:::plan
        CoreControl["qm_control\n(Core Orchestrator)"]:::plan
    end

    %% Controller Plugins
    subgraph "ROS Controller Plugins"
        direction TB
        Controllers["qm_controllers\n(Controller Nodes & Plugins)"]:::ctrl
    end

    %% Messages
    subgraph "Custom ROS Messages"
        direction TB
        Msgs["qm_msgs\n(arm_torque, base_state, ee_state)"]:::msg
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OCS2["OCS2 Solver"]:::ext
        qpOASES["qpOASES (qpoases_catkin)"]:::ext
    end

    %% UI & Visualization
    subgraph "User & Visualization"
        direction TB
        RQT["rqt_controller_manager"]:::ui
        RVIZ["RViz"]:::ui
        Gamepad["Gamepad Input (joy)"]:::ui
    end

    %% Connections
    QMHWSim -->|publishes /base_state,\n/ee_state| Topics
    RobotDesc --> QMHWSim
    Topics --> Estimation
    Estimation -->|state estimate| CoreControl
    Gamepad --> Controllers
    Controllers -->|target trajectories| CoreControl
    CoreControl --> MPCInterface
    CoreControl --> WBC
    MPCInterface -->|MPC solution| WBC
    WBC -->|desired torques| Controllers
    Controllers -->|commands| QMHWSim
    CoreControl --> Msgs
    Controllers --> Msgs
    Estimation --> Msgs
    MPCInterface --> OCS2
    WBC --> qpOASES
    Controllers --> RVIZ
    Estimation --> RVIZ

    ROSMaster --> Topics
    ROSMaster --> Controllers
    ROSMaster --> Estimation
    ROSMaster --> CoreControl
    ROSMaster --> MPCInterface
    ROSMaster --> WBC

    RQT --> Controllers
    RVIZ --> RobotDesc

    %% Click Events
    click QMHWSim "https://github.com/skywoodsz/qm_control/blob/main/qm_gazebo/src/QMHWSim.cpp"
    click RobotDesc "https://github.com/skywoodsz/qm_control/tree/main/qm_description/urdf"
    click Estimation "https://github.com/skywoodsz/qm_control/blob/main/qm_estimation/include/qm_estimation/StateEstimateBase.h"
    click CoreControl "https://github.com/skywoodsz/qm_control/blob/main/qm_control/CMakeLists.txt"
    click MPCInterface "https://github.com/skywoodsz/qm_control/blob/main/qm_interface/include/qm_interface/QMInterface.h"
    click WBC "https://github.com/skywoodsz/qm_control/blob/main/qm_wbc/include/qm_wbc/HierarchicalMpcWbc.h"
    click Controllers "https://github.com/skywoodsz/qm_control/blob/main/qm_controllers/include/qm_controllers/QMController.h"
    click Msgs "https://github.com/skywoodsz/qm_control/blob/main/qm_msgs/msg/arm_torque.msg"
    click qpOASES "https://github.com/skywoodsz/qm_control/blob/main/qpoases_catkin/CMakeLists.txt"

    %% Styles
    classDef sim fill:#ccffcc,stroke:#008000,color:#000000
    classDef infra fill:#f2f2f2,stroke:#999999,color:#000000
    classDef est fill:#cce5ff,stroke:#0073e6,color:#000000
    classDef plan fill:#ffe6cc,stroke:#ff8000,color:#000000
    classDef ctrl fill:#ffcccc,stroke:#e60000,color:#000000
    classDef msg fill:#e6e6e6,stroke:#666666,color:#000000
    classDef ext fill:#dddddd,stroke:#444444,color:#000000
    classDef ui fill:#e5ccff,stroke:#6600cc,color:#000000
```
