homebridge-tuya-plus 3.14.0-dev.19 → 3.14.0-dev.21

package/lib/IrrigationSystemAccessory.js

@@ -46,14 +46,13 @@ class IrrigationSystemAccessory extends BaseAccessory {
         // Self-contained (no reliance on instance state) so it is safe to call
         // both during early service reconciliation and later when wiring
         // characteristics.
-        const cloud = this._isCloud();
         const defaultDuration = isFinite(this.device.context.defaultDuration) ? parseInt(this.device.context.defaultDuration) : 600;
 
         if (Array.isArray(this.device.context.valves) && this.device.context.valves.length) {
             return this.device.context.valves.map((valve, i) => {
-                // A data-point may be a numeric LAN id (1, 2, …) or a Tuya Cloud
-                // code (e.g. "switch_1"). Accept either; only an empty value is
-                // invalid.
+                // A data-point may be a numeric id (1, 2, …) or a Tuya code
+                // (e.g. "switch_1"); both resolve over either transport. Only an
+                // empty value is invalid.
                 const dp = (valve && valve.dp !== undefined && valve.dp !== null) ? ('' + valve.dp).trim() : '';
                 if (!dp) {
                     throw new Error(`The valve definition #${i + 1} is missing a 'dp': ${JSON.stringify(valve)}`);
@@ -72,9 +71,7 @@ class IrrigationSystemAccessory extends BaseAccessory {
         const configs = [];
         for (let i = 0; i < count; i++) {
             configs.push({
-                // Cloud devices address valves by code (switch_1, switch_2, …);
-                // LAN devices by numeric data-point id (1, 2, …).
-                dp: cloud ? ('switch_' + (i + 1)) : String(i + 1),
+                dp: String(i + 1),
                 name: 'Valve ' + (letters[i] || (i + 1)),
                 index: i + 1,
                 duration: defaultDuration
@@ -83,19 +80,11 @@ class IrrigationSystemAccessory extends BaseAccessory {
         return configs;
     }
 
-    // True when this device is reached over the Tuya Cloud (data-points keyed by
-    // string code) rather than the LAN (numeric data-point ids).
-    _isCloud() {
-        return this._coerceBoolean(this.device.context.cloud, false);
-    }
-
-    // Resolve a configurable data-point that may be given as a numeric LAN id or
-    // a Tuya Cloud code, falling back to a sensible default for the active
-    // transport.
-    _resolveDP(value, cloudDefault, lanDefault) {
+    // 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) {
         const v = (value === undefined || value === null) ? '' : ('' + value).trim();
-        if (v !== '') return v;
-        return this._isCloud() ? cloudDefault : lanDefault;
+        return v !== '' ? v : fallback;
     }
 
     _hasBattery() {
@@ -215,10 +204,10 @@ class IrrigationSystemAccessory extends BaseAccessory {
         this._cascadeOn = this._coerceBoolean(this.device.context.masterTurnsOnAllZones, true);
         this._cascadeOff = this._coerceBoolean(this.device.context.masterTurnsOffAllZones, true);
 
-        // Data-points accept a numeric LAN id or a Tuya Cloud code; defaults
-        // differ per transport (cloud uses the standard Tuya codes).
-        this.dpBattery = this._resolveDP(this.device.context.dpBattery, 'battery_percentage', '46');
-        this.dpCharging = this._resolveDP(this.device.context.dpCharging, 'charge_state', '101');
+        // 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');
+        this.dpCharging = this._resolveDP(this.device.context.dpCharging, '101');
 
         // Per-zone runtime state
         this._valves = this._getValveConfigs();

package/lib/SimpleGarageDoorAccessory.js

@@ -98,6 +98,12 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         // and the close that trails a stop in the stop-before-close path.
         this.partialStopTimer = null;
         this.pendingCloseTimer = null;
+        // A partial open that has fired its open but is still waiting for the
+        // controller to report it's moving before arming the auto-stop.
+        this.partialPending = false;
+        // Bumped whenever a partial open starts or is superseded/cancelled, so a
+        // stale auto-stop (and its re-sends) from an earlier flow bails out.
+        this.partialGeneration = 0;
 
         // Seed the initial state from whatever the device has already reported.
         // If it hasn't reported yet, fall back to the persisted target, then to
@@ -227,6 +233,11 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         if (this.characteristicPartialOpen) {
             this.characteristicPartialOpen.updateValue(isOpen);
         }
+
+        // A partial open fires its open and then waits for the controller to
+        // confirm the gate is actually moving before starting the auto-stop
+        // countdown — see _handlePartialOpen.
+        if (this.partialPending && isOpen) this._armPartialStop();
     }
 
     // onGet helper: a cached/optimistic door value is fine to report while the
@@ -310,33 +321,63 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         }
     }
 
-    // Partial open: fire the open action, then after partialOpenMs fire a stop
-    // so the gate ends up parked part-way. Anchored to the button press (the
-    // controller starts moving and reports state within ~1s), which is all the
-    // user asked for.
+    // Partial open: fire the open action, wait partialOpenMs, then fire a stop
+    // so the gate ends up parked part-way.
+    //
+    // The auto-stop is anchored to the controller *reporting the gate is moving*
+    // (the status DP flipping to OPEN), not to the button press: the open
+    // command takes time to reach the gate, and a stop fired before the gate is
+    // actually moving lands as a no-op the controller drops — letting the gate
+    // run all the way open. If the gate already reads open/opening, no fresh
+    // report is coming, so we arm straight away.
     _handlePartialOpen() {
         const {Characteristic} = this.hap;
         const name = this.device.context.name;
         if (!this.device.connected) throw this._commError();
         if (!this.partialOpenMs) return;
-        if (this.partialStopTimer) {
-            // Re-entrant press while a partial is already armed (e.g. a
+        if (this.partialPending || this.partialStopTimer) {
+            // Re-entrant press while a partial is already in progress (e.g. a
             // HomeKit/iOS WRITE retransmit) — ignore so the stop isn't pushed
             // out, which would let the gate run further than intended.
             this.log.debug(`[SimpleGarageDoor] ${name}: partial press ignored — a partial open is already running`);
             return;
         }
 
-        this.log.debug(`[SimpleGarageDoor] ${name}: partial open — opening, will stop in ${this.partialOpenMs}ms`);
+        this.log.debug(`[SimpleGarageDoor] ${name}: partial open — opening, will stop ${this.partialOpenMs}ms after the gate starts moving`);
+        this.partialGeneration++;
+        this.partialPending = true;
         this._applyTarget(Characteristic.TargetDoorState.OPEN);
+
+        const reported = this.device.state ? this.device.state[this.dpState] : undefined;
+        if (this._mapDpState(reported) === true) this._armPartialStop();
+    }
+
+    _armPartialStop() {
+        if (!this.partialPending || this.partialStopTimer) return;
+        this.partialPending = false;
+        const name = this.device.context.name;
+        const generation = this.partialGeneration;
         this.partialStopTimer = setTimeout(() => {
             this.partialStopTimer = null;
             this.log.debug(`[SimpleGarageDoor] ${name}: partial open — firing stop (dp${this.dpStop})`);
-            this.setMultiStateLegacyInBackground({[this.dpStop]: true});
+            this._sendPartialStop(generation, 1);
         }, this.partialOpenMs);
     }
 
+    // The controller occasionally drops a lone write (its command queue can
+    // coalesce back-to-back writes, and brief Wi-Fi blips lose individual
+    // packets), and a dropped stop here is exactly what lets a partial open run
+    // all the way. Re-send it a few times; a stop on an already-parked gate is a
+    // harmless no-op. Bails out if the flow was superseded mid-way.
+    _sendPartialStop(generation, attempt) {
+        if (generation !== this.partialGeneration) return;
+        this.setMultiStateLegacyInBackground({[this.dpStop]: true});
+        if (attempt < 3) setTimeout(() => this._sendPartialStop(generation, attempt + 1), 300);
+    }
+
     _cancelPartialStop() {
+        this.partialPending = false;
+        this.partialGeneration++;
         if (this.partialStopTimer) {
             clearTimeout(this.partialStopTimer);
             this.partialStopTimer = null;

package/lib/TuyaCloudApi.js

@@ -214,6 +214,27 @@ class TuyaCloudApi {
         return (res && Array.isArray(res.result)) ? res.result : [];
     }
 
+    // Read the device's "thing shadow" properties. Like getStatus, but each item
+    // ALSO carries its numeric `dp_id` — which is exactly the id the LAN protocol
+    // uses to address that data-point. That mapping is what lets the plugin bridge
+    // a LAN-style (numeric DP) configuration to the cloud (string codes), and back,
+    // transparently — so the same accessory works over either transport.
+    //
+    // Returns an array of {code, dp_id, value} on success, or null when the
+    // endpoint isn't available (older projects, or the device-shadow API isn't
+    // authorised). Callers fall back to getStatus() in that case (code-only, no
+    // numeric mapping). Never throws.
+    //   Docs: https://developer.tuya.com/en/docs/cloud/116cc8bf6f?id=Kcp2kwfrpe719
+    async getShadowProperties(deviceId) {
+        try {
+            const res = await this.request('GET', `/v2.0/cloud/thing/${encodeURIComponent(deviceId)}/shadow/properties`);
+            return (res && res.result && Array.isArray(res.result.properties)) ? res.result.properties : null;
+        } catch (ex) {
+            this.log.debug(`Tuya Cloud shadow/properties unavailable for ${deviceId} (${ex.message}); falling back to /status.`);
+            return null;
+        }
+    }
+
     // Read the device record (name, product, and crucially `online`). Used to
     // learn whether the device is currently reachable. Returns the raw `result`
     // object or null. Requires the project to have the device-management API

package/lib/TuyaCloudDevice.js

@@ -51,6 +51,15 @@ class TuyaCloudDevice extends EventEmitter {
         this._stopped = false;
         this._retryTimer = null;
 
+        // Bidirectional data-point maps, learned from the device's thing-shadow on
+        // connect. They let this cloud transport (and the LAN+cloud TuyaDevice that
+        // may wrap it) translate between the LAN's numeric data-point ids and the
+        // cloud's string codes. Empty until the shadow is read; empty means
+        // "code-only" (no numeric bridge), which is still fully functional for a
+        // cloud-configured accessory.
+        this.codeByDpId = {}; // '20'        -> 'switch_led'
+        this.dpIdByCode = {}; // 'switch_led' -> '20'
+
         if (props.connect !== false) this._connect();
     }
 
@@ -63,12 +72,25 @@ class TuyaCloudDevice extends EventEmitter {
             return this.log.error(`${this.context.name}: Tuya Cloud is not configured (missing accessId/accessKey).`);
         }
 
+        // First connect only: stagger the initial read so a large install doesn't
+        // fire every device's OpenAPI call in the same instant (rate limits). The
+        // platform hands each device an increasing cloudStartDelay.
+        if (!this._staggered) {
+            this._staggered = true;
+            const delay = parseInt(this.context.cloudStartDelay) || 0;
+            if (delay > 0) {
+                await new Promise(resolve => { const t = setTimeout(resolve, delay); if (t.unref) t.unref(); });
+                if (this._stopped) return;
+            }
+        }
+
         try {
-            const status = await this.api.getStatus(this.context.id);
-            this.state = this._statusToState(status);
+            const props = await this._readInitialProperties();
+            this._learnDpMap(props);
+            this.state = this._propsToState(props);
             this.connected = await this._readOnline();
 
-            this._logDiscoveredCodes(status);
+            this._logDiscoveredCodes(props);
 
             this.emit('connect');
             // Accessories register their characteristics off the first 'change'.
@@ -132,23 +154,58 @@ class TuyaCloudDevice extends EventEmitter {
      *  State helpers
      * ------------------------------------------------------------------ */
 
-    // Convert a Tuya `[{code, value}]` status array into a flat { code: value }.
-    _statusToState(status) {
+    // Read the device's initial data-points. Prefer the thing-shadow (it carries
+    // the numeric dp_id alongside each code, so LAN<->cloud bridging works); fall
+    // back to the plain status endpoint (code+value only) when the shadow isn't
+    // available. Returns an array of {code, value, dp_id?}.
+    async _readInitialProperties() {
+        if (typeof this.api.getShadowProperties === 'function') {
+            const props = await this.api.getShadowProperties(this.context.id);
+            if (Array.isArray(props)) return props;
+        }
+        return this.api.getStatus(this.context.id);
+    }
+
+    // Learn the code <-> numeric dp_id mapping from a shadow-properties read.
+    _learnDpMap(props) {
+        (props || []).forEach(p => {
+            if (!p || typeof p.code !== 'string' || p.dp_id == null) return;
+            const dp = String(p.dp_id);
+            this.codeByDpId[dp] = p.code;
+            this.dpIdByCode[p.code] = dp;
+        });
+    }
+
+    // Index a data-point under BOTH its string code and (when known) its numeric
+    // dp id, so an accessory configured the LAN way (numeric) or the cloud way
+    // (code) both resolve. The dp id comes from the shadow item, or — for code-only
+    // realtime deltas — from the map learned on connect.
+    _indexInto(target, code, value, dpId) {
+        target[code] = value;
+        const dp = dpId != null ? String(dpId) : this.dpIdByCode[code];
+        if (dp != null) target[dp] = value;
+    }
+
+    // Build the dual-keyed state object from a properties/status array.
+    _propsToState(props) {
         const state = {};
-        (status || []).forEach(item => {
-            if (item && typeof item.code === 'string') state[item.code] = item.value;
+        (props || []).forEach(item => {
+            if (item && typeof item.code === 'string') {
+                this._indexInto(state, item.code, item.value, item.dp_id != null ? item.dp_id : item.dpId);
+            }
         });
         return state;
     }
 
     // Apply a fresh snapshot (initial / catch-up) or a realtime delta, diff it
     // against what we hold, and emit only what changed — exactly mirroring
-    // TuyaAccessory._change so accessories behave identically.
+    // TuyaAccessory._change so accessories behave identically. State is dual-keyed
+    // (code + numeric dp) so a LAN-style or cloud-style config both resolve.
     _applyStatus(status) {
-        const incoming = this._statusToState(status);
+        const incoming = this._propsToState(status);
         const changes = {};
-        Object.keys(incoming).forEach(code => {
-            if (incoming[code] !== this.state[code]) changes[code] = incoming[code];
+        Object.keys(incoming).forEach(key => {
+            if (incoming[key] !== this.state[key]) changes[key] = incoming[key];
         });
         if (Object.keys(changes).length) {
             this.state = {...this.state, ...incoming};
@@ -157,10 +214,13 @@ class TuyaCloudDevice extends EventEmitter {
         return changes;
     }
 
-    _logDiscoveredCodes(status) {
+    _logDiscoveredCodes(props) {
         try {
-            const list = (status || []).map(i => `${i.code}=${JSON.stringify(i.value)}`).join(', ');
-            this.log.info(`${this.context.name}: Tuya Cloud data-point codes → ${list || '(none reported)'}`);
+            const list = (props || []).map(i => {
+                const dp = i.dp_id != null ? i.dp_id : (i.dpId != null ? i.dpId : this.dpIdByCode[i.code]);
+                return `${i.code}${dp != null ? `(dp ${dp})` : ''}=${JSON.stringify(i.value)}`;
+            }).join(', ');
+            this.log.info(`${this.context.name}: Tuya Cloud data-points → ${list || '(none reported)'}`);
         } catch (_) { /* logging must never throw */ }
     }
 
@@ -185,7 +245,10 @@ class TuyaCloudDevice extends EventEmitter {
     update(dps) {
         if (!dps || typeof dps !== 'object') return true;
 
-        const commands = Object.keys(dps).map(code => ({code, value: dps[code]}));
+        // Keys may be numeric LAN dp ids (when a LAN-configured accessory falls
+        // back to the cloud) or string codes (a cloud-configured accessory); the
+        // commands API speaks codes, so translate via the learned map.
+        const commands = Object.keys(dps).map(key => ({code: this._toCode(key), value: dps[key]}));
         if (!commands.length) return true;
 
         if (!this.connected) {
@@ -204,6 +267,14 @@ class TuyaCloudDevice extends EventEmitter {
             });
     }
 
+    // Resolve a write key (a numeric LAN dp id or a string code) to the Tuya Cloud
+    // `code` the commands API expects. A numeric id with a known code is
+    // translated; anything else (already a code, or an unmapped id) is passed
+    // through unchanged.
+    _toCode(key) {
+        return this.codeByDpId[key] || key;
+    }
+
     /* ------------------------------------------------------------------ *
      *  Teardown (tidy; Homebridge doesn't strictly require it)
      * ------------------------------------------------------------------ */

package/lib/TuyaDevice.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const EventEmitter = require('events');
+const TuyaAccessory = require('./TuyaAccessory');
+const TuyaCloudDevice = require('./TuyaCloudDevice');
+
+/*
+ * TuyaDevice
+ * ----------
+ * The single `device` object every accessory now talks to. It presents the exact
+ * same minimal contract the accessories already rely on —
+ *
+ *   - `context`            device config (name, id, type, …)
+ *   - `state`              current data-points
+ *   - `connected`          boolean
+ *   - `_connect()`         start talking to the device
+ *   - `update(dps)`        write data-points
+ *   - 'connect' / 'change' events  (change → (changes, state))
+ *
+ * — but underneath it transparently spans BOTH transports:
+ *
+ *   - a LAN backend  (TuyaAccessory)   — the fast, private, local path
+ *   - a cloud backend (TuyaCloudDevice)— Tuya's internet path, used as a fallback
+ *
+ * Behaviour mirrors the official Tuya app: control goes over the LAN whenever the
+ * device is reachable there; if the LAN is down (or the device never appears on it
+ * — e.g. battery-powered "sleepy" units) it falls back to the cloud. Only when
+ * BOTH are unreachable does the device report disconnected, so the accessory shows
+ * "No Response". Accessories don't know or care which path is live.
+ *
+ * The one thing that differs between the transports is how a data-point is
+ * addressed: the LAN speaks numeric ids (1, 2, …), the cloud speaks string codes
+ * (switch_led, …). The cloud backend learns the id<->code map from the device's
+ * thing-shadow and keeps `state` keyed BOTH ways, so a configuration written for
+ * either transport resolves over the other. Writes are translated to whatever the
+ * live backend needs. The net effect: existing LAN configs gain a cloud fallback,
+ * and existing cloud configs gain LAN, with no config change.
+ */
+
+// When a LAN-primary device's cloud backend connects first but can't offer the
+// numeric data-point map (the device-shadow API isn't available), give the LAN a
+// short head start before letting the cloud drive the one-time characteristic
+// registration — so a numeric-DP config still registers against numeric keys.
+const LAN_REGISTRATION_GRACE_MS = 15000;
+
+class TuyaDevice extends EventEmitter {
+    constructor(props = {}) {
+        super();
+        // Several accessories attach their own 'change' listener on top of the one
+        // BaseAccessory uses; keep the default-listener guard from ever warning.
+        this.setMaxListeners(0);
+
+        this.log = props.log || console;
+
+        // A plain config object on `context`, mirroring the transport classes but
+        // without the live helper objects we were handed.
+        this.context = {...props};
+        delete this.context.log;
+        delete this.context.cloudApi;
+        delete this.context.messaging;
+
+        this.state = {};
+        this._stopped = false;
+        this._registered = false;       // has the first 'change' (registration) gone out?
+        this._connectEmitted = false;
+        this._lanGraceElapsed = false;
+
+        // LAN backend — created later, once an IP is known (see attachLan). A
+        // device with no local key can't speak the LAN protocol at all, so it is
+        // cloud-only and this stays null.
+        this.lan = null;
+
+        // Cloud backend — present whenever the platform handed us a shared cloud
+        // session and this device isn't opted out of it.
+        this.cloud = null;
+        if (props.cloudApi) {
+            this.cloud = new TuyaCloudDevice({
+                ...props,
+                cloudApi: props.cloudApi,
+                messaging: props.messaging,
+                log: this.log,
+                connect: false
+            });
+        }
+
+        if (props.connect !== false) this._connect();
+    }
+
+    // Reachable over either transport.
+    get connected() {
+        return !!((this.lan && this.lan.connected) || (this.cloud && this.cloud.connected));
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Lifecycle
+     * ------------------------------------------------------------------ */
+
+    _connect() {
+        if (this.cloud) {
+            this._wire(this.cloud, 'cloud');
+            this.cloud._connect();
+
+            // Safety net for the LAN-without-map registration guard above.
+            if (this.context.key) {
+                setTimeout(() => {
+                    this._lanGraceElapsed = true;
+                    if (!this._registered) this._onBackendChange();
+                }, LAN_REGISTRATION_GRACE_MS).unref?.();
+            }
+        }
+        // The LAN backend is attached by the platform via attachLan() once the
+        // device's IP is known (from discovery, or a configured `ip`), preserving
+        // the existing discovery timing.
+    }
+
+    // Bring up (or update) the LAN transport for a device whose IP is now known.
+    // `target` carries the {ip, version} learned from discovery; a configured
+    // version/forceVersion still take precedence as they always have.
+    attachLan(target = {}) {
+        if (this._stopped || this.lan) return;
+        if (!this.context.key) {
+            this.log.debug(`${this.context.name}: no local key; staying on the cloud only.`);
+            return;
+        }
+        if (!target.ip && !this.context.ip) return;
+
+        let version = this.context.version;
+        if (target.version) version = target.version;          // the device's broadcast wins…
+        if (this.context.forceVersion) version = this.context.forceVersion; // …but forceVersion wins all
+
+        this.lan = new TuyaAccessory({
+            ...this.context,
+            ip: target.ip || this.context.ip,
+            version,
+            log: this.log,
+            connect: false
+        });
+        this._wire(this.lan, 'lan');
+        this.lan._connect();
+    }
+
+    _wire(backend, which) {
+        backend.on('connect', () => this._onBackendConnect(which));
+        backend.on('change', () => this._onBackendChange(which));
+    }
+
+    _onBackendConnect(which) {
+        this.log.debug(`${this.context.name}: ${which} backend connected.`);
+        if (!this._connectEmitted) {
+            this._connectEmitted = true;
+            this.emit('connect');
+        }
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  State merge — LAN wins while it's up, cloud fills the rest / takes over
+     * ------------------------------------------------------------------ */
+
+    _merge() {
+        const merged = {};
+        if (this.cloud && this.cloud.connected) Object.assign(merged, this.cloud.state);
+        // LAN overlays the cloud while it's connected: it's the authoritative,
+        // freshest view for a device that's actually reachable locally.
+        if (this.lan && this.lan.connected) Object.assign(merged, this._lanStateDualKeyed());
+        return merged;
+    }
+
+    // LAN state is keyed by numeric dp id; mirror each value under its cloud code
+    // too (using the map the cloud backend learned), so a code-style config still
+    // resolves while the device is on the LAN.
+    _lanStateDualKeyed() {
+        const lanState = this.lan.state;
+        if (!this.cloud) return lanState;
+        const codeByDpId = this.cloud.codeByDpId;
+        const out = {...lanState};
+        for (const dp in lanState) {
+            const code = codeByDpId[dp];
+            if (code != null) out[code] = lanState[dp];
+        }
+        return out;
+    }
+
+    _onBackendChange(which) {
+        if (this._stopped) return;
+        if (!this._registered && !this._mayRegisterFrom(which)) return;
+
+        const merged = this._merge();
+        const changes = {};
+        Object.keys(merged).forEach(key => {
+            if (merged[key] !== this.state[key]) changes[key] = merged[key];
+        });
+
+        const first = !this._registered;
+        if (first || Object.keys(changes).length) {
+            this.state = {...this.state, ...merged};
+            this._registered = true;
+            // The first emit drives BaseAccessory's one-time characteristic
+            // registration; later emits carry only what actually changed.
+            this.emit('change', changes, this.state);
+        }
+    }
+
+    // Decide whether `which` backend may drive the one-time characteristic
+    // registration. LAN is always safe (numeric signature). The cloud is safe when
+    // the device is cloud-only (no local key), or once it has the numeric map (state
+    // is dual-keyed and so resolves a numeric-DP config), or once the LAN has been
+    // given its head start and didn't show up.
+    _mayRegisterFrom(which) {
+        if (which === 'lan') return true;
+        if (!this.context.key) return true;
+        if (this.cloud && Object.keys(this.cloud.codeByDpId).length) return true;
+        return this._lanGraceElapsed;
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Writes — LAN first, cloud as a fallback
+     * ------------------------------------------------------------------ */
+
+    update(dps) {
+        // Pure LAN (no cloud configured): byte-for-byte the legacy behaviour — a
+        // synchronous boolean, so the sync write helpers keep detecting failures.
+        if (!this.cloud) {
+            return this.lan ? this.lan.update(this._toLanDps(dps)) : false;
+        }
+        return this._updateWithFallback(dps);
+    }
+
+    async _updateWithFallback(dps) {
+        // Prefer the LAN while it's connected.
+        if (this.lan && this.lan.connected) {
+            if (this.lan.update(this._toLanDps(dps)) !== false) return true;
+            this.log.debug(`${this.context.name}: LAN write didn't go through; trying the cloud.`);
+        }
+        if (this.cloud && this.cloud.connected) {
+            return (await this.cloud.update(dps)) !== false;
+        }
+        // Cloud is down too — a last LAN attempt (it may have just dropped, and a
+        // buffered write is better than a guaranteed failure).
+        if (this.lan) return this.lan.update(this._toLanDps(dps)) !== false;
+        return false;
+    }
+
+    // Translate a write keyed by codes and/or numeric ids into the numeric ids the
+    // LAN protocol needs. Numeric ids pass straight through; a code with a known id
+    // is translated; an unmapped code is left as-is (TuyaAccessory.update will then
+    // simply ignore it, which is the safe degradation when no map is available).
+    _toLanDps(dps) {
+        if (!this.cloud || !dps || typeof dps !== 'object') return dps;
+        const dpIdByCode = this.cloud.dpIdByCode;
+        const out = {};
+        for (const key in dps) out[dpIdByCode[key] || key] = dps[key];
+        return out;
+    }
+
+    /* ------------------------------------------------------------------ *
+     *  Teardown (tidy; Homebridge doesn't strictly require it)
+     * ------------------------------------------------------------------ */
+
+    stop() {
+        this._stopped = true;
+        if (this.cloud && typeof this.cloud.stop === 'function') this.cloud.stop();
+        if (this.lan && typeof this.lan.stop === 'function') this.lan.stop();
+    }
+}
+
+module.exports = TuyaDevice;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.19",
-  "description": "A community-maintained Homebridge plugin for controlling Tuya devices locally over LAN. Includes new features, fixes, and updated device support.",
+  "version": "3.14.0-dev.21",
+  "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": {
     "test": "jest",