# ku-gcl/gcl-pendulum architecture

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

- Interactive diagram: https://gitdiagram.com/ku-gcl/gcl-pendulum
- Repository: https://github.com/ku-gcl/gcl-pendulum

## Overview

##### Main Components
- Controller & Control Algorithms:
- Core control logic lives in the src/ directory (files like main.cpp, kalman_filter.*, motor_control.*, sensor.*, etc.). This component is responsible for gathering sensor data, filtering it (via the Kalman filter), and issuing commands to the motor.
- Sensor & Data Acquisition:
- Components for reading physical sensor inputs (e.g., sensor.cpp, encoder.cpp, and related hardware interfacing code). Represent this as the “Sensor Subsystem.”
- Actuator & Motor Control:
- The motor_control.cpp/h files indicate a distinct module handling the physical actuation of the pendulum system.
- Simulation & Analysis Tools:
- In the Tools/ directory, several subdirectories (simulation, analysis, udp) are provided. For example, Tools/simulation/ contains simulation models (InvertedPendulum.py, simulation.py, and supporting scripts such as calc_lqr_gain.py) which mimic the dynamics and response of the inverted pendulum. Tools/analysis and UDP utilities (with MATLAB scripts) are for further analysis and communication testing.
- Utilities & Setup Services:
- Data Logging & Results:
- The data/ and sample/ folders contain CSV files and figures (e.g., logs and plots) that record performance metrics, simulation results, and system outputs. Represent a “Data Logging & Visualization” component.
- Testing Frameworks:

##### Relationships and Interactions
- A feedback loop between the Sensor Subsystem and the Controller: sensor data flows into the Kalman filter-based control algorithm, which then references the motor control to adjust actuator outputs.
- Connections from the Controller and Sensor components to the Data Logging module, where performance is recorded for later analysis.
- Simulation Tools with the Core Control Algorithms, emphasizing that simulation feeds into the design and tuning (e.g., using Tools/simulation to test control strategies before deployment).
- Demonstrate the direction of utility/service flows: The setup and auto-start scripts initialize the control system services (shown in Tools/) which then bridge the gap between hardware initialization and runtime service provision.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the separation between real-time control logic (src/) and simulation/analysis tools (Tools/). This separation allows for isolated testing and development.
- Layered Architecture: Represent the system as layers—from low-level hardware interfacing (sensors and actuators) to mid-level processing (control algorithms) and high-level analysis, simulation, and data visualization.
- Testing and Continuous Integration: Include testing modules as separate but interconnected components to ensure reliability of critical functions (e.g., sensor reading, motor actuation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Real-Time Control Layer"
        sensorSys["Sensors & Data Acquisition"]:::sensors
        controller["Control Algorithm (Kalman Filter & Motor Control)"]:::controller
        actuator["Actuator & Motor Control"]:::actuator
        sensorSys -->|"data"| controller
        controller -->|"control"| actuator
    end

    simTools["Simulation & Analysis Tools"]:::sim

    deployServices["Deployment & Service Management"]:::deploy
    dataLogging["Data Logging & Visualization"]:::logging
    testing["Automated Testing"]:::testing

    simTools -->|"simulate"| controller
    sensorSys -->|"logs"| dataLogging
    controller -->|"logs"| dataLogging
    deployServices -->|"init"| sensorSys
    deployServices -->|"init"| controller
    deployServices -->|"init"| actuator
    testing -->|"tests"| sensorSys
    testing -->|"tests"| controller
    testing -->|"tests"| actuator

    click controller "https://github.com/ku-gcl/gcl-pendulum/tree/master/src/"
    click sensorSys "https://github.com/ku-gcl/gcl-pendulum/blob/master/src/sensor.cpp"
    click sensorSys "https://github.com/ku-gcl/gcl-pendulum/blob/master/src/encoder.cpp"
    click actuator "https://github.com/ku-gcl/gcl-pendulum/blob/master/src/motor_control.cpp"
    click actuator "https://github.com/ku-gcl/gcl-pendulum/blob/master/src/motor_control.h"
    click simTools "https://github.com/ku-gcl/gcl-pendulum/tree/master/Tools/simulation/"
    click simTools "https://github.com/ku-gcl/gcl-pendulum/blob/master/Tools/analysis/analysis.py"
    click deployServices "https://github.com/ku-gcl/gcl-pendulum/blob/master/Tools/setup.sh"
    click deployServices "https://github.com/ku-gcl/gcl-pendulum/blob/master/Tools/pendulum.service"
    click deployServices "https://github.com/ku-gcl/gcl-pendulum/blob/master/Tools/pigpiod.service"
    click deployServices "https://github.com/ku-gcl/gcl-pendulum/blob/master/Tools/pendulum_auto_start_script.py"
    click dataLogging "https://github.com/ku-gcl/gcl-pendulum/tree/master/data/"
    click testing "https://github.com/ku-gcl/gcl-pendulum/tree/master/test/"
    click testing "https://github.com/ku-gcl/gcl-pendulum/tree/master/unit_test/"

    classDef sensors fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef controller fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef actuator fill:#CCCCFF,stroke:#333,stroke-width:2px;
    classDef sim fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FFEC8B,stroke:#333,stroke-width:2px;
    classDef logging fill:#D1E8FF,stroke:#333,stroke-width:2px;
    classDef testing fill:#D1FFD1,stroke:#333,stroke-width:2px;
```
