homebridge-tuya-plus 3.14.0-dev.40 → 3.14.0-dev.41

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,28 @@ 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);
+    }
+
+    // Control a device through the thing-model "send property" endpoint. Some
+    // fully-custom devices (e.g. gate controllers) have no standard instruction
+    // set at all — every /commands API, legacy or iot-03, answers 2008 for them —
+    // but the cloud still models them as thing-model properties (their shadow
+    // reads fine). Issuing those properties is how Tuya's own app drives such a
+    // device. Same [{code, value}, …] in; the body is {properties: "<json>"} where
+    // <json> is a JSON string of {code: value, …}.
+    //   Docs: https://developer.tuya.com/en/docs/cloud/c057ad5cfd?id=Kcp2kxdzftp91
+    async sendProperties(deviceId, commands) {
+        if (!Array.isArray(commands) || !commands.length) return true;
+        const properties = {};
+        commands.forEach(c => { properties[c.code] = c.value; });
+        const res = await this.request('POST', `/v2.0/cloud/thing/${encodeURIComponent(deviceId)}/shadow/properties/issue`, {properties: JSON.stringify(properties)});
         return !!(res && res.result);
     }
 

package/lib/TuyaCloudDevice.js

@@ -59,6 +59,22 @@ 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
+
+        // Per data-point code, the cloud control endpoint learned to work for it
+        // ('commands' or 'properties'). It's tracked per code, not per device,
+        // because one device can be mixed: some data-points live in its standard
+        // instruction set (driven by the iot-03 commands API) and others only in its
+        // thing model (driven by the property endpoint). Every code starts on the
+        // commands API — the one tinytuya and the official plugin use, so the
+        // best-understood for rate limits — and only a code the commands API rejects
+        // as unsupported (2008/2003) is moved to the thing-model endpoint.
+        // _propertiesTried bounds that probe to once per code so a genuinely
+        // uncontrollable data-point can't re-probe on every write.
+        this._codeMethod = {};
+        this._propertiesTried = new Set();
+        this._announcedProperties = false;
 
         // 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,15 +351,143 @@ class TuyaCloudDevice extends EventEmitter {
             return false;
         }
 
