⚠️ Use the Main relay power input and Avoid using VCC and GND from the relay IN GPIO Pin row

• Remove the Yellow VCC-JDVCC jumper.
• Relay JD-VCC pin: Connect to external 5V Positive wire.
• Relay GND pin: Connect to external 5V Negative wire.
• Relay VCC pin: Connect to ESP32 5V (powers the LED).

• Remove the Yellow VCC-JDVCC jumper.
• Relay JD-VCC pin: Connect to external 12V Positive wire.
• Relay GND pin: Connect to external 12V Negative wire.
• Relay VCC pin: Connect to ESP32 5V (powers the LED).

Firmware Version: 9.0.0 (NVS Schema V9)
Author: Raff Alds (Xiv3r)
License: GPLv3 — Free Software Foundation
Target Silicon: Espressif ESP32 (XTensa LX6 Dual-Core @ 240MHz, 520KB SRAM, 4MB Flash)
Compilation Environment: PlatformIO / Arduino IDE
Documentation Hash: SHA-256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

1. Philosophy & Architectural Overview
2. Memory Map & NVS Layout
3. Timekeeping Trinity: Deep Dive
4. Self-Healing Ecosystem
5. Relay Scheduling Engine: Formal Specification
6. GPIO Configuration Matrix
7. Network Subsystems
8. Web Interface: Complete API Reference
9. WiFi & Access Point Management
10. mDNS & Service Discovery Protocol
11. Captive Portal Implementation
12. Boot Button & Hardware Factory Reset
13. Memory & Resource Management
14. Critical State Persistence & Fault Recovery
15. CSS & UI Component Library
16. Boot Sequence Flowchart
17. Main Loop Execution Model
18. Error Codes & Troubleshooting
19. Security Considerations
20. Build Instructions & Dependencies
21. Hardware Pinout & Wiring Guide
22. Glossary of Constants & Macros
23. Appendix: Complete Data Structure Definitions

┌─────────────────────────────────────────────────────────┐
│                    ESP32 Main Loop                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Scheduler│  │  Web     │  │  WiFi    │  │  Time   │ │
│  │ Engine   │  │  Server  │  │  Manager │  │  Trinity│ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
│       │              │              │              │      │
│  ┌────┴──────────────┴──────────────┴──────────────┴───┐ │
│  │           SelfHealingSystem (Health Metrics)        │ │
│  └────────────────────────┬───────────────────────────┘ │
│                           │                              │
│  ┌────────────────────────┴───────────────────────────┐ │
│  │              CriticalRelayState (NVS)               │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Namespace: relay16
Total NVS Consumption: ~5.5KB of 20KB available partition.

• Maximum Write Cycles: 100,000 (ESP32 specification).
• Worst-Case Scenario: Saving every 300s (critical state) + hourly RTC save = ~12,000 writes/year.
• Expected Lifetime: >8 years at maximum write frequency.

Principle of Operation:

1. At sync time, store internalEpoch (UTC seconds) and rtcMicrosAtLastSync (hardware microsecond counter).
2. On read, calculate elapsed microseconds with overflow handling for micros() 71-minute rollover.
3. Apply driftCompensation factor to elapsed time.
4. Add compensated seconds to base epoch.
5. Every RTC_REBASE_INTERVAL (300s), recalculate base to prevent floating-point accumulation errors.

Drift Compensation Formula:

adjusted_seconds = (elapsed_micros / 1,000,000) * driftCompensation
current_epoch    = internalEpoch + floor(adjusted_seconds)
                 + (fractional >= 0.5 ? 1 : 0)

Microsecond Overflow Handling:

if (currentMicros >= rtcMicrosAtLastSync) {
    elapsedMicros = currentMicros - rtcMicrosAtLastSync;
} else {
    // Micros rolled over — rebase and return
    performRTCReabase();
    return internalEpoch;
}

I²C Configuration:

• SDA: GPIO21
• SCL: GPIO22
• Frequency: Standard mode (100kHz)
• Library: RTClib by Adafruit

Initialization Sequence:

