# sagar280190/ball-balancing-pid-system architecture

> Architecture diagram of the GitHub repository sagar280190/ball-balancing-pid-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagar280190/ball-balancing-pid-system
- Repository: https://github.com/sagar280190/ball-balancing-pid-system

## Overview

##### What this project is (type + purpose)
From the file tree + README, this is a **hardware-in-the-loop control system** (mechatronics project) for a **ball-balancing platform driven by a PID controller**.

It is not a typical “web app” architecture; the “system” spans:
- **PC-side Python** (likely UI + serial protocol + PID logic and/or setpoints/telemetry)
- **Arduino firmware** controlling **3 servos** (platform actuation)
- **Physical plant** (ball + plate mechanism)

##### Arduino side (embedded / real-time actuator control)
- `ArduinoCodes/arduino3servoTest/arduino3servoTest.ino`
- Represents **firmware**: servo control, reading commands from serial, writing servo PWM, possibly sending telemetry back.

##### PC side (control + UI + experiments)
- `pythonCodes/interface.py`
- Likely **operator UI** + **serial communication** with Arduino + **control loop orchestration** (PID update rate, setpoint selection, plotting).
- `pythonCodes/data.txt`
- Likely **parameters** (PID gains, calibration constants, offsets).
- `pythonCodes/README.txt`

##### Math / helper scripts (offline computation / calibration)
- `additional codes/programmeIntermediare.py`
- `additional codes/solveEquation.py`
- These look like **engineering tools** used to derive geometry, mapping, or calibration (e.g., servo angle ↔ plate tilt).

##### Documentation / assets
- `TM 2.pdf`, `images/*`, `License.txt`
- As “Documentation” (optional), not part of runtime architecture.

##### PC Container: Python Control & UI
- UI layer (buttons/sliders/plots)
- Control loop (PID computation)
- Serial protocol (encode/decode)
- Config/Calibration loader (`data.txt`)
##### Microcontroller Container: Arduino Firmware
- Modules inside:
- Serial command parser
- Servo kinematics mapping (if implemented there)
- Servo driver (PWM)
- Safety (limits, neutral positions)
##### Sensor Container (if separate hardware/software)
- If it’s a camera, include:
- Camera device
- Vision algorithm (could be Python/OpenCV; not in repo, but you must represent it if it exists in the real system)

- There is no Arduino PID file shown; the Arduino sketch name says “servo test.”
- Therefore, default assumption: **PID is in Python** (or at least orchestrated from Python), and Arduino is an actuator endpoint.

**PC/Python components**
- `pythonCodes/interface.py`
- “UI + Control Loop Coordinator”
- “Serial Client”
- “Parameter management”
- `pythonCodes/data.txt`
- “Configuration: PID gains, calibration constants”
**Offline tools**
- `additional codes/solveEquation.py`
- “Calibration/math solver (offline)”
- `additional codes/programmeIntermediare.py`
- “Intermediate computation / mapping tool”

**Arduino components**
- `ArduinoCodes/arduino3servoTest/arduino3servoTest.ino`
- “Serial command receiver”
- “Servo output module”
- “Servo channel 1/2/3”

##### Architectural patterns to explicitly highlight (because they matter here)
- **Closed-loop feedback control (PID)**: setpoint → error → controller → actuator → plant → sensor → measurement.
- **Hardware abstraction boundary**: PC logic vs microcontroller real-time actuation.
- **Calibration pipeline**: offline math scripts → constants → runtime config (data.txt) → controller/firmware.

- **Signal type** (e.g., “(x,y) position”, “servo angles”, “PWM”)
- **Rate/latency constraints** (e.g., 30 Hz camera, 50–100 Hz control loop, serial baud rate)
- **Units** (degrees, mm, normalized [-1,1])
- **Failure modes** (optional but valuable): dropped serial frames, sensor noise, servo saturation.

