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

package/config.schema.json

@@ -758,6 +758,12 @@
                     "title": "Data-point (numeric id, or cloud code)",
                     "placeholder": "1 or switch_1"
                   },
+                  "dpCountdown": {
+                    "type": ["integer", "string"],
+                    "title": "Countdown data-point (numeric id, or cloud code)",
+                    "description": "Optional. The device's built-in auto-off timer for this zone. Defaults to the switch data-point + 16 (so switch 1 → countdown 17). Set this only for code-addressed or non-standard zones.",
+                    "placeholder": "17 or countdown_1"
+                  },
                   "defaultDuration": {
                     "type": "integer",
                     "title": "Default run time (seconds, 0 = run indefinitely)",
@@ -782,7 +788,16 @@
               "type": "integer",
               "title": "Maximum Run Time (seconds)",
               "placeholder": 7200,
-              "description": "Upper bound advertised to HomeKit for the duration picker (HAP default is 3600 / 1h). Apple's Home app only offers presets up to 1h regardless; longer values can be set from the config or apps like Eve.",
+              "description": "Upper bound advertised to HomeKit for the duration picker (HAP default is 3600 / 1h). Apple's Home app only offers presets up to 1h regardless; longer values can be set from the config or apps like Eve. Also bounds the hardware countdown: a device countdown longer than this (or the 120-min hardware cap) is corrected on connect.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
+              }
+            },
+            "nativeCountdown": {
+              "type": "boolean",
+              "title": "Use the device's built-in countdown timer",
+              "placeholder": true,
+              "description": "When the controller exposes per-zone countdown data-points (countdown_1.., DP 17.. by default), mirror each zone's duration to the hardware timer so a zone still auto-closes on schedule even if Homebridge or the network drops out mid-run. Disable to fall back to the software-timer-only behaviour. Has no effect on devices that don't report a countdown data-point.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
               }

package/lib/IrrigationSystemAccessory.js

@@ -24,6 +24,20 @@ const BaseAccessory = require('./BaseAccessory');
  * command (the device is a laggy, battery-powered Wi-Fi unit), so turning the
  * whole system on/off — or running a scene that toggles several zones at once —
  * results in one network round-trip rather than a burst of them.
+ *
+ * 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).
  */
 class IrrigationSystemAccessory extends BaseAccessory {
     static getCategory(Categories) {
@@ -57,11 +71,14 @@ class IrrigationSystemAccessory extends BaseAccessory {
                 if (!dp) {
                     throw new Error(`The valve definition #${i + 1} is missing a 'dp': ${JSON.stringify(valve)}`);
                 }
+                const dpCountdownExplicit = (valve && valve.dpCountdown !== undefined && valve.dpCountdown !== null) ? ('' + valve.dpCountdown).trim() : '';
                 return {
                     dp,
                     name: (('' + (valve.name || '')).trim()) || ('Zone ' + (i + 1)),
                     index: i + 1,
-                    duration: isFinite(valve.defaultDuration) ? parseInt(valve.defaultDuration) : defaultDuration
+                    duration: isFinite(valve.defaultDuration) ? parseInt(valve.defaultDuration) : defaultDuration,
+                    dpCountdown: dpCountdownExplicit || this._defaultCountdownDP(dp),
+                    countdownConfigured: dpCountdownExplicit !== ''
                 };
             });
         }
@@ -70,16 +87,31 @@ class IrrigationSystemAccessory extends BaseAccessory {
         const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
         const configs = [];
         for (let i = 0; i < count; i++) {
+            const dp = String(i + 1);
             configs.push({
-                dp: String(i + 1),
+                dp,
                 name: 'Valve ' + (letters[i] || (i + 1)),
                 index: i + 1,
-                duration: defaultDuration
+                duration: defaultDuration,
+                dpCountdown: this._defaultCountdownDP(dp),
+                countdownConfigured: false
             });
         }
         return configs;
     }
 
