homebridge-tuya-plus 3.14.0-dev.49 → 3.14.0-dev.51

package/lib/IrrigationSystemAccessory.js

@@ -28,16 +28,26 @@ const BaseAccessory = require('./BaseAccessory');
  * Auto-shutoff is enforced two ways. HomeKit always gets a live software
  * countdown (RemainingDuration) and a local timer that closes the zone when it
  * expires. On top of that, when the device exposes Tuya's per-zone countdown
- * data-points (countdown_1..n, DP 17.. by default), each zone's duration is
- * mirrored to the hardware's own countdown timer (an integer number of minutes,
- * 0 = no limit, 120 = max), so the valve still closes on schedule even if
- * Homebridge or the network drops out while it is running. The two mechanisms
- * are complementary: the software timer drives the UI and the precise
- * (sub-minute) close while connected; the hardware timer is the offline safety
- * net. SetDuration is in seconds and capped by HomeKit at maxDuration, while the
- * hardware countdown is in minutes and capped at 120 — _reconcileCountdown keeps
- * the two consistent on connect (and never leaves the device on a value HomeKit
- * can't represent, i.e. an unbounded 0 or anything above the advertised max).
+ * data-points (countdown_1..n, DP 17.. by default), switching a zone ON also
+ * sends the run length (whole minutes, in the SAME command as the switch) to the
+ * device's own countdown, so the valve still closes on schedule even if
+ * Homebridge or the network drops out mid-run. The two mechanisms are
+ * complementary: the software timer drives the UI and the precise (sub-minute)
+ * close while connected; the hardware countdown is the offline safety net.
+ *
+ * IMPORTANT: on these controllers the countdown dp is NOT a passive "duration"
+ * setting — writing it STARTS a run and switches the zone ON. It is therefore
+ * written only together with a switch-on, or to re-base/repair a zone that is
+ * already running; never while a zone is off, on connect, or merely because the
+ * Duration was edited. (An earlier version wrote it on connect to "fix" zones
+ * reading 0 and opened every valve at once — see the regression tests.)
+ *
+ * The countdown is (re)written on EVERY switch-on, in the SAME command as the
+ * switch — we do not rely on the device persisting it (it appears to reset once a
+ * run finishes), so each run carries its own fresh countdown matching the zone's
+ * current Duration (0 = indefinite). A zone opened at the device instead
+ * (physical button / Tuya app) is caught by the change handler, which gives it a
+ * countdown too when it comes up without a usable one.
  */
 class IrrigationSystemAccessory extends BaseAccessory {
     static getCategory(Categories) {
@@ -325,16 +335,19 @@ class IrrigationSystemAccessory extends BaseAccessory {
             valve.getCharacteristic(Characteristic.InUse)
                 .updateValue(on ? Characteristic.InUse.IN_USE : Characteristic.InUse.NOT_IN_USE);
 
-            // Decide whether this zone can use the hardware countdown, then bring
-            // the device and HomeKit into agreement: adopt a valid device value as
-            // the zone's duration, or push HomeKit's duration down when the device
-            // is on an unbounded (0) or out-of-range countdown HomeKit can't show.
+            // Whether this zone can use the device's hardware countdown. Detection
+            // only gates the write paths; nothing is written on connect — writing
+            // the countdown dp starts a run and would open the zone.
             cfg.countdownSupported = this._isCountdownSupported(cfg, dps);
-            this._reconcileCountdown(cfg, dps);
 
             // Reflect any zone already running at startup (e.g. turned on at the
-            // device, or Homebridge restarted mid-run) and (re)arm its timer.
-            if (on) this._reflectValve(cfg, true);
+            // device, or Homebridge restarted mid-run) and (re)arm its timer. A
+            // zone that is genuinely running can safely be given a countdown, so
+            // repair an unbounded/invalid one here too — closed zones are skipped.
+            if (on) {
+                this._reflectValve(cfg, true);
+                this._ensureRunningCountdown(cfg);
+            }
         });
 
         // --- Service Label namespace ---
@@ -388,8 +401,12 @@ class IrrigationSystemAccessory extends BaseAccessory {
                 valveChanged = true;
                 this._reflectValve(cfg, !!changes[cfg.dp]);
             }
-            if (cfg.countdownSupported && changes.hasOwnProperty(cfg.dpCountdown)) {
-                this._onCountdownChange(cfg, changes[cfg.dpCountdown]);
+            // A zone switched on at the device (or already on) that's left without a
+            // usable countdown gets one so it still auto-closes, offline included.
+            // _ensureRunningCountdown only writes while the zone is on, so this can
+            // never open a closed zone.
+            if (cfg.countdownSupported && (changes.hasOwnProperty(cfg.dp) || changes.hasOwnProperty(cfg.dpCountdown))) {
+                this._ensureRunningCountdown(cfg);
             }
         });
 
@@ -536,15 +553,16 @@ class IrrigationSystemAccessory extends BaseAccessory {
         this.accessory.context.durations[cfg.dp] = seconds;
         this.log.info('%s: zone "%s" duration set to %s', this.device.context.name, cfg.name, seconds ? (seconds + 's') : 'indefinite');
 
-        // Keep the device's hardware countdown in step with the new duration so a
-        // later run — including one started from the physical button or the Tuya
-        // app — still auto-closes on time (and offline).
-        this._queueCountdownWrite(cfg);
-
-        // If the zone is running, re-base its countdown on the new duration.
+        // If the zone is running, re-base its countdown on the new duration — both
+        // the software timer and (safely, since the zone is already on) the device's
+        // hardware countdown. We deliberately do NOT write the hardware countdown
+        // while the zone is off: writing it starts a run and would open the valve.
+        // An off zone's new duration is applied the next time it is switched on
+        // (and the device persists it from there).
         const service = this._valveService(cfg);
         if (service && service.getCharacteristic(Characteristic.InUse).value === Characteristic.InUse.IN_USE) {
             this._clearTimer(cfg.dp);
+            this._queueCountdownWrite(cfg);
             const remainingChar = service.getCharacteristic(Characteristic.RemainingDuration);
             if (seconds > 0) {
                 this._endTimes[cfg.dp] = Date.now() + seconds * 1000;
@@ -579,8 +597,15 @@ class IrrigationSystemAccessory extends BaseAccessory {
     }
 
     /* ------------------------------------------------------------------ *
-     *  Native (hardware) countdown — keep the device's own per-zone timer
-     *  in step with HomeKit so a zone closes on schedule even while offline
+     *  Native (hardware) countdown
+     *
+     *  Lets the device close a zone by itself after N minutes, so a run still
+     *  ends even if Homebridge or the network drops out. The catch: writing the
+     *  countdown dp STARTS a run and switches the zone ON, so it is only ever
+     *  written as part of a switch-on, or to a zone that is already on — never
+     *  while a zone is off and never on connect. It is re-sent on every switch-on
+     *  (the device doesn't reliably keep it between runs), and the software timer
+     *  is the second line of defence if the hardware countdown ever misbehaves.
      * ------------------------------------------------------------------ */
 
     // A zone can use the hardware countdown when the feature isn't disabled, the
@@ -614,55 +639,33 @@ class IrrigationSystemAccessory extends BaseAccessory {
         return Math.min(this._representableCountdownMinutes, Math.max(1, Math.round(s / 60)));
     }
 
-    // Queue a write of this zone's duration to its hardware countdown dp, coalesced
-    // with whatever else is in flight (e.g. the switch-on it accompanies).
+    // Queue this zone's current HomeKit duration to its hardware countdown dp,
+    // coalesced with whatever else is in flight (the switch-ON it accompanies, so
+    // both data-points are written in one command). MUST only be used as part of
+    // switching the zone on, or for a zone already on — writing the countdown
+    // starts a run. Sent on every switch-on (we don't rely on the device
+    // persisting it) so each run carries the current Duration; 0 = indefinite.
     _queueCountdownWrite(cfg) {
         if (!cfg.countdownSupported) return;
         this._queueWrite(cfg.dpCountdown, this._durationToCountdownMinutes(this._getDuration(cfg)));
     }
 
-    // On connect, line the device's stored countdown up with HomeKit. A concrete,
-    // representable value is adopted as the zone's duration (the hardware is the
-    // source of truth for what it will actually do); an unbounded (0) or
-    // out-of-range value is overwritten with HomeKit's own duration so the device
-    // can't be left on a setting HomeKit can't show — or one that would never
-    // auto-close if the unit drops off the network mid-run.
-    _reconcileCountdown(cfg, state) {
-        if (!cfg.countdownSupported) return;
-        const cd = this._parseCountdown(state[cfg.dpCountdown]);
-        if (cd === null) return;
-
-        if (cd >= 1 && cd <= this._representableCountdownMinutes) {
-            // Don't adopt a value seen mid-run: a streamed "remaining" countdown
-            // could masquerade as the set duration (see _onCountdownChange).
-            if (!this._valveInUse(cfg)) this._adoptCountdown(cfg, cd);
-        } else {
-            const minutes = this._durationToCountdownMinutes(this._getDuration(cfg));
-            if (minutes !== cd) {
-                this.log.debug('%s: zone "%s" hardware countdown was %s; setting it to %s', this.device.context.name, cfg.name, cd === 0 ? 'unbounded' : (cd + ' min'), minutes ? (minutes + ' min') : 'unbounded');
-                this._queueWrite(cfg.dpCountdown, minutes);
-            }
-        }
-    }
-
-    // A duration change reported by the device (e.g. set from the Tuya app). Only
-    // adopt it while the zone is idle: some units stream the *remaining* countdown
-    // down to zero while running, and treating that as a new SetDuration would
-    // corrupt the user's setting. A change seen while idle is a real reconfigure.
-    _onCountdownChange(cfg, value) {
-        if (this._valveInUse(cfg)) return;
-        const cd = this._parseCountdown(value);
-        if (cd !== null && cd >= 1 && cd <= this._representableCountdownMinutes) this._adoptCountdown(cfg, cd);
-    }
-
-    _adoptCountdown(cfg, minutes) {
-        const {Characteristic} = this.hap;
-        const seconds = minutes * 60;
-        if (this._getDuration(cfg) === seconds) return;
-        this.accessory.context.durations[cfg.dp] = seconds;
-        const service = this._valveService(cfg);
-        if (service) service.getCharacteristic(Characteristic.SetDuration).updateValue(seconds);
-        this.log.debug('%s: zone "%s" adopted the device\'s %s min countdown as its duration', this.device.context.name, cfg.name, minutes);
+    // For a zone that is RUNNING, make sure the device has a usable countdown so it
+    // still auto-closes (offline included). Used when a zone is switched on at the
+    // device, or was already on at startup. Only ever writes while the zone is on,
+    // so it can never open a closed one. A countdown the device already holds at a
+    // valid value (e.g. a duration the device or Tuya app set for this run) is
+    // respected; only an unbounded (0) or out-of-range one is replaced with the
+    // zone's HomeKit duration. Does nothing for an indefinite (0) HomeKit
+    // duration — there's no finite run to enforce.
+    _ensureRunningCountdown(cfg) {
+        if (!cfg.countdownSupported || !this._valveInUse(cfg)) return;
+        const minutes = this._durationToCountdownMinutes(this._getDuration(cfg));
+        if (minutes <= 0) return;
+        const cd = this._parseCountdown(this.device.state[cfg.dpCountdown]);
+        if (cd === null || (cd >= 1 && cd <= this._representableCountdownMinutes)) return;
+        this.log.debug('%s: zone "%s" is running with countdown %s; setting it to %s min', this.device.context.name, cfg.name, cd === 0 ? 'unbounded' : cd, minutes);
+        this._queueWrite(cfg.dpCountdown, minutes);
     }
 
     _valveInUse(cfg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.49",
+  "version": "3.14.0-dev.51",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices in HomeKit. LAN-first, with an optional Tuya Cloud fallback for any device the LAN can't reach.",
   "main": "index.js",
   "scripts": {

package/test/IrrigationSystemAccessory.test.js

@@ -456,10 +456,31 @@ describe('IrrigationSystemAccessory — native (hardware) countdown', () => {
         expect(instance._durationToCountdownMinutes(999999)).toBe(120); // capped at the 120-min hardware max
     });
 
+    /* --- THE pool-flood regression: writing a countdown opens the zone, so it
+     *     must never be written while a zone is off or on connect --- */
+
+    test('on connect, zones sitting at countdown 0 are NEVER written to (must not open them)', () => {
+        const { device } = makeHarness(
+            { '1': false, '2': false, '3': false, '4': false, '17': 0, '18': 0, '19': 0, '20': 0 },
+            { defaultDuration: 600 }
+        );
+        jest.advanceTimersByTime(2000);
+        expect(device.update).not.toHaveBeenCalled();
+    });
+
+    test('editing the Duration while a zone is OFF does not write to the device', () => {
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
+        valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).triggerSet(1800);
+        jest.advanceTimersByTime(2000);
+        expect(device.update).not.toHaveBeenCalled();
+        // The new duration is remembered (read back via the getter) for the next switch-on.
+        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).triggerGet()).toBe(1800);
+    });
+
     /* --- turning a zone on hands the device its own timer (the offline safety net) --- */
 
     test('turning a zone on sends the hardware countdown alongside the switch (one command)', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 10 }, { defaultDuration: 600 });
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
         valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
         expect(device.update).toHaveBeenCalledTimes(1);
@@ -470,7 +491,7 @@ describe('IrrigationSystemAccessory — native (hardware) countdown', () => {
 
     test('master ON hands every zone its hardware countdown in one command', () => {
         const { accessory, device } = makeHarness(
-            { '1': false, '2': false, '3': false, '4': false, '17': 10, '18': 10, '19': 10, '20': 10 },
+            { '1': false, '2': false, '3': false, '4': false, '17': 0, '18': 0, '19': 0, '20': 0 },
             { defaultDuration: 600 }
         );
         irrigation(accessory).getCharacteristic(Characteristic.Active).triggerSet(1);
@@ -479,7 +500,7 @@ describe('IrrigationSystemAccessory — native (hardware) countdown', () => {
         expect(device.update).toHaveBeenCalledWith({ '1': true, '2': true, '3': true, '4': true, '17': 10, '18': 10, '19': 10, '20': 10 });
     });
 
-    test('an indefinite duration writes an unbounded (0) hardware countdown', () => {
+    test('an indefinite duration turns the zone on with an unbounded (0) countdown', () => {
         const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 0 });
         valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
@@ -487,67 +508,71 @@ describe('IrrigationSystemAccessory — native (hardware) countdown', () => {
         expect(device.update).toHaveBeenCalledWith({ '1': true, '17': 0 });
     });
 
-    test('changing SetDuration pushes the new value to the hardware countdown', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 10 }, { defaultDuration: 600 });
-        valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).triggerSet(1200);
+    test('a sub-minute duration turns the zone on with a 1-min countdown, never 0', () => {
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 30 });
+        valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenCalledWith({ '17': 20 });
+        expect(device.update).toHaveBeenCalledWith({ '1': true, '17': 1 });
     });
 
-    /* --- reconciliation on connect --- */
-
-    test('on connect, an unbounded (0) device countdown is set to the HomeKit duration', () => {
+    test('changing the Duration while a zone is RUNNING re-bases the hardware countdown', () => {
         const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
+        const v = valve(accessory, 1);
+        v.getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenCalledTimes(1);
-        expect(device.update).toHaveBeenCalledWith({ '17': 10 });
-        // HomeKit keeps its own duration; only the device was corrected.
-        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).value).toBe(600);
+        device.update.mockClear();
+        v.getCharacteristic(Characteristic.SetDuration).triggerSet(1200);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledWith({ '17': 20 });
     });
 
-    test('on connect, a valid device countdown is adopted as the zone duration (no write)', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 30 }, { defaultDuration: 600 });
-        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).value).toBe(1800);
+    test('the software timer still closes the zone after the duration, even with a hardware countdown set', () => {
+        // Belt-and-suspenders: if the hardware countdown is unreliable (e.g. the
+        // device clears it mid-run), Homebridge itself still switches the zone off
+        // once the duration elapses — independent of the hardware countdown.
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 60 });
+        const v = valve(accessory, 1);
+        v.getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
-        expect(device.update).not.toHaveBeenCalled();
+        expect(device.update).toHaveBeenCalledWith({ '1': true, '17': 1 }); // on + 1-min hardware countdown
+        device.update.mockClear();
+
+        jest.advanceTimersByTime(60 * 1000);   // the HomeKit duration elapses
+        expect(v.getCharacteristic(Characteristic.Active).value).toBe(0);
+        jest.advanceTimersByTime(500);         // flush the off-write
+        expect(device.update).toHaveBeenCalledWith({ '1': false });
     });
 