##### What to be explicit about given this repo’s gaps
- A **“Ball position measurement”** component anyway.
- It as **External / Not in repo** unless you confirm it exists elsewhere.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram A: System Context / Closed-loop Control
  %% =========================
  subgraph A["A) System Context / Closed-loop Control (Runtime)"]
    direction TB

    OP["Operator\n(setpoint,mode,gains)"]:::external

    subgraph PC_A["PC (Runtime)"]
      direction TB
      PY_A["Python App\n(UI+PID+Serial)\n(interface.py)"]:::pc
      CFG_A[("Runtime Config\n(PID gains,calibration)\n(data.txt)")]:::data
      NOTES_A["Usage Notes\n(how to run)\n(README.txt)"]:::doc
    end

    LINK_A["USB Serial Link\n(protocol boundary)\n(baud,framing)"]:::link

    subgraph MCU_A["Microcontroller (Runtime)"]
      direction TB
      FW_A["Arduino Firmware\n(serial→servo)\n(arduino3servoTest.ino)"]:::mcu
      LIMITS_A["Safety & Limits\n(neutral,saturation)"]:::mcu
    end

    subgraph HW_A["Hardware / Physical System"]
      direction TB
      ARD_HW["Arduino Board\n(real-time PWM)"]:::hw
      SRV["Servos x3\n(PWM→angle)"]:::plant
      PLANT["Ball-and-Plate Plant\n(tilt→ball motion)"]:::plant
    end

    subgraph SENSE_A["Sensing (External/Assumed)"]
      direction TB
      SENSOR["Ball Position Measurement\n(camera/touch/IMU)\nExternal / Not in repo"]:::external
      MEAS["Measured State\n(x,y),optional tilt\n(noise,latency)"]:::external
    end

    %% Control loop flows
    OP -->|"setpoint/mode/gains"| PY_A
    CFG_A -->|"load parameters"| PY_A
    NOTES_A -.->|"operator reads"| OP

    SENSOR -->|"observe plant state"| MEAS
    PLANT -->|"physical state"| SENSOR
    MEAS -->|"feedback:(x,y)@~30Hz"| PY_A

    PY_A -->|"control output:servo_angles/tilt_cmd@~50-100Hz"| LINK_A
    LINK_A -->|"serial frames (cmd)"| FW_A

    FW_A -->|"apply limits"| LIMITS_A
    LIMITS_A -->|"PWM channels x3"| ARD_HW
    ARD_HW -->|"PWM"| SRV
    SRV -->|"actuate tilt"| PLANT

    %% Optional telemetry
    FW_A -->|"telemetry:angles,timing,debug (optional)"| LINK_A
    LINK_A -->|"telemetry"| PY_A
  end

  %% =========================
  %% Diagram B: Container Diagram (Runtime Containers)
  %% =========================
  subgraph B["B) Container Diagram (Runtime Responsibilities)"]
    direction TB

    subgraph PC_B["PC Container: Python Control & UI"]
      direction TB
      UI_B["UI Layer\n(sliders/plots/buttons)"]:::pc
      PID_B["Control Loop / PID\n(setpoint→error→u)"]:::pc
      SER_B["Serial Protocol Client\n(encode/decode frames)"]:::pc
      CFG_B[("Config Loader\n(data.txt)")]:::data

      UI_B -->|"setpoint/gains"| PID_B
      CFG_B -->|"gains,offsets,constants"| PID_B
      PID_B -->|"u:servo_angles/tilt_cmd"| SER_B
    end

    IF_B["Serial Interface\n(USB CDC/COM)\nprotocol boundary"]:::link

    subgraph MCU_B["Microcontroller Container: Arduino Firmware"]
      direction TB
      PARSE_B["Serial Command Parser\n(frame→targets)"]:::mcu
      MAP_B["Kinematics/Mapping\n(targets→servo setpoints)"]:::mcu
      PWM_B["Servo Driver (PWM)\n3 channels"]:::mcu
      SAFE_B["Safety\n(clip,neutral,failsafe)"]:::mcu

      PARSE_B -->|"targets"| MAP_B
      MAP_B -->|"angles"| SAFE_B
      SAFE_B -->|"bounded angles"| PWM_B
    end

    subgraph SENSE_B["Sensor Container (External/Assumed)"]
      direction TB
      CAM_B["Sensor Device\n(camera/touch/IMU)"]:::external
      PIPE_B["Measurement Pipeline\n(CV/filtering)\n(not in repo)"]:::external
      CAM_B -->|"raw data"| PIPE_B
    end

    SER_B -->|"frames(cmd)"| IF_B
    IF_B -->|"frames(cmd)"| PARSE_B

    PIPE_B -->|"state:(x,y)"| PID_B
  end

  %% =========================
  %% Diagram C: Component-to-File (Auditable Mapping)
  %% =========================
  subgraph C["C) Component Diagram (Repo Artifacts + Calibration Pipeline)"]
    direction TB

    subgraph DOC_C["Documentation (Non-runtime)"]
      direction TB
      ROOT_README["Project README\n(overview/instructions)"]:::doc
      REPORT["Report/Spec PDF\n(TM 2.pdf)"]:::doc
      IMAGES["Documentation Assets\n(images/)"]:::doc
      LICENSE["License\n(License.txt)"]:::doc
    end

    subgraph OFF_C["Offline Calibration / Engineering Tools"]
      direction TB
      OFF_README["Offline Tools Notes\n(additional codes/README)"]:::doc
      INTERM["Intermediate Tool\n(mapping/derivations)\n(programmeIntermediare.py)"]:::offline
      SOLVER["Math Solver Utility\n(geometry/kinematics)\n(solveEquation.py)"]:::offline
    end

    subgraph RUN_C["Runtime Config + Apps"]
      direction TB
      PY_C["Python Runtime App\n(interface.py)"]:::pc
      DATA_C[("data.txt\n(PID gains, offsets,\ncalibration constants)")]:::data
      PYNOTES_C["Python Usage Notes\n(pythonCodes/README.txt)"]:::doc
      INO_C["Arduino Sketch\n(arduino3servoTest.ino)"]:::mcu
    end

    %% Calibration pipeline (dashed)
    SOLVER -.->|"derive constants"| INTERM
    INTERM -.->|"export parameters"| DATA_C
    OFF_README -.->|"guides"| INTERM
    OFF_README -.->|"guides"| SOLVER

    %% Runtime usage relations
    DATA_C -->|"loaded by"| PY_C
    PYNOTES_C -.->|"guides operator"| PY_C
    PY_C -->|"serial cmds"| INO_C

    %% Docs relationships
    ROOT_README -.->|"references"| IMAGES
    ROOT_README -.->|"references"| REPORT
    ROOT_README -.->|"license info"| LICENSE
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click FW_A "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/ArduinoCodes/arduino3servoTest/arduino3servoTest.ino"
  click INO_C "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/ArduinoCodes/arduino3servoTest/arduino3servoTest.ino"

  click PY_A "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/interface.py"
  click PY_C "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/interface.py"

  click CFG_A "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/data.txt"
  click CFG_B "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/data.txt"
  click DATA_C "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/data.txt"

  click NOTES_A "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/README.txt"
  click PYNOTES_C "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/pythonCodes/README.txt"

  click INTERM "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/additional codes/programmeIntermediare.py"
  click SOLVER "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/additional codes/solveEquation.py"
  click OFF_README "https://github.com/sagar280190/ball-balancing-pid-system/tree/master/additional codes/README"

  click ROOT_README "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/README.md"
  click REPORT "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/TM 2.pdf"
  click IMAGES "https://github.com/sagar280190/ball-balancing-pid-system/tree/master/images/"
  click LICENSE "https://github.com/sagar280190/ball-balancing-pid-system/blob/master/License.txt"

  %% =========================
  %% Styles (Color coding)
  %% =========================
  classDef pc fill:#1f77b4,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
  classDef mcu fill:#ff7f0e,stroke:#7a3a00,color:#ffffff,stroke-width:1.5px
  classDef plant fill:#2ca02c,stroke:#145214,color:#ffffff,stroke-width:1.5px
  classDef hw fill:#34b679,stroke:#145214,color:#ffffff,stroke-width:1.5px
  classDef external fill:#9e9e9e,stroke:#4f4f4f,color:#ffffff,stroke-width:1.5px
  classDef data fill:#f2f2f2,stroke:#616161,color:#111111,stroke-width:1.5px
  classDef doc fill:#b39ddb,stroke:#4a148c,color:#111111,stroke-width:1.2px
  classDef offline fill:#ffd54f,stroke:#8a6d00,color:#111111,stroke-width:1.5px
  classDef link fill:#00acc1,stroke:#005662,color:#ffffff,stroke-width:1.5px
```
