# jjannix/esp8266-ws2811-leds architecture

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

- Interactive diagram: https://gitdiagram.com/jjannix/esp8266-ws2811-leds
- Repository: https://github.com/jjannix/esp8266-ws2811-leds

## Overview

##### Main Components
- Firmware (ESP8266)
- Firmware source files (in firmware/src) including the WS2811 DMA implementation, I²S registers and related components.
- UDP listener: The firmware receives LED animation commands over UDP on port 2711 with the custom MXP (matrix) protocol.
- Additional control for toggling the LED power supply via UDP commands on port 2777.
- Firmware leverages hardware-level DMA/I²S output, meaning it directly drives the LED strip while using the RX pin.

- Node.js Client Server
- Located in the client folder, where server.js is the entry point.
- Contains the animation files (in the client/animations subfolder) which process or generate timing data for the LED effects.
- The client/server handles live control and animation queue management, forwarding controls via UDP to the ESP8266.
- Configuration file (client/config.json) for setting up LED strip parameters.

- Web UI / Site
- Hosted under client/site with HTML, CSS, and JavaScript files.
- Provides the live preview for the LED strip (livecontrol.html/js/css) and an additional page for managing the animation queue (queue.html/js/css).

- Hardware
- KiCad design files contained in the hardware directory detail the custom PCB design integrating the ESP8266 (ESP-03 module) with a Voltek SPEC7188B power supply.
- These designs illustrate how the ESP8266 is interfaced with the LED strip and the power circuitry that enables/disable LED power.

##### Relationships and Data/Control Flow
- That the Node.js client server sends UDP packets (over WiFi) to the ESP8266 running custom firmware.
- Flow of commands:
- From the web UI (user input via live control or queue management) to the client server.
- From the client server to the ESP8266 firmware (via UDP on port 2711 for animation data and on port 2777 for power control commands).
- That the ESP8266 firmware processes these UDP commands to drive the LED strip via DMA/I²S.
- Optionally, indicate feedback loops if there is any status or monitoring (even if it’s just LED indications).

##### Architectural Patterns / Design Principles
- Layered approach: a backend/firmware layer (embedded control) communicating with a front-end control layer (Node.js server + web interface).
- Use of a custom protocol (MXP over UDP) for communication and the real-time nature of LED control.
- Underline the separation of concerns: firmware handles low-level LED signal generation while the client server handles interactions and animations.

##### Technologies, Frameworks, and Libraries
- ESP8266 SDK / esp-open-sdk (for firmware build and flash as described in the README).
- Node.js and npm (client/server implementation).
- Bower (for managing client-side web dependencies).
- KiCad (for hardware/PCB design).
- UDP-based communication as the primary mechanism for control commands.

##### Final Touches
- Avoid oversimplification; include as many discrete components as is practical given the project’s structure (for example, splitting out the animation subsystem as a distinct element if needed).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Application Layer
    subgraph "Client/Application Layer"
        webui["Web UI - Live Control & Queue"]:::client
        server["Node.js Animation Server"]:::client
        animations["Animation Files (LED Effects)"]:::client
        config["Configuration File (LED Strip Params)"]:::client
    end

    %% Embedded Firmware Layer
    subgraph "Embedded Firmware Layer"
        firmware["ESP8266 Firmware (LED Driver & UDP Listener)"]:::embedded
        power["UDP Power Control (LED Power Toggle)"]:::embedded
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        pcb["Custom PCB Hardware Design (KiCad)"]:::hardware
        led["LED Strip (WS2811 via DMA/I²S)"]:::hardware
        psu["Voltek SPEC7188B PSU"]:::hardware
    end

    %% Data/Control Flow Arrows
    webui -->|"triggers"| server
    animations -->|"provides effect data"| server
    config -->|"provides strip settings"| server
    server -->|"UDP:2711 AnimationCmds"| firmware
    server -->|"UDP:2777 PowerCmds"| power
    firmware -->|"I²S/DMA LED Data"| led
    power -->|"Toggles LED Power"| psu
    pcb --- led
    pcb --- psu

    %% Click Events
    click firmware "https://github.com/jjannix/esp8266-ws2811-leds/blob/master/firmware/src/main.c"
    click power "https://github.com/jjannix/esp8266-ws2811-leds/blob/master/firmware/src/psu.c"
    click server "https://github.com/jjannix/esp8266-ws2811-leds/blob/master/client/server.js"
    click animations "https://github.com/jjannix/esp8266-ws2811-leds/tree/master/client/animations"
    click config "https://github.com/jjannix/esp8266-ws2811-leds/blob/master/client/config.json"
    click webui "https://github.com/jjannix/esp8266-ws2811-leds/tree/master/client/site"
    click pcb "https://github.com/jjannix/esp8266-ws2811-leds/tree/master/hardware"

    %% Styles
    classDef embedded fill:#FFA07A,stroke:#d62728,stroke-width:2px,color:#000;
    classDef client fill:#98FB98,stroke:#006400,stroke-width:2px,color:#000;
    classDef hardware fill:#87CEFA,stroke:#00008B,stroke-width:2px,color:#000;
```
