PowerManager.cpp

#include "wled.h"

#define COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / ((size_t)(!(sizeof(x) % sizeof(0[x])))))

// external usermod: this ID is not present in WLED's const.h (overridable in case of a clash)
#ifndef USERMOD_ID_POWERMANAGER
  #define USERMOD_ID_POWERMANAGER 200
#endif

#ifndef POWERMANAGER_MAX_RELAYS
  #define POWERMANAGER_MAX_RELAYS 4
#else
  #if POWERMANAGER_MAX_RELAYS>16
    #undef POWERMANAGER_MAX_RELAYS
    #define POWERMANAGER_MAX_RELAYS 16
    #warning Maximum relays set to 16
  #endif
#endif

#ifndef POWERMANAGER_PINS
  #define POWERMANAGER_PINS -1
  #define POWERMANAGER_ENABLED false
#else
  #define POWERMANAGER_ENABLED true
#endif

#ifndef POWERMANAGER_HA_DISCOVERY
  #define POWERMANAGER_HA_DISCOVERY false
#endif

#ifndef POWERMANAGER_DELAYS
  #define POWERMANAGER_DELAYS 0
#endif

#ifndef POWERMANAGER_EXTERNALS
  #define POWERMANAGER_EXTERNALS false
#endif

#ifndef POWERMANAGER_INVERTS
  #define POWERMANAGER_INVERTS false
#endif

#ifndef POWERMANAGER_SEGMENTS
  #define POWERMANAGER_SEGMENTS -1
#endif

#ifndef POWERMANAGER_STABILIZE
  #define POWERMANAGER_STABILIZE 1
#endif

// relay 0 doubles as the dedicated "Master AC relay" (e.g. the AC-side trigger of the main PSU):
// when enabled it is on while any segment is on. Only relay 0 can take this role.
#ifndef POWERMANAGER_MASTER
  #define POWERMANAGER_MASTER false
#endif

// sync main power with the Master AC relay: when it cuts because every segment was switched off,
// main power is switched off too (UI/MQTT/HA show off); switching a segment on restores it
#ifndef POWERMANAGER_MASTER_MAIN_SYNC
  #define POWERMANAGER_MASTER_MAIN_SYNC false
#endif

// take over all relays: 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 (default WLED
// behavior). Avoids surprises once part of the relays is segment-coupled.
#ifndef POWERMANAGER_TAKEOVER
  #define POWERMANAGER_TAKEOVER false
#endif

// special relay_t.segment value: relay is on while *any* segment is on (master PSU mode)
#define POWERMANAGER_SEG_ANY 99

#ifndef POWERMANAGER_NAMES
  #define POWERMANAGER_NAMES ""
#endif

#ifndef POWERMANAGER_NAME_LEN
  #define POWERMANAGER_NAME_LEN 33 // max relay name length including terminator
#endif

// anti-flash blackout around segment power-on: black frames sent before / kept up after switching the port
#ifndef POWERMANAGER_BLACK_PRE_MS
  #define POWERMANAGER_BLACK_PRE_MS 200
#endif
#ifndef POWERMANAGER_BLACK_POST_MS
  #define POWERMANAGER_BLACK_POST_MS 200
#endif

// minimum time a port stays off before it may be re-energised: lets the LED strip's capacitors
// discharge so the chips reset properly (re-powering a half-discharged strip can latch a white
// flash no matter what data is streaming)
#ifndef POWERMANAGER_MIN_OFF_MS
  #define POWERMANAGER_MIN_OFF_MS 2000
#endif

// fuse / main power sensing on free AW9523 input ports: per-output fuse sense and a main
// power rail sense, shown as status dots on the Info page and in the segment "Power relays"
// menu. Ports use the same virtual pin numbers as the relays (100-115), -1 = not sensed.
#ifndef POWERMANAGER_FUSE_PINS
  #define POWERMANAGER_FUSE_PINS -1        // per-relay fuse sense port, list in POWERMANAGER_PINS order
#endif
#ifndef POWERMANAGER_MAIN_SENSE_PIN
  #define POWERMANAGER_MAIN_SENSE_PIN -1   // main power rail sense port
#endif
// input polarity: fuse inputs are commonly derived from a blown-fuse indicator circuit and
// read HIGH when the fuse is open (Dig-Next-4 v0r2); the main rail sense reads HIGH when
// power is present. Each group can be inverted separately.
#ifndef POWERMANAGER_FUSE_SENSE_INVERT
  #define POWERMANAGER_FUSE_SENSE_INVERT false // true: fuse input reads high when the fuse is blown
#endif
#ifndef POWERMANAGER_MAIN_SENSE_INVERT
  #define POWERMANAGER_MAIN_SENSE_INVERT false // true: main input reads low when power is present
#endif
#define POWERMANAGER_SENSE_GRACE_MS 1000   // inrush settle window: after any output switches on, a missing rail
                                           // is not yet a fault and fuse inputs are not judged (an indicator can
                                           // flicker while the inrush current drops voltage across its fuse)

// sense input status (Info page dots, "fu"/"main" in the state JSON)
#define SENSE_NA    0  // not configured / expander not found
#define SENSE_OK    1  // voltage present (green)
#define SENSE_FAULT 2  // voltage missing while the main rail is up - blown fuse / dead rail (red)
#define SENSE_IDLE  3  // voltage missing, nothing to judge: main rail not up / main power not present (grey)

// staggered bring-up: outputs never energise closer together than this, spreading the inrush
// hit on the supply when several sections power up at once (boot, main power on, presets).
// Every relay switching on counts as a reference for the next slot.
#ifndef POWERMANAGER_STAGGER
  #define POWERMANAGER_STAGGER true
#endif
#ifndef POWERMANAGER_STAGGER_MS
  #define POWERMANAGER_STAGGER_MS 25
#endif

// power-on blackout phases (relay_t.boPhase)
#define BO_NONE 0
#define BO_PRE  1  // port still off: black frames (if blackout enabled) until black-pre-ms passed AND the stagger slot is free
#define BO_POST 2  // port energised, still sending black frames
#define BO_FADE 3  // still black; cancelled stale transition is being destroyed, clean fade starts next frame

#define BO_FADE_TIMEOUT_MS        250  // max wait in BO_FADE for a cancelled transition to be destroyed
#define POWERMANAGER_FADE_GRACE_MS 1000 // extra wait for a lingering fade-out before cutting power anyway

#define WLED_DEBOUNCE_THRESHOLD 50 //only consider button input of at least 50ms as valid (debouncing)

#define ON  true
#define OFF false

// I2C port expander types
#define EXPANDER_NONE    0
#define EXPANDER_PCF8574 1
#define EXPANDER_AW9523  2

#if defined(USERMOD_USE_PCF8574) && defined(USERMOD_USE_AW9523)
  #error "PowerManager: define either USERMOD_USE_PCF8574 or USERMOD_USE_AW9523, not both"
#endif

#if defined(USERMOD_USE_PCF8574)
  #define POWERMANAGER_EXPANDER EXPANDER_PCF8574
#elif defined(USERMOD_USE_AW9523)
  #define POWERMANAGER_EXPANDER EXPANDER_AW9523
#else
  #ifndef POWERMANAGER_EXPANDER
    #define POWERMANAGER_EXPANDER EXPANDER_NONE
  #endif
#endif

#ifndef PCF8574_ADDRESS
  #define PCF8574_ADDRESS 0x20  // some may start at 0x38
#endif

#ifndef AW9523_ADDRESS
  #define AW9523_ADDRESS 0x58   // AD1=AD0=GND; 0x58-0x5B depending on AD1/AD0 straps
#endif

#ifndef AW9523_P0_PUSHPULL
  #define AW9523_P0_PUSHPULL true // P0_x port drive mode: push-pull (recommended for relays), false = open-drain
#endif

#if POWERMANAGER_EXPANDER == EXPANDER_AW9523
  #define POWERMANAGER_EXPANDER_ADDR AW9523_ADDRESS
#else
  #define POWERMANAGER_EXPANDER_ADDR PCF8574_ADDRESS
#endif

// AW9523(B) register map (registers 0x03, 0x05, 0x07 and 0x13 are the P1 counterparts of P0 at 0x02, 0x04, 0x06 and 0x12)
#define AW9523_REG_IN0    0x00  // input state (read-only)
#define AW9523_REG_OUT0   0x02  // output state: 0=low, 1=high
#define AW9523_REG_CFG0   0x04  // direction: 0=output, 1=input
#define AW9523_REG_INT0   0x06  // interrupt: 0=enabled, 1=disabled
#define AW9523_REG_ID     0x10  // read-only, returns 0x23
#define AW9523_REG_GCR    0x11  // global control: bit4 P0 push-pull, bits 0-1 LED current range
#define AW9523_REG_MODE0  0x12  // port mode: 0=LED, 1=GPIO
#define AW9523_ID_VALUE   0x23
#define AW9523_GCR_GPOMD  0x10  // GCR bit4: P0 port push-pull when set

/*
 * Power Manager usermod
 *
 * Handles multiple relay/MOSFET power outputs (direct GPIO or PCF8574/AW9523 I2C expanders).
 * Relays can be named and coupled to segments: a coupled relay follows its segment's on/off
 * state to cut the actual supply power of individual LED sections, with anti-flash power
 * sequencing, PSU stabilization and a dedicated Master AC relay (relay 0) that is always the
 * last to cut and can mirror WLED's main power state.
 * See readme.md and the "Segment coupling & power sequencing" section below for details.
 *
 * This usermod grew out of WLED's built-in multi_relay usermod:
 *   multi_relay written and maintained by @blazoncek (with contributions noted in its history)
 *   power sequencing / segment coupling extensions and rename by @Quindor (intermit.tech)
 * Settings saved by multi_relay are migrated automatically (see readFromConfig()).
 */


typedef struct relay_t {
  int8_t pin;
  struct { // reduces memory footprint
    bool active   : 1;  // is the relay waiting to be switched
    bool invert   : 1;  // does On mean 1 or 0
    bool state    : 1;  // 1 relay is On, 0 relay is Off
    bool external : 1;  // is the relay externally controlled
    int8_t button : 4;  // which button triggers relay
    bool segSeen  : 1;  // segment coupling: linked segment observed active this session (guards deletion detection against boot races)
    uint8_t boPhase : 2; // power-on blackout phase (BO_NONE/BO_PRE/BO_POST/BO_FADE)
  };
  uint16_t delayOn;     // seconds to wait before switching the relay on
  uint16_t delayOff;    // seconds to wait before switching the relay off
  int8_t segment;       // segment this relay follows: -1 = not coupled, 0..MAX_NUM_SEGMENTS-1 = segment id, 99 = any segment on
  int8_t fusePin;       // AW9523 port sensing this output's post-fuse voltage (virtual pin 100-115, -1 = off)
  char name[POWERMANAGER_NAME_LEN]; // user-friendly name (e.g. physical output port), shown in UI/Info/HA
} Relay;


class PowerManager : public Usermod {

  private:
    // array of relays
    Relay    _relay[POWERMANAGER_MAX_RELAYS];

    uint32_t _switchTimerStart; // switch timer start time
    // segment coupling & power sequencing state (see section comment in the implementation)
    uint32_t _pendingSince[POWERMANAGER_MAX_RELAYS]; // start of a pending delayed switch (0 = nothing pending)
    uint32_t _boStart[POWERMANAGER_MAX_RELAYS];      // start of the current blackout phase
    uint32_t _onAt[POWERMANAGER_MAX_RELAYS];         // last switch-on time (master stabilization window)
    uint32_t _offAt[POWERMANAGER_MAX_RELAYS];        // last switch-off time (minimum off-time gate)
    bool     _oldMode;          // old brightness
    bool     enabled;           // usermod enabled
    bool     initDone;          // status of initialisation
    uint8_t  expanderType;      // I2C port expander type (EXPANDER_NONE/EXPANDER_PCF8574/EXPANDER_AW9523)
    uint8_t  expanderAddr;      // I2C address of port expander
    bool     awP0PushPull;      // AW9523: drive P0_x port in push-pull mode (instead of open-drain)
    bool     awFound;           // AW9523: chip detected on I2C bus (ID register check)
    uint16_t awOutputState;     // AW9523: shadow of output registers (bit n = port n; 0-7 = P0_x, 8-15 = P1_x)
    uint16_t boPreMs;           // blackout: black frames before segment power-on (0 with boPostMs 0 = disabled)
    uint16_t boPostMs;          // blackout: keep sending black frames this long after power-on
    uint16_t stabilizeSec;      // PSU stabilization (seconds): after the Master AC relay powers on,
                                // the strip stays black and dependent coupled relays wait this long
    uint16_t minOffMs;          // minimum port off-time before re-energising (LED capacitor discharge)
    bool     staggerEnabled;    // staggered bring-up: relays switch on at least staggerMs apart
    uint16_t staggerMs;         // spacing between two switch-on events (any relay counts)
    uint32_t _lastOnAt;         // last time any relay switched on (0 = never); staggered bring-up reference
    bool     masterEnabled;     // relay 0 acts as the Master AC relay (segment = POWERMANAGER_SEG_ANY)
    bool     masterMainSync;    // main power follows the Master AC relay (off when it cuts, back on with a segment)
    bool     _autoMainOff;      // this usermod switched main power off (a segment turning on restores it)
    bool     takeOverRelays;    // unconfigured relays stay off instead of following main power
    bool     HAautodiscovery;
    uint16_t periodicBroadcastSec;
    unsigned long lastBroadcast;
    // fuse / main power sensing (AW9523 input ports)
    int8_t   mainSensePin;      // main power rail sense port (virtual pin 100-115, -1 = off)
    bool     fuseSenseInvert;   // fuse inputs read high when the fuse is blown (indicator circuit)
    bool     mainSenseInvert;   // main input reads low when power is present
    uint16_t _senseMask;        // AW9523 ports configured as sense inputs (bit n = port n)
    uint16_t _fuseMask;         // subset of _senseMask that are fuse inputs
    uint16_t _senseStable;      // debounced sense state, bit set = voltage present (invert applied)
    uint16_t _senseRaw;         // last raw sample (debouncing)
    uint8_t  _senseCnt;         // consecutive identical raw samples

