How rafags/airesp32 works
Project Type and Purpose
• This is an embedded full-system emulator: it ports the Apple I computer (6502 CPU, PIA I/O, WozMon + BASIC ROM, memory map) onto an ESP32 microcontroller using the Arduino framework.
• Purpose: cycle-accurate 6502 emulation driving keyboard/display I/O over UART at 115200 baud to recreate the Apple I experience.
File Structure
• Top-level sketch: airesp32.ino – Arduino entry point (setup()/loop())
• Modules, each with .c/.h or .cpp/.h:
• cpu6502.c/h – CPU core, fetch-decode-execute, cycle timing
• mc6821.c/h – PIA peripheral emulation for keyboard/display
• motherboard.c/h – address decoder, memory map of ROM/RAM/PIA
• terminal.cpp/h – UART interface, framing, line wrapping
• 6502.rom.h – embedded flash image of WozMon + BASIC
• No external services; FreeRTOS underlies Arduino but hidden by sketch.
Key Architecture Insights from README
• Single MCU hosts all components in an event loop.
• Data flow: CPU ↔ Memory Map ↔ (RAM | ROM | PIA) ↔ Terminal ↔ External PC terminal.
• Timing: CPU driven by micros() to match 1.023 MHz cycles.
• I/O via UART peripheral of ESP32 at 115200 baud.
• ESP32 MCU (Arduino Core)
• cpu6502 module
• motherboard module
• mc6821 PIA module
• terminal module (serial driver)
• RAM block (32 KB)
• ROM block (8 KB, 6502.rom.h)
• External Terminal App (minicom, PuTTY)
• cpu6502 “reads/writes” → motherboard
• motherboard “routes” reads/writes → RAM / ROM / PIA
• PIA “reads/writes” ↔ terminal module
• terminal module “TX/RX bytes” ↔ External Terminal
• Arduino Core “calls” cpu6502.step() in loop
c. Architectural Patterns and Principles:
• Modular emulation layers (CPU, bus, peripheral)
• Single-threaded event loop (Arduino loop()) with precise timing
• Memory-mapped I/O—classic Von Neumann pattern
• Static arrays for RAM/ROM to meet embedded constraints
d. Key Technologies:
• ESP32 UART driver (Arduino Serial)
• micros() for cycle timing
• C modules compiled under Arduino build system
Important Details to Capture
• The CPU’s dependency on micros() timing to enforce 1.023 MHz.
• The static memory allocation model (no dynamic malloc).
• The mapping ranges: 0x0000–0x7FFF (RAM), 0xD000–0xDFFF (PIA), 0xE000–0xFFFF (ROM).
• Serial port parameters (115200 8N1) as part of the I/O path.
• The main loop calling cpu6502_execute_cycle() and polling PIA/terminal.