# ptsfdtz/pendulum architecture

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

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

## Overview

PendulumLab combines offline single- and double-pendulum simulation with two real-hardware routes: a native Simulink model and a standalone C++ console. In the C++ operator workflow, the console loads configuration, prepares and monitors hardware, performs calibration or balance control, and relies on safety shutdown and run logging. MATLAB simulation, result recording, and the MATLAB hardware adapter are separate capabilities. C++ relationships are grounded in the supplied source index and excerpts; MATLAB subsystem connections are limited to relationships documented in the README because their source was not sampled.

Main entry points: [`src/tools/PendulumConsoleMain.cpp`](https://github.com/ptsfdtz/pendulum/blob/main/src/tools/PendulumConsoleMain.cpp) (Control console), [`matlab/run_pendulum.m`](https://github.com/ptsfdtz/pendulum/blob/main/matlab/run_pendulum.m) (Simulation entry), [`matlab/native_simulink`](https://github.com/ptsfdtz/pendulum/tree/main/matlab/native_simulink) (Native Simulink control), [`matlab/hardware`](https://github.com/ptsfdtz/pendulum/tree/main/matlab/hardware) (MATLAB hardware adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpp["C++ hardware control"]
  node_cpp_console["Control console"]
  node_config["Configuration<br/>[Config.cpp]"]
  node_homing["Home and center"]
  node_encoder_cal["Encoder calibration"]
  node_zero_cal["Motor zero calibration"]
  node_single_ctrl["Single-pendulum control"]
  node_double_ctrl["Double-pendulum control"]
  node_ni_hw["NI encoder and limits<br/>[NI6602.cpp]"]
  node_pci_hw["Analog output<br/>[PCI1723.cpp]"]
  node_safety["Safety shutdown<br/>[SafetyManager.cpp]"]
  node_logger["Run logging<br/>[AsyncLogger.cpp]"]
end

subgraph group_matlab_sim["MATLAB simulation"]
  node_sim_entry["Simulation entry<br/>[run_pendulum.m]"]
  node_single_model["Single-pendulum model"]
  node_double_model["Double-pendulum model"]
  node_sim_engines["Simulation engines"]
  node_results["Run results"]
end

subgraph group_matlab_hw["MATLAB hardware"]
  node_native_model["Native Simulink control"]
  node_matlab_adapter["MATLAB hardware adapter"]
end

node_operator(("Operator"))
node_physical["DAQ and pendulum"]

node_operator -->|"starts control"| node_cpp_console
node_cpp_console -->|"loads settings"| node_config
node_cpp_console -->|"runs homing"| node_homing
node_cpp_console -->|"uses calibration"| node_encoder_cal
node_cpp_console -->|"uses calibration"| node_zero_cal
node_cpp_console -->|"reads sensors"| node_ni_hw
node_cpp_console -->|"commands output"| node_pci_hw
node_cpp_console -->|"registers shutdown"| node_safety
node_cpp_console -->|"records events"| node_logger
node_cpp_console -.->|"selects control"| node_single_ctrl
node_cpp_console -.->|"selects control"| node_double_ctrl
node_operator -->|"runs experiment"| node_sim_entry
node_sim_entry -->|"selects model"| node_single_model
node_sim_entry -->|"selects model"| node_double_model
node_sim_entry -->|"runs engine"| node_sim_engines
node_sim_entry -->|"saves run"| node_results
node_operator -->|"starts hardware model"| node_native_model
node_native_model -->|"controls hardware"| node_physical
node_operator -->|"starts hardware run"| node_matlab_adapter
node_matlab_adapter -->|"accesses hardware"| node_physical

click node_cpp_console "https://github.com/ptsfdtz/pendulum/blob/main/src/tools/PendulumConsoleMain.cpp"
click node_config "https://github.com/ptsfdtz/pendulum/blob/main/src/config/Config.cpp"
click node_homing "https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/HomeCenterController.cpp"
click node_encoder_cal "https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/MotorEncoderCalibration.cpp"
click node_zero_cal "https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/MotorZeroCalibrator.cpp"
click node_single_ctrl "https://github.com/ptsfdtz/pendulum/blob/main/src/control/ReferenceLqrVelocityController.cpp"
click node_double_ctrl "https://github.com/ptsfdtz/pendulum/blob/main/src/control/DoublePendulumLqrController.cpp"
click node_ni_hw "https://github.com/ptsfdtz/pendulum/blob/main/src/hardware/NI6602.cpp"
click node_pci_hw "https://github.com/ptsfdtz/pendulum/blob/main/src/hardware/PCI1723.cpp"
click node_safety "https://github.com/ptsfdtz/pendulum/blob/main/src/safety/SafetyManager.cpp"
click node_logger "https://github.com/ptsfdtz/pendulum/blob/main/src/logging/AsyncLogger.cpp"
click node_sim_entry "https://github.com/ptsfdtz/pendulum/blob/main/matlab/run_pendulum.m"
click node_single_model "https://github.com/ptsfdtz/pendulum/tree/main/matlab/single_pendulum"
click node_double_model "https://github.com/ptsfdtz/pendulum/tree/main/matlab/double_pendulum"
click node_sim_engines "https://github.com/ptsfdtz/pendulum/tree/main/matlab"
click node_results "https://github.com/ptsfdtz/pendulum/tree/main/matlab"
click node_native_model "https://github.com/ptsfdtz/pendulum/tree/main/matlab/native_simulink"
click node_matlab_adapter "https://github.com/ptsfdtz/pendulum/tree/main/matlab/hardware"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cpp_console,node_config,node_homing,node_encoder_cal,node_zero_cal,node_single_ctrl,node_double_ctrl,node_ni_hw,node_pci_hw,node_safety,node_logger toneBlue
class node_sim_entry,node_single_model,node_double_model,node_sim_engines,node_results toneAmber
class node_native_model,node_matlab_adapter toneMint
class node_operator,node_physical toneIndigo
```

## Components

### C++ hardware control

- [Control console](https://github.com/ptsfdtz/pendulum/blob/main/src/tools/PendulumConsoleMain.cpp): `src/tools/PendulumConsoleMain.cpp`
- [Configuration](https://github.com/ptsfdtz/pendulum/blob/main/src/config/Config.cpp): `src/config/Config.cpp`
- [Home and center](https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/HomeCenterController.cpp): `src/calibration/HomeCenterController.cpp`
- [Encoder calibration](https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/MotorEncoderCalibration.cpp): `src/calibration/MotorEncoderCalibration.cpp`
- [Motor zero calibration](https://github.com/ptsfdtz/pendulum/blob/main/src/calibration/MotorZeroCalibrator.cpp): `src/calibration/MotorZeroCalibrator.cpp`
- [Single-pendulum control](https://github.com/ptsfdtz/pendulum/blob/main/src/control/ReferenceLqrVelocityController.cpp): `src/control/ReferenceLqrVelocityController.cpp`
- [Double-pendulum control](https://github.com/ptsfdtz/pendulum/blob/main/src/control/DoublePendulumLqrController.cpp): `src/control/DoublePendulumLqrController.cpp`
- [NI encoder and limits](https://github.com/ptsfdtz/pendulum/blob/main/src/hardware/NI6602.cpp): `src/hardware/NI6602.cpp`
- [Analog output](https://github.com/ptsfdtz/pendulum/blob/main/src/hardware/PCI1723.cpp): `src/hardware/PCI1723.cpp`
- [Safety shutdown](https://github.com/ptsfdtz/pendulum/blob/main/src/safety/SafetyManager.cpp): `src/safety/SafetyManager.cpp`
- [Run logging](https://github.com/ptsfdtz/pendulum/blob/main/src/logging/AsyncLogger.cpp): `src/logging/AsyncLogger.cpp`

### MATLAB simulation

- [Simulation entry](https://github.com/ptsfdtz/pendulum/blob/main/matlab/run_pendulum.m): `matlab/run_pendulum.m`
- [Single-pendulum model](https://github.com/ptsfdtz/pendulum/tree/main/matlab/single_pendulum): `matlab/single_pendulum`
- [Double-pendulum model](https://github.com/ptsfdtz/pendulum/tree/main/matlab/double_pendulum): `matlab/double_pendulum`
- [Simulation engines](https://github.com/ptsfdtz/pendulum/tree/main/matlab): `matlab`
- [Run results](https://github.com/ptsfdtz/pendulum/tree/main/matlab): `matlab`

### MATLAB hardware

- [Native Simulink control](https://github.com/ptsfdtz/pendulum/tree/main/matlab/native_simulink): `matlab/native_simulink`
- [MATLAB hardware adapter](https://github.com/ptsfdtz/pendulum/tree/main/matlab/hardware): `matlab/hardware`

### Other components

- **Operator**
- **DAQ and pendulum**

## Connections

- Operator → Control console: starts control (evidence: `README.md`)
- Control console → Configuration: loads settings (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Home and center: runs homing (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Encoder calibration: uses calibration (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Motor zero calibration: uses calibration (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → NI encoder and limits: reads sensors (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Analog output: commands output (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Safety shutdown: registers shutdown (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Run logging: records events (evidence: `src/tools/PendulumConsoleMain.cpp`)
- Control console → Single-pendulum control: selects control
- Control console → Double-pendulum control: selects control
- Operator → Simulation entry: runs experiment (evidence: `README.md`)
- Simulation entry → Single-pendulum model: selects model (evidence: `README.md`)
- Simulation entry → Double-pendulum model: selects model (evidence: `README.md`)
- Simulation entry → Simulation engines: runs engine (evidence: `README.md`)
- Simulation entry → Run results: saves run (evidence: `README.md`)
- Operator → Native Simulink control: starts hardware model (evidence: `README.md`)
- Native Simulink control → DAQ and pendulum: controls hardware (evidence: `README.md`)
- Operator → MATLAB hardware adapter: starts hardware run (evidence: `README.md`)
- MATLAB hardware adapter → DAQ and pendulum: accesses hardware (evidence: `README.md`)
