MoonModule

Source: MoonModule.h

FixedPin

struct FixedPin

src/core/module/MoonModule.h:116

A pad the silicon fixed, named by the signal it carries.

Public Attributes

uint8_t gpio

const char * role

MoonModule

class MoonModule

src/core/module/MoonModule.h:56

The base class for everything in the system, from effects and drivers to system services.

It is the one deliberate hierarchy, so the UI renders any module with no per-module UI code. The goal is the smallest possible base, since dozens load at once on a device without PSRAM.

Prior art: MoonLight's Node, a small base whose controls bind by reference.

Public Methods

inline void * operator new(size_t size) : Allocate in PSRAM where the platform offers it.

inline void operator delete(void * ptr) noexcept : Return the allocation above.

MoonModule() = default : A module starts enabled, with no children and no controls.

virtual inline ~MoonModule() : Release the children array, the children themselves being the caller's.

MoonModule(const MoonModule &) = delete : A module is identified by its place in the tree, so it is never copied.

MoonModule & operator=(const MoonModule &) = delete : Nor copy-assigned.

MoonModule(MoonModule &&) = delete : Nor moved, its children holding a pointer back to it.

MoonModule & operator=(MoonModule &&) = delete : Nor move-assigned.

virtual inline void setup() : One-time wiring, which by default sets up the children first.

virtual inline void tick() : The hot tick, which by default ticks every enabled child and times each.

virtual inline void tick20ms() : The periodic tick for UI and network work, which by default ticks the children.

virtual inline void tick1s() : The once-a-second tick for housekeeping, which by default ticks the children.

virtual inline void release() : Free everything this module holds, buffers and hardware alike, then the children.

inline void applyState() : Build or tear down each node by its own effective-enabled, which is the one lifecycle path.

virtual inline void onEnabled(bool) : React once to the enabled flag flipping, for a one-shot that is not building state.

virtual inline void onControlChanged(const char *) : React cheaply to one control changing, which runs on every change.

virtual inline bool affectsPrepare(const char *) const : Whether this control's change reshapes dimensions, and so triggers the build sweep.

virtual inline void defineControls() : Declare every control, purely and idempotently, since this is re-run whenever a Select changes.

virtual inline uint8_t fixedPins(FixedPin *, uint8_t) const : Report the pads this module drives that no control names, so the pin map sees them.

inline void rebuildControls() : Clear and rebuild this module's controls and its descendants', re-evaluating what is hidden.

inline uint32_t schemaSignature() const : Hash the schema across this subtree, excluding values, so a resync fires only on a real change.

inline void mixSchema(uint32_t & h) const : Mix this node's schema into the running hash, then its children's.

inline void clearControlsRecursive() : Clear this module's controls and every descendant's.

virtual inline void prepare() : Build this node's derived state for the current controls, the acquire half of the lifecycle.

virtual inline bool firstOutputRgb(uint8_t) const : Read the first output light as RGB, or false where this module has no output.

inline const char * name() const : This module's human label, which the user may rename.

inline void setName(const char * n) : Set the label, truncating it to the buffer.

inline const char * typeName() const : The stable factory key, which lives in flash rather than per instance.

inline void setTypeName(const char * tn) : Set the factory key, which must have static lifetime.

inline bool enabled() const : This module's own enabled flag, which ignores its ancestors.

inline void setEnabled(bool e) : Set the flag, firing the transition hook only on a real change.

virtual inline bool respectsEnabled() const : Whether the enabled flag gates this module's ticks, which a system module declines.

inline bool effectivelyEnabled() const : True unless this module or a gating ancestor is disabled, which the lifecycle keys off.

virtual inline bool appearsInUi() const : Whether this module shows in the UI, which a pure engine with no controls declines.

inline bool dirty() const : Whether this module's state has been touched since the last save.

inline void markDirty() : Mark the state touched, which the persistence layer observes.

inline void clearDirty() : Clear the mark, once the state has been written.

inline MoonModule * parent() const : This module's parent, or null at the top level.

inline void setParent(MoonModule * p) : Set the parent, which the child mutators do.

inline void markWiredByCode() : Mark this module as wired by code, so a file that predates it cannot trim it away.

inline bool isWiredByCode() const : Whether the boot wiring created this module, rather than a file or the user.

