# vsislab/robotamersdk4qmini architecture

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

- Interactive diagram: https://gitdiagram.com/vsislab/robotamersdk4qmini
- Repository: https://github.com/vsislab/robotamersdk4qmini

## Overview

##### Project type and purpose
- This is a C++-based robotics control SDK (RoboTamerSdk4Qmini) for real-time motion control of a biped robot (Unitree Qmini).
- It loads pre-trained reinforcement learning policies (exported as ONNX models) and interfaces with sensors (IMU, joystick) and actuators (Unitree motors, via serial and DDS).

##### File structure
- Top level:
- bin/: executables (run_interface, test_interface), configuration (config.yaml), policy.onnx, helper scripts.
- /: public headers, subdivided into modules (IOPort, crc, onnx runtime wrapper, serialPort, Unitree common & robot APIs, user-defined adapters, utils).
- lib/: prebuilt libraries (Unitree SDK, motor SDK, ONNX runtime).
- source/: C++ source files implementing the interface and controllers.
- thirdparty/: DDS middleware (CycloneDDS stacks) with headers and libs.
- Patterns and build:
- Uses CMake for multi-platform builds (ARM64, x86_64).
- Modular separation: hardware abstraction, sensor interfaces, inference, control loops, communication.

##### README for additional insights
- Confirms modular, thread-safe, real-time design with safety checks.
- Lists dependencies: Yaml-CPP, Eigen, ONNX Runtime, JSONCPP, Unitree SDKs, Python/pygame for joystick UI.
- Execution flow: configure → sensor init → ready mode → position mode → AI control mode.

##### Main components
a. Front-end execution layer (CLI)
– run_interface/test_interface executables
– Configuration loader (config.yaml via Yaml-CPP)
b. Sensor subsystems
– IMU interface (imu_receiver.py/C++ wrapper)
– Joystick input (pygame-based Python or C++ reader)
c. Inference engine
– ONNX Runtime session (policy.onnx)
– Inference module (onnx_inference.h/.cpp)
d. Control & safety logic
– RL controller (rl_controller.cpp)
– Mode switcher, data validation, emergency stop
– Threaded real-time control loop (Motor_thread.hpp)
e. Actuator & communication layer
– Unitree actuator SDK (libunitree_sdk2, unitreeMotor API)
– SerialPort abstraction
– DDS middleware for inter-module messaging (CycloneDDS stacks in thirdparty/)
f. Supporting libraries
– Eigen (linear algebra)
– JsonCpp (data serialization)
– CRC utilities, IOPort abstractions, utils for file I/O and orientation

##### Relationships and interactions
- The CLI executable reads config → spawns sensor threads → collects IMU & joystick data → passes to RL controller
- RL controller calls ONNX inference → produces motor commands
- Commands go through safety checks → handed to Unitree SDK via serial/DDS → robot actuators
- Feedback loop: actuator state (via DDS topics) → control loop → inference

