# shim06/anemoia-esp32 architecture

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

- Interactive diagram: https://gitdiagram.com/shim06/anemoia-esp32
- Repository: https://github.com/shim06/anemoia-esp32

## Overview

**Anemoia-ESP32** is an **embedded firmware application** (Arduino/ESP32) that runs a **Nintendo Entertainment System (NES) emulator** on bare metal-ish hardware (ESP32 + TFT + SD + audio amp + controllers/buttons). It’s not a client/server system; the “system” is a **single device** with multiple peripherals, and the key architecture is the **emulation core + device I/O + UI loop**.

##### Read the file tree as the real architecture map
Top-level key files:
- **`Anemoia-ESP32.ino`**: firmware entry point (Arduino sketch). This is where the **main loop**, initialization of peripherals, and top-level orchestration typically lives.
- **`config.h`**: build-/board-level configuration (pins, options, feature toggles).
- **`platform.txt`**: custom compiler flags/optimizations (important “build architecture” detail).
- **`Anemoia-ST7789.h`, `Anemoia-TFT-Parallel.h`**: display setup/config for TFT_eSPI (hardware binding).

Source structure:
- **`src/core/*`**: the emulator “console” implementation:
- `cpu6502.*` (CPU)
- `ppu2C02.*` (graphics)
- `apu2A03.*` (audio)
- `bus.*` (address bus / memory map / routing)
- `cartridge.*` (ROM parsing, PRG/CHR, header, etc.)
- `mapper.*` + `mappers/mapper00x.*` (bank switching implementations; extensibility point)
- **`src/ui.*`**: on-device UI (game selector menu, overlays, etc.)
- **`src/controller.*`**: input subsystem abstraction (buttons, NES/SNES pads, PS1/PS2 pads)

External dependencies (from README):
- **Arduino ESP32 core v3.2.1**
- **SdFat** (microSD filesystem + ROM loading)
- ESP32 audio output path (likely DAC/PWM/I2S depending on implementation)

##### Main App / Orchestrator
- Source: `Anemoia-ESP32.ino`
- Responsibilities: init HW, load ROM, run emulation loop, coordinate UI vs gameplay, timing.
##### UI Subsystem
- Source: `src/ui.cpp/.h`
- Responsibilities: file select menu, rendering UI to display, user navigation.
##### Input Subsystem
- Source: `src/controller.cpp/.h`
- Responsibilities: abstract multiple controller types into “NES controller state” (A/B/Start/Select/D-pad).
##### Storage / ROM Loader
- External: SdFat
- Responsibility: enumerate `.nes` files, load ROM bytes to cartridge.
##### Display Output
- External: TFT_eSPI + setup headers (`Anemoia-ST7789.h`)
- Responsibility: take PPU output (frame) and push to TFT.
##### Audio Output
- Source: likely fed from `src/core/apu2A03.*`
- Responsibility: mix/convert APU samples → ESP32 audio pin output → amplifier.
##### Emulation Core
- Source: `src/core/*`
- Responsibility: accurate-ish NES behavior and timing.

**Key relationships to show:**
- Main App calls:
- UI (menu mode)
- ROM Loader → Cartridge
- Emulation Core step/tick/frame
- Input Subsystem feeds:
- Emulation Core (controller state into bus/memory-mapped input registers)
- UI (menu navigation)
- Emulation Core produces:
- Video frames → Display Output
- Audio samples → Audio Output

This is where accuracy matters most, and your file tree gives you the exact components.

- **Bus (`bus.*`)** – central hub: routes CPU reads/writes to RAM, PPU registers, APU registers, cartridge space, controller registers, etc.
- **CPU 6502 (`cpu6502.*`)** – executes instructions; accesses bus.
- **PPU 2C02 (`ppu2C02.*`)** – generates pixels; accesses bus/cartridge CHR via mapping; triggers NMI/IRQ to CPU via bus.
- **APU 2A03 (`apu2A03.*`)** – generates audio samples; interacts with CPU writes (sound registers).
- **Cartridge (`cartridge.*`)** – holds PRG/CHR data; owns Mapper instance.
- **Mapper interface (`mapper.*`)** – abstraction for bank switching and address translation.
- **Concrete mappers (`mappers/mapper000,001,002,003,004,069`)** – implementations.

