Modules — User Reference¶
This page explains what modules are and how to use them from the UI. For the technical architecture behind modules, see the developer guide. To write your own module, see add-a-module.md.
What is a Module?¶
A Module is the unit of work in projectMM. Every running function — a light effect, a pixel blender, a WiFi connection, a system status reporter — is a module. Modules are:
- Added and removed at runtime — no reflashing needed.
- Configured through the UI — controls are rendered automatically from each module's schema.
- Stateful — their configuration (control values) is saved to the device and restored on next boot.
- Hierarchical — modules can have parent-child relationships. A child module's lifecycle is managed by its parent.
The standard light pipeline¶
The most common module arrangement for light output:
EffectsLayer (parent)
└─ SineEffectModule (child, writes pixels into EffectsLayer)
DriverLayer (blends all EffectsLayers)
└─ PreviewModule (shows the blended output in the browser)
- EffectsLayer — allocates the pixel buffer. One EffectsLayer per group of effects.
- Effect module (e.g. SineEffectModule) — writes RGB pixels into its EffectsLayer each tick.
- DriverLayer — blends all EffectsLayer outputs into a single frame.
- PreviewModule — streams the blended frame to the browser's WebGL canvas over WebSocket.
Module categories¶
| Category | Examples | Purpose |
|---|---|---|
effect |
SineEffectModule | Generates pixel data, writes into a EffectsLayer |
modifier |
BrightnessModifierModule | Reads pixel data, modifies it in-place |
layout |
EffectsLayer, DriverLayer | Owns pixel buffers, mediates data flow |
driver |
(future) | Sends pixel data to real hardware |
system |
SystemStatusModule | Reports device health; permanent on all platforms |
network |
NetworkModule, WifiStaModule, WifiApModule, EthernetModule | Network connectivity; permanent on ESP32 |
Module reference pages¶
Detailed per-module documentation:
- StatefulModule — base class for all modules
- ModuleManager — owns and manages all modules
- Key-Value Store — generic typed key-value store
- EffectsLayer — pixel buffer owner
- DriverLayer — blends producers
- GridLayout — 3D grid pixel layout
- SineEffectModule — RGB 2D sine effect
- RipplesEffectModule — radial ripple effect
- LinesEffectModule — sweeping lines effect
- BrightnessModifierModule — per-pixel brightness modifier
- PreviewModule — WebGL canvas preview
- SystemStatusModule — heap, CPU, and health reporting
- NetworkModule — device name and MAC address; puts radio into AP+STA mode
- WifiStaModule — connects to an existing Wi-Fi network (STA mode)
- WifiApModule — hosts an open Wi-Fi access point for recovery
- EthernetModule — Ethernet placeholder (not yet implemented)
Test status¶
Every module has automated test coverage. Current results:
- Unit Test Results — 205 tests across 16 feature areas; run on every build
- Deploy Summary — live pipeline tests on PC and ESP32 hardware
Each module reference page below includes a Test coverage section linking directly to the relevant test sections.
The enabled control¶
Every module has an enabled checkbox (added automatically). When unchecked:
- The module's loop() is skipped each tick.
- The module stays in memory — its configuration and state are preserved.
- Children of a disabled parent are also skipped.
This is useful for temporarily disabling an effect without removing it.