iobroker.laundrylens 0.4.5

package/lib/cycleDetector.js

@@ -0,0 +1,488 @@
+"use strict";
+
+/**
+ * CycleDetector v0.4
+ *
+ * State machine: OFF → STARTING → RUNNING ↔ PAUSED → ENDING → OFF
+ *
+ * v0.4 changes:
+ *   - Power trace stored with timestamps (for curve matching)
+ *   - Watchdog against stuck cycles
+ *   - End-spike protection (dishwasher drain pump discharge)
+ *   - Zombie protection (hard limit at 200% of expected duration)
+ */
+
+const STATES = {
+  OFF: "off",
+  STARTING: "starting",
+  RUNNING: "running",
+  PAUSED: "paused",
+  ENDING: "ending",
+};
+
+const DEFAULT_CONFIG = {
+  powerThreshold: 10, // W
+  startEnergyThreshold: 2, // Wh
+  endEnergyThreshold: 0.5, // Wh
+  offDelay: 300, // s
+  startOffDelay: 120, // s – minimum time below threshold in STARTING before falling back to OFF
+  minOffGap: 120, // s
+  suspiciousWindow: 1200, // s (20 min ghost protection)
+  pauseDelay: 60, // s
+  endPhaseOffDelay: 60, // s – shortened offDelay during the end phase
+  endPhasePowerRatio: 0.2, // < 20% of max watts = end phase
+  endPhaseProgressMin: 0.7, // > 70% of expected duration = end phase
+  watchdogMs: 2 * 60 * 60 * 1000, // 2h max cycle duration
+  zombieFactor: 2.0, // 200% of profile duration = zombie kill
+  traceResolutionMs: 10000, // trace point every 10s
+};
+
+/**
+ * Power-based state machine that detects appliance cycles (OFF → STARTING →
+ * RUNNING ↔ PAUSED → ENDING → OFF) from a stream of watt readings.
+ */
+class CycleDetector {
+  /**
+   * @param {object} config          – overrides merged onto DEFAULT_CONFIG
+   * @param {(function(string, string): void)|null} onStateChange  – callback(newState, prevState) fired on every state transition
+   * @param {object|null} [adapter]  – optional ioBroker adapter instance. When provided, adapter.setTimeout()/adapter.clearTimeout() are used for the watchdog timer (so it gets cleaned up automatically on adapter unload) and adapter.log is used for diagnostic logging. Falls back to the native global timers when omitted (e.g. in unit tests).
+   */
+  constructor(config = {}, onStateChange = null, adapter = null) {
+    this.cfg = { ...DEFAULT_CONFIG, ...config };
+    this.onStateChange = onStateChange;
+    this.adapter = adapter;
+
+    // State
+    this.state = STATES.OFF;
+    this.powerTrace = [];
+    this._maxWattsObserved = 0;
+    this._inEndPhase = false; // [{ts, watts}, ...]
+    this._lastTracePoint = 0; // last stored trace point
+    this.cycleStartTime = null;
+    this.lastReadingTime = null;
+    this.lastAboveThreshold = null;
+    this.lastCycleCompleted = false;
+    this.lastBelowThreshold = null;
+    this.belowPauseThreshold = null;
+
+    // Energy
+    this.accumulatedEnergy = 0;
+    this.endingEnergy = 0;
+
+    // Ghost protection
+    this.lastCycleEndTime = null;
+
+    // Watchdog
+    this._watchdogTimer = null;
+
+    // For zombie protection: expected profile duration
+    this.expectedDurationMs = null;
+
+    // Adaptive offDelay
+    this._maxWattsObserved = 0;
+    this._inEndPhase = false;
+  }
+
+  // ── Public API ───────────────────────────────────────────────
+
+  /**
+   * Feed one power reading into the state machine. Drives all state
+   * transitions (OFF/STARTING/RUNNING/PAUSED/ENDING), energy accumulation,
+   * and power-trace recording.
+   *
+   * @param {number} watts      – current power reading in watts
+   * @param {number} timestamp  – reading timestamp in ms (epoch)
+   */
+  processReading(watts, timestamp) {
+    const prevState = this.state;
+
+    // Accumulate energy (Wh, trapezoidal)
+    if (this.lastReadingTime !== null) {
+      const dtH = (timestamp - this.lastReadingTime) / 3_600_000;
+      if (this.state !== STATES.OFF) {
+        this.accumulatedEnergy += watts * dtH;
+      }
+      if (this.state === STATES.ENDING) {
+        this.endingEnergy += watts * dtH;
+      }
+    }
+    this.lastReadingTime = timestamp;
+
+    // Store power trace at the configured resolution
+    if (this.state !== STATES.OFF) {
+      if (timestamp - this._lastTracePoint >= this.cfg.traceResolutionMs) {
+        this.powerTrace.push({ ts: timestamp, watts });
+        this._lastTracePoint = timestamp;
+      }
+      // Track max watts for adaptive offDelay
+      if (watts > this._maxWattsObserved) {
+        this._maxWattsObserved = watts;
+      }
+    }
+
+    // Gate timestamps
+    if (watts >= this.cfg.powerThreshold) {
+      this.lastAboveThreshold = timestamp;
+      this.belowPauseThreshold = null;
+    } else {
+      if (this.belowPauseThreshold === null) {
+        this.belowPauseThreshold = timestamp;
+      }
+      this.lastBelowThreshold = timestamp;
+    }
+
+    this._updateStateMachine(watts, timestamp);
+
+    if (this.state !== prevState) {
+      const data = this._buildEventData();
+      if (typeof this.onStateChange === "function") {
+        this.onStateChange(this.state, data);
+      }
+      return this.state;
+    }
+    return null;
+  }
+
+  /** Resets the detector after a completed cycle */
+  reset() {
+    this._stopWatchdog();
+    this.state = STATES.OFF;
+    this.powerTrace = [];
+    this._lastTracePoint = 0;
+    this.cycleStartTime = null;
+    this.lastAboveThreshold = null;
+    this.lastBelowThreshold = null;
+    this.belowPauseThreshold = null;
+    this.accumulatedEnergy = 0;
+    this.endingEnergy = 0;
+    this.expectedDurationMs = null;
+  }
+
+  /**
+   * Sets the expected profile duration used for zombie protection
+   *
+   * @param {number} ms  – expected cycle duration in milliseconds
+   */
+  setExpectedDuration(ms) {
+    this.expectedDurationMs = ms;
+  }
+
+  /** @returns {Array<{ts:number, watts:number}>} – copy of the recorded power trace for the current cycle */
+  getPowerTrace() {
+    return [...this.powerTrace];
+  }
+
+  /**
+   * Restore a previously saved power trace (e.g. after adapter restart).
+   *
+   * @param {Array<{ts:number, watts:number}>} points  – saved trace points
+   */
+  restoreTrace(points) {
+    // Restore trace from saved state
+    // points: [{ts, watts}]
+    if (!points || points.length === 0) {
+      return;
+    }
+    this.powerTrace = points.map((p) => ({ ts: p.ts, watts: p.watts }));
+  }
+
+  /** @returns {string} – current state machine state (one of STATES) */
+  getCurrentState() {
+    return this.state;
+  }
+
+  // ── State Machine ────────────────────────────────────────────
+
+  /**
+   * Dispatches to the handler for the current state.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _updateStateMachine(watts, now) {
+    switch (this.state) {
+      case STATES.OFF:
+        this._handleOff(watts, now);
+        break;
+      case STATES.STARTING:
+        this._handleStarting(watts, now);
+        break;
+      case STATES.RUNNING:
+        this._handleRunning(watts, now);
+        break;
+      case STATES.PAUSED:
+        this._handlePaused(watts, now);
+        break;
+      case STATES.ENDING:
+        this._handleEnding(watts, now);
+        break;
+    }
+  }
+
+  /**
+   * OFF state handler: waits for power to cross the threshold, then starts
+   * a new cycle. Suppresses "ghost" restarts shortly after an unclean end.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _handleOff(watts, now) {
+    if (watts < this.cfg.powerThreshold) {
+      return;
+    }
+
+    // Suppress ghost cycles - only if the last cycle didn't end cleanly
+    if (this.lastCycleEndTime !== null && !this.lastCycleCompleted) {
+      const gapSec = (now - this.lastCycleEndTime) / 1000;
+      if (gapSec < this.cfg.minOffGap) {
+        return;
+      }
+      if (
+        gapSec < this.cfg.suspiciousWindow &&
+        this.endingEnergy < this.cfg.endEnergyThreshold
+      ) {
+        return;
+      }
+    }
+
+    this.cycleStartTime = now;
+    this.accumulatedEnergy = 0;
+    this.endingEnergy = 0;
+    this.powerTrace = [{ ts: now, watts }];
+    this._lastTracePoint = now;
+    this.belowStartThreshold = null;
+    this._setState(STATES.STARTING);
+    this._startWatchdog();
+  }
+
+  /**
+   * STARTING state handler: confirms the cycle is real once enough energy
+   * has accumulated, or falls back to OFF if power drops before that.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _handleStarting(watts, now) {
+    if (watts < this.cfg.powerThreshold) {
+      // Only fall back to OFF after startOffDelay – prevents flapping
+      if (this.belowStartThreshold === null) {
+        this.belowStartThreshold = now;
+      }
+      const belowSec = (now - this.belowStartThreshold) / 1000;
+      if (belowSec >= this.cfg.startOffDelay) {
+        this._stopWatchdog();
+        this._setState(STATES.OFF);
+        this.powerTrace = [];
+        this.accumulatedEnergy = 0;
+        this.belowStartThreshold = null;
+      }
+      return;
+    }
+    this.belowStartThreshold = null;
+    if (this.accumulatedEnergy >= this.cfg.startEnergyThreshold) {
+      this._setState(STATES.RUNNING);
+    }
+  }
+
+  /**
+   * RUNNING state handler: monitors for the zombie-cycle hard limit and for
+   * power drops that indicate a pause or the end of the cycle.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _handleRunning(watts, now) {
+    // Zombie protection: hard limit at 200% of expected duration
+    if (this.expectedDurationMs && this.cycleStartTime) {
+      const elapsed = now - this.cycleStartTime;
+      if (elapsed > this.expectedDurationMs * this.cfg.zombieFactor) {
+        this.adapter &&
+          this.adapter.log.warn(
+            `[CycleDetector] Zombie-Kill: ${Math.round(elapsed / 60000)} min > ${Math.round((this.expectedDurationMs * this.cfg.zombieFactor) / 60000)} min`,
+          );
+        this.lastCycleEndTime = now;
+        this.endingEnergy = 0;
+        this._setState(STATES.ENDING);
+        return;
+      }
+    }
+
+    if (watts >= this.cfg.powerThreshold) {
+      return;
+    }
+
+    if (this.belowPauseThreshold !== null) {
+      const belowSec = (now - this.belowPauseThreshold) / 1000;
+      const effectiveOff = this._getEffectiveOffDelay(watts, now);
+      if (belowSec >= this.cfg.pauseDelay && belowSec < effectiveOff) {
+        this._setState(STATES.PAUSED);
+        return;
+      }
+      if (belowSec >= effectiveOff) {
+        this.endingEnergy = 0;
+        this._setState(STATES.ENDING);
+      }
+    }
+  }
+
+  /**
+   * PAUSED state handler: resumes to RUNNING if power comes back, or moves
+   * to ENDING once the pause has lasted longer than the effective off-delay.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _handlePaused(watts, now) {
+    if (watts >= this.cfg.powerThreshold) {
+      this._setState(STATES.RUNNING);
+      return;
+    }
+    if (this.lastAboveThreshold !== null) {
+      const pausedSec = (now - this.lastAboveThreshold) / 1000;
+      const effectiveOff = this._getEffectiveOffDelay(watts, now);
+      if (pausedSec >= effectiveOff) {
+        this.endingEnergy = 0;
+        this._setState(STATES.ENDING);
+      }
+    }
+  }
+
+  /**
+   * ENDING state handler: confirms the cycle is truly over after
+   * minOffGap seconds without power, with protection against brief
+   * end-of-cycle power spikes (e.g. a dishwasher's drain pump).
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   */
+  _handleEnding(watts, now) {
+    // End-spike protection (e.g. dishwasher drain pump discharge)
+    if (watts >= this.cfg.powerThreshold) {
+      this._setState(STATES.RUNNING);
+      return;
+    }
+    if (this.lastAboveThreshold !== null) {
+      const offSec = (now - this.lastAboveThreshold) / 1000;
+      if (offSec >= this.cfg.minOffGap) {
+        this.lastCycleEndTime = now;
+        this.lastCycleCompleted = true; // Ended cleanly → ghost protection off
+        this._stopWatchdog();
+        this._setState(STATES.OFF);
+      }
+    }
+  }
+
+  // ── Adaptive offDelay ─────────────────────────────────────────
+
+  /**
+   * Detects whether the cycle is likely in its final, low-power tail end
+   * (based on elapsed progress vs. expected duration and current power
+   * relative to the observed peak).
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   * @returns {boolean}  – true if the cycle appears to be in its end phase
+   */
+  _isInEndPhase(watts, now) {
+    if (!this.cycleStartTime || !this.expectedDurationMs) {
+      return false;
+    }
+    if (this._maxWattsObserved < 50) {
+      return false;
+    } // Not enough data yet
+
+    const progress = (now - this.cycleStartTime) / this.expectedDurationMs;
+    const powerRatio = watts / this._maxWattsObserved;
+
+    return (
+      progress >= this.cfg.endPhaseProgressMin &&
+      powerRatio <= this.cfg.endPhasePowerRatio
+    );
+  }
+
+  /**
+   * Returns the off-delay to apply right now: shortened while the cycle is
+   * in its end phase, otherwise the normal configured off-delay.
+   *
+   * @param {number} watts  – current power reading
+   * @param {number} now    – current timestamp in ms
+   * @returns {number}  – off-delay in seconds to use for ending detection
+   */
+  _getEffectiveOffDelay(watts, now) {
+    if (this._isInEndPhase(watts, now)) {
+      if (!this._inEndPhase) {
+        this._inEndPhase = true;
+        // Adapter log if available
+      }
+      return this.cfg.endPhaseOffDelay;
+    }
+    this._inEndPhase = false;
+    return this.cfg.offDelay;
+  }
+
+  // ── Watchdog ─────────────────────────────────────────────────
+
+  /** Arms the hard-limit watchdog timer that force-ends a cycle stuck for too long. */
+  _startWatchdog() {
+    this._stopWatchdog();
+    const armTimeout = this.adapter
+      ? this.adapter.setTimeout.bind(this.adapter)
+      : setTimeout;
+    this._watchdogTimer = armTimeout(() => {
+      if (this.state !== STATES.OFF) {
+        this.lastCycleEndTime = Date.now();
+        this.lastCycleCompleted = false;
+        this._setState(STATES.ENDING);
+      }
+    }, this.cfg.watchdogMs);
+  }
+
+  /** Cancels the watchdog timer, if one is currently armed. */
+  _stopWatchdog() {
+    if (this._watchdogTimer) {
+      const clear = this.adapter
+        ? this.adapter.clearTimeout.bind(this.adapter)
+        : clearTimeout;
+      clear(this._watchdogTimer);
+      this._watchdogTimer = null;
+    }
+  }
+
+  /**
+   * Immediately and silently ends the current cycle (no state-change
+   * callback fired) - used e.g. by the dryer power-drop detection.
+   *
+   * @param {number} [ts]  – timestamp to record as the end time (defaults to now)
+   */
+  forceEnd(ts) {
+    const now = ts || Date.now();
+    this.lastReadingTime = now;
+    this.lastCycleEndTime = now;
+    this.lastCycleCompleted = true; // Mark as cleanly ended
+    this.state = STATES.OFF; // Go straight to OFF without callback
+    this.powerTrace = [];
+    this.accumulatedEnergy = 0;
+    this.belowStartThreshold = null;
+    this._stopWatchdog();
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────
+
+  /** @param {string} newState  – one of STATES to transition to */
+  _setState(newState) {
+    this.state = newState;
+  }
+
+  /** @returns {object} – snapshot of current cycle info passed to the onStateChange callback */
+  _buildEventData() {
+    return {
+      state: this.state,
+      cycleStartTime: this.cycleStartTime,
+      accumulatedEnergy: this.accumulatedEnergy,
+      traceLength: this.powerTrace.length,
+      timestamp: this.lastReadingTime || Date.now(),
+    };
+  }
+}
+
+module.exports = { CycleDetector, STATES, DEFAULT_CONFIG };

package/lib/mathUtils.js

@@ -0,0 +1,180 @@
+"use strict";
+
+/**
+ * mathUtils.js – NumPy/SciPy-style math utilities
+ *
+ * Replaces:
+ *   numpy.corrcoef   → corrcoef(a, b)
+ *   DTW-Lite         → dtwDistance(a, b, window)
+ *   Resampling       → resample(trace, targetLength)
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pearson Correlation Coefficient  (numpy.corrcoef equivalent)
+// Returns value in [-1, 1].  1 = perfect match, 0 = no correlation.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {number[]} a       – first data series
+ * @param {number[]} b  – must be same length as a
+ * @returns {number}    – Pearson r, or 0 if degenerate
+ */
+function corrcoef(a, b) {
+  const n = Math.min(a.length, b.length);
+  if (n < 2) {
+    return 0;
+  }
+
+  let sumA = 0,
+    sumB = 0;
+  for (let i = 0; i < n; i++) {
+    sumA += a[i];
+    sumB += b[i];
+  }
+  const meanA = sumA / n;
+  const meanB = sumB / n;
+
+  let num = 0,
+    denA = 0,
+    denB = 0;
+  for (let i = 0; i < n; i++) {
+    const da = a[i] - meanA;
+    const db = b[i] - meanB;
+    num += da * db;
+    denA += da * da;
+    denB += db * db;
+  }
+
+  const denom = Math.sqrt(denA * denB);
+  if (denom === 0) {
+    return 0;
+  }
+  return num / denom;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DTW-Lite  (Dynamic Time Warping – simplified, Sakoe-Chiba band)
+// Lower score = better match.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {number[]} a       – first data series
+ * @param {number[]} b       – second data series
+ * @param {number}   window  – Sakoe-Chiba band width (0 = no constraint)
+ * @returns {number}          – normalised DTW distance [0, ∞)
+ */
+function dtwDistance(a, b, window = 0) {
+  const n = a.length;
+  const m = b.length;
+  if (n === 0 || m === 0) {
+    return Infinity;
+  }
+
+  const w = window > 0 ? window : Math.max(n, m);
+
+  // Use flat Float64Array for speed
+  const dtw = new Float64Array((n + 1) * (m + 1)).fill(Infinity);
+  const idx = (i, j) => i * (m + 1) + j;
+  dtw[idx(0, 0)] = 0;
+
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      if (w > 0 && Math.abs(i - j) > w) {
+        continue;
+      }
+      const cost = Math.abs(a[i - 1] - b[j - 1]);
+      dtw[idx(i, j)] =
+        cost +
+        Math.min(
+          dtw[idx(i - 1, j)],
+          dtw[idx(i, j - 1)],
+          dtw[idx(i - 1, j - 1)],
+        );
+    }
+  }
+
+  // Normalise by path length
+  return dtw[idx(n, m)] / (n + m);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Linear resampling  (matches scipy.signal.resample for 1-D)
+// Used to align traces of different lengths before correlation.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resample array `arr` to exactly `targetLen` points using linear interpolation.
+ *
+ * @param {number[]} arr        – source data series
+ * @param {number}   targetLen  – desired output length
+ * @returns {number[]}          – resampled array of length targetLen
+ */
+function resample(arr, targetLen) {
+  if (arr.length === 0) {
+    return new Array(targetLen).fill(0);
+  }
+  if (arr.length === targetLen) {
+    return arr.slice();
+  }
+
+  const result = new Array(targetLen);
+  const scale = (arr.length - 1) / (targetLen - 1 || 1);
+
+  for (let i = 0; i < targetLen; i++) {
+    const pos = i * scale;
+    const lo = Math.floor(pos);
+    const hi = Math.min(lo + 1, arr.length - 1);
+    const frac = pos - lo;
+    result[i] = arr[lo] * (1 - frac) + arr[hi] * frac;
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility: extract watts array from power trace [{ts, watts}, ...]
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {Array<{ts:number, watts:number}>} trace  – power trace to extract from
+ * @returns {number[]}  – array of watt values only
+ */
+function traceToWatts(trace) {
+  return trace.map((p) => p.watts);
+}
+
+/**
+ * Compute total energy (Wh) from a power trace using trapezoidal integration.
+ *
+ * @param {Array<{ts:number, watts:number}>} trace  – power trace to integrate
+ * @returns {number}  – total energy in watt-hours
+ */
+function traceToEnergy(trace) {
+  let energy = 0;
+  for (let i = 1; i < trace.length; i++) {
+    const dtH = (trace[i].ts - trace[i - 1].ts) / 3_600_000;
+    energy += ((trace[i].watts + trace[i - 1].watts) / 2) * dtH;
+  }
+  return energy;
+}
+
+/**
+ * Normalise an array to [0, 1] range.
+ *
+ * @param {number[]} arr  – source data series
+ * @returns {number[]}  – normalised values in [0, 1]
+ */
+function normalise(arr) {
+  const max = Math.max(...arr);
+  const min = Math.min(...arr);
+  const range = max - min || 1;
+  return arr.map((v) => (v - min) / range);
+}
+
+module.exports = {
+  corrcoef,
+  dtwDistance,
+  resample,
+  traceToWatts,
+  traceToEnergy,
+  normalise,
+};