- CPU ⇄ Bus: “mem read/write”
- PPU ⇄ Bus: “register access, DMA, NMI/IRQ signaling”
- APU ⇄ Bus/CPU: “audio registers, IRQ (if used)”
- Bus ⇄ Cartridge/Mapper: “PRG/CHR address translation, bank switching”
- Cartridge → Mapper00x: “polymorphic mapper selection by ROM header”
- PPU → Video Frame Buffer: “rendered frame”
- APU → Audio Buffer: “sample stream”

**Important pattern to explicitly annotate:**
- **“Bus-centric architecture”**: CPU/PPU/APU do not directly read cartridge memory; they go through Bus which delegates to Cartridge/Mapper.
- **“Mapper plugin strategy”**: `mapper.*` + `mappers/*` is a classic Strategy/Polymorphism extensibility point. Call that out as the primary compatibility mechanism.

##### If in menu
- UI renders menu → TFT
- On selection: load ROM via SdFat → Cartridge → instantiate Mapper
##### Else in game
- Run emulation for one frame (or N cycles):
- CPU step cycles
- PPU step (typically multiple PPU cycles per CPU cycle)
- APU step/mix samples
- handle interrupts (NMI/IRQ)
- Present frame: PPU framebuffer → TFT_eSPI push
- Output audio buffer → GPIO25/audio path

**Annotate performance choices from README:**
- “~60.098 FPS NTSC, 1 frame skip” (represent as “frame pacing / frame-skip policy” in Main loop)
- “no PSRAM required” (implies memory layout is tightly controlled)

Concrete guidance:
1. **Hardware peripherals**
2. **Firmware / platform libraries**
3. **Emulation core**

- **Protocol / bus**: “SPI”, “GPIO”, “controller serial protocol”, etc.
- **Data type**: “ROM bytes”, “PRG/CHR”, “framebuffer (RGB565?)”, “PCM samples”
- **Timing**: “per frame”, “per CPU cycle”, “buffered”

Use consistent component name + file mapping in small text, e.g.:
- “CPU 6502 (src/core/cpu6502.*)”
- “PPU 2C02 (src/core/ppu2C02.*)”
- “UI (src/ui.*)”

##### Don’t forget the “build/deploy architecture” callout (specific to this repo)
- Arduino IDE toolchain
- ESP32 Arduino core **v3.2.1** requirement
- Custom `platform.txt` for compiler flags/optimizations
This is unusually important here because performance is a primary project goal, and the repo explicitly modifies build flags.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% 1) HARDWARE CONTEXT
%% =======================
subgraph "Hardware Context (Physical Peripherals)"
direction TB

U["User"]:::external

subgraph "Input Devices"
direction TB
BTN["Tactile Buttons (GPIO)"]:::hardware
NESPAD["NES/SNES Controller (latch/clock/data)"]:::hardware
PSPAD["PS1/PS2 Controller (attention/command/clock/data)"]:::hardware
end

ESP32HW["ESP32 Dev Board"]:::hardware

TFT["TFT Display (ST7789/ILI9341 via SPI or Parallel)"]:::hardware
SDMOD["microSD Module (SPI)"]:::hardware
SDCARD[(".nes ROM Files (microSD card content)")]:::storage
AUD["Audio Out (GPIO25) → Amp + Speaker"]:::hardware

U -->|"button_presses"| BTN
U -->|"controller_input"| NESPAD
U -->|"controller_input"| PSPAD

BTN -->|"GPIO_levels"| ESP32HW
NESPAD -->|"serial_protocol"| ESP32HW
PSPAD -->|"serial_protocol"| ESP32HW

ESP32HW -->|"SPI_or_parallel_pixels"| TFT
ESP32HW <-->|"SPI_block_reads"| SDMOD
SDMOD <-->|"FAT_files"| SDCARD
ESP32HW -->|"PCM_or_PWM_or_DAC_samples"| AUD
end

%% =======================
%% 2) FIRMWARE SUBSYSTEMS
%% =======================
subgraph "Firmware (Arduino/ESP32) — Subsystems"
direction TB

APP["Main App / Orchestrator\n(init, mode switch, timing, frame pacing)"]:::app
CFG["Build/Board Configuration\n(pins, feature toggles)"]:::config

subgraph "Platform + Libraries"
direction TB
ARDUINO["Arduino-ESP32 Core v3.2.1"]:::platform
SDFAT["SdFat (filesystem + ROM loading)"]:::platform
TFTLIB["TFT_eSPI (display driver + draw primitives)"]:::platform
end

