Configuration Reference

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 PowerManager to the custom_usermods of your platformio.ini environment.

You can override the default maximum number of relays (which is 4) by defining POWERMANAGER_MAX_RELAYS (up to 16).

Some settings can be defined (defaults) at compile time by setting the following defines:

// 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

The following definitions should be a list of values (maximum number of entries is POWERMANAGER_MAX_RELAYS) that will be applied to the relays in order: (e.g. assuming POWERMANAGER_MAX_RELAYS=2)

#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"   // relay names (quoted strings)

In platformio_override.ini the name strings need escaped quotes:

  -D POWERMANAGER_NAMES='"Port 1","Port 2"'

These can be set via your platformio_override.ini file or as #define in your my_config.h (remember to set WLED_USE_MY_CONFIG in your platformio_override.ini)

Expander virtual pins (100+) can be used in POWERMANAGER_PINS, allowing fully pre-configured firmware images. Example platformio_override.ini environment for a board with 8 relays on an AW9523:

[env:esp32dev_powermanager_aw9523]
extends = env:esp32dev
custom_usermods = PowerManager
build_flags = ${env:esp32dev.build_flags}
  -D USERMOD_USE_AW9523
  -D AW9523_ADDRESS=0x58
  -D POWERMANAGER_MAX_RELAYS=8
  -D POWERMANAGER_PINS=100,101,102,103,104,105,106,107  ;; P0_0..P0_7

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 there is no PowerManager section, just save current configuration and re-open Usermods settings page.

---

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