# rafags/airesp32 architecture

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

- Interactive diagram: https://gitdiagram.com/rafags/airesp32
- Repository: https://github.com/rafags/airesp32

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ESP32 MCU (Arduino Core)"
        Sketch["airesp32.ino"]:::sketch
        CPUCore["cpu6502.c/.h"]:::cpu
        Bus["motherboard.c/.h"]:::bus
        PIA["mc6821.c/.h"]:::io
        Terminal["terminal.cpp/.h"]:::io
        ROM["6502.rom.h"]:::memory
        RAM["RAM (32 KB)"]:::memory
    end

    External["External Terminal App<br>(minicom / PuTTY)"]:::external

    Sketch -->|"loop: cpu6502_execute_cycle()"| CPUCore
    CPUCore -->|"reads/writes"| Bus
    Bus -->|"routes read/write"| RAM
    Bus -->|"routes read/write"| ROM
    Bus -->|"routes read/write"| PIA
    PIA <-->|"reads/writes"| Terminal
    Terminal <-->|"TX/RX bytes 115200 8N1"| External

    subgraph "Project Documentation"
        Docs["README.md"]:::external
        Lic["LICENSE"]:::external
    end

    click Sketch "https://github.com/rafags/airesp32/blob/main/airesp32.ino"
    click CPUCore "https://github.com/rafags/airesp32/blob/main/cpu6502.c"
    click CPUCore "https://github.com/rafags/airesp32/blob/main/cpu6502.h"
    click Bus "https://github.com/rafags/airesp32/blob/main/motherboard.c"
    click Bus "https://github.com/rafags/airesp32/blob/main/motherboard.h"
    click PIA "https://github.com/rafags/airesp32/blob/main/mc6821.c"
    click PIA "https://github.com/rafags/airesp32/blob/main/mc6821.h"
    click Terminal "https://github.com/rafags/airesp32/blob/main/terminal.cpp"
    click Terminal "https://github.com/rafags/airesp32/blob/main/terminal.h"
    click ROM "https://github.com/rafags/airesp32/blob/main/6502.rom.h"
    click Docs "https://github.com/rafags/airesp32/blob/main/README.md"
    click Lic "https://github.com/rafags/airesp32/tree/main/LICENSE"

    classDef sketch fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef cpu fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef bus fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef memory fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef io fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