    // strings to reduce flash memory usage (used more than twice)
    static const char _name[];
    static const char _legacyName[];
    static const char _enabled[];
    static const char _relay_str[];
    static const char _delay_str[];
    static const char _activeHigh[];
    static const char _external[];
    static const char _button[];
    static const char _broadcast[];
    static const char _HAautodiscovery[];
    static const char _pcf8574[];
    static const char _pcfAddress[];
    static const char _expander[];
    static const char _expanderAddr[];
    static const char _pushPull[];
    static const char _switch[];
    static const char _toggle[];
    static const char _Command[];
    static const char _segment_str[];
    static const char _delayOn_str[];
    static const char _delayOff_str[];
    static const char _stabilize_str[];
    static const char _blackPre[];
    static const char _blackPost[];
    static const char _minOff[];
    static const char _stagger[];
    static const char _staggerMs[];
    static const char _master[];
    static const char _mainSync[];
    static const char _takeOver[];
    static const char _fusePin[];
    static const char _mainSense[];
    static const char _fuseInv[];
    static const char _mainInv[];

    void handleOffTimer();
    void handleSegmentCoupling();
    void handleBlackout();
    void handleSensing();
    uint8_t fuseDot(uint8_t r);
    uint8_t mainDot();
    String  senseDotHtml(uint8_t st);
    // debounced "voltage present" state of a sense port (invert already applied)
    inline bool senseHigh(int8_t pin) { return pin >= 100 && ((_senseStable >> (pin-100)) & 1); }
    void beginFadePhase(uint8_t r);
    void restartSegmentFade(uint8_t r);
    void cancelSegTransitions(uint8_t r);
    bool isSegFading(uint8_t r);
    bool masterHoldsOn();
    bool staggerSlotFree(uint32_t now);
    bool inrushSettling(uint32_t now);
    bool awaitingPower(uint8_t r);
    bool dependentsStillOn();
    void setSegmentLink(uint8_t relay, int seg, bool persist = true);
    void InitHtmlAPIHandle();
    int getValue(String data, char separator, int index);
    uint8_t getActiveRelayCount();

    // number of output ports the configured expander provides (expander pins are 100 .. 100+count-1)
    inline uint8_t expanderPortCount() { return expanderType == EXPANDER_AW9523 ? 16 : 8; }

    // expander configured AND the global I2C bus usable. Deliberately a runtime check that
    // never rewrites the configuration: WLED sets i2c_sda/i2c_scl to -1 when its I2C re-init
    // fails (on ESP32 that happens on any runtime /json/cfg POST, since Wire is already up),
    // and the configured expander type and relay ports must survive that untouched.
    inline bool expanderAvailable() { return expanderType != EXPANDER_NONE && i2c_sda >= 0 && i2c_scl >= 0; }

    // relay is coupled to a segment (exclusively segment-driven, no external/button control)
    inline bool isCoupled(uint8_t r) { return _relay[r].segment >= 0; }

    // invoke fn(Segment&) for every active segment the relay is coupled to
    // (its own segment, or all of them for an "any segment" master relay)
    template<typename FN> void forOwnedSegments(uint8_t r, FN fn) {
      if (_relay[r].segment == POWERMANAGER_SEG_ANY) {
        for (unsigned s = 0; s < strip.getSegmentsNum(); s++) {
          Segment &seg = strip.getSegment(s);
          if (seg.isActive()) fn(seg);
        }
      } else if ((uint8_t)_relay[r].segment < strip.getSegmentsNum()) {
        Segment &seg = strip.getSegment(_relay[r].segment);
        if (seg.isActive()) fn(seg);
      }
    }

    byte IOexpanderWrite(byte address, byte _data);
    byte IOexpanderRead(int address);

    // AW9523 register access (byte pairs use the chip's auto-incrementing register pointer)
    byte    awRegWrite8(uint8_t reg, uint8_t value);
    byte    awRegWrite16(uint8_t reg, uint16_t value);
    int16_t awRegRead8(uint8_t reg); // returns -1 on I2C error
    void    initAW9523(uint16_t state, uint16_t used, uint16_t sense);

    void publishMqtt(int relay);
#ifndef WLED_DISABLE_MQTT
    void publishHomeAssistantAutodiscovery();
#endif

  public:
    /**
     * constructor
     */
    PowerManager();

    /**
     * desctructor
     */
    //~PowerManager() {}

    /**
     * Enable/Disable the usermod
     */
    inline void enable(bool enable) { enabled = enable; }

    /**
     * Get usermod enabled/disabled state
     */
    inline bool isEnabled() { return enabled; }

    /**
     * getId() allows you to optionally give your V2 usermod an unique ID (please define it in const.h!).
     * This could be used in the future for the system to determine whether your usermod is installed.
     */
    inline uint16_t getId() override { return USERMOD_ID_POWERMANAGER; }

    /**
     * switch relay on/off
     */
    void switchRelay(uint8_t relay, bool mode);

    /**
     * toggle relay
     */
    inline void toggleRelay(uint8_t relay) {
      switchRelay(relay, !_relay[relay].state);
    }

    /**
     * setup() is called once at boot. WiFi is not yet connected at this point.
     * You can use it to initialize variables, sensors or similar.
     */
    void setup() override;

    /**
     * connected() is called every time the WiFi is (re)connected
     * Use it to initialize network interfaces
     */
    inline void connected() override { InitHtmlAPIHandle(); }

    /**
     * loop() is called continuously. Here you can check for events, read sensors, etc.
     */
    void loop() override;

    /**
     * called after effects are rendered, just before strip.show();
     * paints segments in a power-on blackout window black
     */
    void handleOverlayDraw() override;

    /**
     * streams the JavaScript that injects the segment-card "Power relays" menu into the
     * main web UI (served at /um.js; the UI runs it after every state render)
     */
#ifdef WLED_ENABLE_UM_UI_INJECT // WLED base includes the usermod web-UI injection mechanism
    void addUIInjectCode(Print &dest) override;
#endif

#ifndef WLED_DISABLE_MQTT
    bool onMqttMessage(char* topic, char* payload) override;
    void onMqttConnect(bool sessionPresent) override;
#endif

    /**
     * handleButton() can be used to override default button behaviour. Returning true
     * will prevent button working in a default way.
     * Replicating button.cpp
     */
    bool handleButton(uint8_t b) override;

    /**
     * addToJsonInfo() can be used to add custom entries to the /json/info part of the JSON API.
     */
    void addToJsonInfo(JsonObject &root) override;

    /**
     * addToJsonState() can be used to add custom entries to the /json/state part of the JSON API (state object).
     * Values in the state object may be modified by connected clients
     */
    void addToJsonState(JsonObject &root) override;

    /**
     * readFromJsonState() can be used to receive data clients send to the /json/state part of the JSON API (state object).
     * Values in the state object may be modified by connected clients
     */
    void readFromJsonState(JsonObject &root) override;

    /**
     * provide the changeable values
     */
    void addToConfig(JsonObject &root) override;

    void appendConfigData() override;

    /**
     * restore the changeable values
     * readFromConfig() is called before setup() to populate properties from values stored in cfg.json
     * 
     * The function should return true if configuration was successfully loaded or false if there was no configuration.
     */
    bool readFromConfig(JsonObject &root) override;
};


// class implementation

void PowerManager::publishMqtt(int relay) {
#ifndef WLED_DISABLE_MQTT
  //Check if MQTT Connected, otherwise it will crash the 8266
  if (WLED_MQTT_CONNECTED){
    char subuf[64];
    sprintf_P(subuf, PSTR("%s/relay/%d"), mqttDeviceTopic, relay);
    mqtt->publish(subuf, 0, false, _relay[relay].state ? "on" : "off");
  }
#endif
}

/**
 * switch off the strip if the delay has elapsed 
 */
void PowerManager::handleOffTimer() {
  unsigned long now = millis();
  bool activeRelays = false;
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].active && _switchTimerStart > 0 && now - _switchTimerStart > (unsigned long)(offMode ? _relay[i].delayOff : _relay[i].delayOn)*1000) {
      // switching on: wait for a free staggered bring-up slot (re-checked every tick); off is immediate
      if (offMode || _relay[i].external || staggerSlotFree(now)) {
        if (!_relay[i].external) switchRelay(i, !offMode);
        _relay[i].active = false;
      }
    } else if (periodicBroadcastSec && now - lastBroadcast > (periodicBroadcastSec*1000)) {
      if (_relay[i].pin>=0) publishMqtt(i);
    }
    activeRelays = activeRelays || _relay[i].active;
  }
  if (!activeRelays) _switchTimerStart = 0;
  if (periodicBroadcastSec && now - lastBroadcast > (periodicBroadcastSec*1000)) lastBroadcast = now;
}

/**
 * HTTP API handler
 * borrowed from:
 * https://github.com/gsieben/WLED/blob/master/usermods/GeoGab-Relays/usermod_GeoGab.h
 */
#define GEOGABVERSION "0.1.3"
void PowerManager::InitHtmlAPIHandle() {  // https://github.com/me-no-dev/ESPAsyncWebServer
  DEBUG_PRINTLN(F("Relays: Initialize HTML API"));

  server.on(F("/relays"), HTTP_GET, [this](AsyncWebServerRequest *request) {
    DEBUG_PRINTLN(F("Relays: HTML API"));
    String janswer;
    String error = "";
    //int params = request->params();
    janswer = F("{\"NoOfRelays\":");
    janswer += String(POWERMANAGER_MAX_RELAYS) + ",";

    if (getActiveRelayCount()) {
      // Commands
      if (request->hasParam(FPSTR(_switch))) {
        /**** Switch ****/
        AsyncWebParameter* p = request->getParam(FPSTR(_switch));
        // Get Values
        for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
          int value = getValue(p->value(), ',', i);
          if (value==-1) {
            error = F("There must be as many arguments as relays");
          } else {
            // Switch
            if (_relay[i].external) switchRelay(i, (bool)value);
          }
        }
      } else if (request->hasParam(FPSTR(_toggle))) {
        /**** Toggle ****/
        AsyncWebParameter* p = request->getParam(FPSTR(_toggle));
        // Get Values
        for (int i=0;i<POWERMANAGER_MAX_RELAYS;i++) {
          int value = getValue(p->value(), ',', i);
          if (value==-1) {
            error = F("There must be as many arguments as relays");
          } else {
            // Toggle
            if (value && _relay[i].external) toggleRelay(i);
          }
        }
      } else {
        error = F("No valid command found");
      }
    } else {
      error = F("No active relays");
    }

    // Status response
    char sbuf[16];
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      sprintf_P(sbuf, PSTR("\"%d\":%d,"), i, (_relay[i].pin<0 ? -1 : (int)_relay[i].state));
      janswer += sbuf;
    }
    janswer += F("\"error\":\"");
    janswer += error;
    janswer += F("\",");
    janswer += F("\"SW Version\":\"");
    janswer += String(F(GEOGABVERSION));
    janswer += F("\"}");
    request->send(200, "application/json", janswer);
  });
}

int PowerManager::getValue(String data, char separator, int index) {
  int found = 0;
  int strIndex[] = {0, -1};
  int maxIndex = data.length()-1;

  for(int i=0; i<=maxIndex && found<=index; i++){
    if(data.charAt(i)==separator || i==maxIndex){
        found++;
        strIndex[0] = strIndex[1]+1;
        strIndex[1] = (i == maxIndex) ? i+1 : i;
    }
  }
  return found>index ? data.substring(strIndex[0], strIndex[1]).toInt() : -1;
}

//Write a byte to the IO expander
byte PowerManager::IOexpanderWrite(byte address, byte _data ) {
  Wire.beginTransmission(address);
  Wire.write(_data);
  return Wire.endTransmission(); 
}

