homebridge-tuya-plus 3.14.0-dev.37 → 3.14.0-dev.39

package/AGENTS.md

@@ -146,10 +146,9 @@ optional, off-by-default flags read through `_debugConfig()` and coerced with
   `cloud` block to be useful).
 - `debug.logCloudHttp` — trace every Tuya Cloud HTTP request/response (method,
   path, headers, body, status, response) at `debug`, with all credentials
-  (token, signature, password, access key/id, uid) redacted. Use it to see
-  exactly what a failing `POST …/commands` sent and how the cloud replied (e.g.
-  the `code`/`value` behind a `2008`). Verbose and per-request — keep it off in
-  normal operation, and remember Homebridge debug logging must be on to see it.
+  (token, signature, password, access key/id, uid) redacted. Verbose and
+  per-request — keep it off in normal operation, and remember Homebridge
+  debug logging must be on to see it.
 
 ## Git & PR workflow
 

package/lib/TuyaCloudApi.js

@@ -218,8 +218,12 @@ class TuyaCloudApi {
     }
 
     // Read every reported data-point in one call → array of {code, value}.
+    // Uses the current iot-03 device API, not the legacy /v1.0/devices/* set: the
+    // legacy endpoints answer 2003 ("function not support") for devices they don't
+    // model, where iot-03 works. This is the same family tinytuya and the official
+    // Tuya Homebridge plugin use throughout.
     async getStatus(deviceId) {
-        const res = await this.request('GET', `/v1.0/devices/${encodeURIComponent(deviceId)}/status`);
+        const res = await this.request('GET', `/v1.0/iot-03/devices/${encodeURIComponent(deviceId)}/status`);
         return (res && Array.isArray(res.result)) ? res.result : [];
     }
 
@@ -253,10 +257,12 @@ class TuyaCloudApi {
         return (res && res.result && typeof res.result === 'object') ? res.result : null;
     }
 
-    // Issue one or more commands: [{code, value}, …].
+    // Issue one or more commands: [{code, value}, …]. Uses the current iot-03
+    // device-control endpoint (the legacy /v1.0/devices/{id}/commands answers 2008
+    // for devices it doesn't model), matching tinytuya and the official plugin.
     async sendCommands(deviceId, commands) {
         if (!Array.isArray(commands) || !commands.length) return true;
-        const res = await this.request('POST', `/v1.0/devices/${encodeURIComponent(deviceId)}/commands`, {commands});
+        const res = await this.request('POST', `/v1.0/iot-03/devices/${encodeURIComponent(deviceId)}/commands`, {commands});
         return !!(res && res.result);
     }
 

package/lib/TuyaCloudDevice.js

@@ -59,6 +59,8 @@ class TuyaCloudDevice extends EventEmitter {
         this._retryTimer = null;
         this._retryDelay = 0;          // current connect-retry backoff (ms); grows on repeated failure
         this._lastConnectError = null; // last surfaced connect error, so identical repeats stay quiet
+        this._lastWriteError = null;   // last surfaced command-failure message, so identical repeats stay quiet
+        this._warnedNoCloudCode = false; // surfaced the "data-point has no cloud code" note once
 
         // Bidirectional data-point maps, learned from the device's thing-shadow on
         // connect. They let this cloud transport (and the LAN+cloud TuyaDevice that
@@ -335,17 +337,66 @@ class TuyaCloudDevice extends EventEmitter {
             return false;
         }
 
-        return this.api.sendCommands(this.context.id, commands)
+        // Split off data-points we couldn't translate to a Tuya Cloud code: their
+        // "code" is still a numeric LAN dp id (e.g. '1'), which the commands API
+        // can't address — it would always answer "command or value not support
+        // (2008)". This is the missing-dp-map case (the device-shadow API that
+        // carries the id→code mapping isn't authorised for the project), so don't
+        // fire a doomed command; explain it once instead.
+        const sendable = [], undeliverable = [];
+        commands.forEach(c => (this._isUntranslatedDpId(c.code) ? undeliverable : sendable).push(c));
+        if (undeliverable.length) this._reportUndeliverableWrite(undeliverable);
+        if (!sendable.length) return false;
+
+        return this.api.sendCommands(this.context.id, sendable)
             .then(ok => {
-                if (!ok) this.log.warn(`${this.context.name}: Tuya Cloud rejected command ${JSON.stringify(commands)}`);
+                if (ok) this._lastWriteError = null;
+                else this.log.warn(`${this.context.name}: Tuya Cloud rejected command ${JSON.stringify(sendable)}`);
                 return ok;
             })
             .catch(ex => {
-                this.log.error(`${this.context.name}: cloud command failed: ${ex.message}`);
+                this._reportWriteFailure(ex.message);
                 return false;
             });
     }
 
