How sushimanz/arcade-marquee-manager works
1. What this repo is
This is an ESP32 firmware project for driving a HUB75 LED matrix marquee and cycling through a set of visual demos/games. It is built as a PlatformIO / Arduino project, not a general-purpose application.
2. Top-level runtime boundary
The firmware entrypoint is src/main.ino. That sketch is the orchestration layer: it initializes the display hardware, selects or schedules demos, and runs the active demo logic. There is no separate backend, UI server, or network subsystem in this repo.
3. Display hardware subsystem
The core hardware dependency is the vendored driver in lib/MatrixPanelDriver. It includes ESP32-HUB75-MatrixPanel-I2S-DMA plus Adafruit_GFX, which together provide the drawing API and the ESP32 I2S/DMA transport to the matrix panels. This is the key boundary between firmware logic and physical LEDs.
4. Global configuration layer
src/definitions.h centralizes board/display constants such as panel resolution, chain size, and shared values used by all demos. The README makes clear this is the place where panel geometry is adapted for different matrix sizes. This file is the main compile-time configuration boundary.
5. Demo framework architecture
The demos are not standalone sketches; they plug into a common framework under src/demos/utilities. That layer defines the demo abstraction and shared helpers, including the patterns for reset, primary loop, and optional exit condition. The main runtime treats each demo as a scheduled unit with a duration and lifecycle callbacks.
6. Per-demo isolation
Each animation/game lives in its own .cpp/.h pair under src/demos such as conway, pong, snake, maze, plasma, and others. Each demo owns its own state and rendering behavior, which keeps game logic isolated from the rest of the system. Shared state is intentionally minimized and, per the README, kept static inside the .cpp files.
7. Rendering/data flow
The basic flow is: demo logic computes frame state → demo issues draw calls → MatrixPanel driver pushes pixels to the HUB75 panels. Rendering is direct-to-display; there is no scene graph, compositor, or retained UI layer. The demos use dma_display methods like pixel drawing and fill operations to produce frames.
8. Important architectural constraint: write-only display
The README highlights a major limitation: the display API does not provide pixel reads, and it does not auto-clear the screen. That means demos must explicitly erase or redraw their content, and any demo that needs previous frame state must maintain its own buffer in memory. This strongly shapes the implementation style of animation and game demos.
9. Demo lifecycle model
Each demo is scheduled with a timer-based runtime and optional lifecycle hooks: reset before start, primary loop during execution, and optional exit condition. That makes the system more like a cooperative demo runner than a preemptive game engine. Timing and termination are managed at the demo-framework level, not inside a centralized scheduler.
10. Project boundaries and unused areas
include/ and test/ are present but marked unused, so the meaningful code path is concentrated in src/ and lib/. platformio.ini controls build/upload settings, while the external library folder is the main non-project dependency. There is no evidence of cloud services, storage, or other external runtime infrastructure.
11. Hardware assumptions
The code is targeted at an ESP32 driving a 256x64 HUB75 matrix, often implemented as four 64x64 panels chained horizontally. The architecture assumes side-by-side chaining and a 64-pixel-tall display; support for other geometries exists but is described as less tested. Power, wiring, and the ESP32-to-panel signal path are therefore part of the system boundary.
12. How to diagram it
A clear architecture diagram would show: PlatformIO build config → ESP32 firmware (main.ino) → demo framework/utilities → individual demo modules → MatrixPanel driver → HUB75 panels. definitions.h should be drawn as a shared configuration input across the firmware, and lib/MatrixPanelDriver as the hardware abstraction layer underneath all rendering.
Main entry points: demo.h Demo core · ESP32-HUB75-MatrixPanel-I2S-DMA.h Matrix driver · definitions.h Definitions · main.ino Main sketch
Components 16
Firmware
PlatformIO-managed ESP32 application code.
- PlatformIO · Build, upload, and environment settings.
platformio.ini - Main sketch · ESP32 runtime orchestrator for display setup and demo execution.
src/main.ino - Definitions · Central geometry and firmware constants.
src/definitions.h - Demo core · Common demo abstraction and scheduling hooks.
src/demos/utilities/demo.h - Demo utils · Shared demo support routines and timing helpers.
src/demos/utilities/demo_utilities.h
Demos
Individual marquee animations and games.
- Conway · Game of Life style demo.
src/demos/conway.h - Pong · Ball-and-paddle demo.
src/demos/pong.h - Snake · Grid-based snake game demo.
src/demos/snake.h - Maze · Maze generation and traversal demo.
src/demos/maze.h - Plasma · Procedural color field animation.
src/demos/plasma.h - Disco ball · Animated light effect demo.
src/demos/discoball.h - Other demos · Additional marquee demos such as IEEE, UB, linerocker, and paintrollers.
Display Lib
Vendored HUB75 drawing and transport stack.
- Matrix driver · HUB75 panel drawing API and ESP32 panel control.
lib/MatrixPanelDriver/src/ESP32-HUB75-MatrixPanel-I2S-DMA.h - Adafruit GFX · 2D drawing primitives used by demos and the driver.
lib/MatrixPanelDriver/src/Adafruit_GFX.h - DMA transport · Low-level ESP32 parallel output engine for panel refresh.
lib/MatrixPanelDriver/src/esp32_i2s_parallel_dma.h - HUB75 panels · Chained LED matrix hardware driven by the ESP32.
Connections 30
- PlatformIO → Main sketch: builds · PlatformIO compiles and uploads the firmware entrypoint.
- Definitions → Main sketch: configures · Shared geometry and constants shape startup and scheduling.
- Definitions → Demo core: feeds · Common constants are consumed by the demo framework.
- Definitions → Conway: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Pong: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Snake: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Maze: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Plasma: feeds · Demo geometry and limits depend on shared definitions.
- Definitions → Disco ball: feeds · Demo geometry and limits depend on shared definitions.
- Main sketch → Demo core: orchestrates · The sketch selects demos and advances their lifecycle.
- Main sketch → Matrix driver: initializes · Firmware sets up the display hardware boundary.
- Demo core → Demo utils: uses · Lifecycle logic relies on shared helper routines.
- Demo core → Conway: runs · The framework executes the Conway demo as a scheduled unit.
- Demo core → Pong: runs · The framework executes the Pong demo as a scheduled unit.
- Demo core → Snake: runs · The framework executes the Snake demo as a scheduled unit.
- Demo core → Maze: runs · The framework executes the Maze demo as a scheduled unit.
- Demo core → Plasma: runs · The framework executes the Plasma demo as a scheduled unit.
- Demo core → Disco ball: runs · The framework executes the Disco ball demo as a scheduled unit.
- Demo core → Other demos: runs · Additional demos plug into the same lifecycle model.
- Conway → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Pong → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Snake → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Maze → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Plasma → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Disco ball → Matrix driver: draws to · Demo rendering is issued directly to the panel driver.
- Other demos → Matrix driver: draws to · Remaining demos use the same direct rendering path.
- Matrix driver → Adafruit GFX: uses · The matrix driver exposes Adafruit GFX drawing primitives.
- Matrix driver → DMA transport: drives · The driver pushes pixels through the ESP32 DMA backend.
- DMA transport → HUB75 panels: refreshes · Parallel I2S/DMA output updates the physical LED panels.
- Adafruit GFX → HUB75 panels: renders · Drawing primitives ultimately target the hardware display.