1. Wire.begin(21, 22) — Initialize I²C bus.
2. rtc.begin() — Probe device address 0x68.
3. Check rtc.lostPower() — If true, RTC time is invalid.
4. Validate year range: 2020-2100.
5. Validate epoch: VALID_UNIX_TIME() macro checks bounds.

Sync Strategy:

States:

IDLE (0) ──(interval elapsed)──► CONNECTING (1) ──(request sent)──► WAITING (2)
  ▲                                    │                                  │
  └────────(timeout/fallback)──────────┘                                  │
  ▲                                                                       │
  └───────────────────(success: sync epoch)───────────────────────────────┘

Fallback Server Rotation: Index cycles through NTP_SERVERS[] array. On timeout, increments to next server. On full rotation back to starting index, increments ntpFailCount.

Validation Rules:

• Epoch must be >= 1577836800 (2020-01-01 00:00:00 UTC)
• Epoch must be < 4294967295 (Year 2106 limit)
• Rejects with HTTP 400 if invalid

Post-Sync Actions:

1. Set timeSource = TIME_SOURCE_BROWSER
2. Call syncInternalRTC(browserUtcEpoch)
3. Update DS3231 if present
4. Save RTC state to NVS
5. Flush schedule cache
6. Return local time string in response

ESP32's 32-bit time_t will overflow on 2106-02-07. This firmware:

• Defines MAX_UNIX_TIME = 4294967295UL
• All epoch assignments validated through VALID_UNIX_TIME() macro
• Schedule cache updates skipped if epoch < MIN_UNIX_TIME
• NTP/browser syncs beyond limit rejected

struct HealthMetrics {
    uint32_t wifiFailures      = 0;  // Incremented when WiFi disconnected >3 checks
    uint32_t ntpFailures       = 0;  // Incremented on full NTP server rotation failure
    uint32_t mdnsFailures      = 0;  // Reserved for future mDNS health checks
    uint32_t dnsFailures       = 0;  // Reserved for future DNS health checks
    uint32_t webServerFailures = 0;  // Reserved for future HTTP health checks
    unsigned long lastRecoveryAttempt = 0;  // Timestamp of last smartRecovery()
    bool inRecoveryMode        = false;     // Prevents recursive recovery
};

smartRecovery() runs every 10 seconds and:

1. Checks WiFi station health (increment failure counter at 3+ failures)
2. Refreshes mDNS service advertisements every 300s
3. Performs full health check every 1800s (30 min)
4. Saves critical state if dirty
5. Verifies all relay output states against expected values
6. Ensures AP is broadcasting

performTargetedRecovery() is a full-service restart without reboot:

1. liveReconfigureWebServer()
2. liveReconfigureDNS()
3. liveReconfigureMDNS()
4. liveReconfigureWiFi()
5. liveReconfigureAP()
6. recoverRTC()
7. verifyRelayStates()
8. Reset all health failure counters to zero

All schedule times are converted to seconds since midnight (0-86399):

SSM = hour * 3600 + minute * 60 + second

For each relay i:
  If manualOverride[i] is TRUE:
    Output = manualState[i]
    Continue
  
  shouldBeOn = FALSE
  For each schedule slot s (0-7):
    If NOT enabled[s]: continue
    
    // Day-of-week check
    If (days[s] & todayBitmask) == 0: continue
    
    // Day-of-month check  
    If monthDays[s] != 0 AND (monthDays[s] & (1 << (today-1))) == 0: continue
    
    start = SSM(startHour[s], startMinute[s], startSecond[s])
    stop  = SSM(stopHour[s], stopMinute[s], stopSecond[s])
    
    // Always-ON schedule
    If start == stop:
      shouldBeOn = TRUE
      break
    
    // Normal schedule (start < stop)
    If start < stop AND current_SSM >= start AND current_SSM < stop:
      shouldBeOn = TRUE
      break
    
    // Overnight schedule (start > stop)
    If start > stop AND (current_SSM >= start OR current_SSM < stop):
      shouldBeOn = TRUE
      break
  
  // Apply debounced output with 500ms minimum interval
  If shouldBeOn != lastDebouncedState[i]:
    If millis() - lastStateChange[i] >= 500:
      setRelayOutput(i, shouldBeOn)
      lastDebouncedState[i] = shouldBeOn
      lastStateChange[i] = millis()

