projectMM¶
Working name: projectMM (MM = MoonModules). Temporary name — may change before first release.
A cross-platform, open-source runtime for modular, loop-driven processes. Small units of work (Modules) with a setup()/loop()/teardown() lifecycle, scheduled as fast as possible across ESP32, Raspberry Pi, and PC.
The entry domain is light control — LEDs and other light sources, driven directly via GPIO or over a network (Art-NET, DDP, E1.31). The runtime is shaped to fit audio processing, sensor pipelines, and other repeating-process domains without modification.
Full docs: projectMM
Documentation¶
| Document | What it covers |
|---|---|
| architecture.md | Components, boundaries, concurrency model, state persistence, platform targets |
| design.md | Module lifecycle, naming, JSON UI description, frontend approach, backend language |
| deploy.md | Build, deploy, flash, test, and CI pipeline |
| standards-and-guidelines.md | Coding standards, anti-debt checklist, testing rules, AI workflow, contribution workflow |
| development/ | Development history: process, backlog, and release documents |
Why We Are Building This¶
projectMM is a deliberate restart from scratch — not a fork, not an extension, but a re-derivation from first principles. The reasons:
- AI changes the ball game. Code that used to be expensive to write is now cheap. Systems designed under the old cost model made trade-offs (monolithic modules, dense abstractions, implicit conventions) that no longer make sense. A codebase designed to be read and extended by AI agents looks different from one designed to minimize keystrokes for a human maintainer.
- Technical debt compounds. Every system we have shipped or contributed to eventually hit a wall where the cost of adding features exceeded the value delivered. Rather than paying that tax again on an inherited codebase, we want to start clean with explicit anti-debt practices baked into the process.
- Contribution friction is real. Past projects have been effectively single-maintainer despite being open source. We want to design the system — its code, its documentation, its module boundaries — so that a new contributor (human or AI) can make a meaningful change on day one.
- Cross-platform from the start. Previous projects started MCU-first and bolted on desktop support later, which never felt native. projectMM treats PC, Raspberry Pi, and ESP32 as peer targets from commit #1.
- The runtime shape is domain-agnostic by design. Light control (LEDs and other lights, via GPIO or network) is our entry domain, but the same module shape (setup/loop/teardown lifecycle, hot path, JSON-driven UI) fits audio processing, sensor pipelines, and other repeating-process domains.
Vision¶
Build a cross-platform, open-source runtime for modular, loop-driven processes — small units of work with a setup/loop/teardown lifecycle that the runtime schedules as fast as possible. The first domain is light control — LEDs and other light sources driven via GPIO or network protocols (Art-NET, DDP, E1.31); the runtime is designed so that audio processing, sensor pipelines, and other repeating-process domains fit the same shape.
Core Principles¶
- Understandable by humans and AI. Code is written to be read and extended, not just executed. If an AI agent struggles to contribute, a human probably will too.
- Minimal footprint. The base system runs well on the smallest classic ESP32. If a feature forces us above that budget, it is opt-in.
- Anti-debt by construction. We treat avoiding technical debt as a first-class design goal, not a cleanup task.
- Cross-platform from commit #1. PC, Raspberry Pi, and ESP32 are peer targets.
- Open community contributions. The project is designed to lower the barrier to a first meaningful contribution.
- Iterative development. Requirements and design evolve cycle by cycle, driven by questions and discoveries from the previous iteration.
- Generic runtime, specialized modules. The runtime does not know about lights. Light support is a set of modules, alongside (future) audio, sensor, and other modules.
The System in One Paragraph¶
projectMM is a module runtime. A Module is a unit of work with a setup() phase (allocate, register UI, subscribe to inputs), a loop() phase (do work, repeatedly, as fast as the runtime allows) and a teardown() phase (closing down). Modules register themselves with a scheduler that runs their loops on a hot path. Each Module also publishes a JSON description of its controls, which any frontend can render into a UI. Modules maintain (persistant) state and can be added and removed at runtime. The same runtime binary shape runs on ESP32, Raspberry Pi, and PC, with platform-specific modules providing I/O (GPIO, audio devices, network sockets, LED drivers, etc.).
Background¶
The people starting projectMM maintain two existing repositories under MoonModules:
- WLED-MM — a fork of WLED, used as a playground for new functionality that could not (or should not) land upstream.
- MoonLight — a from-scratch project built after WLED-MM hit architectural limits. MoonLight introduced the Node concept (see MoonLight nodes) and is a fork of ESP32-sveltekit for its UI system. See also why MoonLight exists.
What We Keep¶
- The setup/loop lifecycle per module, directly inspired by Arduino's
setup()/loop()— it is simple, everyone understands it, and it maps cleanly to both MCU and desktop runtimes. - The modular functionality idea, originally from WLED usermods, then refined into MoonLight Nodes and called Modules here.
- The idea of a JSON-defined UI per module, where the backend describes its controls and the frontend renders them.
- Clean teardown: a module that is removed cleans up everything it created.
What We Leave Behind¶
- Dependency on an upstream UI framework we do not control. MoonLight's dependency on ESP32-sveltekit tied its flash/heap budget to decisions made elsewhere and made classic ESP32 devices painful.
- Implicit conventions and undocumented design decisions. MoonLight has strong opinions that live in one maintainer's head, which is a known barrier to contribution.
- Monolithic frontend and backend builds that consume a large share of an ESP32's flash and memory before the application gets its first byte.
- "Nodes and noodles" as a user-facing metaphor. The runtime concept is valuable, but the graphical-noodles presentation was never delivered and the name constrains the mental model. We use the more generic term Module.