+    // Default countdown data-point for a zone. On these devices the per-zone
+    // countdown timers sit 16 ids above the switches (switch_1=DP 1 → countdown_1
+    // =DP 17, … switch_4=DP 4 → countdown_4=DP 20), so derive it from a numeric
+    // switch dp. A code-addressed switch (e.g. "switch_1") has no derivable
+    // numeric neighbour — the user must set `dpCountdown` explicitly for those —
+    // so return '' (native countdown stays off for that zone unless configured).
+    _defaultCountdownDP(switchDp) {
+        const trimmed = ('' + switchDp).trim();
+        const n = parseInt(trimmed, 10);
+        return (isFinite(n) && String(n) === trimmed) ? String(n + 16) : '';
+    }
+
     // Resolve a configurable data-point (a numeric id or a Tuya code), trimming and
     // falling back to a default when it isn't set.
     _resolveDP(value, fallback) {
@@ -204,6 +236,21 @@ class IrrigationSystemAccessory extends BaseAccessory {
         this._cascadeOn = this._coerceBoolean(this.device.context.masterTurnsOnAllZones, true);
         this._cascadeOff = this._coerceBoolean(this.device.context.masterTurnsOffAllZones, true);
 
+        // Native (hardware) per-zone countdown. On by default, but only ever used
+        // for a zone whose countdown data-point the device actually reports (see
+        // _isCountdownSupported); set nativeCountdown:false to force the legacy
+        // software-timer-only behaviour even on a device that supports it.
+        this._nativeCountdown = this._coerceBoolean(this.device.context.nativeCountdown, true);
+        // Tuya's per-zone countdown is an integer number of minutes, hardware-
+        // capped at 120 (0 = no limit). The largest countdown we treat as valid is
+        // also bounded by what HomeKit's SetDuration can represent (its advertised
+        // maxValue, _maxDuration seconds), so the two views never disagree. With
+        // the default 7200s (=120min) max this is the full 120; lower maxDuration
+        // to e.g. 3600 to have the device's longer/over-cap countdowns corrected
+        // down to 60min on connect.
+        this._maxCountdownMinutes = 120;
+        this._representableCountdownMinutes = Math.max(1, Math.min(this._maxCountdownMinutes, Math.floor(this._maxDuration / 60)));
+
         // Data-points default to this device's numeric ids; a Tuya code may be
         // configured instead and works over either transport.
         this.dpBattery = this._resolveDP(this.device.context.dpBattery, '46');
@@ -278,6 +325,13 @@ 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.
+            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);
@@ -330,9 +384,13 @@ class IrrigationSystemAccessory extends BaseAccessory {
 
         let valveChanged = false;
         this._valves.forEach(cfg => {
-            if (!changes.hasOwnProperty(cfg.dp)) return;
-            valveChanged = true;
-            this._reflectValve(cfg, !!changes[cfg.dp]);
+            if (changes.hasOwnProperty(cfg.dp)) {
+                valveChanged = true;
+                this._reflectValve(cfg, !!changes[cfg.dp]);
+            }
+            if (cfg.countdownSupported && changes.hasOwnProperty(cfg.dpCountdown)) {
+                this._onCountdownChange(cfg, changes[cfg.dpCountdown]);
+            }
         });
 
         if (changes.hasOwnProperty(this.dpBattery) && this._hasBattery()) {
@@ -384,6 +442,7 @@ class IrrigationSystemAccessory extends BaseAccessory {
         }
 
         this._queueWrite(cfg.dp, on);
+        if (on) this._queueCountdownWrite(cfg);
         this._reflectValve(cfg, on);
         this._syncAggregate();
     }
@@ -456,6 +515,7 @@ class IrrigationSystemAccessory extends BaseAccessory {
             const currentlyOn = !!(service && service.getCharacteristic(Characteristic.Active).value);
             if (currentlyOn === on) return;
             this._queueWrite(cfg.dp, on);
+            if (on) this._queueCountdownWrite(cfg);
             this._reflectValve(cfg, on);
         });
         this._syncAggregate();
@@ -476,6 +536,11 @@ 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.
         const service = this._valveService(cfg);
         if (service && service.getCharacteristic(Characteristic.InUse).value === Characteristic.InUse.IN_USE) {
@@ -513,6 +578,99 @@ class IrrigationSystemAccessory extends BaseAccessory {
         return max;
     }
 
+    /* ------------------------------------------------------------------ *
+     *  Native (hardware) countdown — keep the device's own per-zone timer
+     *  in step with HomeKit so a zone closes on schedule even while offline
+     * ------------------------------------------------------------------ */
+
+    // A zone can use the hardware countdown when the feature isn't disabled, the
+    // zone has a countdown data-point, and either the user mapped that dp
+    // explicitly or the device actually reports a plausible value there — so we
+    // never write a countdown to a device (or a dp) that isn't really one.
+    _isCountdownSupported(cfg, state) {
+        if (!this._nativeCountdown || !cfg.dpCountdown) return false;
+        if (cfg.countdownConfigured) return true;
+        return this._looksLikeCountdown(state[cfg.dpCountdown]);
+    }
+
+    _looksLikeCountdown(value) {
+        const n = this._parseCountdown(value);
+        return n !== null && n >= 0 && n <= this._maxCountdownMinutes;
+    }
+
+    _parseCountdown(value) {
+        if (value === undefined || value === null || value === '') return null;
+        const n = parseInt(value, 10);
+        return isFinite(n) ? n : null;
+    }
+
+    // SetDuration (seconds) -> hardware countdown (whole minutes). 0 stays 0 (both
+    // sides mean "no limit"); any other value is forced to at least 1 minute so a
+    // sub-minute duration can never round down to 0 and silently make the run
+    // unbounded, and is capped at what both the hardware and HomeKit allow.
+    _durationToCountdownMinutes(seconds) {
+        const s = Math.max(0, parseInt(seconds) || 0);
+        if (s === 0) return 0;
+        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).
+    _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);
+    }
+
+    _valveInUse(cfg) {
+        const {Characteristic} = this.hap;
+        const service = this._valveService(cfg);
+        return !!(service && service.getCharacteristic(Characteristic.InUse).value === Characteristic.InUse.IN_USE);
+    }
+
     /* ------------------------------------------------------------------ *
      *  Aggregation: roll zone state up to the IrrigationSystem service
      * ------------------------------------------------------------------ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.48",
+  "version": "3.14.0-dev.49",
   "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

@@ -422,6 +422,153 @@ describe('IrrigationSystemAccessory — device-side change reflection', () => {
     });
 });
 
+describe('IrrigationSystemAccessory — native (hardware) countdown', () => {
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => { jest.clearAllTimers(); jest.useRealTimers(); });
+
+    /* --- data-point resolution --- */
+
+    test('derives each zone\'s countdown data-point as its switch dp + 16 by default', () => {
+        const { instance } = makeHarness();
+        expect(instance._getValveConfigs().map(c => c.dpCountdown)).toEqual(['17', '18', '19', '20']);
+    });
+
+    test('a custom zone may map an explicit countdown data-point', () => {
+        const { instance } = makeHarness({}, { valves: [{ name: 'Lawn', dp: 'switch_1', dpCountdown: 'countdown_1' }] });
+        const cfg = instance._getValveConfigs()[0];
+        expect(cfg.dpCountdown).toBe('countdown_1');
+        expect(cfg.countdownConfigured).toBe(true);
+    });
+
+    test('a code-addressed zone gets no default countdown dp (must be set explicitly)', () => {
+        const { instance } = makeHarness({}, { valves: [{ name: 'Lawn', dp: 'switch_1' }] });
+        expect(instance._getValveConfigs()[0].dpCountdown).toBe('');
+    });
+
+    /* --- seconds <-> minutes conversion --- */
+
+    test('converts SetDuration seconds to whole countdown minutes, never 0 for a real run', () => {
+        const { instance } = makeHarness({ '1': false, '17': 10 });
+        expect(instance._durationToCountdownMinutes(0)).toBe(0);        // indefinite stays indefinite
+        expect(instance._durationToCountdownMinutes(30)).toBe(1);       // sub-minute rounds up to 1, not 0
+        expect(instance._durationToCountdownMinutes(600)).toBe(10);
+        expect(instance._durationToCountdownMinutes(5400)).toBe(90);
+        expect(instance._durationToCountdownMinutes(999999)).toBe(120); // capped at the 120-min hardware max
+    });
+
+    /* --- 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 });
+        valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        // The countdown rides along so the device closes the valve itself even if
+        // Homebridge/the network drops while it's running.
+        expect(device.update).toHaveBeenCalledWith({ '1': true, '17': 10 });
+    });
+
+    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 },
+            { defaultDuration: 600 }
+        );
+        irrigation(accessory).getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        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', () => {
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 0 });
+        valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        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);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledWith({ '17': 20 });
+    });
+
+    /* --- reconciliation on connect --- */
+
+    test('on connect, an unbounded (0) device countdown is set to the HomeKit duration', () => {
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600 });
+        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);
+    });
+
+    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);
+        jest.advanceTimersByTime(500);
+        expect(device.update).not.toHaveBeenCalled();
+    });
+
+    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 });
+        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);
+        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 });
+        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);
+    });
+
+    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);
+        jest.advanceTimersByTime(500);
+        const before = v.getCharacteristic(Characteristic.SetDuration).value;
+        device.emitChange({ '17': 5 });
+        expect(v.getCharacteristic(Characteristic.SetDuration).value).toBe(before);
+    });
+
+    /* --- opt-out & unsupported devices --- */
+
+    test('nativeCountdown:false never touches the countdown data-point', () => {
+        const { accessory, device } = makeHarness({ '1': false, '17': 0 }, { defaultDuration: 600, nativeCountdown: false });
+        valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        expect(device.update).toHaveBeenCalledWith({ '1': true });
+    });
+
+    test('a device that reports no countdown data-point is unaffected (software timer only)', () => {
+        const { accessory, device } = makeHarness({ '1': false }, { defaultDuration: 600 });
+        valve(accessory, 1).getCharacteristic(Characteristic.Active).triggerSet(1);
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        expect(device.update).toHaveBeenCalledWith({ '1': true });
+    });
+});
+
 describe('IrrigationSystemAccessory — battery mapping', () => {
     test('clamps the level into 0–100', () => {
         const { instance } = makeHarness();

package/wiki/Supported-Device-Types.md

@@ -792,9 +792,15 @@ The defaults match the common 4-zone layout (valves A–D on data-points `1`–`
 
 #### Per-zone timers and "indefinite" mode
 
-Each zone has its own **Duration**. When a zone is switched on it runs for that duration and the plugin closes it automatically (HomeKit's countdown is display-only — the plugin always enforces the shut-off, even after a Homebridge restart).
+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:
 
-* Set a zone's duration to **`0`** to make it run **indefinitely** (until it is switched off again) — handy for long, manual watering tasks.
+* 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.
+
+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.
+
+* 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.
 * 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
@@ -816,17 +822,23 @@ Switching the whole Irrigation System tile **off** closes every open zone, and s
     /* Simple: number of valves on sequential data-points 1, 2, 3, … */
     "valveCount": 4,
     /* …or, for custom names / non-sequential data-points, define them explicitly
-       (this overrides valveCount). defaultDuration is in seconds; 0 = indefinite. */
+       (this overrides valveCount). defaultDuration is in seconds; 0 = indefinite.
+       dpCountdown is the device's built-in auto-off timer for the zone; it
+       defaults to the switch dp + 16 (so switch 1 → countdown 17) and only needs
+       setting for code-addressed or non-standard zones. */
     "valves": [
         { "name": "Front Lawn", "dp": 1, "defaultDuration": 900 },
         { "name": "Back Lawn",  "dp": 2, "defaultDuration": 900 },
         { "name": "Flower Beds","dp": 3, "defaultDuration": 600 },
-        { "name": "Drip Line",  "dp": 4, "defaultDuration": 0 }
+        { "name": "Drip Line",  "dp": 4, "defaultDuration": 0, "dpCountdown": 20 }
     ],
 
     /* --- Timers --- */
     "defaultDuration": 600,   /* default per-zone run time, seconds (0 = indefinite) */
     "maxDuration": 7200,      /* upper bound advertised to HomeKit, seconds */
+    "nativeCountdown": true,  /* mirror durations to the device's own countdown timer
+                                 (countdown_1.., DP 17..) so zones still auto-close
+                                 offline; set false for software-timer-only */
 
     /* --- Master switch behaviour --- */
     "masterTurnsOnAllZones": true,