subgraph "App Subsystems"
direction TB
UI["UI Subsystem\n(menu, overlays, navigation)"]:::app
INPUT["Input Subsystem\n(controller abstraction → NES buttons)"]:::app
DISP["Display Output\n(PPU frame → TFT push)"]:::app
AUDIOOUT["Audio Output\n(APU samples → ESP32 audio pin)"]:::app
ROMLOADER["Storage / ROM Loader\n(enumerate & load .nes)"]:::app
end

CORE["Emulation Core"]:::core

APP -->|"reads_pins_options"| CFG
APP -->|"polls_inputs"| INPUT
APP -->|"menu_mode"| UI
APP -->|"game_mode_tick"| CORE
APP -->|"frame_pacing_~60.098fps\n+frame_skip_policy"| CORE

UI -->|"menu_navigation"| INPUT
UI -->|"draws_UI"| DISP

ROMLOADER -->|"uses"| SDFAT
DISP -->|"uses"| TFTLIB
APP -->|"uses"| ARDUINO

CORE -->|"video_framebuffer_(RGB565?)"| DISP
CORE -->|"audio_sample_stream"| AUDIOOUT

ROMLOADER -->|"ROM_bytes"| CORE
end

%% Bridge: firmware to hardware (context)
INPUT -->|"GPIO_reads / controller_protocol"| ESP32HW
DISP -->|"pixels_over_SPI_or_parallel"| TFT
ROMLOADER <-->|"SPI_to_SD"| SDMOD
AUDIOOUT -->|"GPIO25_audio"| AUD

%% =======================
%% 3) EMULATOR CORE COMPONENTS
%% =======================
subgraph "Emulation Core (NES) — Bus-Centric Architecture"
direction TB

BUS["Bus\n(address decode, memory map routing)"]:::core
CPU["CPU 6502"]:::core
PPU["PPU 2C02 (Graphics)"]:::core
APU["APU 2A03 (Audio)"]:::core

CART["Cartridge\n(ROM parsing, PRG/CHR storage)"]:::core
MAPPERIF["Mapper Interface (Strategy)"]:::mapper

subgraph "Concrete Mappers (Strategy Implementations)"
direction TB
M000["Mapper 000"]:::mapperimpl
M001["Mapper 001"]:::mapperimpl
M002["Mapper 002"]:::mapperimpl
M003["Mapper 003"]:::mapperimpl
M004["Mapper 004"]:::mapperimpl
M069["Mapper 069"]:::mapperimpl
end

VFB[("Video Frame Buffer")]:::buffer
ABUF[("Audio Buffer")]:::buffer

CPU <-->|"mem_read/write_per_CPU_cycle"| BUS
PPU <-->|"register_access_DMA\nNMI/IRQ_signaling"| BUS
APU <-->|"audio_register_writes\nIRQ_optional"| BUS

BUS <-->|"PRG/CHR_reads_writes\naddress_translation"| CART
CART -->|"selects_mapper_by_ROM_header"| MAPPERIF
MAPPERIF -->|"polymorphic_dispatch"| M000
MAPPERIF -->|"polymorphic_dispatch"| M001
MAPPERIF -->|"polymorphic_dispatch"| M002
MAPPERIF -->|"polymorphic_dispatch"| M003
MAPPERIF -->|"polymorphic_dispatch"| M004
MAPPERIF -->|"polymorphic_dispatch"| M069

PPU -->|"rendered_frame_per_frame"| VFB
APU -->|"mixed_samples_buffered"| ABUF

VFB -->|"push_to_TFT"| DISP
ABUF -->|"output_to_audio_pin"| AUDIOOUT

INPUT -->|"controller_state→memory_mapped_input_regs"| BUS

NOTE1["Note: Bus-centric routing\nCPU/PPU/APU access cartridge via Bus → Cartridge → Mapper"]:::note
NOTE2["Note: Mapper plugin strategy\nPrimary compatibility mechanism for bank switching"]:::note
NOTE1 -.-> BUS
NOTE2 -.-> MAPPERIF
end

%% =======================
%% 4) RUNTIME / FRAME FLOW
%% =======================
subgraph "Runtime (Per Frame / Mode Flow)"
direction TB

START["Loop Start"]:::runtime
POLL["Poll Input\n(controller.* normalize buttons)"]:::runtime
MODE{"Menu Mode?"}:::runtime
RENDERUI["UI: Render Menu / Overlays"]:::runtime
SELECT{"ROM Selected?"}:::runtime
LOAD["Load ROM via SdFat\n→ Cartridge + Mapper init"]:::runtime
EMUL["Emulate One Frame\nCPU step + PPU step + APU mix\nhandle NMI/IRQ"]:::runtime
PRESENT["Present Frame\nPPU framebuffer → TFT_eSPI push"]:::runtime
SOUND["Output Audio\nAPU buffer → GPIO25 path"]:::runtime

