# aralkaramogh/dc-microgrid-black-start-controller architecture

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

- Interactive diagram: https://gitdiagram.com/aralkaramogh/dc-microgrid-black-start-controller
- Repository: https://github.com/aralkaramogh/dc-microgrid-black-start-controller

## Overview

This repository develops a DC microgrid black-start controller in two forms: a MATLAB digital twin for scenario and Monte Carlo evaluation, and ESP32 firmware intended to run the controller on hardware. The principal workflow detects blackout, authorises an operator, checks sensors and SOC, soft-starts the bus, connects solar, restores loads by priority, then monitors and protects normal operation. The graph includes simulation evaluation and hardware telemetry branches. Firmware calls are supported by the shown excerpts; MATLAB subsystem relationships are limited to README-documented workflow and capabilities, since MATLAB source was not sampled.

Main entry points: [`run_all.m`](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/run_all.m) (Simulation Runner), [`firmware/src/main.cpp`](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/main.cpp) (RTOS Task Runtime), [`firmware/src/fsm.cpp`](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/fsm.cpp) (Black-Start FSM), [`src/plant_fallback.m`](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/plant_fallback.m) (Circuit Plant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Digital Twin"]
  node_params["Microgrid Parameters"]
  node_scenarios["Scenarios<br/>[define_scenarios.m]"]
  node_pv_model["PV Model<br/>[pv_model.m]"]
  node_plant["Circuit Plant<br/>[plant_fallback.m]"]
  node_matlab_fsm["Black-Start FSM<br/>[blackstart_fsm.m]"]
  node_matlab_restoration["Load Restoration"]
  node_matlab_step["Restoration Step"]
  node_runner["Simulation Runner<br/>[run_all.m]"]
end

subgraph group_firmware_control["Firmware Control"]
  node_firmware_main["RTOS Task Runtime<br/>[main.cpp]"]
  node_firmware_fsm["Black-Start FSM<br/>[fsm.cpp]"]
  node_restoration["Load Restoration<br/>[restoration.cpp]"]
  node_protection["Fault Protection<br/>[protection.cpp]"]
  node_config["Controller Configuration<br/>[config.h]"]
end

subgraph group_firmware_io["Firmware I/O"]
  node_sensors["Sensor Acquisition<br/>[sensors.cpp]"]
  node_rfid["RFID Authentication<br/>[auth_rfid.cpp]"]
  node_pwm["Soft-Start PWM<br/>[pwm_soft_start.cpp]"]
  node_telemetry["Serial Telemetry<br/>[telemetry.cpp]"]
end

subgraph group_evaluation["Evaluation"]
  node_kpi["KPI Evaluation<br/>[kpi_compute.m]"]
  node_montecarlo["Monte Carlo<br/>[montecarlo.m]"]
  node_sil_export["SIL Vectors"]
  node_hardware_capture["Serial Capture<br/>[capture_serial.py]"]
  node_hw_compare["Hardware Comparison"]
end

node_operator(("Operator"))
node_solar_battery_loads["Microgrid Hardware"]

node_operator -->|"presents card"| node_rfid
node_solar_battery_loads -.->|"provides readings"| node_sensors
node_firmware_main -->|"reads and calibrates"| node_sensors
node_firmware_main -->|"ticks"| node_firmware_fsm
node_firmware_main -->|"polls"| node_rfid
node_firmware_main -->|"prints telemetry"| node_telemetry
node_firmware_main -->|"sets duty"| node_pwm
node_firmware_main -->|"applies gates"| node_solar_battery_loads
node_firmware_fsm -->|"checks faults"| node_protection
node_firmware_fsm -->|"steps loads"| node_restoration
node_rfid -->|"injects auth"| node_firmware_fsm
node_scenarios -->|"defines cases"| node_runner
node_runner -->|"runs scenarios"| node_plant
node_runner -->|"evaluates runs"| node_kpi
node_runner -->|"runs variations"| node_montecarlo
node_runner -->|"exports readings"| node_sil_export
node_plant -->|"simulates control"| node_matlab_fsm
node_matlab_fsm -->|"uses restoration logic"| node_matlab_restoration
node_matlab_restoration -.->|"delegates steps"| node_matlab_step
node_pv_model -->|"plots PV curves"| node_runner
node_params -->|"supplies parameters"| node_runner
node_sil_export -->|"replays sensor vectors"| node_firmware_fsm
node_telemetry -->|"streams serial data"| node_hardware_capture
node_hardware_capture -->|"provides capture"| node_hw_compare
node_plant -->|"provides simulation"| node_hw_compare
node_config -->|"sets thresholds"| node_firmware_fsm

click node_params "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/params/dc_microgrid_params.m"
click node_scenarios "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/define_scenarios.m"
click node_pv_model "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/pv_model.m"
click node_plant "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/plant_fallback.m"
click node_matlab_fsm "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/blackstart_fsm.m"
click node_matlab_restoration "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/load_restoration_engine.m"
click node_matlab_step "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/load_restoration_engine_step.m"
click node_runner "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/run_all.m"
click node_kpi "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/kpi_compute.m"
click node_montecarlo "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/montecarlo.m"
click node_sil_export "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/export_sil_vectors.m"
click node_firmware_main "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/main.cpp"
click node_firmware_fsm "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/fsm.cpp"
click node_restoration "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/restoration.cpp"
click node_protection "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/protection.cpp"
click node_sensors "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/sensors.cpp"
click node_rfid "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/auth_rfid.cpp"
click node_pwm "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/pwm_soft_start.cpp"
click node_telemetry "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/telemetry.cpp"
click node_config "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/include/config.h"
click node_hardware_capture "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/tools/capture_serial.py"
click node_hw_compare "https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/tools/compare_hw_vs_sim.m"

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_params,node_scenarios,node_pv_model,node_plant,node_matlab_fsm,node_matlab_restoration,node_matlab_step,node_runner toneBlue
class node_firmware_main,node_firmware_fsm,node_restoration,node_protection,node_config toneAmber
class node_sensors,node_rfid,node_pwm,node_telemetry toneMint
class node_kpi,node_montecarlo,node_sil_export,node_hardware_capture,node_hw_compare toneRose
class node_operator,node_solar_battery_loads toneIndigo
```

## Components

### Digital Twin

- [Microgrid Parameters](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/params/dc_microgrid_params.m): `params/dc_microgrid_params.m`
- [Scenarios](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/define_scenarios.m): `src/define_scenarios.m`
- [PV Model](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/pv_model.m): `src/pv_model.m`
- [Circuit Plant](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/plant_fallback.m): `src/plant_fallback.m`
- [Black-Start FSM](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/blackstart_fsm.m): `src/blackstart_fsm.m`
- [Load Restoration](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/load_restoration_engine.m): `src/load_restoration_engine.m`
- [Restoration Step](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/load_restoration_engine_step.m): `src/load_restoration_engine_step.m`
- [Simulation Runner](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/run_all.m): `run_all.m`

### Firmware Control

- [RTOS Task Runtime](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Black-Start FSM](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/fsm.cpp): `firmware/src/fsm.cpp`
- [Load Restoration](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/restoration.cpp): `firmware/src/restoration.cpp`
- [Fault Protection](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/protection.cpp): `firmware/src/protection.cpp`
- [Controller Configuration](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/include/config.h): `firmware/include/config.h`

### Firmware I/O

- [Sensor Acquisition](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/sensors.cpp): `firmware/src/sensors.cpp`
- [RFID Authentication](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/auth_rfid.cpp): `firmware/src/auth_rfid.cpp`
- [Soft-Start PWM](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/pwm_soft_start.cpp): `firmware/src/pwm_soft_start.cpp`
- [Serial Telemetry](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/firmware/src/telemetry.cpp): `firmware/src/telemetry.cpp`

### Evaluation

- [KPI Evaluation](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/kpi_compute.m): `src/kpi_compute.m`
- [Monte Carlo](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/montecarlo.m): `src/montecarlo.m`
- [SIL Vectors](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/src/export_sil_vectors.m): `src/export_sil_vectors.m`
- [Serial Capture](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/tools/capture_serial.py): `tools/capture_serial.py`
- [Hardware Comparison](https://github.com/aralkaramogh/dc-microgrid-black-start-controller/blob/master/tools/compare_hw_vs_sim.m): `tools/compare_hw_vs_sim.m`

### Other components

- **Operator**
- **Microgrid Hardware**

## Connections

- Operator → RFID Authentication: presents card (evidence: `README.md`)
- Microgrid Hardware → Sensor Acquisition: provides readings
- RTOS Task Runtime → Sensor Acquisition: reads and calibrates (evidence: `firmware/src/main.cpp`)
- RTOS Task Runtime → Black-Start FSM: ticks (evidence: `firmware/src/main.cpp`)
- RTOS Task Runtime → RFID Authentication: polls (evidence: `firmware/src/main.cpp`)
- RTOS Task Runtime → Serial Telemetry: prints telemetry (evidence: `firmware/src/main.cpp`)
- RTOS Task Runtime → Soft-Start PWM: sets duty (evidence: `firmware/src/main.cpp`)
- RTOS Task Runtime → Microgrid Hardware: applies gates (evidence: `firmware/src/main.cpp`)
- Black-Start FSM → Fault Protection: checks faults (evidence: `firmware/src/fsm.cpp`)
- Black-Start FSM → Load Restoration: steps loads (evidence: `firmware/src/fsm.cpp`)
- RFID Authentication → Black-Start FSM: injects auth (evidence: `firmware/src/auth_rfid.cpp`)
- Scenarios → Simulation Runner: defines cases (evidence: `README.md`)
- Simulation Runner → Circuit Plant: runs scenarios (evidence: `README.md`)
- Simulation Runner → KPI Evaluation: evaluates runs (evidence: `README.md`)
- Simulation Runner → Monte Carlo: runs variations (evidence: `README.md`)
- Simulation Runner → SIL Vectors: exports readings (evidence: `README.md`)
- Circuit Plant → Black-Start FSM: simulates control (evidence: `README.md`)
- Black-Start FSM → Load Restoration: uses restoration logic (evidence: `README.md`)
- Load Restoration → Restoration Step: delegates steps
- PV Model → Simulation Runner: plots PV curves (evidence: `README.md`)
- Microgrid Parameters → Simulation Runner: supplies parameters (evidence: `README.md`)
- SIL Vectors → Black-Start FSM: replays sensor vectors (evidence: `README.md`)
- Serial Telemetry → Serial Capture: streams serial data (evidence: `README.md`)
- Serial Capture → Hardware Comparison: provides capture (evidence: `README.md`)
- Circuit Plant → Hardware Comparison: provides simulation (evidence: `README.md`)
- Controller Configuration → Black-Start FSM: sets thresholds