//Read a byte from the IO expander
byte PowerManager::IOexpanderRead(int address) {
  byte _data = 0;
  Wire.requestFrom(address, 1);
  if (Wire.available()) {
    _data = Wire.read();
  }
  return _data;
}

//Write a byte to an AW9523 register
byte PowerManager::awRegWrite8(uint8_t reg, uint8_t value) {
  Wire.beginTransmission(expanderAddr);
  Wire.write(reg);
  Wire.write(value);
  return Wire.endTransmission();
}

//Write two consecutive AW9523 registers (low byte to reg, high byte to reg+1) in one transaction
byte PowerManager::awRegWrite16(uint8_t reg, uint16_t value) {
  Wire.beginTransmission(expanderAddr);
  Wire.write(reg);
  Wire.write((uint8_t)(value & 0xFF));
  Wire.write((uint8_t)(value >> 8));
  return Wire.endTransmission();
}

//Read a byte from an AW9523 register, -1 on I2C error
int16_t PowerManager::awRegRead8(uint8_t reg) {
  Wire.beginTransmission(expanderAddr);
  Wire.write(reg);
  if (Wire.endTransmission(false) != 0) return -1; // repeated start
  if (Wire.requestFrom(expanderAddr, (uint8_t)1) != 1) return -1;
  return Wire.read();
}

/**
 * initialise AW9523: verify chip ID, then configure only the ports used by relays
 * (GPIO mode, output direction, interrupts masked) and the sense inputs (GPIO mode, input
 * direction) without disturbing other ports.
 * state = desired output level per port (invert already applied), used = ports owned by
 * relays, sense = ports read as fuse / main power sense inputs
 */
void PowerManager::initAW9523(uint16_t state, uint16_t used, uint16_t sense) {
  awFound = (awRegRead8(AW9523_REG_ID) == AW9523_ID_VALUE);
  if (!awFound) {
    DEBUG_PRINTLN(F("AW9523 not found."));
    return;
  }

  // merge relay states into shadow of output registers so unrelated ports keep their level
  int16_t lo = awRegRead8(AW9523_REG_OUT0);
  int16_t hi = awRegRead8(AW9523_REG_OUT0+1);
  awOutputState = (lo < 0 || hi < 0) ? 0 : ((uint16_t)hi << 8) | (uint8_t)lo;
  awOutputState = (awOutputState & ~used) | (state & used);
  awRegWrite16(AW9523_REG_OUT0, awOutputState); // set levels before flipping direction to avoid glitches

  // P0 port drive mode; keep LED current bits, reserved bits must be written 0
  int16_t gcr = awRegRead8(AW9523_REG_GCR);
  awRegWrite8(AW9523_REG_GCR, ((gcr < 0 ? 0 : gcr) & 0x03) | (awP0PushPull ? AW9523_GCR_GPOMD : 0));

  for (int p = 0; p < 2; p++) { // p=0: P0_x registers, p=1: P1_x registers
    uint8_t oMask = used >> (8*p);   // relay outputs
    uint8_t iMask = sense >> (8*p);  // sense inputs (polled, so interrupts stay masked too)
    if (!oMask && !iMask) continue;
    int16_t v;
    v = awRegRead8(AW9523_REG_MODE0+p); if (v >= 0) awRegWrite8(AW9523_REG_MODE0+p, v | oMask | iMask);      // GPIO mode
    v = awRegRead8(AW9523_REG_CFG0+p);  if (v >= 0) awRegWrite8(AW9523_REG_CFG0+p, (v & ~oMask) | iMask);    // direction
    v = awRegRead8(AW9523_REG_INT0+p);  if (v >= 0) awRegWrite8(AW9523_REG_INT0+p, v | oMask | iMask);       // interrupts off
  }
  DEBUG_PRINTLN(F("AW9523 inited."));
}


// public methods

PowerManager::PowerManager()
  : _switchTimerStart(0)
  , enabled(POWERMANAGER_ENABLED)
  , initDone(false)
  , expanderType(POWERMANAGER_EXPANDER)
  , expanderAddr(POWERMANAGER_EXPANDER_ADDR)
  , awP0PushPull(AW9523_P0_PUSHPULL)
  , awFound(false)
  , awOutputState(0)
  , boPreMs(POWERMANAGER_BLACK_PRE_MS)
  , boPostMs(POWERMANAGER_BLACK_POST_MS)
  , stabilizeSec(POWERMANAGER_STABILIZE)
  , minOffMs(POWERMANAGER_MIN_OFF_MS)
  , staggerEnabled(POWERMANAGER_STAGGER)
  , staggerMs(POWERMANAGER_STAGGER_MS)
  , _lastOnAt(0)
  , masterEnabled(POWERMANAGER_MASTER)
  , masterMainSync(POWERMANAGER_MASTER_MAIN_SYNC)
  , _autoMainOff(false)
  , takeOverRelays(POWERMANAGER_TAKEOVER)
  , HAautodiscovery(POWERMANAGER_HA_DISCOVERY)
  , periodicBroadcastSec(60)
  , lastBroadcast(0)
  , mainSensePin(POWERMANAGER_MAIN_SENSE_PIN)
  , fuseSenseInvert(POWERMANAGER_FUSE_SENSE_INVERT)
  , mainSenseInvert(POWERMANAGER_MAIN_SENSE_INVERT)
  , _senseMask(0)
  , _fuseMask(0)
  , _senseStable(0)
  , _senseRaw(0)
  , _senseCnt(0)
{
  const int8_t defPins[] = {POWERMANAGER_PINS};
  const int8_t defFusePins[] = {POWERMANAGER_FUSE_PINS};
  const int8_t relayDelays[] = {POWERMANAGER_DELAYS};
  const bool relayExternals[] = {POWERMANAGER_EXTERNALS};
  const bool relayInverts[] = {POWERMANAGER_INVERTS};
  const int8_t relaySegments[] = {POWERMANAGER_SEGMENTS};
  const char* const relayNames[] = {POWERMANAGER_NAMES};

  for (size_t i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    _relay[i].pin      = i < COUNT_OF(defPins) ? defPins[i] : -1;
    _relay[i].delayOn  = i < COUNT_OF(relayDelays) ? relayDelays[i] : 0;
    _relay[i].delayOff = i < COUNT_OF(relayDelays) ? relayDelays[i] : 0;
    _relay[i].invert   = i < COUNT_OF(relayInverts) ? relayInverts[i] : false;
    _relay[i].active   = false;
    _relay[i].state    = false;
    _relay[i].external = i < COUNT_OF(relayExternals) ? relayExternals[i] : false;
    _relay[i].button   = -1;
    _relay[i].segment  = i < COUNT_OF(relaySegments) ? relaySegments[i] : -1;
    _relay[i].segSeen  = false;
    _relay[i].boPhase  = BO_NONE;
    _pendingSince[i]   = 0;
    _boStart[i]        = 0;
    _onAt[i]           = 0;
    _offAt[i]          = 0;
    _relay[i].fusePin  = i < COUNT_OF(defFusePins) ? defFusePins[i] : -1;
    strlcpy(_relay[i].name, i < COUNT_OF(relayNames) ? relayNames[i] : "", POWERMANAGER_NAME_LEN);
  }
  // relay 0 is the dedicated Master AC relay slot; only it may follow all segments
  if (masterEnabled) {
    _relay[0].segment = POWERMANAGER_SEG_ANY;
    if (_relay[0].delayOff == 0) _relay[0].delayOff = 5; // default PSU anti-cycling hold (config overrides)
  }
  for (size_t i=1; i<POWERMANAGER_MAX_RELAYS; i++)
    if (_relay[i].segment == POWERMANAGER_SEG_ANY) _relay[i].segment = -1;
}

/**
 * switch relay on/off
 */
void PowerManager::switchRelay(uint8_t relay, bool mode) {
  if (relay>=POWERMANAGER_MAX_RELAYS || _relay[relay].pin<0) return;
  if (_relay[relay].pin >= 100 && !expanderAvailable()) return; // expander relay without a usable I2C bus: inert
  if (_relay[relay].state != mode) { // timestamps drive the stabilization, minimum off-time and stagger windows
    if (mode) { _onAt[relay] = millis(); _lastOnAt = _onAt[relay] ? _onAt[relay] : 1; }
    else      _offAt[relay] = millis();
  }
  _relay[relay].state = mode;
  if (expanderType == EXPANDER_PCF8574 && _relay[relay].pin >= 100) {
    // we need to send all outputs at the same time
    uint8_t state = 0;
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (_relay[i].pin < 100) continue;
      uint8_t pin = _relay[i].pin - 100;
      state |= (_relay[i].invert ? !_relay[i].state : _relay[i].state) << pin; // fill relay states for all pins
    }
    IOexpanderWrite(expanderAddr, state);
    DEBUG_PRINT(F("Writing to PCF8574: ")); DEBUG_PRINTLN(state);
  } else if (expanderType == EXPANDER_AW9523 && _relay[relay].pin >= 100) {
    // shadow register lets us switch a single port without touching the others
    uint8_t port = _relay[relay].pin - 100;
    bitWrite(awOutputState, port, _relay[relay].invert ? !mode : mode);
    awRegWrite16(AW9523_REG_OUT0, awOutputState);
    DEBUG_PRINT(F("Writing to AW9523: ")); DEBUG_PRINTLN(awOutputState);
  } else if (_relay[relay].pin < 100) {
    pinMode(_relay[relay].pin, OUTPUT);
    digitalWrite(_relay[relay].pin, _relay[relay].invert ? !_relay[relay].state : _relay[relay].state);
  } else return;
  publishMqtt(relay);
}

uint8_t PowerManager::getActiveRelayCount() {
  uint8_t count = 0;
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) if (_relay[i].pin>=0) count++;
  return count;
}

/**
 * couple/decouple a relay to a segment (-1 = none, 0..n = segment id).
 * persist=false applies the link without writing cfg.json - used by preset-carried links
 * ("save":false) so switching presets does not wear flash; the configured links then
 * remain the boot baseline. The Master AC relay role (segment 99) is configured via
 * settings only, not via this API.
 */
void PowerManager::setSegmentLink(uint8_t relay, int seg, bool persist) {
  if (relay >= POWERMANAGER_MAX_RELAYS) return;
  if (relay == 0 && masterEnabled) return; // Master AC relay is not re-linkable
  if (seg < -1 || seg >= (int)strip.getMaxSegments()) seg = -1;
  if (_relay[relay].segment == seg) return;
  _relay[relay].segment = seg;
  _relay[relay].segSeen = false;
  _relay[relay].boPhase = BO_NONE;
  _pendingSince[relay] = 0;
  if (seg >= 0) _relay[relay].external = false; // coupled relays are exclusively segment-driven
  // "Take over all relays": an unlinked relay has no role anymore and must not stay powered.
  // Without it the relay keeps its state until the next main power toggle (default behavior:
  // relays without a role are not touched); handleSegmentCoupling() skips uncoupled relays,
  // so this is the only place a menu/API unlink can switch the relay off.
  else if (takeOverRelays && _relay[relay].state) switchRelay(relay, false);
  if (persist) configNeedsWrite = true; // persist to cfg.json (written from main loop)
}


//Functions called by WLED

#ifndef WLED_DISABLE_MQTT
/**
 * handling of MQTT message
 * topic only contains stripped topic (part after /wled/MAC)
 * topic should look like: /relay/X/command; where X is relay number, 0 based
 */
bool PowerManager::onMqttMessage(char* topic, char* payload) {
  if (strlen(topic) > 8 && strncmp_P(topic, PSTR("/relay/"), 7) == 0) {
    char *numEnd;
    uint8_t relay = strtoul(topic+7, &numEnd, 10);
    // relay number may have more than one digit; "/command" must directly follow it
    if (numEnd != topic+7 && strcmp_P(numEnd, _Command) == 0 && relay<POWERMANAGER_MAX_RELAYS) {
      String action = payload;
      if (action == "on") {
        if (_relay[relay].external) switchRelay(relay, true);
        return true;
      } else if (action == "off") {
        if (_relay[relay].external) switchRelay(relay, false);
        return true;
      } else if (action == FPSTR(_toggle)) {
        if (_relay[relay].external) toggleRelay(relay);
        return true;
      }
    }
  }
  return false;
}

/**
 * subscribe to MQTT topic for controlling relays
 */
void PowerManager::onMqttConnect(bool sessionPresent) {
  //(re)subscribe to required topics
  char subuf[64];
  if (mqttDeviceTopic[0] != 0) {
    strcpy(subuf, mqttDeviceTopic);
    strcat_P(subuf, PSTR("/relay/#"));
    mqtt->subscribe(subuf, 0);
    if (HAautodiscovery) publishHomeAssistantAutodiscovery();
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (_relay[i].pin<0) continue;
      publishMqtt(i); //publish current state
    }
  }
}

