# quantumjv/esp8266-ledmatrix-wifidisplay architecture

> Architecture diagram of the GitHub repository quantumjv/esp8266-ledmatrix-wifidisplay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantumjv/esp8266-ledmatrix-wifidisplay
- Repository: https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay

## Overview

##### Project type and purpose
- This is an embedded full-stack (firmware + web UI) project running on an ESP8266.
- Purpose: drive a MAX7219 LED matrix display over WiFi, letting users enter text and brightness through a browser-based captive-portal interface.

##### File structure
- Top level:
- ESP8266_LED_MATRIX_TEXT_DISPLAY.ino – main Arduino sketch (entry point)
- ESP8266_LED_Matrix_code.cpp – same logic in a .cpp for syntax highlighting
- README.md, LICENSE, Screenshots/ – documentation
- No separate “src” or “lib” folders; code is monolithic but separates concerns (WiFi setup, web server, display driver).

##### README for additional insights
- Uses MD_MAX72xx library for LED matrix control.
- Uses WiFiManager to handle captive-portal, WiFi credentials, fallback AP.
- Embedded HTTP server serves a small HTML/CSS UI.
- No external cloud services—entirely on-device.

a. Main components:
- Hardware layer:
– ESP8266 module (NodeMCU/Wemos)
– MAX7219-based LED matrix (4×8×8 segments)
– Power supply (3.3V or 5V + level shifter)
- Firmware/Software layer on ESP8266:
– WiFiManager module
– HTTP server module (serves HTML + handles form submissions)
– MD_MAX72xx driver module (controls LED matrix)
– Configuration/state manager (stores WiFi creds, brightness, last message)
- External clients:
– User’s browser on smartphone/computer
- Network:
– WiFi Access Point (ESP8266_AP) or Station mode to home router
b. Relationships and interactions:
1. On power-up, Firmware → WiFiManager: attempt STA connect ← credentials storage.
2. If STA fails or reset button used → WiFiManager spawns Captive Portal AP.
3. User’s browser ↔ HTTP server (ESP8266) over WiFi:
– GET / → serve HTML+CSS UI
– POST text/brightness → update internal state
4. Firmware loop reads state → MD_MAX72xx driver → LED matrix refresh.
5. After STA success, display IP on LED matrix.
c. Architectural patterns/design principles:
- Modular separation: network management vs. web UI vs. display driver.
- Event-driven loop in Arduino (setup/loop) managing state changes.
- Fallback pattern: STA mode → AP captive portal.
- Single-point HTTP server for control interface (no external HTTP frameworks).
d. Key technologies/frameworks/libraries:
- ESP8266 Arduino core (WiFi, hardware abstraction)
- MD_MAX72xx (LED matrix control)
- WiFiManager (WiFi provisioning + captive portal)
- Arduino webserver (ESP8266WebServer)
- HTML/CSS/JS (served from flash)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Network
    subgraph "User & Network"
        Browser["User Browser"]:::external
        Router["Home WiFi Router"]:::external
        AP["ESP8266 AP (Captive Portal)"]:::network
    end

    %% Documentation
    subgraph "Documentation"
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
        Screenshots["Screenshots/"]:::docs
    end

    %% Firmware Core & Modules
    subgraph "Firmware (ESP8266 Core)"
        Sketch["ESP8266_LED_MATRIX_TEXT_DISPLAY.ino"]:::core
        Cpp["ESP8266_LED_Matrix_code.cpp"]:::core
        Loop["Main Loop (setup()/loop())"]:::core
        Config["Credentials Store"]:::storage
        WiFiMgr["WiFiManager Module"]:::network
        HTTP["HTTP Server Module"]:::network
        Static["Static Asset Handler"]:::network
        Form["Form Processor"]:::network
        Driver["MD_MAX72xx Driver"]:::driver
    end

    %% Hardware Layer
    subgraph "Hardware"
        ESP8266["ESP8266 Module (NodeMCU)"]:::hardware
        Matrix["MAX7219 LED Matrix"]:::hardware
        Power["Power Supply"]:::hardware
    end

    %% Connections
    Browser -->|"HTTP GET/POST"| HTTP
    HTTP -->|"serve UI"| Static
    HTTP -->|"process form"| Form
    Sketch -->|integrates| WiFiMgr
    Sketch -->|integrates| HTTP
    Sketch -->|integrates| Driver
    Loop -->|calls provisioning| WiFiMgr
    WiFiMgr -->|reads/writes| Config
    WiFiMgr -->|"spawn AP on fail"| AP
    Loop -->|"SPI write"| Driver
    Driver -->|"drives"| Matrix
    ESP8266 <-->|"802.11 frames"| Router
    Loop -->|"display IP"| Matrix

    %% Click Events
    click Sketch "https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay/blob/main/ESP8266_LED_MATRIX_TEXT_DISPLAY.ino"
    click Cpp "https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay/blob/main/ESP8266_LED_Matrix_code.cpp"
    click README "https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay/blob/main/README.md"
    click LICENSE "https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay/tree/main/LICENSE"
    click Screenshots "https://github.com/quantumjv/esp8266-ledmatrix-wifidisplay/tree/main/Screenshots/"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#000
    classDef driver fill:#90EE90,stroke:#000
    classDef hardware fill:#98FB98,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef core fill:#D3D3D3,stroke:#000
    classDef storage fill:#DDA0DD,stroke:#000
    classDef docs fill:#F0E68C,stroke:#000
```
