Advanced power switching usermod for WLED: named relay/MOSFET outputs (direct GPIO or PCF8574 / AW9523(B) I2C expanders) coupled to segments, so turning a segment off cuts that section's actual supply power - with anti-flash power sequencing, PSU stabilization, a dedicated Master AC relay and optional main-power sync.
This usermod is heavily based on the multi_relay usermod made by blazoncek (see the Heritage section below).
Built and tested against WLED 0.16 (the stable release branch; also compiles on the 17.0-dev nightlies). Needs WLED's external-usermod build system (0.16 or newer).
Designed with the QuinLED Dig-Next-2 WLED controller in mind, enabling the per port individual power output control hardware feature.
Each release attaches a ready-to-flash ZIP for the
QuinLED Dig-Next-2 (WLED 0.16 + this usermod, all board defaults compiled in): unzip and double-click
Flash-Dig-Next-2.bat - it lists your serial ports, asks for the board's COM port, erases the board and
writes the factory image using the bundled flasher (nothing to install). The ZIP also contains the plain
.bin for OTA updates through WLED's Manual OTA Update page, the individual flash parts, an esptool
variant of the batch file, and a NOTICE with the licenses of the bundled tools. Erase before flashing a
board that ran another build: stored settings would otherwise override the compiled pin map.
As an external usermod (recommended): add the repository to custom_usermods in your
platformio_override.ini environment - WLED's build system fetches and links it automatically:
[env:my_build]
extends = env:esp32dev
custom_usermods = https://github.com/intermittech/wled-usermod-powermanager.git(This always builds the newest version automatically. See examples/platformio_override.ini
for complete environments including all compile-time options.)
Or as a local copy: copy this repository into your WLED tree as
usermods/PowerManager/ and use custom_usermods = PowerManager.
The "Power relays" menu on the segment cards (shown on the right): link power relays right where you control the segment, with the current assignment of every relay at a glance - green for this segment, dimmed for relays serving another one.
The menu is generated by the usermod itself and served to the web UI by the device
(/um.js). WLED just needs a small usermod-agnostic injection hook (designed by
@blazoncek, proposed for WLED mainline in wled/WLED#5741),
applied to the source tree before building the firmware. It is entirely optional: without it everything works and links are configured
on the Usermods settings page instead — and once the hook is merged into WLED, no
patching is needed at all.
See ui-patch/ for the automatic patcher (anchor-based, idempotent, with
backup) and the manual patch documentation. Firmware built from a hooked tree without
this usermod behaves exactly like stock WLED.
This usermod grew out of WLED's built-in multi_relay usermod, written and maintained by
@blazoncek (with contributions credited in the change log,
which preserves that lineage). Power Manager is maintained separately and is not meant to
be installed alongside multi_relay - it uses its own configuration (PowerManager) and JSON
API key, and automatically migrates settings saved by a previous multi_relay installation
on first boot. The MQTT topics (.../relay/N) and the HTTP /relays API are kept unchanged so
existing automations and Home Assistant entities keep working.
Select the expander type in the usermod settings (or at compile time). Relays are attached to expander ports using virtual pin numbers starting at 100:
| Expander | Ports | Virtual pins | I2C addresses |
|---|---|---|---|
| PCF8574 | 8 (P0-P7) | 100-107 | 0x20-0x27 (PCF8574A: 0x38-0x3F) |
| AW9523 | 16 (P0_0-P0_7, P1_0-P1_7) | 100-107 (P0_x), 108-115 (P1_x) | 0x58-0x5B (AD1/AD0 straps) |
Expander use requires global I2C pins to be defined in LED & Hardware settings. After changing the expander type, save and re-open the Usermods settings page so the pin dropdowns show the matching port names.
AW9523 specifics (boot-time detection, per-port configuration, push-pull vs open-drain, RSTN wiring): I2C Port Expander Support (wiki)
- Segment coupling - link any relay to a segment; the section's supply power follows the segment's on/off state
- Master AC relay - dedicated relay 0 slot for the PSU trigger: on while any segment is on, always the last to cut, 5s anti-cycling off-delay by default
- Main power sync (optional) - WLED's power button mirrors reality: off when the master cuts, restored by switching a segment on
- Power sequencing - per-relay on/off delays, fade-aware power-off, anti-flash black frames around power-on, PSU stabilization window, minimum off-time against rapid-cycle flashes
- Staggered bring-up - outputs switch on one at a time (25 ms apart by default), so the power supply sees one inrush at a time instead of every section at once
- Power sensing (optional) - fuse state per output and main supply rail presence via spare AW9523 inputs, shown as green/red/grey status dots on the Info page and in the segment menu
- Named relays - up to 16 outputs named after your physical ports, shown in the segment menu, Info page and Home Assistant
- Take over all relays (optional) - unconfigured relays stay off until given a role
- Preset-carried links (advanced) - presets can re-map relay links for layout-switching setups
Full details, timing behavior and caveats: Segment Coupling and Power Sequencing (wiki)
Fuse and main power rail sensing: Power Sensing (wiki)
Everything is configurable on the Usermods settings page (general, expander, broadcast and
power-sequencing sections, with the Master AC relay as the first relay block), and every
default can be baked into prebuilt firmware via POWERMANAGER_* compile-time defines.
All options and defines: Configuration Reference (wiki)
Relays are controllable via the HTTP /relays endpoint, the JSON API ({"PowerManager":...})
and MQTT (.../relay/N); externally controlled relays appear in Home Assistant automatically
via MQTT autodiscovery.
Endpoints, payloads and topics: API Reference (wiki)
See the Change Log in the wiki - the full lineage from the 2021 multi_relay beginnings to the current release.
Licensed under the EUPL-1.2, like WLED itself - see LICENSE.