void PowerManager::publishHomeAssistantAutodiscovery() {
  for (int i = 0; i < POWERMANAGER_MAX_RELAYS; i++) {
    char uid[24], json_str[1024], buf[128];
    size_t payload_size;
    sprintf_P(uid, PSTR("%s_sw%d"), escapedMac.c_str(), i);

    if (_relay[i].pin >= 0 && _relay[i].external) {
      StaticJsonDocument<1024> json;
      if (_relay[i].name[0]) sprintf_P(buf, PSTR("%s %s"), serverDescription, _relay[i].name); //max length: 33 + 1 + 32 = 66
      else sprintf_P(buf, PSTR("%s Switch %d"), serverDescription, i); //max length: 33 + 8 + 3 = 44
      json[F("name")] = buf;

      sprintf_P(buf, PSTR("%s/relay/%d"), mqttDeviceTopic, i); //max length: 33 + 7 + 3 = 43
      json["~"] = buf;
      strcat_P(buf, _Command);
      mqtt->subscribe(buf, 0);

      json[F("stat_t")]  = "~";
      json[F("cmd_t")]   = F("~/command");
      json[F("pl_off")]  = "off";
      json[F("pl_on")]   = "on";
      json[F("uniq_id")] = uid;

      strcpy(buf, mqttDeviceTopic); //max length: 33 + 7 = 40
      strcat_P(buf, PSTR("/status"));
      json[F("avty_t")]       = buf;
      json[F("pl_avail")]     = F("online");
      json[F("pl_not_avail")] = F("offline");
      //TODO: dev
      payload_size = serializeJson(json, json_str);
    } else {
      //Unpublish disabled or internal relays
      json_str[0]  = 0;
      payload_size = 0;
    }
    sprintf_P(buf, PSTR("homeassistant/switch/%s/config"), uid);
    mqtt->publish(buf, 0, true, json_str, payload_size);
  }
}
#endif

/**
 * setup() is called once at boot. WiFi is not yet connected at this point.
 * You can use it to initialize variables, sensors or similar.
 */
void PowerManager::setup() {
  // pins retrieved from cfg.json (readFromConfig()) prior to running setup(). An expander
  // without a usable I2C bus is left configured but inert (see expanderAvailable()).

  uint16_t state = 0; // desired expander output levels (invert applied)
  uint16_t used  = 0; // expander ports used by relays
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (isCoupled(i)) _relay[i].external = false; // coupled relays are exclusively segment-driven
    // coupled relays boot in Off state; handleSegmentCoupling() syncs them once segments are up
    if (_relay[i].pin >= 100) {
      uint8_t port = _relay[i].pin - 100;
      if (expanderType == EXPANDER_NONE || port >= expanderPortCount()) {
        _relay[i].pin = -1; // no expander configured or port out of range
        continue;
      }
      if (!expanderAvailable()) continue; // I2C bus not usable right now: keep the config, relay stays inert
      if (!_relay[i].external && !isCoupled(i)) _relay[i].state = takeOverRelays ? false : !offMode;
      state |= (uint16_t)(_relay[i].invert ? !_relay[i].state : _relay[i].state) << port;
      used  |= (uint16_t)1 << port;
    } else if (_relay[i].pin>=0) {
      // UM_MultiRelay is the closest core PinOwner; the enum cannot be extended by external usermods
      if (PinManager::allocatePin(_relay[i].pin,true, PinOwner::UM_MultiRelay)) {
        if (!_relay[i].external && !isCoupled(i)) _relay[i].state = takeOverRelays ? false : !offMode;
        switchRelay(i, _relay[i].state);
        _relay[i].active = false;
      } else {
        _relay[i].pin = -1;  // allocation failed
      }
    }
  }
  // fuse / main power sense inputs (AW9523 only): free expander ports; a port already used
  // by a relay is never reconfigured as an input (the relay wins, the sense entry is ignored)
  _senseMask = 0; _fuseMask = 0; _senseStable = 0; _senseRaw = 0; _senseCnt = 0;
  if (expanderType == EXPANDER_AW9523) {
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (i == 0 && masterEnabled) continue; // the Master AC relay has no fuse sense (main rail = main power sense)
      int8_t sp = _relay[i].fusePin;
      if (sp >= 100 && sp < 100+(int)expanderPortCount() && !(used & (1<<(sp-100)))) _fuseMask |= 1<<(sp-100);
    }
    _senseMask = _fuseMask;
    if (mainSensePin >= 100 && mainSensePin < 100+(int)expanderPortCount() && !(used & (1<<(mainSensePin-100))))
      _senseMask |= 1<<(mainSensePin-100);
  }

  if (!expanderAvailable()) {
    awFound = false; // nothing to talk to: expander relays and sensing stay inert until I2C is back
  } else if (expanderType == EXPANDER_PCF8574) {
    IOexpanderWrite(expanderAddr, (uint8_t)state);  // init expander (set all outputs)
    DEBUG_PRINTLN(F("PCF8574 inited."));
  } else if (expanderType == EXPANDER_AW9523) {
    initAW9523(state, used, _senseMask);
  }
  _oldMode = offMode;
  initDone = true;
}

/**
 * loop() is called continuously. Here you can check for events, read sensors, etc.
 */
void PowerManager::loop() {
  static unsigned long lastUpdate = 0;
  yield();
  if (!enabled) return;
  handleBlackout(); // ms-precision power-on sequencing for coupled relays (cheap, runs every pass)
  if (strip.isUpdating() && millis() - lastUpdate < 100) return;

  if (millis() - lastUpdate < 100) return;  // update only 10 times/s
  lastUpdate = millis();

  //set relay when LEDs turn on
  if (_oldMode != offMode) {
    _oldMode = offMode;
    _switchTimerStart = millis();
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      // with "take over all relays", unconfigured relays do not follow main power (stay off)
      if ((_relay[i].pin>=0) && !_relay[i].external && !isCoupled(i) && !takeOverRelays) _relay[i].active = true;
    }
  }

  handleOffTimer();
  handleSegmentCoupling();
  handleSensing();
}

/**
 * 10x/s tick: poll the AW9523 sense inputs (per-output fuse sense, main power rail sense).
 * Debounced over 3 identical samples (~300ms); an I2C hiccup keeps the last stable state.
 */
void PowerManager::handleSensing() {
  if (!_senseMask || expanderType != EXPANDER_AW9523 || !awFound) return;
  uint32_t now = millis();
  int16_t lo = awRegRead8(AW9523_REG_IN0);
  int16_t hi = awRegRead8(AW9523_REG_IN0+1);
  if (lo < 0 || hi < 0) return;
  uint16_t raw = (((uint16_t)hi << 8) | (uint8_t)lo) & _senseMask;
  // normalise to "voltage present" per group: fuse inputs of the indicator type read high
  // when the fuse is BLOWN, the main input may be wired active low
  uint16_t inv = (fuseSenseInvert ? _fuseMask : 0) | (mainSenseInvert ? (_senseMask & ~_fuseMask) : 0);
  raw ^= inv;
  // inrush settle window: the inrush of an output that just switched on (the last one of a
  // staggered bring-up in particular) can briefly light a blown-fuse indicator, so indicator-
  // type fuse inputs keep their last stable state until the window has passed (a voltage-type
  // reading of "present" is always trustworthy and is not held). The main rail keeps updating.
  if (fuseSenseInvert && inrushSettling(now)) raw = (raw & ~_fuseMask) | (_senseStable & _fuseMask);
  if (raw == _senseRaw) { if (_senseCnt < 3) _senseCnt++; }
  else { _senseRaw = raw; _senseCnt = 1; }
  if (_senseCnt >= 3) _senseStable = raw;
}

/**
 * status of one relay's fuse sense input (SENSE_* levels). Voltage present is always green.
 * The fuses sit UPSTREAM of the output MOSFETs (Dig-Next-4 v0r2), so the post-fuse sense
 * node is live whenever the main rail is up - a blown fuse is detectable regardless of the
 * output's own on/off state. Missing voltage is therefore a fault (red) whenever the main
 * rail is confirmed up: by the hardware main sense when configured (already debounced, no
 * extra grace needed), otherwise by the Master AC relay being on past its stabilization
 * window. Without either reference a dead sense cannot be told apart from the PSU simply
 * being off - grey.
 */
uint8_t PowerManager::fuseDot(uint8_t r) {
  int8_t sp = _relay[r].fusePin;
  if (sp < 100 || !awFound || !(_senseMask & (1<<(sp-100)))) return SENSE_NA;
  bool mainUp = (mainSensePin >= 100 && (_senseMask & (1<<(mainSensePin-100)))) ? senseHigh(mainSensePin)
              : (masterEnabled && _relay[0].state
                 && (millis() - _onAt[0] > stabilizeSec*1000UL + POWERMANAGER_SENSE_GRACE_MS));
  bool present = senseHigh(sp); // already normalised: true = fuse intact / voltage after the fuse
  // an indicator-type input (inverted) also reads "intact" when there is no power at all,
  // so it can only be trusted while the main rail is up; a voltage-type input reading
  // "present" is proof by itself
  if (!mainUp) return (present && !fuseSenseInvert) ? SENSE_OK : SENSE_IDLE;
  // inrush settle window after any output switched on: readings are not judged yet, a fault
  // is only ever reported once the window has passed (see handleSensing())
  if (inrushSettling(millis())) return present ? SENSE_OK : SENSE_IDLE;
  return present ? SENSE_OK : SENSE_FAULT;
}

/**
 * status of the main power rail sense input. Missing voltage is a fault (red) once the Master
 * AC relay has been on past the PSU stabilization window (plus grace) - the relay closed but
 * no power arrived on the main terminals. Without that expectation (relay off, or no master
 * relay configured) an absent rail is just "not present" (grey).
 */
uint8_t PowerManager::mainDot() {
  if (mainSensePin < 100 || !awFound || !(_senseMask & (1<<(mainSensePin-100)))) return SENSE_NA;
  if (senseHigh(mainSensePin)) return SENSE_OK;
  bool expected = masterEnabled && _relay[0].state
    && (millis() - _onAt[0] > stabilizeSec*1000UL + POWERMANAGER_SENSE_GRACE_MS);
  return expected ? SENSE_FAULT : SENSE_IDLE;
}

// colored status dot for the Info page (values render as raw HTML there)
String PowerManager::senseDotHtml(uint8_t st) {
  static const char* const dotCol[] = {"#888", "#2c2", "#e33", "#888"}; // NA, OK, FAULT, IDLE
  String d = F("<span style='color:");
  d += dotCol[st < 4 ? st : 0];
  d += F("'>&#9679;</span>");
  return d;
}

// --------------------------------------------------------------------------------------------
// Segment coupling & power sequencing
//
// A relay with `segment` >= 0 is exclusively segment-driven: on while its segment is on (or,
// for POWERMANAGER_SEG_ANY master relays, while any segment is on) and global power is on.
//
// Power-off: segment off -> wait for its fade-out to finish -> wait delay-off-s -> port off
//            (whichever ends later; toggling the segment back on cancels the pending cut).
// Power-on:  segment on -> delay-on-s -> min-off-ms since the last cut -> PSU stabilization
//            of master relays -> blackout sequence, advanced per loop pass by handleBlackout():
//   BO_PRE:  handleOverlayDraw() paints the segment black every frame (blackout enabled), port
//            still off; it is switched on once black-pre-ms passed and the staggered bring-up
//            slot is free (outputs energise at least stagger-ms apart, see staggerSlotFree())
//   BO_POST: port energised while the incoming data is black; stays black over the power ramp
//            (a master relay additionally holds all-black for stabilize-s so the PSU settles)
//   BO_FADE: transitions are force-completed so a stale one (e.g. armed by a global power
//            toggle, with a non-black "from" state) cannot corrupt the restart; one serviced
//            frame later restartSegmentFade() fades the segment up from black
//
// From the first frame after a segment is switched on (or after boot) until its port really
// delivers power, handleOverlayDraw() keeps the segment black as well (awaitingPower()): the
// tick that starts the sequence runs at 10Hz, and the normal frames rendered in between show
// up as a "blip" wherever the LEDs are powered regardless of the relay (master relay not
// wired, bench supply, boot with the supply already up).
// --------------------------------------------------------------------------------------------

/**
 * is any segment the relay is coupled to still running a transition (fade)?
 */
bool PowerManager::isSegFading(uint8_t r) {
  bool fading = false;
  forOwnedSegments(r, [&fading](Segment &seg) { fading |= seg.isInTransition(); });
  return fading;
}

/**
 * force any running transition on the relay's segment(s) to complete (duration 0);
 * it is destroyed on the next serviced frame
 */
void PowerManager::cancelSegTransitions(uint8_t r) {
  forOwnedSegments(r, [](Segment &seg) { seg.startTransition(0); });
}

// restart a segment's fade from black: with `on` temporarily false, startTransition()
// re-captures a running fade-up's "from" brightness as ~0 and restarts its timer, or
// starts a fresh transition from 0 if there is none
static void fadeFromBlack(Segment &seg) {
  seg.on = false;
  seg.startTransition(strip.getTransition(), blendingStyle != TRANSITION_FADE);
  seg.on = true;
}