32-bit integer where bit n (0-indexed) represents day n+1 of the month.

• 0x00000000 — No filtering (all days match)
• 0xFFFFFFFF — All 31 days match (redundant with 0)
• 0x00000001 — Only day 1 of month
• 0x40000000 — Only day 31

To avoid recalculating schedules on every API call:

• scheduleActiveCache[MAX_RELAYS] — Boolean array of computed states
• Updated every SCHEDULE_CACHE_INTERVAL (1000ms) or on time sync
• cachedTodayBit and cachedMonthDay store current date components
• Invalidated on manual override changes, schedule saves, or time source changes

// Allowed GPIOs (avoiding flash, PSRAM, and strapping pins):
int validPins[] = {
    15,  2,  4,   // ADC2, safe for output
    16, 17,       // UART2 (if not used), safe for output  
    5, 18, 19,    // VSPI (if not used), safe for output
    3,  1,        // UART0 (if serial disabled), safe for output
    23,           // VSPI MOSI
    13, 14,       // ADC2, HSPI
    27, 26, 25,   // DAC, ADC2
    33, 32        // ADC1, XTAL (32 requires caution)
};
// Pins explicitly excluded:
// 0  - BOOT button (strapping)
// 6-11 - Flash memory
// 12  - MTDI strapping
// 21,22 - I²C reserved for DS3231
// 34-39 - Input-only GPIOs

Digital Write Path:
  relayConfigs[i].manualOverride?
    YES → targetState = relayConfigs[i].manualState
    NO  → targetState = scheduleActiveCache[i]

  extConfig.global_active_mode?
    1 (Global LOW)  → physicalOutput = !targetState
    2 (Global HIGH) → physicalOutput = targetState
    0 (Per-Relay)   → physicalOutput = gpioConfig.activeLow[i] ? !targetState : targetState

  digitalWrite(gpioConfig.pins[i], physicalOutput)

        ┌──────────┐
        │DISCONNECT│◄──────────────────────────────┐
        └────┬─────┘                               │
             │                                      │
    ┌────────▼────────┐    timeout/error    ┌───────┴──────┐
    │   CONNECTING    ├─────────────────────►│ COOLDOWN    │
    └────────┬────────┘                      │ (5 min)     │
             │ success                        └──────┬──────┘
    ┌────────▼────────┐                              │
    │   CONNECTED     │◄─────────────────────────────┘
    └────────┬────────┘    retry after cooldown
             │ disconnect detected
             └──────────────► DISCONNECT

• Port: 53 (standard DNS)
• Behavior: All queries resolved to WiFi.softAPIP()
• Startup: dnsServer.start(DNS_PORT, "*", WiFi.softAPIP())
• Processing: dnsServer.processNextRequest() called in each loop() iteration
• Purpose: Captive portal functionality + seamless client redirection

All API responses include:

Content-Type: application/json
Access-Control-Allow-Origin: * (implicit via WebServer)
Connection: close (HTTP/1.1)

{
  "success": false,
  "error": "Human-readable error message"
}

[
  {
    "state": false,
    "manual": false,
    "name": "Relay 1",
    "pin": 15,
    "schedules": [
      {
        "startHour": 8, "startMinute": 0, "startSecond": 0,
        "stopHour": 17, "stopMinute": 0, "stopSecond": 0,
        "enabled": true,
        "days": 127,
        "monthDays": 0
      },
      // ... 7 more schedule slots
    ]
  },
  // ... up to 15 more relays
]

{"relay": 0, "state": true}

{"utc_epoch": 1718400000}

{
  "success": true,
  "utc_epoch": 1718400000,
  "local_time": "2024-06-15 08:00:00",
  "gmt_offset": 28800,
  "time_source": "browser",
  "rtc_present": true,
  "rtc_synced": true,
  "drift": 1.0
}

struct ResponseCache {
    String relaysJson;       // Cached /api/relays response
    String systemJson;       // Cached /api/system response
    String timeJson;         // Cached /api/time response
    unsigned long lastUpdate = 0;
    bool valid = false;
};

