How ubieee/arcade-marquee-manager works
1. What this repository is
- This is a PlatformIO-based ESP32 firmware project for driving a HUB75 LED matrix marquee and cycling through a set of visual demos/games.
- It is not a conventional app with request/response flow; the architecture is a single embedded runtime that continuously renders to the matrix panel hardware.
2. Top-level split: app code vs. vendored display library
- The repository has two main code boundaries:
- src/ contains the project’s own firmware logic and all demos.
- lib/MatrixPanelDriver/ contains a vendored ESP32 HUB75 DMA display library plus its bundled Adafruit GFX dependency.
- The app code depends on that library for all panel I/O, pixel drawing, text, and DMA-driven refresh.
3. Runtime entry point and orchestration
- src/main.ino is the application entry point and likely owns the ESP32 Arduino lifecycle (setup/loop).
- The main loop’s job is to initialize the display, select or advance demos, and call the currently active demo function(s) repeatedly.
- The README implies demos are selected from a central registry rather than discovered dynamically.
4. Demo framework as the core application subsystem
- src/demos/utilities/demo.h and demo.cpp appear to define the demo abstraction used throughout the project.
- Each demo is represented by a Demo struct containing:
- the main render/update function,
- a runtime duration,
- an optional reset function,
- an optional exit-condition function.
- This makes the system time-sliced and function-pointer driven, with the framework managing when a demo starts, runs, and exits.
5. Demo registry and lifecycle
- The README describes a vector of Demo entries in demo.cpp, meaning the active demo list is centralized there.
- Lifecycle is:
- optional reset,
- repeated primary loop execution,
- optional exit check before each iteration,
- automatic termination when the configured time elapses.
- This is the main control-flow boundary in the project: demos do not own the full program, they are scheduled by the demo manager.
6. Individual demo modules
- src/demos/ contains the actual visual/program demos:
- IEEE, UB, discoball, linerocker, maze, paintrollers, plasma, pong, snake, conway.
- Each demo is split into a .cpp and .h pair and is expected to expose no-parameter functions that the registry can call.
- Some demos are simple animation loops; others are interactive or stateful mini-games.
7. Shared demo utilities
- src/demos/utilities/ holds common code reused by multiple demos.
- Based on the README and file names, this layer likely includes the Demo struct definition, common demo helpers, and shared timing/state helpers.
- This prevents each demo from reimplementing its own scheduling or boilerplate.
8. Hardware abstraction and global display access
- Demos talk to the panel through a shared global display object, referenced in the README as dma_display of type MatrixPanel_I2S_DMA.
- The display library boundary is important:
- demos call methods such as pixel drawing, fills, text, and color conversion,
- the library handles HUB75 signaling and DMA refresh on ESP32.
- The project uses global externs for hardware access and colors, which keeps demo signatures simple but couples demos to the display runtime.
9. Configuration and display geometry
- src/definitions.h is the central configuration file for panel dimensions and other shared constants.
- The README highlights that the code assumes a left-to-right chained panel layout and uses values like PANEL_TOTAL_X, PANEL_RES_Y, PANEL_RES_X, and PANEL_CHAIN.
- This file is the architectural boundary for hardware portability: changing panel geometry is meant to happen here, not inside each demo.
10. Rendering model and state handling
- The architecture is immediate-mode drawing against a hardware-backed framebuffer-like interface, but with an important limitation: there is no built-in getPixel.
- As a result, demos that need simulation state over time must maintain their own buffers or internal state, as seen in the README’s reference to conway.cpp.
- This means the project mixes:
- pure animation demos that redraw every frame,
- stateful simulations that track their own world model.
11. Build and deployment environment
- The project is built with PlatformIO and deployed to an ESP32.
- The external runtime environment matters architecturally because the code is compiled as Arduino-style embedded firmware, not desktop software.
- Serial monitoring and upload are part of the operational workflow, but the core runtime remains device-local once flashed.
12. Non-active folders and project boundaries
- include/ and test/ are present but marked unutilized in the README, so they do not currently participate in the architecture.
- This reinforces that the live system is concentrated in src/ plus the vendored matrix driver under lib/.
13. How to think about the system diagram
- The clean architecture view is:
- ESP32 firmware runtime at the center,
- demo scheduler dispatching into one of many demo modules,
- shared utilities/config providing constants and demo scaffolding,
- display driver library as the hardware I/O boundary,
- HUB75 matrix panels as the external physical output device.
- The main data flow is one-way: demo logic generates visual state and pushes it into the display driver, which streams it to the LED matrix.
Main entry points: ESP32-HUB75-MatrixPanel-I2S-DMA.h Matrix driver · demo.cpp Demo manager · definitions.h Display config · demos Animations
Components 14
Firmware
Project-owned ESP32 Arduino firmware and demo logic
- Main loop · ESP32 setup/loop orchestration for the marquee runtime
src/main.ino - Display config · Shared geometry and hardware constants for the chained matrix layout
src/definitions.h - Demo API · Function-pointer based demo abstraction with timing and lifecycle hooks
src/demos/utilities/demo.h - Demo manager · Central registry and lifecycle control for the active demo sequence
src/demos/utilities/demo.cpp - Demo helpers · Common helper declarations reused by multiple demos
src/demos/utilities/demo_utilities.h - Helper impl · Shared demo support routines and utility implementations
src/demos/utilities/demo_utilities.cpp - Animations · Visual demo modules such as IEEE, UB, discoball, linerocker, plasma, and paintrollers
src/demos - Games · Interactive/stateful demos such as maze, pong, and snake
src/demos - Conway · Stateful cellular automaton demo that maintains its own world state
src/demos/conway.cpp
Display Library
Vendored HUB75 DMA display stack and bundled graphics dependency
- Matrix driver · ESP32 HUB75 panel driver used for drawing, text, and DMA refresh
lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h - GFX layer · Bundled Adafruit GFX compatibility layer used by the display driver
lib/MatrixPanelDriver/src/Adafruit_GFX.h - Virtual panel · Panel mapping abstraction for chained matrix layouts
lib/MatrixPanelDriver/src/ESP32-VirtualMatrixPanel-I2S-DMA.h - DMA engine · Low-level I2S parallel DMA implementation for continuous LED refresh
lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h
Hardware
Physical LED matrix output device
- LED matrix · Physical chained HUB75 LED matrix marquee output
Connections 20
- Main loop → Display config: reads · Uses shared panel geometry and constants
- Main loop → Demo manager: runs · Initializes the system and drives demo execution
- Demo manager → Demo API: uses · Schedules demos through the common demo interface
- Demo manager → Demo helpers: calls · Depends on shared helper declarations
- Demo helpers → Helper impl: implemented by · Helper declarations are defined in the utility implementation
- Demo manager → Animations: dispatches · Selects and advances visual animation demos
- Demo manager → Games: dispatches · Selects and advances interactive game demos
- Demo manager → Conway: dispatches · Schedules the Conway simulation demo
- Animations → Matrix driver: draws via · Renders frames through the shared matrix display object
- Games → Matrix driver: draws via · Uses the display driver for pixels, text, and clears
- Conway → Matrix driver: draws via · Pushes simulation output to the hardware display
- Animations → Display config: uses · Relies on panel geometry and color constants
- Games → Display config: uses · Relies on panel geometry and color constants
- Conway → Display config: uses · Relies on panel geometry and color constants
- Matrix driver → GFX layer: wraps · Builds on the bundled Adafruit GFX layer
- Matrix driver → Virtual panel: maps · Supports chained panel addressing and layout mapping
- Matrix driver → DMA engine: refreshes with · Streams frame data through the DMA backend
- DMA engine → LED matrix: drives · Outputs HUB75 signals to the physical matrix panels
- Virtual panel → LED matrix: targets · Describes the chained physical panel arrangement
- Helper impl → Matrix driver: supports · Provides shared drawing or runtime helpers that assume the display API