/**
 * restart the fade-up of the relay's segment(s) from black. WLED starts the fade the moment
 * a segment is switched on, so by the time delay-on-s and the blackout have passed it may
 * have partly or fully elapsed and the LEDs would snap on - restarting it here makes the
 * full fade visible once power is ready.
 */
void PowerManager::restartSegmentFade(uint8_t r) {
  bool restarted = false;
  forOwnedSegments(r, [&restarted](Segment &seg) {
    if (seg.on) { fadeFromBlack(seg); restarted = true; }
  });
  if (!restarted) return;
  if (strip.getTransition()) {
    // handleTransitions() force-ends ALL segment transitions (setTransitionMode(false)) when the
    // global transition window - started at the original on-click - expires. Re-open it so it
    // outlives the restarted fade, otherwise the fade's tail gets chopped (visible brightness
    // pop). If a global brightness ramp is in flight (main power on), re-anchor it at its current
    // level first: resetting the timer alone rewinds briT and causes a visible dip. This is the
    // same re-anchoring stateUpdated() does for changes arriving mid-transition.
    briOld = briT;
    transitionStartTime = millis();
    transitionActive = true;
  }
  strip.trigger(); // rendering may have gone idle during a long hold (PSU stabilization)
}

/**
 * is an "any segment" master relay (PSU trigger) either still off (its own power-on pending)
 * or within the stabilization window? Dependent segment-coupled relays postpone their power-on
 * until this clears, giving the power supply time to come up and settle before sections draw
 * load. Only applies when a stabilization time is configured.
 */
bool PowerManager::masterHoldsOn() {
  if (stabilizeSec == 0) return false;
  unsigned long now = millis();
  for (int m=0; m<POWERMANAGER_MAX_RELAYS; m++) {
    if (_relay[m].pin < 0 || _relay[m].segment != POWERMANAGER_SEG_ANY) continue;
    if (!_relay[m].state) return true; // master not on yet (its own power-on sequence is pending)
    if (now - _onAt[m] < (uint32_t)stabilizeSec * 1000) return true; // still stabilizing
  }
  return false;
}

/**
 * staggered bring-up: has enough time passed since the last relay switched on? Every switch-on
 * counts (master, sections, external/API relays), so two outputs never energise within
 * stagger-ms of each other - the supply sees one inrush at a time instead of all at once.
 */
// inrush settle window after the last relay switched on (see POWERMANAGER_SENSE_GRACE_MS)
bool PowerManager::inrushSettling(uint32_t now) {
  return _lastOnAt != 0 && now - _lastOnAt < POWERMANAGER_SENSE_GRACE_MS;
}

bool PowerManager::staggerSlotFree(uint32_t now) {
  if (!staggerEnabled || staggerMs == 0 || _lastOnAt == 0) return true;
  return now - _lastOnAt >= staggerMs;
}

/**
 * is any specific-segment coupled relay still switched on? An "any segment" master must be
 * the last to cut power: the sections it feeds may have longer off-delays than the master.
 */
bool PowerManager::dependentsStillOn() {
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].pin >= 0 && isCoupled(i) && _relay[i].segment != POWERMANAGER_SEG_ANY && _relay[i].state) return true;
  }
  return false;
}

/**
 * enter BO_FADE: force-complete stale transitions now, restart the fade one frame later
 */
void PowerManager::beginFadePhase(uint8_t r) {
  _relay[r].boPhase = BO_FADE;
  _boStart[r] = millis();
  cancelSegTransitions(r);
  strip.trigger(); // the next serviced frame destroys the cancelled transition(s)
}

/**
 * 10x/s tick: drive coupled relays towards their segment's on/off state (see section comment)
 */
void PowerManager::handleSegmentCoupling() {
  unsigned long now = millis();

  // main power sync, on-half: we switched main power off when the master cut - a segment
  // being switched on brings it back (turning main power on manually just clears the flag)
  if (_autoMainOff) {
    if (bri > 0) _autoMainOff = false;
    else {
      bool anyOn = false;
      for (unsigned s = 0; s < strip.getSegmentsNum() && !anyOn; s++) {
        const Segment &seg = strip.getSegment(s);
        anyOn = seg.isActive() && seg.on;
      }
      if (anyOn) {
        _autoMainOff = false;
        toggleOnOff(); // on (restores briLast); the master then powers up through the normal sequence
        stateUpdated(CALL_MODE_DIRECT_CHANGE);
      }
    }
  }

  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].pin < 0 || !isCoupled(i)) continue;

    bool segOn = false;
    if (_relay[i].segment == POWERMANAGER_SEG_ANY) {
      forOwnedSegments(i, [&segOn](Segment &seg) { segOn |= seg.on; });
    } else if ((uint8_t)_relay[i].segment < strip.getSegmentsNum() && strip.getSegment(_relay[i].segment).isActive()) {
      _relay[i].segSeen = true;
      segOn = strip.getSegment(_relay[i].segment).on;
    } else if (_relay[i].segSeen) {
      // linked segment was deleted at runtime: cut power and drop the link so a new segment
      // reusing this id does not inherit it. segSeen guards against boot races: segments may
      // not exist yet during the first loop passes, links must survive that.
      if (_relay[i].state) switchRelay(i, false);
      setSegmentLink(i, -1);
      continue;
    }

    bool target = segOn && !offMode;
    if (target == _relay[i].state) {
      _pendingSince[i] = 0; // in sync; also cancels a pending delayed switch
      if (!target && _relay[i].boPhase == BO_PRE) _relay[i].boPhase = BO_NONE; // segment went off again before power-on
      continue;
    }

    if (target) { // segment on, relay still off
      if (_relay[i].boPhase != BO_NONE) continue;                    // power-on sequence already running (handleBlackout())
      // PSU first: while a master relay is still powering up or stabilizing, keep the delay-on
      // timer unarmed so delay-on-s starts counting only once the PSU is ready (sequential).
      // With the master already up and past its window, only delay-on-s applies.
      if (_relay[i].segment != POWERMANAGER_SEG_ANY && masterHoldsOn()) { _pendingSince[i] = 0; continue; }
      if (_pendingSince[i] == 0) _pendingSince[i] = now ? now : 1;   // 0 means "nothing pending"
      if (now - _pendingSince[i] < (uint32_t)_relay[i].delayOn * 1000) continue;
      if (now - _offAt[i] < minOffMs) continue; // let the LEDs discharge after a cut (prevents white flash)
      _pendingSince[i] = 0;
      // hand over to the per-pass power-on sequence (handleBlackout()): black window, staggered
      // energise slot, post-power hold, fade restart. With blackout disabled the black windows
      // are zero-length and no black is painted, but the stagger slot still applies.
      _relay[i].boPhase = BO_PRE;
      _boStart[i] = now;
      strip.trigger();            // make sure frames are being rendered/sent
    } else {      // segment off, relay still on
      if (_pendingSince[i] == 0) _pendingSince[i] = now ? now : 1;
      // master relay: hold while any dependent section relay is still on - the PSU must be the
      // last to cut. Its delay-off then counts from the moment the last section switched off.
      if (_relay[i].segment == POWERMANAGER_SEG_ANY && dependentsStillOn()) {
        _pendingSince[i] = now ? now : 1;
        continue;
      }
      unsigned long elapsed = now - _pendingSince[i];
      // let a running fade-out finish before cutting power (bounded in case transition state lingers)
      if (isSegFading(i) && elapsed < strip.getTransition() + POWERMANAGER_FADE_GRACE_MS) continue;
      if (elapsed >= (uint32_t)_relay[i].delayOff * 1000) {
        _pendingSince[i] = 0;
        _relay[i].boPhase = BO_NONE; // abandon a power-on sequence still in a late phase
        switchRelay(i, false);
        // main power sync, off-half: the master just cut because every segment was switched
        // off (bri > 0 rules out a main power press as the cause) - reflect it on main power
        if (_relay[i].segment == POWERMANAGER_SEG_ANY && masterMainSync && bri > 0) {
          toggleOnOff(); // off (preserves briLast)
          stateUpdated(CALL_MODE_DIRECT_CHANGE);
          _autoMainOff = true;
        }
      }
    }
  }
}

/**
 * power-on blackout state machine (see section comment). Called every loop pass, unlike the
 * 100ms coupling tick, so the phase timing is ms-accurate.
 */
void PowerManager::handleBlackout() {
  unsigned long now = millis();
  // evaluate BO_FADE readiness for ALL relays before any fade is restarted: a restart creates a
  // fresh transition on the segment, which a later relay in this loop (sharing the segment, or
  // an "any segment" master) would mistake for the stale transition it is waiting on - stalling
  // against it until the safety timeout and staggering the fades instead of starting them in
  // parallel. A duplicate restart of a same-pass fresh transition is a no-op.
  uint16_t fadeReady = 0; // bitmask, POWERMANAGER_MAX_RELAYS is capped at 16
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].boPhase == BO_FADE && (!isSegFading(i) || now - _boStart[i] > BO_FADE_TIMEOUT_MS))
      fadeReady |= (uint16_t)1 << i;
  }
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    switch (_relay[i].boPhase) {
      case BO_PRE: // port still off (black frames streaming if blackout is enabled)
        if (now - _boStart[i] >= boPreMs && staggerSlotFree(now)) { // staggered bring-up: one output per slot
          switchRelay(i, true); // LEDs power up while the incoming data is black
          _relay[i].boPhase = BO_POST;
          _boStart[i] = now;
        }
        break;
      case BO_POST: { // port on, stay black over the power ramp
        uint32_t hold = boPostMs;
        // master (any-segment) relay: extend the all-black hold by the PSU stabilization time
        if (_relay[i].segment == POWERMANAGER_SEG_ANY) hold += (uint32_t)stabilizeSec * 1000;
        if (now - _boStart[i] >= hold) beginFadePhase(i);
        break;
      }
      case BO_FADE: // cancelled stale transition is being destroyed, still black
        if ((fadeReady >> i) & 1) {
          _relay[i].boPhase = BO_NONE;
          restartSegmentFade(i); // the LEDs have power now - fade up from black
        }
        break;
    }
  }
}

/**
 * does a coupled relay's segment want power that its port is not delivering yet? True while a
 * power-on sequence runs (BO_PRE/BO_POST/BO_FADE) and, with blackout enabled, already from the
 * very first frame after the segment was switched on: the 10Hz coupling tick starts the
 * sequence up to 100ms later, and until then WLED would render normal frames - harmless on a
 * port that is really unpowered, but a visible blip on hardware where power is present anyway
 * (a Master AC relay that is configured but not wired, a bench supply, boot with the supply
 * already up). The same rule covers the other waits in the power-on path (delay-on-s,
 * min-off-ms, dependents waiting for the master's stabilization). A port that cannot be
 * driven at all (expander without I2C) is not blacked out - that would only hide the problem.
 */
bool PowerManager::awaitingPower(uint8_t r) {
  if (_relay[r].pin < 0 || !isCoupled(r)) return false;
  if (_relay[r].boPhase == BO_FADE) return true;          // one black frame while the stale transition is destroyed
  if (_relay[r].boPhase != BO_NONE) return boPreMs || boPostMs; // power-on sequence: black window only with blackout enabled
  if (_relay[r].state || !(boPreMs || boPostMs)) return false; // port energised / blackout disabled
  if (_relay[r].pin >= 100 && !expanderAvailable()) return false;
  if (offMode) return false;
  bool segOn = false;
  forOwnedSegments(r, [&segOn](Segment &seg) { segOn |= seg.on; });
  return segOn;                                            // wants power, port still off
}

/**
 * paint the segments of relays whose port is not delivering power yet black (called for every
 * frame, after effects are rendered and just before strip.show())
 */
void PowerManager::handleOverlayDraw() {
  if (!enabled) return;
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (!awaitingPower(i)) continue;
    if (_relay[i].segment == POWERMANAGER_SEG_ANY) { // master relay: black out the whole strip
      unsigned len = strip.getLengthTotal();
      for (unsigned p = 0; p < len; p++) strip.setPixelColor(p, 0);
      continue;
    }
    if ((uint8_t)_relay[i].segment >= strip.getSegmentsNum()) continue;
    const Segment &seg = strip.getSegment(_relay[i].segment);
    if (!seg.isActive()) continue;
#ifndef WLED_DISABLE_2D
    if (strip.isMatrix && seg.is2D()) {
      for (int y = seg.startY; y < seg.stopY; y++)
        for (int x = seg.start; x < seg.stop; x++) strip.setPixelColorXY(x, y, 0);
      continue;
    }
#endif
    for (unsigned p = seg.start; p < seg.stop; p++) strip.setPixelColor(p, 0);
  }
}

#ifdef WLED_ENABLE_UM_UI_INJECT
/**
 * Segment-card "Power relays" menu, injected into the main UI via the /um.js mechanism
 * (concept by @blazoncek). This runs as the body of umInject(s) after every state render,
 * so the menu survives segment card re-renders; `s` is the freshly applied state object,
 * carrying our relay list from addToJsonState(). Menu open/close state persists in
 * window.pmOpen across renders. When the usermod is disabled, s.PowerManager is absent
 * and any previously injected menus are removed. On WLED bases without the injection
 * mechanism this block compiles out and relays are linked on the settings page instead.
 */