• Invalidation: On any POST/PUT operation, valid set to false.
• Expiry: Auto-invalidated after 5 seconds (stale data prevention).
• Memory: Cache strings cleared on expiry to free heap.

Function: setWiFiStationEnabled(bool enabled)

• Disable: Disconnects WiFi, switches to WIFI_AP mode, stops NTP state machine, clears all pending WiFi operations.
• Enable: Switches to WIFI_AP_STA, initiates WiFi.begin(), resets reconnect counters.
• Persistence: Saved to extConfig.sta_enabled in NVS.

Problem: WiFi scanning and connecting simultaneously causes radio contention. Solution: pauseWiFiForScan() temporarily disconnects and sets wifiPauseUntil for 15 seconds. Recovery: After scan completes, wifiPauseUntil extended by 5 seconds, then normal reconnection resumes.

Restart Logic: restartAPIfNeeded(bool forceRestart) — if forceRestart=true or settings changed, calls WiFi.softAPdisconnect(true), 500ms delay, then WiFi.softAP() with new parameters.

// Input: "ESP32_16CH_Timer_Switch"
// Process:
// 1. Convert to lowercase
// 2. Replace spaces and underscores with hyphens
// 3. Remove all non-alphanumeric, non-hyphen characters
// 4. Truncate to 31 characters
// Output: "esp32-16ch-timer-switch"

Service: _http._tcp
Port: 80
TXT Records:
  model=ESP32
  version=v9
  channels=<active_relay_count>

• Start: startMDNS() — called in setup, also by liveReconfigureMDNS()
• Stop: stopMDNS() — not normally called, only on hostname change
• Restart: restartMDNS() — calls liveReconfigureMDNS() which detects !mdnsStarted and reinitializes
• Scheduled Restart: scheduleMDNSRestart() — sets 2-second timer to debounce rapid changes

The following paths are commonly probed by operating systems to detect captive portals:

• onNotFound() handler catches all unregistered paths
• Responds with HTTP 302 redirect to http://<AP_IP>/
• /generate_204 returns empty 302 (Android expects no content)
• All "success" endpoints return simple plaintext to satisfy OS checks

• Pin: GPIO0 (BOOT button on most ESP32 dev boards)
• Pull: INPUT_PULLUP — button press reads LOW
• Hold Duration: 5000ms (FACTORY_RESET_HOLD)

1. digitalRead(BOOT_BUTTON_PIN) returns LOW (pressed)
2. Timer starts on first detection of press
3. If held for 5000ms:
   • preferences.clear() — erase entire NVS namespace
   • initDefaults() — recreate factory configuration
   • All relays forced OFF
   • AP restarted with default credentials
   • WiFi station attempted if credentials exist
   • factoryResetTriggered flag prevents re-trigger during same press
4. On button release, flag reset for next use

static unsigned long lastHeapCheck = 0;
static size_t minFreeHeap = 0;

void checkAndCleanMemory() {
    if (timeHasElapsed(millis(), lastHeapCheck, 300000)) { // Every 5 min
        size_t freeHeap = ESP.getFreeHeap();
        if (freeHeap < minFreeHeap || minFreeHeap == 0) {
            minFreeHeap = freeHeap; // Track minimum observed
        }
        if (freeHeap < 20000) { // Less than 20KB
            performMemoryCleanup();
        }
    }
}

1. WiFi Scan Cleanup: WiFi.scanDelete() if no scan in progress
2. Task Yielding: 10 iterations of yield() + delay(1) to process background tasks
3. NVS Flush: preferences.end() to close any open handles
4. Fragmentation Reduction: Allocate/free 512-byte blocks (5 iterations) to trigger heap compaction

• Every 60s, check for orphaned WiFiClient connections
• Force-close up to 5 stale connections per cycle
• Response cache auto-invalidated after 5s

struct CriticalRelayState {
    uint32_t magic;           // 0xDEADBEEF — validity marker
    bool relayStates[16];     // Last known output states
    bool manualOverrides[16]; // Manual override flags
    uint32_t timestamp;       // Millis at time of save
    uint32_t checksum;        // XOR-based integrity check
};

