homebridge-tuya-plus 3.14.0-dev.18 → 3.14.0-dev.20

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/SimpleDimmerAccessory.js

@@ -25,20 +25,24 @@ class SimpleDimmerAccessory extends BaseAccessory {
         this.dpPower = this._getCustomDP(this.device.context.dpPower) || '1';
         this.dpBrightness = this._getCustomDP(this.device.context.dpBrightness) || this._getCustomDP(this.device.context.dp) || '2';
 
-        const characteristicOn = service.getCharacteristic(Characteristic.On)
+        this._characteristicOn = service.getCharacteristic(Characteristic.On)
             .updateValue(dps[this.dpPower])
             .onGet(() => this.getStateAsync(this.dpPower))
             .onSet(value => this.setStateAsync(this.dpPower, value));
 
-        const characteristicBrightness = service.getCharacteristic(Characteristic.Brightness)
+        this._characteristicBrightness = service.getCharacteristic(Characteristic.Brightness)
             .updateValue(this.convertBrightnessFromTuyaToHomeKit(dps[this.dpBrightness]))
             .onGet(() => this.getBrightness())
             .onSet(value => this.setBrightness(value));
 
+        this._registerChangeListener();
+    }
+
+    _registerChangeListener() {
         this.device.on('change', changes => {
-            if (changes.hasOwnProperty(this.dpPower) && characteristicOn.value !== changes[this.dpPower]) characteristicOn.updateValue(changes[this.dpPower]);
-            if (changes.hasOwnProperty(this.dpBrightness) && this.convertBrightnessFromHomeKitToTuya(characteristicBrightness.value) !== changes[this.dpBrightness])
-                characteristicBrightness.updateValue(this.convertBrightnessFromTuyaToHomeKit(changes[this.dpBrightness]));
+            if (changes.hasOwnProperty(this.dpPower) && this._characteristicOn.value !== changes[this.dpPower]) this._characteristicOn.updateValue(changes[this.dpPower]);
+            if (changes.hasOwnProperty(this.dpBrightness) && this.convertBrightnessFromHomeKitToTuya(this._characteristicBrightness.value) !== changes[this.dpBrightness])
+                this._characteristicBrightness.updateValue(this.convertBrightnessFromTuyaToHomeKit(changes[this.dpBrightness]));
         });
     }
 

package/lib/SimpleGarageDoorAccessory.js

@@ -197,7 +197,7 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         if (this.pendingCloseTimer) return;
         const isOpen = this._mapDpState(changes[this.dpState]);
         if (isOpen === null) {
-            this.log.info(`[SimpleGarageDoor] ${this.device.context.name}: ignoring unknown state DP value ${JSON.stringify(changes[this.dpState])}`);
+            this.log.debug(`[SimpleGarageDoor] ${this.device.context.name}: ignoring unknown state DP value ${JSON.stringify(changes[this.dpState])}`);
             return;
         }
         this._applyReportedState(isOpen);
@@ -266,7 +266,7 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
     // own, even mid-close. Abandon any pending stop-before-close.
     _sendOpen() {
         this._cancelPendingClose();
-        this.log.info(`[SimpleGarageDoor] ${this.device.context.name}: open (dp${this.dpOpen})`);
+        this.log.debug(`[SimpleGarageDoor] ${this.device.context.name}: open (dp${this.dpOpen})`);
         this.setMultiStateLegacyInBackground({[this.dpOpen]: true});
     }
 
@@ -278,19 +278,19 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         if (this.pendingCloseTimer) {
             // A stop-before-close is already running — don't restart it (and
             // push the close out) on a duplicate or retransmitted request.
-            this.log.info(`[SimpleGarageDoor] ${name}: close ignored — a stop-before-close is already running`);
+            this.log.debug(`[SimpleGarageDoor] ${name}: close ignored — a stop-before-close is already running`);
             return;
         }
         if (this._isStopped()) {
-            this.log.info(`[SimpleGarageDoor] ${name}: close (dp${this.dpClose}) — gate already stopped`);
+            this.log.debug(`[SimpleGarageDoor] ${name}: close (dp${this.dpClose}) — gate already stopped`);
             this.setMultiStateLegacyInBackground({[this.dpClose]: true});
             return;
         }
-        this.log.info(`[SimpleGarageDoor] ${name}: stop-before-close — stop (dp${this.dpStop}) now, close (dp${this.dpClose}) in ${this.stopBeforeCloseMs}ms`);
+        this.log.debug(`[SimpleGarageDoor] ${name}: stop-before-close — stop (dp${this.dpStop}) now, close (dp${this.dpClose}) in ${this.stopBeforeCloseMs}ms`);
         this.setMultiStateLegacyInBackground({[this.dpStop]: true});
         this.pendingCloseTimer = setTimeout(() => {
             this.pendingCloseTimer = null;
-            this.log.info(`[SimpleGarageDoor] ${name}: stop-before-close — firing close (dp${this.dpClose})`);
+            this.log.debug(`[SimpleGarageDoor] ${name}: stop-before-close — firing close (dp${this.dpClose})`);
             this.setMultiStateLegacyInBackground({[this.dpClose]: true});
         }, this.stopBeforeCloseMs);
     }
@@ -323,15 +323,15 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
             // Re-entrant press while a partial is already armed (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.info(`[SimpleGarageDoor] ${name}: partial press ignored — a partial open is already running`);
+            this.log.debug(`[SimpleGarageDoor] ${name}: partial press ignored — a partial open is already running`);
             return;
         }
 
-        this.log.info(`[SimpleGarageDoor] ${name}: partial open — opening, will stop in ${this.partialOpenMs}ms`);
+        this.log.debug(`[SimpleGarageDoor] ${name}: partial open — opening, will stop in ${this.partialOpenMs}ms`);
         this._applyTarget(Characteristic.TargetDoorState.OPEN);
         this.partialStopTimer = setTimeout(() => {
             this.partialStopTimer = null;
-            this.log.info(`[SimpleGarageDoor] ${name}: partial open — firing stop (dp${this.dpStop})`);
+            this.log.debug(`[SimpleGarageDoor] ${name}: partial open — firing stop (dp${this.dpStop})`);
             this.setMultiStateLegacyInBackground({[this.dpStop]: true});
         }, this.partialOpenMs);
     }

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;