START -->|"per_loop"| POLL
POLL --> MODE
MODE -->|"yes"| RENDERUI
RENDERUI --> SELECT
SELECT -->|"yes"| LOAD
SELECT -->|"no"| START
LOAD -->|"enter_game_mode"| START

MODE -->|"no"| EMUL
EMUL --> PRESENT
PRESENT --> SOUND
SOUND -->|"next_frame"| START

PERF["Perf Notes:\n~60.098 FPS NTSC, 1 frame skip\nno PSRAM required"]:::note
PERF -.-> EMUL
end

%% =======================
%% 5) BUILD / TOOLCHAIN CALLOUT
%% =======================
subgraph "Build / Toolchain (Performance-Critical)"
direction TB
IDE["Arduino IDE / Toolchain"]:::build
PLAT["Custom platform.txt\n(compiler flags/optimizations)"]:::build
IDE -->|"uses"| ARDUINO
IDE -->|"applies"| PLAT
end

%% =======================
%% Click Events (from component_mapping)
%% =======================
click APP "https://github.com/shim06/anemoia-esp32/blob/main/Anemoia-ESP32.ino"
click CFG "https://github.com/shim06/anemoia-esp32/blob/main/config.h"
click PLAT "https://github.com/shim06/anemoia-esp32/blob/main/platform.txt"
click UI "https://github.com/shim06/anemoia-esp32/blob/main/src/ui.cpp"
click INPUT "https://github.com/shim06/anemoia-esp32/blob/main/src/controller.cpp"
click CORE "https://github.com/shim06/anemoia-esp32/tree/main/src/core/"
click CPU "https://github.com/shim06/anemoia-esp32/blob/main/src/core/cpu6502.cpp"
click PPU "https://github.com/shim06/anemoia-esp32/blob/main/src/core/ppu2C02.cpp"
click APU "https://github.com/shim06/anemoia-esp32/blob/main/src/core/apu2A03.cpp"
click BUS "https://github.com/shim06/anemoia-esp32/blob/main/src/core/bus.cpp"
click CART "https://github.com/shim06/anemoia-esp32/blob/main/src/core/cartridge.cpp"
click MAPPERIF "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mapper.cpp"
click M000 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper000.cpp"
click M001 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper001.cpp"
click M002 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper002.cpp"
click M003 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper003.cpp"
click M004 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper004.cpp"
click M069 "https://github.com/shim06/anemoia-esp32/blob/main/src/core/mappers/mapper069.cpp"
click TFT "https://github.com/shim06/anemoia-esp32/blob/main/Anemoia-ST7789.h"
click TFTLIB "https://github.com/shim06/anemoia-esp32/blob/main/Anemoia-ST7789.h"
click DISP "https://github.com/shim06/anemoia-esp32/blob/main/Anemoia-TFT-Parallel.h"
click ROMLOADER "https://github.com/shim06/anemoia-esp32/blob/main/src/core/cartridge.cpp"
click AUDIOOUT "https://github.com/shim06/anemoia-esp32/blob/main/src/core/apu2A03.cpp"

%% =======================
%% Styles
%% =======================
classDef hardware fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827;
classDef storage fill:#F3F4F6,stroke:#6B7280,stroke-dasharray: 3 2,color:#111827;

classDef platform fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A;
classDef build fill:#E0F2FE,stroke:#0369A1,stroke-width:1px,color:#082F49;

classDef app fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#052E16;
classDef config fill:#ECFCCB,stroke:#4D7C0F,stroke-width:1px,color:#1A2E05;

classDef core fill:#FFEDD5,stroke:#C2410C,stroke-width:1px,color:#431407;
classDef mapper fill:#F3E8FF,stroke:#7C3AED,stroke-width:1px,color:#2E1065;
classDef mapperimpl fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#2E1065;

classDef buffer fill:#FEF9C3,stroke:#A16207,stroke-width:1px,color:#422006;

classDef runtime fill:#FFF7ED,stroke:#9A3412,stroke-width:1px,color:#431407;
classDef external fill:#FFFFFF,stroke:#111827,stroke-width:1.5px,color:#111827;
classDef note fill:#FFF1F2,stroke:#9F1239,stroke-dasharray: 4 3,color:#500724;
```