uint32_t sum = 0;
for (int i = 0; i < 16; i++) {
    sum += relayStates[i] ? (1 << (i % 32)) : 0;
    sum += manualOverrides[i] ? (1 << ((i+16) % 32)) : 0;
}
return sum ^ timestamp;

On boot, restoreCriticalState():

1. Reads criticalState from NVS
2. Validates magic == 0xDEADBEEF
3. Validates checksum matches recalculation
4. If both pass, reapplies manual overrides to relay outputs
5. Returns true if restored, false if invalid/corrupt

@media(max-width:500px) {
    .grid { grid-template-columns: 1fr; }     /* Single column */
    .ibar { grid-template-columns: 1fr; }      /* Stack info boxes */
    .input-row { flex-direction: column; }     /* Stack inputs */
    .day { width:24px; height:22px; font-size:10px; } /* Smaller day buttons */
}

• Position: Fixed bottom center, slides up from below viewport
• Colors: Green (ok) for success, Red (er) for errors
• Duration: 3 seconds auto-dismiss
• Stacking: Previous toast cleared on new toast (clearTimeout)

POWER ON / RESET
     │
     ▼
Serial.begin(115200)
     │
     ▼
initRTC() ─────────────► DS3231 detected? ──Yes──► rtcPresent = true
     │                        │
     │                        No
     │                        │
     ▼                        ▼
loadGPIOConfig()        rtcPresent = false
     │
     ▼
pinMode(BOOT_BUTTON, INPUT_PULLUP)
     │
     ▼
[Initialize all relay GPIOs as OUTPUT, set LOW]
     │
     ▼
[Initialize relayConfigs[] with defaults]
     │
     ▼
loadConfiguration() ────► Valid? ──No──► initDefaults()
     │                      │
     │                     Yes
     │                      │
     ▼                      ▼
loadExtConfig()        [Continue]
     │
     ▼
[Time Initialization Priority]
  1. loadRTCFromDS3231()  (if present & valid)
  2. loadRTCState()       (from NVS backup)
  3. Set timeSource = NONE
     │
     ▼
WiFi.mode(WIFI_AP_STA)
     │
     ▼
timeClient.begin()
     │
     ▼
[If sta_enabled: WiFi.begin(ssid, pass)]
[Else: WiFi.mode(WIFI_AP)]
     │
     ▼
WiFi.softAP(ap_ssid, ap_password, channel, hidden)
     │
     ▼
startMDNS()
     │
     ▼
dnsServer.start(53, "*", AP_IP)
     │
     ▼
setupWebServer()
     │
     ▼
updateScheduleCache()
     │
     ▼
restoreCriticalState() ───► Restored? ──Yes──► Apply manual overrides
     │                        │
     │                        No
     │                        │
     ▼                        ▼
[Enter main loop()]     [Enter main loop()]

1. checkBootButton()           [Background: GPIO0 hold detection]
2. server.handleClient()       [Foreground: Process 1 HTTP request]
3. dnsServer.processNext()     [Foreground: Process 1 DNS query]
4. Stale connection cleanup    [Every 60s]
5. Memory cleanup              [Every 30s]
6. Web server health check     [Every 60s]
7. Smart recovery              [Every 10s]
8. Heap monitoring             [Every 300s]
9. DS3231 periodic sync        [Every 3600s]
10. Auto-save internal RTC     [Every 3600s, if no external source]
11. mDNS restart (if scheduled)[On timer expiry]
12. WiFi scan timeout check    [On scan active]
13. WiFi connection state machine [On connecting/disconnected]
14. NTP sync state machine     [On interval/retry]
15. Schedule processing        [Every 250ms]
16. Critical state save        [Every 300s, if dirty]
17. yield()                    [RTOS task switch]

• No single operation blocks for >10ms (except WiFi.scanNetworks() which is async)
• server.handleClient() processes exactly one HTTP request per call
• dnsServer.processNextRequest() processes exactly one DNS query per call
• yield() called at end of loop to allow FreeRTOS task switching