-        return this.api.sendCommands(this.context.id, commands)
-            .then(ok => {
-                if (!ok) this.log.warn(`${this.context.name}: Tuya Cloud rejected command ${JSON.stringify(commands)}`);
-                return ok;
-            })
-            .catch(ex => {
-                this.log.error(`${this.context.name}: cloud command failed: ${ex.message}`);
-                return false;
-            });
+        // 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._dispatch(sendable);
+    }
+
+    // Send a write, routing each data-point to the cloud endpoint it accepts. Codes
+    // go over the standard commands API unless we've learned they need the thing
+    // model, so the two groups can travel in parallel to their own endpoints. A
+    // device with both kinds (a normal switch plus a custom trigger) drives each
+    // correctly. Resolves true only if every group succeeded, false otherwise
+    // (never rejects), mirroring TuyaAccessory.update for the awaiting accessory.
+    async _dispatch(commands) {
+        const viaProperties = commands.filter(c => this._codeMethod[c.code] === 'properties');
+        const viaCommands = commands.filter(c => this._codeMethod[c.code] !== 'properties');
+
+        const [byCommands, byProperties] = await Promise.all([
+            this._sendGroup('commands', viaCommands),
+            this._sendGroup('properties', viaProperties)
+        ]);
+
+        if (byCommands.ok && byProperties.ok) {
+            this._lastWriteError = null;
+            return true;
+        }
+        this._reportWriteFailure(byCommands.error || byProperties.error);
+        return false;
+    }
+
+    // Send one group of codes over `method`, recording per code which endpoint
+    // worked. A commands group rejected as unsupported (2008/2003) is retried over
+    // the thing-model property endpoint — where a custom device's data-points live —
+    // but only for codes not already confirmed on commands or already tried there,
+    // so a confirmed code is never moved and an uncontrollable one can't re-probe on
+    // every write. Resolves to {ok, error}; never rejects.
+    async _sendGroup(method, codes) {
+        if (!codes.length) return {ok: true};
+
+        const res = await this._send(method, codes);
+        if (res.ok) return this._learn(codes, method);
+        if (method !== 'commands' || !this._isInstructionMismatch(res.error)) return res;
+
+        const fresh = codes.filter(c => this._codeMethod[c.code] !== 'commands' && !this._propertiesTried.has(c.code));
+        if (!fresh.length) return res;
+        fresh.forEach(c => this._propertiesTried.add(c.code));
+
+        this.log.debug(`${this.context.name}: the cloud command API rejected ${this._codesOf(fresh)} (${res.error}); trying the thing-model property endpoint.`);
+        const viaProperties = await this._send('properties', fresh);
+        if (!viaProperties.ok) {
+            this.log.debug(`${this.context.name}: the thing-model property endpoint also failed for ${this._codesOf(fresh)}: ${viaProperties.error}`);
+            return res;
+        }
+        if (!this._announcedProperties) {
+            this._announcedProperties = true;
+            this.log.info(`${this.context.name}: controlling some of this device's data-points over the Tuya thing-model property endpoint (they aren't in its standard instruction set).`);
+        }
+        return this._learn(fresh, 'properties');
+    }
+
+    // Invoke one control endpoint; resolves to {ok, error} and never rejects, so a
+    // missing-method mock or a network error can't escape the dispatch.
+    _send(method, commands) {
+        let call;
+        try {
+            call = method === 'properties'
+                ? this.api.sendProperties(this.context.id, commands)
+                : this.api.sendCommands(this.context.id, commands);
+        } catch (ex) {
+            return Promise.resolve({ok: false, error: ex && ex.message ? ex.message : String(ex)});
+        }
+        return Promise.resolve(call).then(
+            res => res !== false ? {ok: true} : {ok: false, error: `Tuya Cloud rejected ${JSON.stringify(commands)}`},
+            ex => ({ok: false, error: ex && ex.message ? ex.message : String(ex)})
+        );
+    }
+
+    _learn(codes, method) {
+        codes.forEach(c => { this._codeMethod[c.code] = method; });
+        return {ok: true};
+    }
+
+    _codesOf(commands) {
+        return commands.map(c => c.code).join(', ');
+    }
+
+    // True for the "this code/value isn't a valid command for this device" errors —
+    // command or value not support (2008) and function not support (2003) — which
+    // are what a device with no standard instruction set answers, and exactly the
+    // case the thing-model endpoint can still handle. Other failures (auth,
+    // permission, network) won't be helped by the fallback, so we don't probe.
+    _isInstructionMismatch(message) {
+        return /\bcode (2008|2003)\b|command or value not support|function not support/i.test(message || '');
+    }
+
+    // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.40",
+  "version": "3.14.0-dev.41",
   "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,35 @@ 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('sendProperties issues thing-model properties as a JSON-string body', async () => {
