# jandelgado/jled architecture

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

- Interactive diagram: https://gitdiagram.com/jandelgado/jled
- Repository: https://github.com/jandelgado/jled

## Overview

This project is an embedded C++ library aimed at providing non-blocking, time‐driven LED effects (e.g., on/off, blink, breathe, candle, fade, and user-defined effects) for a wide range of hardware platforms (Arduino, ESP8266, ESP32, mbed, Raspberry Pi Pico, etc.). The file structure and README indicate that JLed is both a core library and a suite of examples and tests that demonstrate platform-independent usage via a thin hardware abstraction layer (HAL).

##### Main Components
- Library Core: At the heart of the project, you have files in the “src” directory (such as jled.h, jled_base.cpp/h, etc.) that implement the main LED effects and control logic.
- Hardware Abstraction Layer (HAL): Within “src,” there are several HAL implementations (arduino_hal.h, esp32_hal.cpp, esp8266_hal.h, mbed_hal.h, pico_hal.h) that isolate the platform-specific GPIO and timing functionality.
- Effect Evaluators: The core effect operations (Blink, Breathe, FadeOn, FadeOff, Candle, etc.) form a processing layer where the LED brightness function is calculated, scaled, possibly inverted, and then written to the hardware.
- Examples/Usage Layer: The “examples” folder holds sample sketches (for Arduino, mbed, custom HAL, etc.) demonstrating how users can leverage the library in real applications.
- Testing Framework: The “test” directory contains unit tests (including a mocked hardware layer and Catch2 framework) to verify correct behavior of LED effects and state transitions.

##### Depicting Relationships and Data Flow
- At the top level, the “User Application” or example sketches invoke the public API of the JLed library, constructing LED objects, configuring effects, and calling Update() in a loop.
- The Library Core then evaluates the configured effect for the current time; this is where different LED effect states (e.g., breathe, blink, fade) are calculated.
- The output is passed down to a “Signal Processing” stage where brightness values are scaled based on configured minimum and maximum brightness, and optionally inverted if LowActive is enabled.
- The processed brightness value is handed off to the respective HAL instance (Arduino, ESP8266, ESP32, mbed, Pico, etc.), which then directly manipulates the GPIO pins or PWM channels of the hardware.
- Additionally, the test components simulate this flow using mocked HAL implementations to verify that the correct output is sent under various conditions.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Core LED effect logic is separated from platform-specific details via the HAL. This encourages portability and ease of integration on multiple hardware platforms.
- Non-blocking Design: Emphasize that the library operates in a time-driven manner where repeated Update() calls progress the effect, without blocking the main loop.
- Testability: The existence of a comprehensive unit testing suite and use of mocks highlight a strong emphasis on modular, testable design.

- Then, clearly separate the hardware abstraction details where the effect’s result is adapted to specific MCU platforms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UA("User Application (Examples)"):::app
    CORE("JLed Core API"):::core
    EVAL("Effect Evaluator"):::effect
    PROC("PWM Scaling & Inversion"):::proc
    HAL("Hardware Abstraction Layer"):::hal
    GPIO("GPIO/PWM Output"):::hal
    TEST("Unit Test Suite (Catch2)"):::test

    UA -->|"calls"| CORE
    CORE -->|"evaluates"| EVAL
    EVAL -->|"processes"| PROC
    PROC -->|"forwards to"| HAL
    HAL -->|"controls"| GPIO
    CORE -- "tested by" --> TEST

    subgraph "Platform-Specific HALs"
        AHAL("Arduino HAL"):::hal
        ESP32("ESP32 HAL"):::hal
        ESP8266("ESP8266 HAL"):::hal
        MBED("mbed HAL"):::hal
        PICO("Pico HAL"):::hal
    end

    HAL -->|"selects"| AHAL
    HAL -->|"selects"| ESP32
    HAL -->|"selects"| ESP8266
    HAL -->|"selects"| MBED
    HAL -->|"selects"| PICO

    click UA "https://github.com/jandelgado/jled/tree/master/examples"
    click CORE "https://github.com/jandelgado/jled/blob/master/src/jled.h"
    click AHAL "https://github.com/jandelgado/jled/blob/master/src/arduino_hal.h"
    click ESP32 "https://github.com/jandelgado/jled/blob/master/src/esp32_hal.cpp"
    click ESP8266 "https://github.com/jandelgado/jled/blob/master/src/esp8266_hal.h"
    click MBED "https://github.com/jandelgado/jled/blob/master/src/mbed_hal.h"
    click PICO "https://github.com/jandelgado/jled/blob/master/src/pico_hal.h"
    click TEST "https://github.com/jandelgado/jled/tree/master/test"

    classDef app fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef effect fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef proc fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef hal fill:#ffd9b3,stroke:#333,stroke-width:2px;
    classDef test fill:#ccffff,stroke:#333,stroke-width:2px;
```