• Authentication: None (open access)
• Encryption: None for HTTP; WPA2 for AP mode
• Network Exposure: AP isolated by default; STA connects to configured network

1. Change Default Passwords: Both AP and STA credentials
2. Disable AP if Not Needed: Set AP password to empty and hide SSID, or modify code
3. Network Isolation: Place device on VLAN with no internet access if only local control needed
4. HTTPS: Not feasible on ESP32 without significant overhead; consider reverse proxy
5. Physical Security: BOOT button factory reset can be disabled by removing checkBootButton() from loop

• All endpoints accept POST without CSRF tokens
• Mitigation: AP mode is isolated; STA mode should be on trusted network
• Browser sync endpoint could be exploited to set arbitrary time

[env:esp32dev]
platform = espressif32 @ 6.4.0
board = esp32dev
framework = arduino
monitor_speed = 115200
board_build.partitions = default.csv
lib_deps = 
    arduino-libraries/NTPClient @ ^3.2.1
    bblanchon/ArduinoJson @ ^6.21.3
    adafruit/RTClib @ ^2.1.1

• Board: "ESP32 Dev Module"
• Partition Scheme: "Default 4MB with spiffs (1.2MB APP/1.5MB SPIFFS)"
• Flash Frequency: 80MHz
• Flash Mode: QIO
• Core Debug Level: None (production)

• ArduinoJson 6.x required; version 7 has breaking API changes
• Some String operations may generate fragmentation warnings (acceptable at this scale)
• snprintf buffer size warnings are intentional — all buffers sized for maximum config values

                    ┌─────────────────────┐
               EN  ─┤○ ○                 ○├─  GND
            VP/S4  ─┤  ○               ○  ├─  D23 (Relay 9)
            VN/S5  ─┤  ○               ○  ├─  D22 (I²C SCL)
              D34  ─┤  ○               ○  ├─  TX0/D1 (Relay 8)
              D35  ─┤  ○               ○  ├─  RX0/D3 (Relay 7)
              D32  ─┤  ○  ESP32 DEV    ○  ├─  D21 (I²C SDA)
       Relay 16 ← D33  ─┤  ○               ○  ├─  GND
        Relay 15 ← D25  ─┤  ○               ○  ├─  D19 (Relay 6)
        Relay 14 ← D26  ─┤  ○               ○  ├─  D18 (Relay 5)
        Relay 13 ← D27  ─┤  ○               ○  ├─  D5  (Relay 4)
        Relay 12 ← D14  ─┤  ○               ○  ├─  D17 
        Relay 11 ← D13  ─┤  ○               ○  ├─  D16 
               GND  ─┤○ ○                 ○├─  D4  (Relay 3)
              VIN  ─┤○ ○                 ○├─  D2  (Relay 2)
        Relay 10 ← D15  ─┤○ ○                 ○├─  D0  (BOOT)
                    └─────────────────────┘

DS3231    →    ESP32
VCC       →    3.3V
GND       →    GND
SDA       →    GPIO21
SCL       →    GPIO22

• Active LOW modules: Most 16-channel relay boards are active LOW (relay ON when GPIO LOW)
  • Set Global Active Mode to "Active LOW" or configure per-relay
• Active HIGH modules: Solid-state relays (SSR) typically active HIGH
• Flyback Diodes: Ensure relay module has built-in diodes or add external 1N4148
• Power: Relay coils should be powered externally, not from ESP32 3.3V

#define VALID_UNIX_TIME(epoch) ((epoch) > MIN_UNIX_TIME && (epoch) < MAX_UNIX_TIME)

inline bool timeHasElapsed(unsigned long current, unsigned long previous, unsigned long interval) {
    return (current - previous) >= interval;  // Overflow-safe
}

inline bool isTimeReached(unsigned long current, unsigned long target) {
    return (long)(current - target) >= 0;  // Signed comparison for future timestamps
}