+        const api = ready();
+        let captured;
+        api._httpsRequest = async (method, path, headers, bodyStr) => {
+            captured = {method, path, body: JSON.parse(bodyStr)};
+            return {success: true, result: true};
+        };
+        const ok = await api.sendProperties('dev', [{code: 'wfh_close', value: true}]);
+        expect(ok).toBe(true);
+        expect(captured.method).toBe('POST');
+        expect(captured.path).toBe('/v2.0/cloud/thing/dev/shadow/properties/issue');
+        expect(captured.body).toEqual({properties: JSON.stringify({wfh_close: true})});
+    });
+
+    test('sendProperties short-circuits on an empty command list', async () => {
+        const api = ready();
+        api._httpsRequest = jest.fn();
+        await expect(api.sendProperties('dev', [])).resolves.toBe(true);
+        expect(api._httpsRequest).not.toHaveBeenCalled();
+    });
+
     test('getMqttConfig posts the expected body and returns the broker config', async () => {
         const api = ready();
         api.uid = 'UID';

package/test/TuyaCloudDevice.test.js

@@ -10,7 +10,8 @@ function makeApi(status = [{code: 'switch_1', value: false}, {code: 'battery_per
         isConfigured: () => true,
         getStatus: jest.fn().mockResolvedValue(status),
         getDeviceInfo: jest.fn().mockResolvedValue({online: true}),
-        sendCommands: jest.fn().mockResolvedValue(true)
+        sendCommands: jest.fn().mockResolvedValue(true),
+        sendProperties: jest.fn().mockResolvedValue(true)
     };
 }
 
@@ -151,6 +152,96 @@ 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}]);
+        expect(api.sendProperties).not.toHaveBeenCalled();
+    });
+
+    // A fully-custom device (e.g. a gate controller) is rejected by every /commands
+    // API with 2008; the plugin must fall back to the thing-model property endpoint
+    // on its own, with no configuration.
+    describe('automatic control-endpoint fallback', () => {
+        const gate = 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();
+            return {api, dev};
+        };
+
+        test('a 2008 from commands falls back to the thing-model property endpoint', async () => {
+            const {api, dev} = await gate();
+            api.sendCommands.mockRejectedValue(new Error('POST /v1.0/iot-03/devices/dev1/commands failed: command or value not support (code 2008)'));
+
+            await expect(dev.update({'102': true})).resolves.toBe(true);
+            expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'wfh_close', value: true}]);
+            expect(api.sendProperties).toHaveBeenCalledWith('dev1', [{code: 'wfh_close', value: true}]);
+        });
+
+        test('once the property endpoint works it is used directly (no repeat doomed command)', async () => {
+            const {api, dev} = await gate();
+            api.sendCommands.mockRejectedValue(new Error('command or value not support (code 2008)'));
+
+            await dev.update({'102': true}); // probes: commands → properties
+            await dev.update({'102': false}); // should go straight to properties
+            expect(api.sendCommands).toHaveBeenCalledTimes(1);
+            expect(api.sendProperties).toHaveBeenCalledTimes(2);
+        });
+
+        test('a non-instruction failure (network) does NOT probe the thing model', async () => {
+            const {api, dev} = await gate();
+            api.sendCommands.mockRejectedValue(new Error('request timed out'));
+
+            await expect(dev.update({'102': true})).resolves.toBe(false);
+            expect(api.sendProperties).not.toHaveBeenCalled();
+        });
+
+        test('the property fallback is probed only once when it also fails', async () => {
+            const {api, dev} = await gate();
+            api.sendCommands.mockRejectedValue(new Error('command or value not support (code 2008)'));
+            api.sendProperties.mockRejectedValue(new Error('command or value not support (code 2008)'));
+
+            await dev.update({'102': true});
+            await dev.update({'102': true});
+            expect(api.sendProperties).toHaveBeenCalledTimes(1);
+            expect(api.sendCommands).toHaveBeenCalledTimes(2);
+        });
+
+        // The crux: a single device with a normal DP (standard instruction set) and
+        // a custom DP (thing model only) must drive EACH over its own endpoint.
+        test('a mixed device routes each data-point to the endpoint it accepts', async () => {
+            const api = makeApi();
+            api.getShadowProperties = jest.fn().mockResolvedValue([
+                {code: 'switch_1', dp_id: 1, value: false},   // standard → commands
+                {code: 'wfh_open', dp_id: 101, value: false}  // custom → properties only
+            ]);
+            // The commands API accepts switch_1 but rejects any batch containing wfh_open.
+            api.sendCommands.mockImplementation((id, cmds) =>
+                cmds.some(c => c.code === 'wfh_open')
+                    ? Promise.reject(new Error('command or value not support (code 2008)'))
+                    : Promise.resolve(true));
+            const dev = makeDevice(api, null, {key: 'abc'});
+            await dev._connect();
+
+            await dev.update({'1': true});    // learns switch_1 → commands
+            await dev.update({'101': true});  // commands 2008 → learns wfh_open → properties
+
+            api.sendCommands.mockClear();
+            api.sendProperties.mockClear();
+
+            // A write touching both now splits: switch_1 over commands, wfh_open over properties.
+            await expect(dev.update({'1': false, '101': true})).resolves.toBe(true);
+            expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: false}]);
+            expect(api.sendProperties).toHaveBeenCalledWith('dev1', [{code: 'wfh_open', 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 +445,97 @@ 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);
+            api.sendProperties.mockRejectedValue(ex); // thing-model fallback can't rescue it either
+
+            await dev.update({'1': true}); // mapped → dispatched → rejected by both endpoints
+            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.sendProperties.mockRejectedValue(new Error('command or value not support (code 2008)')); // fallback can't rescue
+
+            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,15 @@ 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. That works for almost everything.
+
+Some **custom data-points** (e.g. a gate/garage controller's open/close/stop) aren't in the device's standard instruction set — `/commands` answers `2003`/`2008` for them — yet the cloud still models them as **thing-model properties** (their status reads fine, and the device acts on the same write over the LAN). For these, **you don't need to configure anything**: when a `/commands` write is rejected with `2008`/`2003`, the plugin automatically retries it through Tuya's thing-model endpoint (`POST /v2.0/cloud/thing/{id}/shadow/properties/issue`) — which is how Tuya's own app drives such a device — and remembers the working endpoint **per data-point**. So a device that mixes ordinary DPs (a switch) with custom ones (a trigger) drives each over the endpoint it accepts; the standard commands API is always tried first.
+
+If a write fails on **both** endpoints, the data-point is genuinely **report-only** for that device (its Tuya product defines it that way), which only the manufacturer can change — 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.