-    test('on connect, a countdown above the representable max is corrected (maxDuration 3600 → 60min cap)', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 90 }, { defaultDuration: 600, maxDuration: 3600 });
+    /* --- zones turned on at the device (physical button / Tuya app) --- */
+
+    test('a zone switched on at the device with no countdown is given one so it still auto-closes', () => {
+        const { device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
+        device.update.mockClear();
+        device.emitChange({ '1': true });               // external on; device countdown still 0
         jest.advanceTimersByTime(500);
         expect(device.update).toHaveBeenCalledWith({ '17': 10 });
-        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).value).toBe(600);
     });
 
-    test('with the default 120-min cap, a 90-min device countdown is adopted rather than corrected', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 90 }, { defaultDuration: 600 });
-        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).value).toBe(5400);
+    test('a zone switched on at the device with a valid countdown is left as the device set it', () => {
+        const { device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
+        device.update.mockClear();
+        device.emitChange({ '1': true, '17': 5 });      // external on with its own 5-min run
         jest.advanceTimersByTime(500);
         expect(device.update).not.toHaveBeenCalled();
     });
 
-    test('a sub-minute duration is corrected to 1 min, never left unbounded', () => {
-        const { device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 30 });
+    test('an externally-started zone is left alone when its HomeKit duration is indefinite', () => {
+        const { device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 0 });
+        device.update.mockClear();
+        device.emitChange({ '1': true });
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenCalledWith({ '17': 1 });
-    });
-
-    /* --- device-side countdown changes --- */
-
-    test('a duration change from the device (Tuya app) is adopted while the zone is idle', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 10 }, { defaultDuration: 600 });
-        device.emitChange({ '17': 25 });
-        expect(valve(accessory, 1).getCharacteristic(Characteristic.SetDuration).value).toBe(1500);
+        expect(device.update).not.toHaveBeenCalled();
     });
 