+    // A Tuya Cloud data-point is addressed by a string "code" (e.g. 'switch',
+    // 'temp_set'); a code that is all digits is really a numeric LAN dp id that
+    // _toCode couldn't translate (no map learned), which the cloud can't address.
+    _isUntranslatedDpId(code) {
+        return /^\d+$/.test(code);
+    }
+
+    // Surfaced once: the cloud can't address these data-points because the numeric
+    // id→code map was never learned (the device-shadow/thing-model API isn't
+    // authorised for this project — the same gap that makes shadow/properties
+    // return "No space permission"). Mirrors the connect-failure dedup: one
+    // actionable line, then quiet at debug. Stays harmless (debug) while the device
+    // is reachable over the LAN, since the cloud is only a fallback there.
+    _reportUndeliverableWrite(commands) {
+        const ids = commands.map(c => c.code).join(', ');
+        if (this._warnedNoCloudCode) {
+            return this.log.debug(`${this.context.name}: cloud write skipped — no Tuya Cloud code for data-point(s) ${ids}.`);
+        }
+        this._warnedNoCloudCode = true;
+        const lanReachable = !!(this.isLanConnected && this.isLanConnected());
+        const level = lanReachable ? 'debug' : (this.context.key ? 'warn' : 'error');
+        this.log[level](`${this.context.name}: can't control this device over the Tuya Cloud — its data-points are addressed by numeric id (${ids}) but the cloud only accepts string "codes", so the command would be rejected ("command or value not support"). That id→code mapping is read from the device-shadow API, which isn't authorised for this cloud project ("No space permission"); authorise it (and add the device to the project's space), or set the accessory's dp* options to cloud codes. The device still works over the LAN.`);
+    }
+
+    // A genuine command failure (the cloud was reached but rejected/errored).
+    // Deduped like the connect path — surfaced once, identical repeats drop to
+    // debug — with the level matched to severity: a LAN-capable device is only
+    // momentarily off the LAN (warn), a cloud-only one is stuck until it clears
+    // (error). _lastWriteError is cleared on the next successful command.
+    _reportWriteFailure(message) {
+        if (message === this._lastWriteError) {
+            return this.log.debug(`${this.context.name}: cloud command still failing: ${message}`);
+        }
+        this._lastWriteError = message;
+        this.log[this.context.key ? 'warn' : 'error'](`${this.context.name}: cloud command failed: ${message}`);
+    }
+
     // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.37",
+  "version": "3.14.0-dev.39",
   "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/TuyaCloudApi.test.js

@@ -173,7 +173,7 @@ describe('TuyaCloudApi — endpoints', () => {
         const ok = await api.sendCommands('dev', [{code: 'switch_1', value: true}]);
         expect(ok).toBe(true);
         expect(captured.method).toBe('POST');
-        expect(captured.path).toBe('/v1.0/devices/dev/commands');
+        expect(captured.path).toBe('/v1.0/iot-03/devices/dev/commands');
         expect(captured.body).toEqual({commands: [{code: 'switch_1', value: true}]});
     });
 
@@ -184,6 +184,14 @@ describe('TuyaCloudApi — endpoints', () => {
         expect(api._httpsRequest).not.toHaveBeenCalled();
     });
 
+    test('getStatus reads from the iot-03 device endpoint', async () => {
+        const api = ready();
+        let path;
+        api._httpsRequest = async (method, p) => { path = p; return {success: true, result: []}; };
+        await api.getStatus('dev');
+        expect(path).toBe('/v1.0/iot-03/devices/dev/status');
+    });
+
     test('getMqttConfig posts the expected body and returns the broker config', async () => {
         const api = ready();
         api.uid = 'UID';

package/test/TuyaCloudDevice.test.js

@@ -151,6 +151,16 @@ describe('TuyaCloudDevice', () => {
         expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: true}]);
     });
 
+    test('a translated write is dispatched to the (iot-03) commands API', async () => {
+        const api = makeApi();
+        api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'wfh_close', dp_id: 102, value: false}]);
+        const dev = makeDevice(api, null, {key: 'abc'});
+        await dev._connect();
+
+        await dev.update({'102': true});
+        expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'wfh_close', value: true}]);
+    });
+
     test('realtime code-only deltas are mirrored to numeric ids via the learned map', async () => {
         const api = makeApi();
         api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'switch_1', dp_id: 1, value: false}]);
@@ -354,4 +364,95 @@ describe('TuyaCloudDevice', () => {
             }
         });
     });