void PowerManager::addUIInjectCode(Print &dest) {
  dest.print(F(
    "let pmE=t=>d.createElement(t);" // cE() only exists on the settings pages, not in the main UI
    "let pmR=[];"
    "if(s&&s.PowerManager)pmR=(Array.isArray(s.PowerManager.relays)?s.PowerManager.relays:[s.PowerManager])"
      ".filter(r=>r.seg!==undefined&&r.seg!=99);"
    "window.pmOpen=window.pmOpen||{};"
    "d.querySelectorAll('#segcont .segin').forEach(sc=>{"
      "let old=sc.querySelector('.pmrow');if(old)old.remove();"
      "old=sc.querySelector('.pmlist');if(old)old.remove();"
      "if(!pmR.length)return;"
      "let i=parseInt(sc.id.replace('seg',''));if(isNaN(i))return;"
  ));
  dest.print(F(
      "let lnk=pmR.filter(r=>r.seg==i).map(r=>r.name||('Relay '+r.relay)).join(', ');"
      "let hd=pmE('div');hd.className='check revchkl pmrow';hd.style.cursor='pointer';"
      "hd.title='Link power relays: their output is cut when this segment is off';"
      "hd.textContent='Power relays: '+(lnk||'none');"
      "let ic=pmE('i');ic.className='icons e-icon'+(pmOpen[i]?' exp':'');"
      "ic.style.cssText='position:absolute;left:0;top:3px;transition:transform .3s;';"
      "ic.innerHTML='&#xe395;';hd.appendChild(ic);"
      "let ls=pmE('div');ls.className='pmlist'+(pmOpen[i]?'':' hide');ls.style.marginLeft='16px';"
      "hd.onclick=()=>{pmOpen[i]=!pmOpen[i];ls.classList.toggle('hide',!pmOpen[i]);ic.classList.toggle('exp',pmOpen[i]);};"
  ));
  dest.print(F(
      "pmR.forEach(r=>{"
        "let lb=pmE('label');lb.className='check revchkl';"
        "if(r.fu){let fd=pmE('span');fd.textContent='\\u25CF ';" // fuse sense dot (state carries "fu" when sensing is configured)
          "fd.style.color=r.fu==1?'#2c2':r.fu==2?'#e33':'#888';"
          "fd.title=r.fu==1?'fuse OK - voltage present':r.fu==2?'no voltage after fuse - check fuse':'main power off';"
          "lb.appendChild(fd);}"
        "lb.append(r.name||('Relay '+r.relay));"
        "let sp;"
        "if(r.seg==i){sp=pmE('span');sp.style.cssText='color:var(--c-g);font-size:smaller;';"
          "sp.textContent=' (this segment)';lb.appendChild(sp);}"
        "else if(r.seg>=0){let os=(s.seg||[]).find(q=>q.id==r.seg);sp=pmE('span');"
          "sp.style.cssText='color:var(--c-d);font-size:smaller;';"
          "sp.textContent=' ('+(os&&os.n?os.n:'Segment '+r.seg)+')';lb.appendChild(sp);}"
        "let cb=pmE('input');cb.type='checkbox';cb.checked=(r.seg==i);"
        "cb.onchange=()=>{requestJson({PowerManager:{relay:r.relay,seg:cb.checked?i:-1}});};"
        "let cm=pmE('span');cm.className='checkmark';"
        "lb.appendChild(cb);lb.appendChild(cm);ls.appendChild(lb);"
      "});"
      "let dl=sc.querySelector('div.del');"
      "if(dl){sc.insertBefore(hd,dl);sc.insertBefore(ls,dl);}else{sc.appendChild(hd);sc.appendChild(ls);}"
    "});"
  ));
}
#endif // WLED_ENABLE_UM_UI_INJECT

/**
 * handleButton() can be used to override default button behaviour. Returning true
 * will prevent button working in a default way.
 * Replicating button.cpp
 */
bool PowerManager::handleButton(uint8_t b) {
  yield();
  if (!enabled
    || buttons[b].type == BTN_TYPE_NONE
    || buttons[b].type == BTN_TYPE_RESERVED
    || buttons[b].type == BTN_TYPE_PIR_SENSOR
    || buttons[b].type == BTN_TYPE_ANALOG
    || buttons[b].type == BTN_TYPE_ANALOG_INVERTED) {
    return false;
  }

  bool handled = false;
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].button == b && _relay[i].external) {
      handled = true;
    }
  }
  if (!handled) return false;

  unsigned long now = millis();

  //button is not momentary, but switch. This is only suitable on pins whose on-boot state does not matter (NOT gpio0)
  if (buttons[b].type == BTN_TYPE_SWITCH) {
    //handleSwitch(b);
    if (buttons[b].pressedBefore != isButtonPressed(b)) {
      buttons[b].pressedTime = now;
      buttons[b].pressedBefore = !buttons[b].pressedBefore;
    }

    if (buttons[b].longPressed == buttons[b].pressedBefore) return handled;
      
    if (now - buttons[b].pressedTime > WLED_DEBOUNCE_THRESHOLD) { //fire edge event only after 50ms without change (debounce)
      for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
        if (_relay[i].button == b && !isCoupled(i)) {
          switchRelay(i, buttons[b].pressedBefore);
          buttons[b].longPressed = buttons[b].pressedBefore; //save the last "long term" switch state
        }
      }
    }
    return handled;
  }

  //momentary button logic
  if (isButtonPressed(b)) { //pressed

    if (!buttons[b].pressedBefore) buttons[b].pressedTime = now;
    buttons[b].pressedBefore = true;

    if (now - buttons[b].pressedTime > 600) { //long press
      //longPressAction(b); //not exposed
      //handled = false; //use if you want to pass to default behaviour
      buttons[b].longPressed = true;
    }

  } else if (!isButtonPressed(b) && buttons[b].pressedBefore) { //released

    long dur = now - buttons[b].pressedTime;
    if (dur < WLED_DEBOUNCE_THRESHOLD) {
      buttons[b].pressedBefore = false;
      return handled;
    } //too short "press", debounce
    bool doublePress = buttons[b].waitTime; //did we have short press before?
    buttons[b].waitTime = 0;

    if (!buttons[b].longPressed) { //short press
      // if this is second release within 350ms it is a double press (buttonWaitTime!=0)
      if (doublePress) {
        //doublePressAction(b); //not exposed
        //handled = false; //use if you want to pass to default behaviour
      } else  {
        buttons[b].waitTime = now;
      }
    }
    buttons[b].pressedBefore = false;
    buttons[b].longPressed = false;
  }
  // if 350ms elapsed since last press/release it is a short press
  if (buttons[b].waitTime && now - buttons[b].waitTime > 350 && !buttons[b].pressedBefore) {
    buttons[b].waitTime = 0;
    //shortPressAction(b); //not exposed
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (_relay[i].button == b && !isCoupled(i)) {
        toggleRelay(i);
      }
    }
  }
  return handled;
}

/**
 * addToJsonInfo() can be used to add custom entries to the /json/info part of the JSON API.
 */
void PowerManager::addToJsonInfo(JsonObject &root) {
  if (enabled) {
    JsonObject user = root["u"];
    if (user.isNull())
      user = root.createNestedObject("u");

    // visual separator above the PowerManager block (info keys/values render as raw HTML;
    // the hr is stretched from the key cell across the empty value cell)
    user.createNestedArray(F("<hr style=\"width:200%\">")).add(F(""));

    JsonArray infoArr = user.createNestedArray(FPSTR(_name)); //name
    infoArr.add(String(getActiveRelayCount()));
    infoArr.add(F(" relays"));

    if (expanderType == EXPANDER_AW9523) {
      JsonArray awArr = user.createNestedArray(F("AW9523"));
      awArr.add(awFound ? F("found @") : F("not found @"));
      awArr.add(String(F(" 0x")) + String(expanderAddr, HEX));
    }

    // fuse / main power sense overview: a single green dot when every sensed fuse is fine,
    // grey when the main rail is down (nothing to judge), otherwise only the broken ports
    // are listed with red dots. Per-relay dots are on the coupled relay rows below.
    if (_senseMask && awFound) {
      String dots;
      bool anySense = false, anyOk = false, anyFault = false;
      for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
        uint8_t fd = fuseDot(i);
        if (fd == SENSE_NA) continue;
        anySense = true;
        if (fd == SENSE_OK) { anyOk = true; continue; }
        if (fd != SENSE_FAULT) continue;
        anyFault = true;
        dots += senseDotHtml(fd);
        dots += F("&nbsp;");
        if (_relay[i].name[0]) dots += _relay[i].name;
        else { dots += F("Relay "); dots += i; }
        dots += F("&nbsp;&nbsp;");
      }
      if (anySense) {
        if (!anyFault) dots = senseDotHtml(anyOk ? SENSE_OK : SENSE_IDLE);
        user.createNestedArray(F("Fuses")).add(dots);
      }
      uint8_t md = mainDot();
      if (md != SENSE_NA) {
        String m = senseDotHtml(md);
        m += F("&nbsp;");
        m += (md == SENSE_OK) ? F("present") : ((md == SENSE_FAULT) ? F("AC relay on, no power detected") : F("not present"));
        user.createNestedArray(F("Main power")).add(m);
      }
    }

    String uiDomString;
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (_relay[i].pin<0 || !_relay[i].external) continue;
      uiDomString = F("Relay "); uiDomString += i;
      if (_relay[i].name[0]) { uiDomString += F(" ("); uiDomString += _relay[i].name; uiDomString += ')'; }
      infoArr = user.createNestedArray(uiDomString); // timer value

      uiDomString = F("<button class=\"btn btn-xs\" onclick=\"requestJson({");
      uiDomString += FPSTR(_name);
      uiDomString += F(":{");
      uiDomString += FPSTR(_relay_str);
      uiDomString += F(":");
      uiDomString += i;
      uiDomString += F(",on:");
      uiDomString += _relay[i].state ? "false" : "true";
      uiDomString += F("}});\">");
      uiDomString += F("<i class=\"icons ");
      uiDomString += _relay[i].state ? "on" : "off";
      uiDomString += F("\">&#xe08f;</i></button>");
      infoArr.add(uiDomString);
    }

    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
      if (_relay[i].pin<0 || !isCoupled(i)) continue;
      uiDomString = F("Relay "); uiDomString += i;
      if (_relay[i].name[0]) { uiDomString += F(" ("); uiDomString += _relay[i].name; uiDomString += ')'; }
      infoArr = user.createNestedArray(uiDomString);
      if (_relay[i].segment == POWERMANAGER_SEG_ANY) uiDomString = F("follows any segment");
      else {
        uiDomString = F("follows ");
        uint8_t sid = _relay[i].segment;
        // show the segment's custom name when it has one
        if (sid < strip.getSegmentsNum() && strip.getSegment(sid).name && strip.getSegment(sid).name[0]) {
          uiDomString += strip.getSegment(sid).name;
        } else {
          uiDomString += F("segment "); uiDomString += sid;
        }
      }
      uiDomString += _relay[i].state ? F(" (on)") : F(" (off)");
      uint8_t fd = fuseDot(i); // fuse sense dot in front of the coupled relay's status
      if (fd != SENSE_NA) uiDomString = senseDotHtml(fd) + F("&nbsp;") + uiDomString;
      infoArr.add(uiDomString);
    }
  }
}

/**
 * addToJsonState() can be used to add custom entries to the /json/state part of the JSON API (state object).
 * Values in the state object may be modified by connected clients
 */
void PowerManager::addToJsonState(JsonObject &root) {
  if (!initDone || !enabled) return;  // prevent crash on boot applyPreset()
  JsonObject multiRelay = root[FPSTR(_name)];
  if (multiRelay.isNull()) {
    multiRelay = root.createNestedObject(FPSTR(_name));
  }
  #if POWERMANAGER_MAX_RELAYS > 1
  JsonArray rel_arr = multiRelay.createNestedArray(F("relays"));
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    if (_relay[i].pin < 0) continue;
    JsonObject relay = rel_arr.createNestedObject();
    relay[FPSTR(_relay_str)] = i;
    relay["state"] = _relay[i].state;
    relay["seg"]   = _relay[i].segment;
    uint8_t fd = fuseDot(i);
    if (fd != SENSE_NA) relay["fu"] = fd; // fuse sense status (SENSE_OK/FAULT/IDLE) for the segment menu
    if (_relay[i].name[0]) relay["name"] = (const char*)_relay[i].name;
  }
  uint8_t md = mainDot();
  if (md != SENSE_NA) multiRelay["main"] = md; // main power sense status
  #else
  multiRelay[FPSTR(_relay_str)] = 0;
  multiRelay["state"] = _relay[0].state;
  multiRelay["seg"]   = _relay[0].segment;
  uint8_t fd0 = fuseDot(0);
  if (fd0 != SENSE_NA) multiRelay["fu"] = fd0;
  uint8_t md0 = mainDot();
  if (md0 != SENSE_NA) multiRelay["main"] = md0;
  if (_relay[0].name[0]) multiRelay["name"] = (const char*)_relay[0].name;
  #endif
}

