Skip to content

Configuration Reference

Jump to bottom
intermittech edited this page Jul 15, 2026 · 3 revisions

Relay names

Each relay can be given a name (up to 32 characters, e.g. the physical output port it powers: "LED Out 3", "Kitchen cabinet"). Names are shown in the segment "Power relays" menu, on the Info page, and are used as the Home Assistant entity name for external relays. Set names on the Usermods settings page, or at compile time via POWERMANAGER_NAMES (see below).

Usermod installation

Add the repository URL (or PowerManager for a local copy in usermods/) to the custom_usermods of your platformio_override.ini environment.

All defaults can be pre-set at compile time. The usual way is -D defines in the build_flags of your platformio_override.ini environment - this allows fully pre-configured firmware images. A complete example for a board with 7 relays on an AW9523 expander and relay 0 acting as the Master AC relay:

[env:my_powermanager_build]
extends = env:esp32dev
custom_usermods = https://github.com/intermittech/wled-usermod-powermanager.git
build_flags = ${env:esp32dev.build_flags}
  -D USERMOD_USE_AW9523                    ;; onboard AW9523(B) expander (or USERMOD_USE_PCF8574)
  -D AW9523_ADDRESS=0x58                   ;; AD0=AD1=GND (0x58-0x5B)
  -D POWERMANAGER_MAX_RELAYS=7             ;; up to 16 (default 4)
  -D POWERMANAGER_PINS=106,100,101,102,103,104,105   ;; GPIOs or expander virtual pins (100+)
  -D POWERMANAGER_NAMES='"AC Relay","5A_1","10A_1","5A_2","5A_3","10A_2","5A_4"'  ;; note the escaped quotes
  -D POWERMANAGER_MASTER=true              ;; relay 0 = dedicated Master AC relay (PSU trigger)
  -D POWERMANAGER_MASTER_MAIN_SYNC=true    ;; main power mirrors the Master AC relay
  -D POWERMANAGER_STABILIZE=2              ;; PSU stabilization seconds after the master closes
  -D POWERMANAGER_SEGMENTS=-1,0,1,2,3,-1,-1  ;; pre-link relays to segments (-1 = not linked)
  -D POWERMANAGER_DELAYS=0,0,0,0,0,0,0     ;; seeds both delay-on-s and delay-off-s per relay
  -D POWERMANAGER_TAKEOVER=true            ;; unconfigured relays stay off instead of following main power
  -D POWERMANAGER_BLACK_PRE_MS=200         ;; anti-flash black frames before power-on (ms)
  -D POWERMANAGER_BLACK_POST_MS=200        ;; ... and kept up after power-on (ms)
  -D POWERMANAGER_MIN_OFF_MS=2000          ;; minimum port off-time (LED capacitor discharge)
  -D WLED_AUTOSEGMENTS                     ;; one segment per LED output (recommended pairing)

List defines (PINS, NAMES, SEGMENTS, DELAYS, EXTERNALS, INVERTS) take one value per relay, in order (up to POWERMANAGER_MAX_RELAYS entries). Expander ports use virtual pin numbers 100+ (see I2C port expander support).

Alternatively, the same settings can be set as #defines in a my_config.h file (remember to set WLED_USE_MY_CONFIG in your platformio_override.ini):

// enable or disable HA discovery for externally controlled relays
#define POWERMANAGER_HA_DISCOVERY true

// select an I2C port expander (define at most one of these)
#define USERMOD_USE_PCF8574
#define USERMOD_USE_AW9523

// expander I2C address (defaults: PCF8574 0x20, AW9523 0x58)
#define PCF8574_ADDRESS 0x20
#define AW9523_ADDRESS 0x58

// AW9523 P0_x drive mode: true = push-pull (default), false = open-drain
#define AW9523_P0_PUSHPULL true

// anti-flash blackout around segment power-on (ms)
#define POWERMANAGER_BLACK_PRE_MS 200
#define POWERMANAGER_BLACK_POST_MS 200

// PSU stabilization seconds, applied to the Master AC relay
#define POWERMANAGER_STABILIZE 1

// minimum port off-time in ms before re-energising (LED capacitor discharge)
#define POWERMANAGER_MIN_OFF_MS 2000

// per-relay lists (one entry per relay, up to POWERMANAGER_MAX_RELAYS)
#define POWERMANAGER_PINS 12,18
#define POWERMANAGER_DELAYS 0,0             // seeds both delay-on-s and delay-off-s
#define POWERMANAGER_EXTERNALS false,true
#define POWERMANAGER_INVERTS false,false
#define POWERMANAGER_SEGMENTS 0,-1          // couple relay 0 to segment 0 (-1 = not coupled)
#define POWERMANAGER_MASTER true            // relay 0 = dedicated Master AC relay (PSU trigger)
#define POWERMANAGER_MASTER_MAIN_SYNC true  // main power mirrors the Master AC relay
#define POWERMANAGER_TAKEOVER true          // unconfigured relays stay off instead of following main power
#define POWERMANAGER_NAMES "Port 1","Port 2"

Configuration

Usermod can be configured via the Usermods settings page.

  • enabled - enable/disable usermod
  • expander - I2C port expander type (None / PCF8574 / AW9523)
  • expander-address - I2C address of the expander (WARNING: enter decimal value; PCF8574: 32-39 or 56-63, AW9523: 88-91)
  • AW9523-pushpull - drive the AW9523 P0_x port in push-pull mode (untick for open-drain)
  • broadcast- time in seconds between MQTT relay-state broadcasts
  • HA-discovery- enable Home Assistant auto discovery
  • take-over-relays - off by default (stock behavior): when enabled, unconfigured relays (pin set, but no segment link and not externally controlled) stay off until they are given a role, instead of following main power - avoids surprises once part of the relays is segment-coupled
  • black-pre-ms / black-post-ms - anti-flash: black frames sent to a coupled segment before/after its power port switches on (both 0 = disabled); see Segment coupling
  • stabilize-s - PSU stabilization time in seconds: the other relays wait this long after the Master AC relay powers on (default 1, max 60); each relay's own delay-on-s is added on top, allowing a staggered power-on; see Segment coupling
  • min-off-ms - minimum time a port stays off before it may be re-energised (LED capacitor discharge, prevents white flash on rapid toggling; max 10000); see Segment coupling
  • pin - ESP GPIO pin the relay is connected to, or expander virtual pin 100+ (can be configured at compile time -D POWERMANAGER_PINS=xx,xx,...)
  • delay-on-s / delay-off-s - delay in seconds before the relay switches on / off (individually per relay; a legacy delay-s value migrates to both)
  • active-high - shown as Active Low on the settings page: when ticked, relay On drives the output low (for active-low relay boards); unticked (default) On drives it high. The config key stores the invert flag and keeps its historical name for compatibility.
  • external - shown as External control: if enabled, WLED does not control the relay, it can only be triggered by an external command (MQTT, HTTP, JSON or button); not available for segment-coupled relays (the checkbox is disabled once a segment is set)
  • button - button (from LED Settings) that controls this relay
  • segment - couple this relay to a segment (-1 = off, 0-31 = follow that segment); see Segment coupling
  • master - relay 0 only: use it as the dedicated Master AC relay (on while any segment is on); see Segment coupling
  • main-sync - relay 0 only: main power mirrors the Master AC relay (off when it cuts, back on with a segment); see Segment coupling
  • name - user-friendly relay name (max 32 chars), shown in the segment "Power relays" menu, Info page and Home Assistant; see Relay names

If you do not see the PowerManager section on the Usermods settings page, make sure the usermod is compiled into the firmware you are currently running.

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

Clone this wiki locally