# gurdeepsinghiet/esp32_bootloader architecture

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

- Interactive diagram: https://gitdiagram.com/gurdeepsinghiet/esp32_bootloader
- Repository: https://github.com/gurdeepsinghiet/esp32_bootloader

## Overview

This firmware turns an ESP32 into an SD-card emulator launcher and updater. On startup it mounts the card, then either checks root-level firmware/version files or scans emulator folders and presents a PS/2 menu. It compares versions, flashes changed firmware to the OTA app partition, and boots the selected emulator. Maintenance also supports downloading emulator files over Wi-Fi and extracting app images from merged binaries. Main-flow wiring is based on the sampled source and README; unsampled implementation details are not inferred.

Main entry points: [`src/main.cpp`](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp) (Boot Coordinator), [`src/render.h`](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/render.h) (Emulator Menu), [`src/extract.h`](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/extract.h) (Firmware Extractor), [`src/updater.h`](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/updater.h) (Online Updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and Flash"]
  node_main["Boot Coordinator<br/>[main.cpp]"]
  node_mount["SD Mount<br/>[main.cpp]"]
  node_version["Version Check<br/>[main.cpp]"]
  node_ota["OTA Flash<br/>[main.cpp]"]
  node_partitions[("ESP32 App Partitions")]
  node_launch["Emulator Boot<br/>[main.cpp]"]
end

subgraph group_card["Card and Configuration"]
  node_discover["Firmware Discovery<br/>[main.cpp]"]
  node_config["SD Configuration<br/>[rc.h]"]
end

subgraph group_interface["Display and Input"]
  node_menu["Emulator Menu<br/>[render.h]"]
  node_ps2["PS/2 Input<br/>[main.cpp]"]
  node_display["VGA Display<br/>[render.h]"]
end

subgraph group_maintenance["Emulator Maintenance"]
  node_updater["Online Updater<br/>[updater.h]"]
  node_extractor["Firmware Extractor<br/>[extract.h]"]
end

node_power(("Power On"))
node_operator(("Device Operator"))
node_sd[("SD Card")]
node_wifi(("Emulator Service"))

node_power -->|"starts"| node_main
node_main -->|"initializes"| node_mount
node_mount -->|"mounts"| node_sd
node_main -->|"loads settings"| node_config
node_config -->|"reads/writes"| node_sd
node_main -->|"scans firmware"| node_discover
node_discover -->|"reads files"| node_sd
node_main -->|"presents choices"| node_menu
node_menu -->|"polls keys"| node_ps2
node_operator -->|"presses keys"| node_ps2
node_menu -->|"draws interface"| node_display
node_main -->|"checks version"| node_version
node_version -->|"reads version"| node_sd
node_main -->|"flashes when changed"| node_ota
node_ota -->|"reads firmware"| node_sd
node_ota -->|"writes ota_0"| node_partitions
node_main -->|"boots selected app"| node_launch
node_launch -->|"selects app"| node_partitions
node_menu -->|"dispatches maintenance"| node_updater
node_menu -->|"dispatches extraction"| node_extractor
node_updater -.->|"requests catalog/files"| node_wifi
node_updater -->|"saves downloads"| node_sd
node_extractor -->|"reads merged images"| node_sd
node_extractor -->|"writes app and version"| node_sd
node_extractor -->|"reports progress"| node_display

click node_main "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_mount "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_discover "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_version "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_ota "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_launch "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_config "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/rc.h"
click node_menu "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/render.h"
click node_ps2 "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp"
click node_display "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/render.h"
click node_updater "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/updater.h"
click node_extractor "https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/extract.h"

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_main,node_mount,node_version,node_ota,node_partitions,node_launch toneBlue
class node_discover,node_config,node_sd toneAmber
class node_menu,node_ps2,node_display toneMint
class node_updater,node_extractor toneRose
class node_power,node_operator,node_wifi toneIndigo
```

## Components

### Boot and Flash

- [Boot Coordinator](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- [SD Mount](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- [Version Check](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- [OTA Flash](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- **ESP32 App Partitions**
- [Emulator Boot](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`

### Card and Configuration

- [Firmware Discovery](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- [SD Configuration](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/rc.h): `src/rc.h`

### Display and Input

- [Emulator Menu](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/render.h): `src/render.h`
- [PS/2 Input](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/main.cpp): `src/main.cpp`
- [VGA Display](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/render.h): `src/render.h`

### Emulator Maintenance

- [Online Updater](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/updater.h): `src/updater.h`
- [Firmware Extractor](https://github.com/gurdeepsinghiet/esp32_bootloader/blob/main/src/extract.h): `src/extract.h`

### Other components

- **Power On**
- **Device Operator**
- **SD Card**
- **Emulator Service**

## Connections

- Power On → Boot Coordinator: starts
- Boot Coordinator → SD Mount: initializes
- SD Mount → SD Card: mounts
- Boot Coordinator → SD Configuration: loads settings
- SD Configuration → SD Card: reads/writes
- Boot Coordinator → Firmware Discovery: scans firmware
- Firmware Discovery → SD Card: reads files
- Boot Coordinator → Emulator Menu: presents choices
- Emulator Menu → PS/2 Input: polls keys
- Device Operator → PS/2 Input: presses keys
- Emulator Menu → VGA Display: draws interface
- Boot Coordinator → Version Check: checks version
- Version Check → SD Card: reads version
- Boot Coordinator → OTA Flash: flashes when changed
- OTA Flash → SD Card: reads firmware
- OTA Flash → ESP32 App Partitions: writes ota_0
- Boot Coordinator → Emulator Boot: boots selected app
- Emulator Boot → ESP32 App Partitions: selects app
- Emulator Menu → Online Updater: dispatches maintenance
- Emulator Menu → Firmware Extractor: dispatches extraction
- Online Updater → Emulator Service: requests catalog/files
- Online Updater → SD Card: saves downloads
- Firmware Extractor → SD Card: reads merged images
- Firmware Extractor → SD Card: writes app and version
- Firmware Extractor → VGA Display: reports progress