How tort32/pxmatrix works
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