##### Architectural patterns & principles
- Modular layering: separation of concerns (configuration, sensing, inference, control, actuation)
- Producer-consumer threads for real-time sensor and control loops
- Hardware abstraction layer for easy porting to different robot platforms
- Fail-safe design: emergency stop, sensor validation before sending commands
- Use of message-oriented middleware (DDS) for decoupled communication

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Front-end Execution"
        A_run["CLI: run_interface"]:::frontend
        A_test["CLI: test_interface"]:::frontend
        A_run -->|"loads config"| B_config
        A_test -->|"loads config"| B_config
    end

    subgraph "Configuration Loader"
        B_config["Config Loader\n(Yaml-CPP)"]:::logic
    end

    subgraph "Sensors"
        C_imu["IMU Interface"]:::hardware
        C_js["Joystick Interface"]:::hardware
    end

    subgraph "Controller"
        D_mode["Mode Switcher"]:::logic
        D_rl["RL Controller"]:::logic
        D_loop["Control Loop\n(Motor Thread)"]:::logic
        D_mode --> D_rl
        D_rl --> D_loop
    end

    subgraph "Inference Engine"
        E_onnx["ONNX Runtime\n(policy.onnx)"]:::infra
        E_onnx -->|provides inference| D_rl
    end

    subgraph "Safety & Comm"
        F_safety["Safety Check"]:::logic
        F_serial["SerialPort Abstraction"]:::hardware
        F_dds["DDS Middleware"]:::infra
        D_loop -->|commands| F_safety
        F_safety --> F_serial
        F_safety --> F_dds
    end

    subgraph "Actuation"
        G_unitree["Unitree SDK\nunitree_sdk2"]:::hardware
        G_motor["Motor SDK\nunitreeMotor"]:::hardware
        F_serial -->|serial write| G_unitree
        F_dds -->|DDS publish| G_unitree
        G_unitree -->|motor API| G_motor
    end

    Robot["Unitree Qmini\n(Biped Robot)"]:::hardware
    G_motor -->|actuates| Robot

    B_config -->|init sensor threads| C_imu
    B_config -->|init sensor threads| C_js
    C_imu -->|IMU data| D_mode
    C_js -->|Joystick data| D_mode

    subgraph "Utilities"
        H_crc["CRC Utilities"]:::infra
        H_iop["IOPort Abstraction"]:::infra
        H_utils["Supporting Utils"]:::infra
    end
    H_utils --> B_config

    classDef frontend fill:#b0e0e6,stroke:#333,stroke-width:1px
    classDef logic fill:#98fb98,stroke:#333,stroke-width:1px
    classDef hardware fill:#add8e6,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px

    click A_run "https://github.com/vsislab/robotamersdk4qmini/blob/main/source/run_interface.cpp"
    click A_run "https://github.com/vsislab/robotamersdk4qmini/tree/main/bin/run_interface"
    click A_test "https://github.com/vsislab/robotamersdk4qmini/blob/main/source/test_interface.cpp"
    click A_test "https://github.com/vsislab/robotamersdk4qmini/tree/main/bin/test_interface"
    click B_config "https://github.com/vsislab/robotamersdk4qmini/blob/main/bin/config.yaml"
    click B_config "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/utils/config.h"
    click C_imu "https://github.com/vsislab/robotamersdk4qmini/blob/main/bin/imu_receiver.py"
    click C_imu "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/IMU/imu_receiver.py"
    click C_imu "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/IMUReader.h"
    click C_imu "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/imu_interface.py"
    click C_js "https://github.com/vsislab/robotamersdk4qmini/blob/main/bin/joystick.py"
    click C_js "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/joystick_reader.h"
    click E_onnx "https://github.com/vsislab/robotamersdk4qmini/blob/main/bin/policy.onnx"
    click E_onnx "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/onnx_inference.h"
    click E_onnx "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/onnx/onnxruntime_cxx_api.h"
    click D_rl "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/rl_controller.h"
    click D_rl "https://github.com/vsislab/robotamersdk4qmini/blob/main/source/user/rl_controller.cpp"
    click D_mode "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/mode_switcher.h"
    click D_loop "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/user/Motor_thread.hpp"
    click F_serial "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/serialPort/SerialPort.h"
    click G_unitree "https://github.com/vsislab/robotamersdk4qmini/tree/main/include/unitree"
    click G_unitree "https://github.com/vsislab/robotamersdk4qmini/blob/main/lib/x86_64/libunitree_sdk2.a"
    click G_unitree "https://github.com/vsislab/robotamersdk4qmini/blob/main/lib/aarch64/libunitree_sdk2.a"
    click G_motor "https://github.com/vsislab/robotamersdk4qmini/tree/main/include/unitreeMotor"
    click G_motor "https://github.com/vsislab/robotamersdk4qmini/tree/main/lib/m8010motor"
    click F_dds "https://github.com/vsislab/robotamersdk4qmini/tree/main/thirdparty/include/dds"
    click F_dds "https://github.com/vsislab/robotamersdk4qmini/tree/main/include/unitree/common/dds"
    click H_crc "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/crc/crc32.h"
    click H_crc "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/crc/crc_ccitt.h"
    click H_iop "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/IOPort/IOPort.h"
    click H_utils "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/utils/orientation_tools.h"
    click H_utils "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/utils/read_txt_file.h"
    click H_utils "https://github.com/vsislab/robotamersdk4qmini/blob/main/include/utils/cpp_types.h"
```
