Presets¶
A preset is a saved state brought back with one click: a look you liked, a geometry you wired, a hardware setup you got right. They live on the Control card as a grid of 64 pads. Saving, applying and changing one: Save, edit and apply a preset. The gallery: install from it and share in it.
Two different things are called a preset. The pads on the Control card are what people usually mean, and what follows is about those. The fixture profile under Drivers names which channel carries red or pan: see FixtureProfiles.
What a preset holds¶
A preset is a state document: the containers it sets, by name, with the modules and controls inside, the same document PATCH /api/state applies.
Saving from a pad captures one of four containers whole, chosen as a radio button:
| Capture | What it holds | What it is |
|---|---|---|
| Effects | the layer, its effects and modifiers | a look |
| Layouts | where the lights are | a geometry |
| Drivers | pins, brightness, outputs | a hardware setup |
| Services | sensors and bridges | a service configuration |
One container per save is what makes a look portable: an Effects preset applies on any board, because it carries no pin map. Add Drivers to it and it becomes a device snapshot tied to one rig's wiring, which is a different and much less shareable thing.
A secret stays out of a document, so a preset never carries a password. A preset written by hand, or added from elsewhere, can hold less than a container. This one sets only the palette and leaves the brightness, the pins and the running look alone:
Applying one¶
A saved container is a restore, not an overlay. It carries "$patch": "replace", so a preset carrying more modules than the device has adds them, and one describing fewer removes what it omits. That is what makes a pad reliable: what you saved is what comes back, rather than what you saved merged with whatever drifted since.
One active preset per container, so a layout preset and a look stay lit together. Applying a new look replaces only the look, and a palette preset holds the Drivers pad next to it. A pad is tinted by its container: layout blue, effects violet, driver green, service amber.
A restore changes the module tree, which pauses rendering while it runs, so a large preset stalls the lights for a moment. Every removal runs before any creation, so a module can move between layers under its own name.
Arranging the pads¶
A pad is a position, not a list entry: slot 14 stays slot 14 whether or not anything sits in it, and deleting slot 3 does not shuffle slot 4 into its place.
The order persists, stamped into each preset's own file, so a preset folder copied to another device brings its layout along.
Where they live¶
One file per preset, at /.config/presets/<name>.json, holding the document and its pad as "$slot". A name may use printable characters but no /, \ or ., up to 31 characters.
They ride along in a backup, which is how a rig's looks move to another device.
A preset file added, edited or removed in the File Manager shows on the pads at once.
In Home Assistant¶
Only Effects presets travel to Home Assistant, where they appear as the light entity's effect list over MQTT, or in the native preset dropdown through the WLED integration.
Layouts and Drivers presets are deliberately excluded: they rewire pins and geometry, and should not be reachable from something that believes it is choosing a color scheme. The restriction is enforced where a preset is applied, not only by leaving them out of the list. Setting that up is in Home automation.
When a preset refuses to apply¶
The card names the first failure and where it is, such as no such control at Effects.Layer.Noise.speed:
- It names a container, a module type or a role this device does not have. Found before anything changes, so nothing does.
- A control inside it is unknown here, or a value is out of range. Found as it is written, so what came before the failure stays applied.
- It was saved by an older MoonLight. Listed but not applied: a backup and restore converts it.
- The file is malformed. The live tree is untouched.