How shim06/anemoia-esp32 works
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.