/**
 * readFromJsonState() can be used to receive data clients send to the /json/state part of the JSON API (state object).
 * Values in the state object may be modified by connected clients
 */
void PowerManager::readFromJsonState(JsonObject &root) {
  if (!initDone || !enabled) return;  // prevent crash on boot applyPreset()
  JsonObject usermod = root[FPSTR(_name)];
  if (!usermod.isNull()) {
    if (usermod[FPSTR(_relay_str)].is<int>() && usermod[FPSTR(_relay_str)].as<int>()>=0) {
      uint8_t rly = usermod[FPSTR(_relay_str)].as<int>();
      if (rly < POWERMANAGER_MAX_RELAYS) {
        if (usermod["seg"].is<int>()) setSegmentLink(rly, usermod["seg"].as<int>(), usermod["save"] | true);
        if (usermod["on"].is<bool>()) {
          if (!isCoupled(rly)) switchRelay(rly, usermod["on"].as<bool>());
        } else if (usermod["on"].is<const char*>() && usermod["on"].as<const char*>()[0] == 't') {
          if (!isCoupled(rly)) toggleRelay(rly);
        }
      }
    }
  } else if (root[FPSTR(_name)].is<JsonArray>()) {
    JsonArray relays = root[FPSTR(_name)].as<JsonArray>();
    for (JsonVariant r : relays) {
      if (r[FPSTR(_relay_str)].is<int>() && r[FPSTR(_relay_str)].as<int>()>=0) {
        uint8_t rly = r[FPSTR(_relay_str)].as<int>();
        if (rly >= POWERMANAGER_MAX_RELAYS) continue;
        if (r["seg"].is<int>()) setSegmentLink(rly, r["seg"].as<int>(), r["save"] | true);
        if (r["on"].is<bool>()) {
          if (!isCoupled(rly)) switchRelay(rly, r["on"].as<bool>());
        } else if (r["on"].is<const char*>() && r["on"].as<const char*>()[0] == 't') {
          if (!isCoupled(rly)) toggleRelay(rly);
        }
      }
    }
  }
}

/**
 * provide the changeable values
 */
void PowerManager::addToConfig(JsonObject &root) {
  JsonObject top = root.createNestedObject(FPSTR(_name));

  top[FPSTR(_enabled)] = enabled;
  top[FPSTR(_takeOver)] = takeOverRelays;
  top[FPSTR(_expander)] = expanderType;
  top[FPSTR(_expanderAddr)] = expanderAddr;
  top[FPSTR(_pushPull)] = awP0PushPull;
  top[FPSTR(_broadcast)] = periodicBroadcastSec;
  top[FPSTR(_HAautodiscovery)] = HAautodiscovery;
  top[FPSTR(_blackPre)]  = boPreMs;
  top[FPSTR(_blackPost)] = boPostMs;
  top[FPSTR(_stabilize_str)] = stabilizeSec;
  top[FPSTR(_minOff)] = minOffMs;
  top[FPSTR(_stagger)] = staggerEnabled;
  top[FPSTR(_staggerMs)] = staggerMs;
  top[FPSTR(_mainSense)] = mainSensePin;
  top[FPSTR(_mainInv)] = (uint8_t)(mainSenseInvert ? 1 : 0); // numeric: rendered as dropdowns on the settings page
  top[FPSTR(_fuseInv)] = (uint8_t)(fuseSenseInvert ? 1 : 0);
  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    String parName = FPSTR(_relay_str); parName += '-'; parName += i;
    JsonObject relay = top.createNestedObject(parName);
    if (i == 0) { // relay 0 = Master AC relay slot
      relay[FPSTR(_master)]   = masterEnabled;
      relay[FPSTR(_mainSync)] = masterMainSync;
    }
    relay["name"]             = (const char*)_relay[i].name;
    relay["pin"]              = _relay[i].pin;
    relay[FPSTR(_activeHigh)] = _relay[i].invert;
    relay[FPSTR(_delayOn_str)]  = _relay[i].delayOn;
    relay[FPSTR(_delayOff_str)] = _relay[i].delayOff;
    relay[FPSTR(_external)]   = _relay[i].external;
    relay[FPSTR(_button)]     = _relay[i].button;
    relay[FPSTR(_segment_str)] = _relay[i].segment;
    relay[FPSTR(_fusePin)]    = _relay[i].fusePin;
  }
  DEBUG_PRINTLN(F("PowerManager config saved."));
}

void PowerManager::appendConfigData() {
  oappend(F("dd=addDropdown('PowerManager','expander');"));
  oappend(F("addOption(dd,'None',0);"));
  oappend(F("addOption(dd,'PCF8574',1);"));
  oappend(F("addOption(dd,'AW9523',2);"));
  oappend(F("addInfo('PowerManager:broadcast-sec',1,'(MQTT message)');"));
  oappend(F("mrT=d.getElementsByName('PowerManager:take-over-relays');if(mrT.length>1){"
      "if(mrT[0].previousSibling)mrT[0].previousSibling.nodeValue=' Take over all relays ';"
      "mrT[1].insertAdjacentHTML('afterend',\"<div style='font-size:smaller;'>unconfigured relays (no segment link, not external) stay off instead of following main power</div>\");}"));
  // anti-flash blackout explanation on its own line below the second field
  oappend(F("mrB=d.getElementsByName('PowerManager:black-post-ms');if(mrB.length>1)mrB[1].insertAdjacentHTML('afterend',\"<div style='font-size:smaller;'>anti-flash: black frames sent to a coupled segment before (pre) and after (post) its power port switches on; both 0 = disabled</div>\");"));
  // segment coupling explanation on its own line below the first relay's segment field (avoids wrapping)
  oappend(F("mrQ=d.getElementsByName('PowerManager:relay-0:segment');if(mrQ.length>1)mrQ[1].insertAdjacentHTML('afterend',\"<div id='mrQI' style='font-size:smaller;'>-1 = off &middot; 0-31 = follow that segment</div>\");"));
  // PSU stabilization explanation below its (global) field
  oappend(F("mrY=d.getElementsByName('PowerManager:stabilize-s');if(mrY.length>1)mrY[1].insertAdjacentHTML('afterend',\"<div style='font-size:smaller;'>PSU stabilization: after the Master AC relay powers on, the other relays wait this long; a relay's own Delay On S is added on top (staggered power-on)</div>\");"));
  oappend(F("mrO=d.getElementsByName('PowerManager:min-off-ms');if(mrO.length>1)mrO[1].insertAdjacentHTML('afterend',\"<div style='font-size:smaller;'>minimum port off-time before re-energising, lets LEDs discharge (prevents white flash on rapid toggling)</div>\");"));
  // per relay row: grey out External for coupled relays (exclusively segment-driven).
  // Relay 0 is the dedicated "Master AC relay" slot: its Master checkbox renames the heading,
  // hides the segment row (driven to 99/-1 behind the scenes) and badges it as the PSU master.
  oappend(F("for(let r=0;;r++){"
      "let sg=d.getElementsByName('PowerManager:relay-'+r+':segment'),ex=d.getElementsByName('PowerManager:relay-'+r+':external');"
      "if(sg.length<2||ex.length<2)break;"
      "let fx=()=>{let c=parseInt(sg[1].value)>=0;ex[1].disabled=c;if(c)ex[1].checked=false;};"
      "sg[1].addEventListener('input',fx);"
      // relabel truthfully ('active-high' stores the invert flag, 'external' = externally controlled)
      // and join both checkboxes on one line with a small divider
      "let a=mrW('relay-'+r+':active-high'),e2=mrW('relay-'+r+':external');"
      "if(a)a.firstChild.nodeValue=' Active Low ';"
      "if(e2)e2.firstChild.nodeValue=' External control ';"
      "let fw=mrW('relay-'+r+':fuse-pin');if(fw)fw.firstChild.nodeValue=' Fuse sense pin ';"
      "if(a&&e2){if(a.lastChild&&a.lastChild.nodeName=='BR')a.removeChild(a.lastChild);"
      "let dl=cE('span');dl.textContent='|';dl.style.cssText='opacity:.5;margin:0 8px;';"
      "a.after(dl);dl.after(e2);}"
      "if(r==0){"
        "let mk=d.getElementsByName('PowerManager:relay-0:master'),w=mrW('relay-0:segment'),q=gId('mrQI'),hu;"
        "d.querySelectorAll('#um u').forEach(u=>{if(u.textContent=='Relay 0')hu=u;});"
        "if(mk.length>1){"
          "let mw=mrW('relay-0:master');if(mw)mw.firstChild.nodeValue=' Enabled ';"
          "let ws=mrW('relay-0:main-sync');"
          "if(ws){ws.firstChild.nodeValue=' Sync main power ';"
            "let dv=cE('div');dv.style.fontSize='smaller';"
            "dv.innerHTML='all segments off &rarr; main power off; turning any segment back on automatically enables main power again';"
            "ws.insertBefore(dv,ws.lastChild);}"
          "let fm=()=>{let on=mk[1].checked;"
            "if(hu){hu.textContent=on?'Master AC relay':'Relay 0';hu.classList.toggle('warn',on);}"
            "if(w)w.style.display=on?'none':'';if(q)q.style.display=on?'none':'';"
            // the Master AC relay has no fuse sense pin: the main rail is covered by the Power sensing section
            "if(fw){fw.style.display=on?'none':'';if(on){let fi=d.getElementsByName('PowerManager:relay-0:fuse-pin');if(fi.length>1)fi[1].value=-1;}}"
            "if(ws)ws.style.display=on?'':'none';"
            "if(on)sg[1].value=99;else if(parseInt(sg[1].value)==99)sg[1].value=-1;"
            "fx();};"
          "mk[1].addEventListener('change',fm);fm();"
          // convenience default when enabling the master by hand: 5s PSU anti-cycling off-delay
          "mk[1].addEventListener('change',()=>{if(mk[1].checked){let df=d.getElementsByName('PowerManager:relay-0:delay-off-s');if(df.length>1&&parseInt(df[1].value)==0)df[1].value=5;}});"
        "}"
      "}else{sg[1].min=-1;sg[1].max=63;}"
      "fx();}"));
  // wrap a field row (label text node + hidden & visible input + line break) in a span so it can be shown/hidden
  oappend(F("function mrW(n){let e=d.getElementsByName('PowerManager:'+n);if(e.length<2)return null;let s=cE('span'),l=e[0].previousSibling,r=e[1].nextSibling;e[0].parentNode.insertBefore(s,l);s.append(l,e[0],e[1]);if(r&&r.nodeName=='BR')s.append(r);return s;}"));
  oappend(F("mrA=mrW('expander-address');mrP=mrW('AW9523-pushpull');"));
  // section dividers + bold headers (the usermod's own h3 title stays the biggest)
  oappend(F("mrH=(el,t)=>{if(el)el.insertAdjacentHTML('beforebegin','<hr class=\"sml\"><p style=\"font-weight:bold;font-size:105%;margin:8px 0 4px;\">'+t+'</p>');};"));
  // staggered bring-up: checkbox + spacing field (spacing greyed out while disabled)
  oappend(F("mrSG=mrW('stagger');mrSM=mrW('stagger-ms');"
      "if(mrSG){mrSG.firstChild.nodeValue=' Staggered bring-up ';"
      "mrSG.insertBefore(Object.assign(cE('div'),{innerHTML:'outputs never switch on closer together than the spacing below - spreads the inrush hit on the power supply when several sections power up at once (boot, main power on, presets); a waiting output simply keeps its anti-flash black window a little longer'}),mrSG.lastChild).style.fontSize='smaller';}"
      "if(mrSM)mrSM.firstChild.nodeValue=' Stagger spacing ms ';"
      "let sgc=d.getElementsByName('PowerManager:stagger'),sgm=d.getElementsByName('PowerManager:stagger-ms');"
      "if(sgc.length>1&&sgm.length>1){let fs=()=>{sgm[1].disabled=!sgc[1].checked;};sgc[1].addEventListener('change',fs);fs();}"));
  oappend(F("mrH(mrW('expander'),'Expander');"));
  oappend(F("mrH(mrW('broadcast-sec'),'Broadcast');"));
  oappend(F("mrH(mrW('black-pre-ms'),'Power sequencing');"));
  // power sensing section (AW9523 input ports; fields exist for other expanders but are inert)
  // polarity settings as dropdowns whose options read as sentences (an "invert" checkbox was unclear)
  oappend(F("dd=addDropdown('PowerManager','main-sense-mode');addOption(dd,'high when power is present',0);addOption(dd,'low when power is present',1);"));
  oappend(F("dd=addDropdown('PowerManager','fuse-sense-mode');addOption(dd,'high when the fuse is OK (voltage after the fuse)',0);addOption(dd,'high when the fuse is blown (indicator circuit)',1);"));
  oappend(F("mrMS=mrW('main-sense-pin');mrH(mrMS,'Power sensing');"
      "if(mrMS)mrMS.firstChild.nodeValue=' Main power sense pin ';"
      "mrMM=mrW('main-sense-mode');if(mrMM)mrMM.firstChild.nodeValue=' Main power sense input is ';"
      "mrFM=mrW('fuse-sense-mode');"
      "if(mrFM){mrFM.firstChild.nodeValue=' Fuse sense inputs are ';"
      "mrFM.insertBefore(Object.assign(cE('div'),{innerHTML:'Free AW9523 input ports can sense the main supply rail and the fuse of each output (the fuse sense pin is set per relay below). Status dots on the Info page and in the segment relay menu:<br><span style=color:#2c2>&#9679; green = OK</span>&nbsp;&nbsp;&nbsp;<span style=color:#e33>&#9679; red = fault</span>&nbsp;&nbsp;&nbsp;<span style=color:#888>&#9679; grey = main power off</span>'}),mrFM.lastChild).style.fontSize='smaller';}"));
  oappend(F("if(mrP){mrP.firstChild.nodeValue=' AW9523 Push-Pull ';mrP.insertBefore(Object.assign(cE('div'),{innerHTML:'P0_x drive mode, off = open-drain'}),mrP.lastChild).style.fontSize='smaller';}"));
  oappend(F("mrI=cE('div');mrI.style.fontSize='smaller';if(mrA)mrA.insertBefore(mrI,mrA.lastChild);"));
  // hide address & push-pull rows unless the matching expander is selected; show that expander's valid addresses
  oappend(F("mrS=d.getElementsByName('PowerManager:expander')[1];"));
  oappend(F("function mrU(){let v=mrS.value;if(mrA)mrA.style.display=v==0?'none':'';if(mrP)mrP.style.display=v==2?'':'none';mrI.innerHTML=v==2?'decimal: 88-91 (0x58-0x5B), default 88':'decimal: 32-39 (0x20-0x27), PCF8574A 56-63 (0x38-0x3F), default 32';}"));
  oappend(F("if(mrS){mrS.addEventListener('change',mrU);mrU();}"));
  // named pin dropdown entries for expander ports; only offered when an expander is configured
  // (change of expander type requires save & reload of this page)
  if (expanderType == EXPANDER_AW9523) {
    oappend(F("mrPP=[['P0_0',100],['P0_1',101],['P0_2',102],['P0_3',103],['P0_4',104],['P0_5',105],['P0_6',106],['P0_7',107],['P1_0',108],['P1_1',109],['P1_2',110],['P1_3',111],['P1_4',112],['P1_5',113],['P1_6',114],['P1_7',115]];"
        "mrSP=[['none',-1]].concat(mrPP);"
        "d.extra.push({'PowerManager':{pin:mrPP,'fuse-pin':mrSP,'main-sense-pin':mrSP}});"));
  } else if (expanderType == EXPANDER_PCF8574) {
    oappend(F("d.extra.push({'PowerManager':{pin:[['P0',100],['P1',101],['P2',102],['P3',103],['P4',104],['P5',105],['P6',106],['P7',107]]}});"));
  }
}

