# tort32/pxmatrix architecture

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

- Interactive diagram: https://gitdiagram.com/tort32/pxmatrix
- Repository: https://github.com/tort32/pxmatrix

## Overview

##### Project Type and Purpose
- This is an embedded library (Arduino/PlatformIO) for driving monochrome LED matrix panels on ESP8266, ESP32 and AVR-based boards.
- It provides hardware-abstraction APIs, scan routines (via timer interrupts), gamma correction, double buffering, and supports both hardware and software SPI.

##### File Structure Analysis
- Top-level files:
- README.md, LICENSE, .gitignore – project metadata
- library.properties – Arduino/PlatformIO library manifest
- Directories:
- src/ – core headers and implementation files (PxMatrix.h, PxMatrix_impl.h, plus AVR/STL/gamma variants)
- examples/ – application sketches demonstrating basic usage, chaining, buffering
- No “backend/frontend” split – single codebase targeted at embedded controllers.

##### README Highlights
- Hardware targets: ESP32, ESP8266, AVR (Arduino UNO)
- Wiring modes: parallel rows vs zigzag chaining
- Performance notes: risks of blocking calls, jitter, recommendation to use hardware SPI and high-speed controllers for larger matrices.

##### Components
a. Application Layer (Example Sketches)
- Sketch logic (setup(), loop(), drawFrame())
- Calls to PxMatrix APIs: begin(), display(), showBuffer(), setMatrixSize(), etc.
b. PxMatrix Library Core
- Public API (PxMATRIX class)
- Internals: scan routine, buffer management (ACTIVE/INACTIVE), gamma tables, SPI abstraction
c. Hardware Abstraction
- Hardware SPI driver vs software bit-banged SPI
- GPIO pin mappings: DATA, CLOCK, LATCH pins, address lines A, B (and optional B2, B3)
d. Timer Interrupt Subsystem
- Timer peripheral configuration (timerBegin, timerAttachInterrupt)
- ISR: display_updater() invoking display() to shift scan lines
e. LED Matrix Panel
- Shift registers (HUB12/HUB08 interface)
- Daisy-chain or zigzag row chaining
f. Physical Wiring
- MCU pins → module chain → power rails
- Optional ground pairing, noise mitigation

##### Relationships and Data Flow
- Application Sketch → invokes PxMatrix API → configures matrix, triggers rendering
- PxMatrix Core → on timer ISR → scans display buffer line by line → writes data via SPI abstraction
- SPI (hardware/software) → toggles shift registers → parallel address lines control row selection
- Double Buffering: Sketch writes to inactive buffer → calls showBuffer() → buffers swap → next ISR rendering uses updated frame

##### Architectural Patterns & Principles
- Hardware Abstraction Layer (HAL) separating SPI implementation from core logic
- Interrupt-driven scanning (Producer/Consumer: main code produces frames, ISR consumes frames)
- Modular layering: API layer → core scan logic → HAL → physical hardware

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        HELLO["Hello Sketch"]:::application
        LIFE["Life Sketch"]:::application
        SCAN["Scan Sketch"]:::application
    end

    subgraph "Library Core"
        PxAPI["PxMATRIX Class"]:::library
        ScanEngine["Scan Engine\n(Buffer Mgmt & ISR)"]:::library
        Gamma["Gamma Correction Module"]:::library
        AVR["AVR/STL Variant"]:::library
    end

    subgraph "HAL - SPI Drivers"
        HW_SPI["Hardware SPI Driver"]:::hal
        SW_SPI["Software SPI Driver"]:::hal
    end

    subgraph "Hardware Components"
        TIMER["Timer Module"]:::hardware
        GPIO["MCU GPIO Pins"]:::hardware
        ShiftReg["Shift Registers\n(HUB12/HUB08)"]:::hardware
    end

    LED["LED Matrix Panel"]:::phys

    HELLO -->|"calls begin(), setMatrixSize(), showBuffer()"| PxAPI
    LIFE -->|"calls begin(), setMatrixSize(), showBuffer()"| PxAPI
    SCAN -->|"calls begin(), setMatrixSize(), showBuffer()"| PxAPI
    HELLO -.->|"showBuffer() triggers buffer swap"| ScanEngine

    PxAPI -->|"uses gamma macros"| Gamma
    PxAPI -->|"platform adjustments"| AVR
    PxAPI --> ScanEngine

    TIMER -->|"ISR: display()"| ScanEngine

    ScanEngine -->|"writes data"| HW_SPI
    ScanEngine -->|"writes data"| SW_SPI

    HW_SPI -->|"toggles lines"| GPIO
    SW_SPI -->|"toggles lines"| GPIO

    GPIO --> ShiftReg
    ShiftReg --> LED

    click HELLO "https://github.com/tort32/pxmatrix/blob/main/examples/hello/hello.ino"
    click LIFE "https://github.com/tort32/pxmatrix/blob/main/examples/life/life.ino"
    click SCAN "https://github.com/tort32/pxmatrix/blob/main/examples/scan/scan.ino"
    click PxAPI "https://github.com/tort32/pxmatrix/blob/main/src/PxMatrix.h"
    click ScanEngine "https://github.com/tort32/pxmatrix/blob/main/src/PxMatrix_impl.h"
    click Gamma "https://github.com/tort32/pxmatrix/blob/main/src/PxMatrix_gamma.h"
    click AVR "https://github.com/tort32/pxmatrix/blob/main/src/PxMatrix_avr_stl.h"
    click LIB_CONF "https://github.com/tort32/pxmatrix/blob/main/library.properties"

    classDef application fill:#a8f0a1,stroke:#333,stroke-width:1px
    classDef library fill:#a1c4f0,stroke:#333,stroke-width:1px
    classDef hal fill:#f0c4a1,stroke:#333,stroke-width:1px
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef phys fill:#8b0000,stroke:#333,stroke-width:1px
```