-    test('a countdown change reported while the zone runs is ignored (could be a streamed remaining value)', () => {
-        const { accessory, device } = makeHarness({ '1': false, '17': 10 }, { defaultDuration: 600 });
-        const v = valve(accessory, 1);
-        v.getCharacteristic(Characteristic.Active).triggerSet(1);
+    test('a zone already running at startup with no countdown is given one (offline-safe)', () => {
+        const { device } = makeHarness({ '1': true, '17': 0 }, { defaultDuration: 600 });
         jest.advanceTimersByTime(500);
-        const before = v.getCharacteristic(Characteristic.SetDuration).value;
-        device.emitChange({ '17': 5 });
-        expect(v.getCharacteristic(Characteristic.SetDuration).value).toBe(before);
+        expect(device.update).toHaveBeenCalledWith({ '17': 10 });
     });
 
     /* --- opt-out & unsupported devices --- */

package/wiki/Supported-Device-Types.md

@@ -794,13 +794,13 @@ The defaults match the common 4-zone layout (valves A–D on data-points `1`–`
 
 Each zone has its own **Duration**. When a zone is switched on it runs for that duration and is then closed automatically. Two mechanisms enforce this together:
 
-* a **software timer** in the plugin drives HomeKit's live countdown and the precise (sub-minute) shut-off while Homebridge is connected — it also re-closes a zone that was switched on at the device or that was already running when Homebridge restarted; and
-* the device's **own countdown timer**, when the controller exposes one (`countdown_1..n`, DP `17..` by default). Each zone's duration is mirrored to it (as whole minutes), so the valve still closes on schedule **even if Homebridge or the network drops out while it's running** — the hardware closes itself. This is on by default whenever the device reports these data-points; set `nativeCountdown: false` to fall back to the software timer alone.
+* a **software timer** in the plugin drives HomeKit's live countdown and the precise (sub-minute) shut-off while Homebridge is connected — it also closes a zone that was switched on at the device or that was already running when Homebridge restarted; and
+* the device's **own countdown timer**, when the controller exposes one (`countdown_1..n`, DP `17..` by default). When a zone is switched **on**, its run length (whole minutes) is sent to the hardware countdown in the *same command* as the switch, so the valve still closes on schedule **even if Homebridge or the network drops out while it's running** — the hardware closes itself. This is on by default whenever the device reports these data-points; set `nativeCountdown: false` to fall back to the software timer alone.
 
-On connect the plugin lines the two up: a valid device countdown is adopted as the zone's Duration, while a device left on an unbounded (`0`) or out-of-range countdown is corrected to HomeKit's own Duration so a zone can never be stuck running with no auto-close.
+> On these controllers the countdown is **not** a passive setting — *writing it starts a run and opens the zone*. So the plugin only ever sets it while switching a zone on (or for a zone that's already running); it is **never** written on connect or while a zone is off. The two mechanisms are belt-and-suspenders: the hardware countdown handles the offline case, and the software timer still switches the zone off after its Duration if the hardware countdown is unreliable. A zone switched on at the device with no usable countdown is given one (so it still auto-closes offline); a valid countdown the device set itself (e.g. a duration chosen in the Tuya app) is left alone.
 
-* Set a zone's duration to **`0`** to make it run **indefinitely** (until it is switched off again) — handy for long, manual watering tasks. (The hardware countdown is set to `0` too, which the device also reads as "no limit".)
-* The hardware countdown is whole **minutes**, capped by the device at **120 min**; HomeKit's Duration is in seconds. The largest device countdown the plugin treats as valid is also bounded by `maxDuration` (default `7200`s = 120 min) — lower `maxDuration` to e.g. `3600` to have any device countdown over 60 minutes corrected down on connect.
+* Set a zone's duration to **`0`** to make it run **indefinitely** (until it is switched off again) — handy for long, manual watering tasks. (No finite hardware countdown is sent, so the device won't auto-close it either.)
+* The hardware countdown is whole **minutes**, capped by the device at **120 min**; HomeKit's Duration is in seconds. The value written is bounded by `maxDuration` (default `7200`s = 120 min) — lower `maxDuration` to e.g. `3600` to cap zone runs at 60 minutes.
 * Apple's Home app only offers duration presets up to **1 hour**. For longer runs (up to `maxDuration`) or to preset "indefinite" zones, set `defaultDuration` / the per-valve `defaultDuration` in the config, or use the Eve app.
 
 #### Master ("toggle all") switch