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

package/test/index.test.js

@@ -0,0 +1,141 @@
+'use strict';
+
+// Mock every module that would touch the network or HAP, so we can exercise the
+// platform's orchestration (cloud-session setup, per-device cloud policy, and
+// discovery -> attachLan routing) in isolation.
+jest.mock('../lib/TuyaDevice', () => jest.fn().mockImplementation(function(props) {
+    this.context = {...props};
+    this.cloud = props.cloudApi ? {} : null; // truthy iff a shared cloud session was handed in
+    this.attachLan = jest.fn();
+    this._connect = jest.fn();
+}));
+jest.mock('../lib/TuyaAccessory', () => jest.fn().mockImplementation(function(props) {
+    this.context = {...props};
+    this._connect = jest.fn();
+}));
+jest.mock('../lib/TuyaCloudApi', () => jest.fn().mockImplementation(function(cfg) {
+    this.endpoint = 'https://openapi.example.com';
+    this.cfg = cfg;
+}));
+jest.mock('../lib/TuyaCloudMessaging', () => jest.fn().mockImplementation(function() {}));
+jest.mock('../lib/TuyaDiscovery', () => ({
+    start: jest.fn(function() { return this; }),
+    on: jest.fn(function() { return this; })
+}));
+
+const TuyaDevice = require('../lib/TuyaDevice');
+const TuyaCloudApi = require('../lib/TuyaCloudApi');
+const TuyaCloudMessaging = require('../lib/TuyaCloudMessaging');
+const TuyaDiscovery = require('../lib/TuyaDiscovery');
+
+const makeHap = () => ({
+    Characteristic: class { setProps() { return this; } getDefaultValue() { return 0; } },
+    Formats: {FLOAT: 'float', UINT32: 'uint32', UINT16: 'uint16'},
+    Perms: {READ: 'pr', NOTIFY: 'ev', WRITE: 'pw'},
+    Categories: {OTHER: 1, SWITCH: 8, SPRINKLER: 28},
+    Service: {AccessoryInformation: {UUID: '3E'}},
+    uuid: {generate: s => 'uuid:' + s}
+});
+
+// Load the platform factory and capture the registered platform class.
+const factory = require('../index');
+function getPlatformClass() {
+    let cls;
+    factory({
+        platformAccessory: function() {},
+        hap: makeHap(),
+        registerPlatform: (pluginName, platformName, c) => { cls = c; }
+    });
+    return cls;
+}
+
+function makeLog() {
+    const log = jest.fn();
+    log.info = jest.fn(); log.warn = jest.fn(); log.error = jest.fn(); log.debug = jest.fn();
+    return log;
+}
+
+function makeApi() {
+    return {hap: makeHap(), on: jest.fn(), registerPlatformAccessories: jest.fn()};
+}
+
+function run(config) {
+    const Platform = getPlatformClass();
+    const platform = new Platform(makeLog(), config, makeApi());
+    platform.addAccessory = jest.fn(); // bypass HAP accessory creation
+    platform.discoverDevices();
+    return platform;
+}
+
+const propsFor = id => {
+    const call = TuyaDevice.mock.calls.find(c => c[0].id === id);
+    return call && call[0];
+};
+const instanceFor = id => TuyaDevice.mock.instances.find(i => i.context && i.context.id === id);
+
+const SW = (extra = {}) => ({id: 'bf11111111111111', key: 'k1', type: 'switch', name: 'Switch', ...extra});
+// A keyless device can't speak the LAN protocol, so it is cloud-only.
+const SLEEPY = (extra = {}) => ({id: 'bf22222222222222', type: 'irrigationsystem', name: 'Sprinklers', ...extra});
+const CLOUD = {accessId: 'aid', accessKey: 'akey', region: 'eu'};
+
+// discoverDevices schedules a long discovery-timeout timer; fake timers keep it
+// from holding the event loop open after the tests finish.
+beforeEach(() => { jest.clearAllMocks(); jest.useFakeTimers(); });
+afterEach(() => { jest.useRealTimers(); });
+
+describe('TuyaLan — cloud session setup', () => {
+    test('no cloud config → no session, devices are pure-LAN', () => {
+        run({devices: [SW()]});
+        expect(TuyaCloudApi).not.toHaveBeenCalled();
+        expect(propsFor('bf11111111111111').cloudApi).toBeUndefined();
+    });
+
+    test('a top-level cloud block creates the single shared session', () => {
+        run({cloud: CLOUD, devices: [SW()]});
+        expect(TuyaCloudApi).toHaveBeenCalledTimes(1);
+        expect(TuyaCloudApi.mock.calls[0][0]).toMatchObject({accessId: 'aid', accessKey: 'akey', region: 'eu'});
+        expect(TuyaCloudMessaging).toHaveBeenCalledTimes(1);
+    });
+
+    test('realtime:false skips the MQTT session', () => {
+        run({cloud: {...CLOUD, realtime: false}, devices: [SW()]});
+        expect(TuyaCloudApi).toHaveBeenCalledTimes(1);
+        expect(TuyaCloudMessaging).not.toHaveBeenCalled();
+    });
+});
+
+describe('TuyaLan — cloud participation', () => {
+    test('with a session, every device shares the one global fallback', () => {
+        run({cloud: CLOUD, devices: [SW(), SLEEPY()]});
+        expect(propsFor('bf11111111111111').cloudApi).toBeDefined(); // LAN device, cloud fallback
+        expect(propsFor('bf22222222222222').cloudApi).toBeDefined(); // keyless, cloud-only
+    });
+
+    test('without a session, no device gets a cloud backend', () => {
+        run({devices: [SW()]});
+        expect(propsFor('bf11111111111111').cloudApi).toBeUndefined();
+    });
+});
+
+describe('TuyaLan — discovery routing', () => {
+    test('only keyed devices are discovered; keyless ones are cloud-only', () => {
+        run({cloud: CLOUD, devices: [SW(), SLEEPY()]});
+        expect(TuyaDiscovery.start).toHaveBeenCalledTimes(1);
+        expect(TuyaDiscovery.start.mock.calls[0][0].ids).toEqual(['bf11111111111111']);
+    });
+
+    test('a discovered device is handed its LAN target via attachLan', () => {
+        run({cloud: CLOUD, devices: [SW()]});
+        // capture the 'discover' handler registered on the discovery emitter
+        const onDiscover = TuyaDiscovery.on.mock.calls.find(c => c[0] === 'discover');
+        expect(onDiscover).toBeDefined();
+        onDiscover[1]({id: 'bf11111111111111', ip: '10.0.0.7', version: '3.3'});
+        const inst = instanceFor('bf11111111111111');
+        expect(inst.attachLan).toHaveBeenCalledWith({ip: '10.0.0.7', version: '3.3'});
+    });
+
+    test('a cloud-only configuration starts no LAN discovery', () => {
+        run({cloud: CLOUD, devices: [SLEEPY()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+    });
+});

package/wiki/Supported-Device-Types.md

@@ -353,7 +353,7 @@ These are switches that allow turning on and off, and dimming. Two distinct type
 
 The following options apply to `WledDimmer` only (they are ignored by `SimpleDimmer`):
 
-- `syncBrightnessToWled`: set to the WLED device IP (e.g. "192.168.1.50" or "192.168.1.50:80") to sync HomeKit brightness changes directly to WLED over HTTP, keeping the Tuya dimmer at 100%.
+- `syncBrightnessToWled`: set to the WLED device IP (e.g. "192.168.1.50" or "192.168.1.50:80") to sync HomeKit brightness changes directly to WLED over HTTP, keeping the Tuya dimmer at 100%. This talks to the WLED controller directly on your **LAN**, independently of how the Tuya dimmer is reached — so if the Tuya dimmer is ever on the cloud fallback (because the LAN is down), the WLED sync is best-effort and may not go through until the LAN is back.
 - `presetEffects`: array of effect configs to expose as switches in HomeKit (each turns on a WLED fx preset, optionally with staticColor).
 
 ```json5
@@ -500,9 +500,10 @@ external stop, where close is accepted immediately), a close is sent as
     /* Optional. If set, exposes an extra stateful switch that mirrors
        whether the gate is currently open in HomeKit's view. Tapping it
        ON triggers a partial-open: the gate opens and then stops itself
-       this many milliseconds later, leaving the gate partially open.
-       Tapping it OFF triggers a standard full close. Useful for letting
-       someone pass through briefly. Leave unset to skip the switch. */
+       this many milliseconds after it actually starts moving, leaving the
+       gate partially open. Tapping it OFF triggers a standard full close.
+       Useful for letting someone pass through briefly. Leave unset to skip
+       the switch. */
     "partialOpenMs": 2000,
 
     /* Optional. Exposes extra Force Open and Force Close momentary

package/wiki/Tuya-Cloud-Setup.md

@@ -1,10 +1,12 @@
 # Tuya Cloud Setup
 
-This plugin is **LAN-first** — almost every Tuya device is controlled locally. But a few devices **cannot** be reached over the LAN at all:
+This plugin is **LAN-first** — every Tuya device is controlled locally whenever it can be. Adding your Tuya Cloud credentials turns the cloud into a **transparent fallback for every device**: each accessory tries the LAN first, and only falls back to the cloud when the device can't be reached locally. It's **opt-in** (nothing happens unless you add credentials) and **local stays the preferred path**.
 
-> Battery-powered **"sleepy"** devices — most notably multi-zone **irrigation / faucet timers** — sleep almost all the time to save battery and only ever connect *outbound* to Tuya's cloud (over MQTT) for a brief moment when they wake. They never keep the local port open and never answer LAN discovery, so the local protocol can't reach them. (Tuya's own developer docs state LAN control is unavailable in low-power mode.)
+It helps in two situations:
 
-For these devices the plugin can talk to the **Tuya Cloud** instead. It is **opt-in, per device** — your other devices stay 100% local.
+> **Devices that are never on the LAN.** Battery-powered **"sleepy"** devices — most notably multi-zone **irrigation / faucet timers** — sleep almost all the time to save battery and only ever connect *outbound* to Tuya's cloud (over MQTT) for a brief moment when they wake. They never keep the local port open and never answer LAN discovery, so the local protocol can't reach them. (Tuya's own developer docs state LAN control is unavailable in low-power mode.)
+
+> **Devices that occasionally drop off the LAN.** If a normally-local device sometimes shows "No Response" in HomeKit, the cloud fallback quietly covers those moments — local control still runs first.
 
 * Initial state + control go through the Tuya OpenAPI (signed HTTPS).
 * Live updates (including physical button presses) arrive over Tuya's **MQTT** message service — no polling.
@@ -42,7 +44,9 @@ Still in the project: **Devices → Link App Account → Add App Account**, then
 
 ## 5. Configure the plugin
 
-Add a **top-level `cloud` block** with your credentials, and set **`"cloud": true`** on the device. There are two project styles:
+Add a **top-level `cloud` block** with your credentials. That's all that's needed — every device then tries the LAN first and uses the cloud as a backup.
+
+A device that is **never** reachable on the LAN (a battery-powered "sleepy" timer) simply has **no local `key`**: without one it can't speak the LAN protocol, so the plugin reaches it through the cloud session. There are two project styles:
 
 ### Smart Home project (recommended — what most people have)
 
@@ -65,8 +69,8 @@ Authenticates as your app account (username/password), so it sees exactly the de
             "name": "Garden Irrigation",
             "type": "IrrigationSystem",
             "id": "bfae6739xxxxxxxxxxxxxx",      // the cloud Device ID
-            "cloud": true,
             "valveCount": 4
+            // no "key" -> this device is reached over the cloud
         }
     ]
 }
@@ -84,36 +88,18 @@ If you created a **Custom** project (devices linked by QR to the project's asset
 }
 ```
 
-### Per-device credentials (optional)
-
-Instead of (or in addition to) the platform block, a device can carry its own credentials — handy if different devices live in different Tuya projects:
-
-```json5
-{
-    "name": "Garden Irrigation",
-    "type": "IrrigationSystem",
-    "id": "bfae6739xxxxxxxxxxxxxx",
-    "cloud": {
-        "accessId": "…",
-        "accessKey": "…",
-        "region": "eu",
-        "username": "…",
-        "password": "…",
-        "countryCode": "48"
-    }
-}
-```
-
-> No local `key` is needed for cloud devices — the cloud authenticates with your project credentials.
+> There is one global session. The plugin doesn't support per-device cloud credentials or multiple Tuya accounts — put your credentials in the single top-level `cloud` block. A cloud-only device just omits its local `key`.
 
 ---
 
-## Data-points are addressed by "code" on the cloud
+## Data-points: numbers on the LAN, codes on the cloud
+
+Over the LAN, data-points are numbered (1, 2, …). Over the **cloud** they're named **codes** (e.g. `switch_1`, `battery_percentage`). You normally don't need to care which is which: when the cloud session connects, the plugin reads the device's *thing shadow*, which lists both the code **and** the numeric id for each data-point, and learns the mapping. From then on a configuration written either way works over either transport — a numeric-DP config falls back to the cloud, and a code-based config works on the LAN.
 
-Over the LAN, data-points are numbered (1, 2, …). Over the **cloud** they're named **codes** (e.g. `switch_1`, `battery_percentage`). When a cloud device connects, the plugin **logs the exact codes** it reports, e.g.:
+When a cloud device connects, the plugin **logs the data-points** it reports (code and numeric id), e.g.:
 
 ```
-Garden Irrigation: Tuya Cloud data-point codes → switch_1=false, switch_2=false, switch_3=false, switch_4=false, countdown_1=0, …, battery_percentage=99
+Garden Irrigation: Tuya Cloud data-points → switch_1(dp 1)=false, switch_2(dp 2)=false, switch_3(dp 3)=false, switch_4(dp 4)=false, countdown_1(dp 5)=0, …, battery_percentage(dp 46)=99
 ```
 
 The `IrrigationSystem` defaults already match the common 4-zone layout (`switch_1`…`switch_4`, battery `battery_percentage`). If your device differs, use the logged codes: