Segment Coupling and Power Sequencing

Segment coupling

A relay can be coupled to a WLED segment so it follows that segment's on/off state - useful for cutting the actual supply power of an LED section when its segment is turned off in the UI. Per relay, the segment value is:

• -1 - not coupled (default; relay behaves as before)
• 0-31 - relay follows that segment: on when the segment is on (and global power is on), off otherwise

Master AC relay: relay 0 doubles as a dedicated master slot, meant for the AC-side trigger of the main power supply (the other relays typically switch DC MOSFET outputs). Enable it with the Enabled checkbox in its section on the settings page (or -D POWERMANAGER_MASTER=true for pre-built images) and pick its pin; while enabled it is on whenever any segment is on, and internally uses the reserved segment value 99 (only relay 0 may hold it). A master relay never switches off while any section relay is still on - the PSU is always the last to cut, and its delay-off-s counts from the moment the last section switched off. It defaults to a 5 second off-delay (PSU anti-cycling: quick re-ons never drop the supply); set your own value to override.

The optional Sync main power setting (main-sync, -D POWERMANAGER_MASTER_MAIN_SYNC=true) mirrors the master on WLED's main power state: when the master cuts because every segment was switched off, main power is switched off as well (UI, MQTT and Home Assistant all show off) - and switching any segment back on restores main power and powers everything up through the normal sequence. Turning main power off yourself behaves as usual: segments stay dark until you turn it back on.

The global stabilize-s setting adds a PSU stabilization window to the master relay: after it powers on, the strip is held black and all segment-coupled relays postpone energising their sections for that many seconds, giving the supply time to come up and stabilize before load is applied. Once the window clears, sections power up with the normal anti-flash sequence and fade in. When the master had to power up first, a section's delay-on-s starts counting only after the stabilization window has passed (2s stabilize + 2s delay-on = 4s total); if the master was already on, only delay-on-s applies.

Behavior:

• Switching on honours the relay's delay-on-s, then runs the anti-flash sequence (see below). Switching off first lets the segment's fade-out (transition) finish, and additionally honours the relay's delay-off-s setting - the relay switches at whichever ends later (both measured from the moment the segment is turned off). Toggling the segment back before the pending switch fires cancels it.
• Anti-flash power-on: to prevent LEDs from flashing while their supply ramps up, the segment is forced to black black-pre-ms (default 200) before the port is energised and kept black for black-post-ms (default 200) after. The fade-up transition is then (re)started, so the full fade is visible once power is ready - even when delay-on-s postponed the power-on past the original fade. Set both to 0 to disable and switch instantly.
• Minimum off-time: after a port is cut it will not be re-energised for min-off-ms (default 2000). Re-powering a half-discharged strip can make the LED chips latch a white flash regardless of the (black) data being sent; this gate lets the strip's capacitors discharge first. Set to 0 to disable.
• Global (main) power off turns all coupled relays off (after the LED fade completes); global power on restores each relay according to its segment's state.
• A coupled relay is exclusively segment-driven: external is forced off and MQTT/HTTP/JSON on-off commands and buttons are ignored for it. Its state is still published via MQTT.
• Multiple relays may follow the same segment (one section fed by several supplies).

Caveats:

• Deleting a linked segment switches its relay(s) off and removes the link automatically, so a segment created later (which reuses the freed id) does not inherit stale relay links. Note this also applies when WLED itself rebuilds segments (e.g. after changing LED outputs, or segment resets on critically low memory) - re-link afterwards.
• Segments are referenced by their index. In the rare cases where WLED compacts the segment list (batch deletion of most segments, low-memory purge), remaining segment ids shift and links should be checked.

Coupling can be set via the Usermods settings page, or via JSON: {"PowerManager":{"relay":1,"seg":2}} ("seg":-1 decouples; the master role is settings-only and cannot be assigned via the API). Changes are persisted automatically unless "save":false is added, which applies the link in RAM only.

Recommended setup: enable "Make a segment for each output" (LED settings, or -D WLED_AUTOSEGMENTS). Segments then map 1:1 to the physical outputs and never move, so links are configured once and simply keep working - presets need no special handling.

Per-preset relay links (advanced)

Relay links are static configuration by default - they describe wiring, and ordinary (color/effect) presets do not touch them. Most users never need this section. Only if your presets re-shape the segment layout, a preset can carry its own links, applied together with the preset. Save the preset with an API command instead of "Use current state" (or edit it once in the preset dialog) and include a PowerManager block next to the state, e.g.:

{"on":true,"seg":[{"id":0,"start":0,"stop":60,"on":true},{"id":1,"start":60,"stop":120,"on":true}],
 "PowerManager":[{"relay":1,"seg":0,"save":false},{"relay":2,"seg":1,"save":false}]}

Use "save":false inside presets so switching them does not write to flash; the links configured in settings remain the boot baseline (have the boot preset carry its own links, and note that any later settings save captures whatever links are active at that moment). In a preset with fewer segments, explicitly set the unused relays to "seg":-1 - this beats the automatic unlink to it and avoids a config write per layout switch. Presets without a PowerManager block never change links, and presets containing one are simply ignored on builds without this usermod.

With the usermod web-UI injection hook applied to the WLED tree (see the ui-patch folder; designed by @blazoncek and proposed for WLED mainline in wled/WLED#5741), each segment shows a collapsible "Power relays" menu listing all relays by name (see below) for linking one or more relays to that segment. The menu itself is generated by the usermod and served by the device at /um.js — the hook is usermod-agnostic, and firmware built from a hooked tree without the usermod behaves exactly like stock WLED.

---

This page is generated from the usermod's in-tree readme (usermods/PowerManager/readme.md) by sync_wiki.py - edit there, not here.