struct SystemConfig {
    uint16_t magic;           // 0x1234
    uint8_t  version;         // 9
    char     sta_ssid[32];    // Station WiFi SSID
    char     sta_password[64];// Station WiFi password (64 char for WPA2-Enterprise)
    char     ap_ssid[32];     // Access Point SSID
    char     ap_password[32]; // Access Point password
    char     ntp_server[48];  // Primary NTP server hostname
    int32_t  gmt_offset;      // Seconds from UTC (e.g., 28800 = UTC+8)
    int32_t  daylight_offset; // DST offset in seconds
    time_t   last_rtc_epoch;  // Last saved internal RTC epoch
    float    rtc_drift;       // Drift compensation factor (1.0 = perfect)
    char     hostname[32];    // mDNS hostname
} __attribute__((packed));

struct ExtConfig {
    uint8_t magic;             // 0xEC
    uint8_t ap_channel;        // 1-13
    uint8_t ntp_sync_hours;    // 1-24
    uint8_t ap_hidden;         // 0=visible, 1=hidden
    uint8_t global_active_mode;// 0=per-relay, 1=all LOW, 2=all HIGH
    uint8_t sta_enabled;       // 0=AP only, 1=AP+STA
    uint8_t reserved[26];      // Future expansion
} __attribute__((packed));

struct TimerSchedule {
    uint8_t  startHour[8];    // 0-23
    uint8_t  startMinute[8];  // 0-59
    uint8_t  startSecond[8];  // 0-59
    uint8_t  stopHour[8];     // 0-23
    uint8_t  stopMinute[8];   // 0-59
    uint8_t  stopSecond[8];   // 0-59
    bool     enabled[8];      // Schedule slot active
    uint8_t  days[8];         // Day-of-week bitmask
    uint32_t monthDays[8];    // Day-of-month bitmask
};

struct RelayConfig {
    TimerSchedule schedule;   // 8 schedule slots
    bool          manualOverride; // Manual override active
    bool          manualState;    // Manual override target state
    char          name[16];       // User-assigned relay name
};

struct GPIOPinConfig {
    uint8_t pins[MAX_RELAYS];     // GPIO numbers [0-15]
    uint8_t count;                // Active relay count (1-16)
    uint16_t magic;               // 0xD002
    bool activeLow[MAX_RELAYS];   // Per-relay active level
};

struct CriticalRelayState {
    uint32_t magic;              // 0xDEADBEEF
    bool relayStates[MAX_RELAYS];// Last output states
    bool manualOverrides[MAX_RELAYS]; // Override flags
    uint32_t timestamp;          // Millis at save time
    uint32_t checksum;           // XOR integrity check
};

struct HealthMetrics {
    uint32_t wifiFailures;
    uint32_t ntpFailures;
    uint32_t mdnsFailures;
    uint32_t dnsFailures;
    uint32_t webServerFailures;
    unsigned long lastRecoveryAttempt;
    bool inRecoveryMode;
};

struct ResponseCache {
    String relaysJson;
    String systemJson;
    String timeJson;
    unsigned long lastUpdate;
    bool valid;
};

Find this line inside sketch.ino

• You can add, remove or reassign the gpio pins

// Change GPIO PIN
  15, // IN1  - Relay 1
  2,  // IN2  - Relay 2
  4,  // IN3  - Relay 3
  5,  // IN4  - Relay 4
  18, // IN5  - Relay 5
  19, // IN6  - Relay 6
  3,  // IN7  - Relay 7
  1,  // IN8  - Relay 8
  23, // IN9  - Relay 9
  13, // IN10 - Relay 10
  14, // IN11 - Relay 11
  27, // IN12 - Relay 12
  26, // IN13 - Relay 13
  25, // IN14 - Relay 14
  33, // IN15 - Relay 15
  32  // IN16 - Relay 16

// Change GPIO PIN
const DEFAULT_PINS = [15,2,4,5,18,19,3,1,23,13,14,27,26,25,33,32];

You can add more gpio pins like 16, 17 in int validPins.

// Change GPIO PIN
int validPins[] = {15, 2, 4, 16, 17, 5, 18, 19, 3, 1, 23, 13, 14, 27, 26, 25, 33, 32};

Auto Build firmware binaries using github action

• https://github.com/xiv3r/arduino