/**
 * restore the changeable values
 * readFromConfig() is called before setup() to populate properties from values stored in cfg.json
 * 
 * The function should return true if configuration was successfully loaded or false if there was no configuration.
 */
bool PowerManager::readFromConfig(JsonObject &root) {
  int8_t oldPin[POWERMANAGER_MAX_RELAYS];

  JsonObject top = root[FPSTR(_name)];
  if (top.isNull()) {
    // migrate settings saved by the built-in multi_relay usermod this one grew out of
    // (all keys are compatible; the config is re-saved under the new section name)
    top = root[FPSTR(_legacyName)];
    if (!top.isNull()) {
      DEBUG_PRINTLN(F("PowerManager: migrating MultiRelay config."));
      configNeedsWrite = true;
    }
  }
  if (top.isNull()) {
    DEBUG_PRINT(FPSTR(_name));
    DEBUG_PRINTLN(F(": No config found. (Using defaults.)"));
    return false;
  }

  //bool configComplete = !top.isNull();
  //configComplete &= getJsonValue(top[FPSTR(_enabled)], enabled);
  enabled = top[FPSTR(_enabled)] | enabled;
  if (!top[FPSTR(_expander)].isNull()) {
    expanderType = top[FPSTR(_expander)] | expanderType;
    expanderAddr = top[FPSTR(_expanderAddr)] | expanderAddr;
  } else if (!top[FPSTR(_pcf8574)].isNull()) {
    // migrate legacy (pre-AW9523) config keys
    if (top[FPSTR(_pcf8574)] | false) expanderType = EXPANDER_PCF8574;
    expanderAddr = top[FPSTR(_pcfAddress)] | expanderAddr;
  }
  awP0PushPull = top[FPSTR(_pushPull)] | awP0PushPull;
  if (expanderType > EXPANDER_AW9523) expanderType = EXPANDER_NONE;
  // fix I2C address if it does not match the selected expander (e.g. after changing type)
  if (expanderType == EXPANDER_AW9523 && (expanderAddr < 0x58 || expanderAddr > 0x5B)) expanderAddr = AW9523_ADDRESS;
  if (expanderType == EXPANDER_PCF8574 && expanderAddr >= 0x58) expanderAddr = PCF8574_ADDRESS;
  // an unusable I2C bus does NOT downgrade the configured expander (runtime check instead,
  // see expanderAvailable()) - rewriting it here would persist the loss to cfg.json
  periodicBroadcastSec = top[FPSTR(_broadcast)] | periodicBroadcastSec;
  periodicBroadcastSec = min(900,max(0,(int)periodicBroadcastSec));
  HAautodiscovery = top[FPSTR(_HAautodiscovery)] | HAautodiscovery;
  takeOverRelays = top[FPSTR(_takeOver)] | takeOverRelays;
  boPreMs  = top[FPSTR(_blackPre)]  | boPreMs;
  boPostMs = top[FPSTR(_blackPost)] | boPostMs;
  boPreMs  = min(500,max(0,(int)boPreMs));
  boPostMs = min(500,max(0,(int)boPostMs));
  stabilizeSec = top[FPSTR(_stabilize_str)] | stabilizeSec;
  stabilizeSec = min(60,max(0,(int)stabilizeSec));
  minOffMs = top[FPSTR(_minOff)] | minOffMs;
  minOffMs = min(10000,max(0,(int)minOffMs));
  staggerEnabled = top[FPSTR(_stagger)] | staggerEnabled;
  staggerMs = top[FPSTR(_staggerMs)] | staggerMs;
  staggerMs = min(2000,max(0,(int)staggerMs));
  int msp = top[FPSTR(_mainSense)] | (int)mainSensePin;
  mainSensePin = (msp >= 100 && msp <= 115) ? msp : -1;
  fuseSenseInvert = (top[FPSTR(_fuseInv)] | (int)fuseSenseInvert) != 0;
  mainSenseInvert = (top[FPSTR(_mainInv)] | (int)mainSenseInvert) != 0;

  for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++) {
    String parName = FPSTR(_relay_str); parName += '-'; parName += i;
    oldPin[i]          = _relay[i].pin;
    _relay[i].pin      = top[parName]["pin"] | _relay[i].pin;
    _relay[i].invert   = top[parName][FPSTR(_activeHigh)] | _relay[i].invert;
    _relay[i].external = top[parName][FPSTR(_external)]   | _relay[i].external;
    if (!top[parName][FPSTR(_delay_str)].isNull()) { // migrate legacy single delay (applied to both directions)
      _relay[i].delayOn = _relay[i].delayOff = top[parName][FPSTR(_delay_str)].as<int>();
    }
    _relay[i].delayOn  = top[parName][FPSTR(_delayOn_str)]  | _relay[i].delayOn;
    _relay[i].delayOff = top[parName][FPSTR(_delayOff_str)] | _relay[i].delayOff;
    _relay[i].button   = top[parName][FPSTR(_button)]     | _relay[i].button;
    _relay[i].delayOn  = min(600,max(0,(int)_relay[i].delayOn));  // bounds checking max 10min
    _relay[i].delayOff = min(600,max(0,(int)_relay[i].delayOff));
    if (i == 0) {
      masterEnabled  = top[parName][FPSTR(_master)]   | masterEnabled;
      masterMainSync = top[parName][FPSTR(_mainSync)] | masterMainSync;
    }
    int seg = top[parName][FPSTR(_segment_str)] | (int)_relay[i].segment;
    if (seg < -1 || (seg >= (int)strip.getMaxSegments() && seg != POWERMANAGER_SEG_ANY)) seg = -1;
    if (i > 0 && seg == POWERMANAGER_SEG_ANY) seg = -1; // only the Master AC relay (relay 0) may follow all segments
    _relay[i].segment  = seg;
    int fp = top[parName][FPSTR(_fusePin)] | (int)_relay[i].fusePin;
    _relay[i].fusePin  = (fp >= 100 && fp <= 115) ? fp : -1;
    if (top[parName]["name"].is<const char*>()) strlcpy(_relay[i].name, top[parName]["name"].as<const char*>(), POWERMANAGER_NAME_LEN);
  }
  // relay 0 is the dedicated Master AC relay slot
  if (masterEnabled) _relay[0].segment = POWERMANAGER_SEG_ANY;
  else if (_relay[0].segment == POWERMANAGER_SEG_ANY) _relay[0].segment = -1;

  DEBUG_PRINT(FPSTR(_name));
  if (!initDone) {
    // reading config prior to setup()
    DEBUG_PRINTLN(F(" config loaded."));
  } else {
    // deallocate all pins 1st
    for (int i=0; i<POWERMANAGER_MAX_RELAYS; i++)
      if (oldPin[i]>=0 && oldPin[i]<100) {
        PinManager::deallocatePin(oldPin[i], PinOwner::UM_MultiRelay);
      }
    // allocate new pins
    setup();
    DEBUG_PRINTLN(F(" config (re)loaded."));
  }
  // use "return !top["newestParameter"].isNull();" when updating Usermod with new features
  return !top[FPSTR(_staggerMs)].isNull();
}

// strings to reduce flash memory usage (used more than twice)
const char PowerManager::_name[]            PROGMEM = "PowerManager";
const char PowerManager::_legacyName[]      PROGMEM = "MultiRelay";       // config section of the multi_relay ancestor (migration)
const char PowerManager::_enabled[]         PROGMEM = "enabled";
const char PowerManager::_relay_str[]       PROGMEM = "relay";
const char PowerManager::_delay_str[]       PROGMEM = "delay-s";
const char PowerManager::_activeHigh[]      PROGMEM = "active-high";
const char PowerManager::_external[]        PROGMEM = "external";
const char PowerManager::_button[]          PROGMEM = "button";
const char PowerManager::_broadcast[]       PROGMEM = "broadcast-sec";
const char PowerManager::_HAautodiscovery[] PROGMEM = "HA-autodiscovery";
const char PowerManager::_pcf8574[]         PROGMEM = "use-PCF8574";      // legacy config key (read for migration only)
const char PowerManager::_pcfAddress[]      PROGMEM = "PCF8574-address";  // legacy config key (read for migration only)
const char PowerManager::_expander[]        PROGMEM = "expander";
const char PowerManager::_expanderAddr[]    PROGMEM = "expander-address";
const char PowerManager::_pushPull[]        PROGMEM = "AW9523-pushpull";
const char PowerManager::_switch[]          PROGMEM = "switch";
const char PowerManager::_toggle[]          PROGMEM = "toggle";
const char PowerManager::_Command[]         PROGMEM = "/command";
const char PowerManager::_segment_str[]     PROGMEM = "segment";
const char PowerManager::_delayOn_str[]     PROGMEM = "delay-on-s";
const char PowerManager::_delayOff_str[]    PROGMEM = "delay-off-s";
const char PowerManager::_stabilize_str[]   PROGMEM = "stabilize-s";
const char PowerManager::_blackPre[]        PROGMEM = "black-pre-ms";
const char PowerManager::_blackPost[]       PROGMEM = "black-post-ms";
const char PowerManager::_minOff[]          PROGMEM = "min-off-ms";
const char PowerManager::_stagger[]         PROGMEM = "stagger";
const char PowerManager::_staggerMs[]       PROGMEM = "stagger-ms";
const char PowerManager::_master[]          PROGMEM = "master";
const char PowerManager::_mainSync[]        PROGMEM = "main-sync";
const char PowerManager::_takeOver[]        PROGMEM = "take-over-relays";
const char PowerManager::_fusePin[]         PROGMEM = "fuse-pin";
const char PowerManager::_mainSense[]       PROGMEM = "main-sense-pin";
const char PowerManager::_fuseInv[]         PROGMEM = "fuse-sense-mode";   // 0 = high when the fuse is OK, 1 = high when blown
const char PowerManager::_mainInv[]         PROGMEM = "main-sense-mode";   // 0 = high when power present, 1 = low when present


static PowerManager powerManager;
REGISTER_USERMOD(powerManager);