inline ControlList & controls() : This module's controls, which its own defineControls fills.

inline const ControlList & controls() const : The controls, for a reader such as the serializer.

inline bool readBool(const char * name, bool dflt) const : Read a boolean control by name, or the given default where it is absent.

inline uint8_t readUint8(const char * name, uint8_t dflt) const : Read a byte-backed control by name, or the given default where it is absent.

virtual inline ModuleRole role() const : Role for type identification (no RTTI needed).

virtual inline const char * tags() const : Emoji tags for the module picker, beyond the chip the UI derives from the role.

virtual inline const char * acceptsChildRoles() const : The roles this module accepts as children, which is what the add-child picker offers.

virtual inline bool userEditable() const : Whether the user may delete or replace this module, which a load-bearing child declines.

virtual inline bool appliesConfigLive() const : Whether a written config may re-apply live, which a module with one-shot setup declines.

virtual inline void quiesce() : Park any worker of this module's that reads the tree, returning once it is idle.

inline void quiesceForMutation() : Park both workers that read the tree, which every structural mutator calls first.

inline bool addChild(MoonModule * child) : Append a child, growing the array on demand.

inline bool removeChild(MoonModule * child) : Remove a child, which the caller then releases and deletes.

inline MoonModule * replaceChildAt(uint8_t i, MoonModule * fresh) : Swap in a fresh child at this position, returning the old one for the caller to delete.

inline bool moveChildTo(MoonModule * child, uint8_t newIndex) : Move a child to an absolute position, the siblings between shifting toward the gap.

inline uint8_t childCount() const : How many children this module holds.

inline MoonModule * child(uint8_t i) const : One child by index, or null past the end.

inline size_t classSize() const : This module's instance size, which registration sets once.

inline void setClassSize(size_t s) : Record the instance size, which the factory does at registration.

inline size_t dynamicBytes() const : The heap this module has allocated, which its build sets.

inline void setDynamicBytes(size_t b) : Record the heap total, for a module that allocates outside a scratch buffer.

inline const char * status() const : The short message this module wants the user to see, or null for none.

inline Severity severity() const : How much that message matters.

inline void setStatus(const char * msg, Severity sev = Severity::Status) : Set the message, whose storage the caller owns since the slot does not copy.

inline void clearStatus() : Clear the message.

inline uint32_t tickTimeUs() const : Average microseconds per tick over the last second, which parents measure for children.

inline void addAccumUs(uint32_t us) : Add one tick's time to the running total.

inline void publishTiming(uint32_t frameCount) : Average the accumulated time into the published figure, then recurse.

Public Static Methods

static inline void setSchemaChangedHook(SchemaChangedFn fn) : Install the hook that resyncs clients after a schema change.

static inline void setQuiesceRenderHook(QuiesceRenderFn fn) : Install the hook that stops the render worker before a structural mutation.

static inline void notifySchemaChanged() : Fire the resync directly, for a change the control rebuild does not cover.

static inline void notifyQuiesceRender() : Stop the render worker directly, for a mutation that frees memory outside the child array.

Public Types

enum Severity : How much a status message matters, which picks the icon the UI shows.

Value	Description
Status	ℹ️ neutral info, current state ("connected")
Warning	⚠️ silent degradation ("buffer reduced")
Error	❌ something failed ("WiFi auth failed")

using SchemaChangedFn = void(*)() : The schema-changed hook's type, a function pointer so core needs no web-layer include.

using QuiesceRenderFn = void(*)() : The quiesce-render hook's type, the same decoupling from the light domain.

More info

The lifecycle

setup and release bracket a module's life, and three tick rates run between them. defineControls declares the controls, and prepare builds derived state. That is what makes every config change apply live, with no reboot. Controls bind by reference, so persisted values land before any setup runs.

Parent and child

Modules form a tree of parents and children, with no arbitrary graph. The children array and its four mutators live once here, never overridden. It starts empty, so a leaf allocates nothing, and grows on demand. Children are told apart by role, which is also how a container filters them.

Enabled, and self-reporting

Every module carries an enabled flag, and each decides what disabled means. A system module ignores it, so the user cannot lock themselves out. Each module reports its instance size, its heap, and its tick time.

Friends

friend class ScratchBufferBase