+
+    describe('write-failure handling (no log spam)', () => {
+        afterEach(() => jest.restoreAllMocks());
+
+        // A LAN-style accessory (numeric dps) over a cloud project that never
+        // learned the id→code map: the write can't be addressed, so it must not be
+        // fired (it would always be a 2008), and the cause is surfaced just once.
+        test('a numeric write with no learned code map is skipped, not sent, and surfaced once', async () => {
+            const api = makeApi(); // /status only → no dp map
+            const dev = makeDevice(api, null, {key: 'abc'}); // LAN-capable, LAN down here
+            await dev._connect();
+            expect(dev.codeByDpId).toEqual({});
+
+            const warn = jest.spyOn(log, 'warn');
+            const debug = jest.spyOn(log, 'debug');
+
+            expect(dev.update({'1': true})).toBe(false);
+            expect(api.sendCommands).not.toHaveBeenCalled();
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain('over the Tuya Cloud');
+
+            dev.update({'1': true}); // identical → quiet at debug, still not sent
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(debug).toHaveBeenCalledWith(expect.stringContaining('cloud write skipped'));
+            expect(api.sendCommands).not.toHaveBeenCalled();
+        });
+
+        test('the undeliverable-write note is harmless (debug) while the device is reachable over the LAN', async () => {
+            const dev = makeDevice(makeApi(), null, {key: 'abc', isLanConnected: () => true});
+            await dev._connect();
+            const warn = jest.spyOn(log, 'warn');
+            const debug = jest.spyOn(log, 'debug');
+
+            expect(dev.update({'1': true})).toBe(false);
+            expect(warn).not.toHaveBeenCalled();
+            expect(debug).toHaveBeenCalledWith(expect.stringContaining('over the Tuya Cloud'));
+        });
+
+        test('a cloud-only device (no key) surfaces the undeliverable write at error level', async () => {
+            const dev = makeDevice(makeApi()); // no key → cloud is the only path
+            await dev._connect();
+            const error = jest.spyOn(log, 'error');
+            const warn = jest.spyOn(log, 'warn');
+
+            expect(dev.update({'1': true})).toBe(false);
+            expect(warn).not.toHaveBeenCalled();
+            expect(error).toHaveBeenCalledTimes(1);
+        });
+
+        // A genuinely dispatched command that the cloud rejects (e.g. a real 2008
+        // on a mapped code): surface once, then suppress identical repeats to debug.
+        test('a repeated cloud command failure is surfaced once then suppressed to debug', async () => {
+            const api = makeApi();
+            api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'switch_1', dp_id: 1, value: false}]);
+            const dev = makeDevice(api, null, {key: 'abc'});
+            await dev._connect();
+
+            const warn = jest.spyOn(log, 'warn');
+            const debug = jest.spyOn(log, 'debug');
+            const ex = new Error('POST /v1.0/iot-03/devices/dev1/commands failed: command or value not support (code 2008)');
+            api.sendCommands.mockRejectedValue(ex);
+
+            await dev.update({'1': true}); // mapped → dispatched → rejected
+            expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: true}]);
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain('code 2008');
+
+            await dev.update({'1': true}); // identical failure → quiet
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(debug).toHaveBeenCalledWith(expect.stringContaining('still failing'));
+        });
+
+        test('a command failure re-surfaces after an intervening success', async () => {
+            const api = makeApi();
+            api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'switch_1', dp_id: 1, value: false}]);
+            const dev = makeDevice(api, null, {key: 'abc'});
+            await dev._connect();
+            const warn = jest.spyOn(log, 'warn');
+
+            api.sendCommands.mockRejectedValueOnce(new Error('command or value not support (code 2008)'));
+            await dev.update({'1': true});
+            expect(warn).toHaveBeenCalledTimes(1);
+
+            api.sendCommands.mockResolvedValueOnce(true); // success clears the dedup
+            await dev.update({'1': true});
+
+            api.sendCommands.mockRejectedValueOnce(new Error('command or value not support (code 2008)'));
+            await dev.update({'1': true});
+            expect(warn).toHaveBeenCalledTimes(2);
+        });
+    });
 });

package/wiki/Tuya-Cloud-Setup.md

@@ -69,3 +69,13 @@ Add a **top-level `cloud` block** with your credentials:
 ### Security note
 
 Your **Access Secret** and app password are sensitive. Keep them only in your Homebridge `config.json`. If you ever share a config for support, redact them.
+
+## Troubleshooting
+
+### A device reads fine over the cloud but won't accept commands (`command or value not support`, code `2008` / `2003`)
+
+The plugin controls devices through Tuya's current **`iot-03`** device API (`POST /v1.0/iot-03/devices/{id}/commands`), the same one tinytuya and the official Tuya Homebridge plugin use. Tuya's older `/v1.0/devices/*` endpoints answer `2003` (*function not support*) or `2008` for devices they don't fully model — using `iot-03` avoids that for the vast majority of devices.
+
+If a write still fails with `2008`/`2003` on `iot-03`, the data-point is genuinely not cloud-controllable for that device: its Tuya product defines the DP as **report-only** (it shows up in status but can't be commanded), even though the device acts on it over the LAN. That can only be changed by the device's manufacturer in the Tuya cloud — there's no cloud workaround. Such devices still work normally over the **LAN**; only the cloud fallback can't drive them.
+
+The undocumented `debug.logCloudHttp` switch logs the full (credential-redacted) request/response for every cloud call if you want to see exactly what was sent and how the cloud replied.