# harris170/fake-microcontroller-emulator architecture

> Architecture diagram of the GitHub repository harris170/fake-microcontroller-emulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harris170/fake-microcontroller-emulator
- Repository: https://github.com/harris170/fake-microcontroller-emulator

## Overview

##### Project Type and Purpose
- This is a C++-based microcontroller emulator (STM32) with a small C stub CLI (“nob”) that automates building and running your firmware in simulation.
- You write firmware (e.g. `blinking_task`) against a provided MCU API; the emulator simulates CPU, memory, peripherals (GPIO), and high-level components (LED).

##### File Structure
- Top-level “nob.c/.h”: CLI stub that invokes `g++` to compile the emulator + firmware.
- `include/`: Public headers defining the emulator’s API
- `microcontroller/…` (memory, GPIO, MCU lifecycle)
- `components/…` (LED wrapper)
- `source/`: Emulator implementation files (`main.cpp`, `microcontroller.cpp`, `gpio.cpp`, `component.cpp`)
- `firmware/`: Example firmware (declares and implements `blinking_task`)
- `examples/`: Additional firmware snippets for testing (e.g. `led_shift.hpp`)
- Build output placed under `build/` by `nob.exe`.

##### Key README Insights
- Build flow:
1. `gcc -o nob nob.c` → produces `nob.exe`
2. `./nob.exe` → invokes `g++` on emulator + firmware, outputs `fake_microcontroller_emulator.exe` in `build/`
- Runtime API:
- `mcu::flash_program(entry_fn)`
- `mcu::boot_system()`
- `mcu::start_execution()`
- Firmware instantiates peripherals (e.g. `LED status_led`) which auto-wire to GPIO pins.

##### Main Components
a. Build Layer
- “nob.exe” CLI (C)
- Build System (g++) → generates emulator binary + linked firmware
b. Emulator Engine
- MCU Core (lifecycle management)
- Memory Model (flash, registers)
- GPIO Subsystem (CRH, ODR registers)
- Component Layer (LED class)
c. Firmware Module
- `firmware.cpp/.hpp` (e.g. `blinking_task`)
- Example code under `examples/`
d. Console Output (simulated peripheral I/O)

##### Relationships & Interactions
- Compile-time:
nob.exe → invokes g++ → links emulator engine + firmware → `fake_microcontroller_emulator.exe`
- Run-time:
1. Emulator starts → calls `flash_program(blinking_task)` → writes entry into flash model
2. `boot_system()` sets up registers and initial state
3. `start_execution()` enters firmware loop
4. Firmware calls `GPIOA->ODR ^= …`; Component layer intercepts and prints `[Status LED] PIN13 -> ON/OFF`
5. Sleep emulated via `std::this_thread::sleep_for`

##### Architectural Patterns & Principles
- Modular layering: Build stub / core emulator / firmware
- Dependency inversion: Firmware code depends only on abstract headers (`include/`)
- Registration pattern: Components auto-register with low-level peripheral models
- Clear separation of compile-time vs. simulation-time responsibilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Layer
    subgraph "Build Layer"
        CLI["nob.exe CLI Stub"]:::orange
        GPP["g++ Invocation"]:::orange
        CLI -->|"invokes"| GPP
    end
    GPP -->|"compiles"| EmulatorBIN["fake_microcontroller_emulator.exe"]:::orange

    %% Emulator Engine
    subgraph "Emulator Engine"
        ENTRY["Emulator Entry Point\nmain.cpp"]:::blue
        MC["MCU Core"]:::blue
        MEM(("Memory Model\n(Flash, Registers)")):::blue
        GPIO["GPIO Subsystem\n(CRH, ODR)"]:::blue
        COMP["Component Layer\n(LED Wrapper)"]:::blue
        ENTRY -->|"calls start"| MC
        MC -->|"manages lifecycle"| MEM
        MC -->|"controls"| GPIO
        GPIO -.->|"register write events"| COMP
    end
    EmulatorBIN -->|"runs"| ENTRY

    %% Firmware & I/O
    subgraph "Firmware Module & Console Output"
        FW["Firmware Module\nblinking_task"]:::green
        EX1["Example Firmware\nled_blink.hpp"]:::green
        EX2["Example Firmware\nled_shift.hpp"]:::green
        CON["Console Output"]:::grey
        MC -->|"flash_program()"| FW
        MC -->|"boot_system()"| MC
        MC -->|"start_execution()"| FW
        FW -->|"writes to GPIO"| GPIO
        COMP -->|"prints status"| CON
    end

    %% Click Events
    click CLI "https://github.com/harris170/fake-microcontroller-emulator/blob/main/nob.c"
    click CLI "https://github.com/harris170/fake-microcontroller-emulator/blob/main/nob.h"
    click ENTRY "https://github.com/harris170/fake-microcontroller-emulator/blob/main/source/main.cpp"
    click MC "https://github.com/harris170/fake-microcontroller-emulator/blob/main/include/microcontroller/microcontroller.hpp"
    click MC "https://github.com/harris170/fake-microcontroller-emulator/blob/main/source/microcontroller.cpp"
    click MEM "https://github.com/harris170/fake-microcontroller-emulator/blob/main/include/microcontroller/memory.hpp"
    click MEM "https://github.com/harris170/fake-microcontroller-emulator/blob/main/source/microcontroller.cpp"
    click GPIO "https://github.com/harris170/fake-microcontroller-emulator/blob/main/include/microcontroller/gpio.hpp"
    click GPIO "https://github.com/harris170/fake-microcontroller-emulator/blob/main/source/gpio.cpp"
    click COMP "https://github.com/harris170/fake-microcontroller-emulator/blob/main/include/components/component.hpp"
    click COMP "https://github.com/harris170/fake-microcontroller-emulator/blob/main/include/components/led.hpp"
    click COMP "https://github.com/harris170/fake-microcontroller-emulator/blob/main/source/component.cpp"
    click FW "https://github.com/harris170/fake-microcontroller-emulator/blob/main/firmware/firmware.hpp"
    click FW "https://github.com/harris170/fake-microcontroller-emulator/blob/main/firmware/firmware.cpp"
    click EX1 "https://github.com/harris170/fake-microcontroller-emulator/blob/main/examples/led_blink.hpp"
    click EX2 "https://github.com/harris170/fake-microcontroller-emulator/blob/main/examples/led_shift.hpp"

    %% Styles
    classDef orange fill:#f96,stroke:#333,stroke-width:1px;
    classDef blue fill:#9cf,stroke:#333,stroke-width:1px;
    classDef green fill:#9f9,stroke:#333,stroke-width:1px;
    classDef grey fill:#ccc,stroke:#333,stroke-width:1px;
```
