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

package/test/TuyaDevice.test.js

@@ -0,0 +1,252 @@
+'use strict';
+
+// The LAN backend opens real TCP sockets; stub it so attachLan() can be tested
+// without touching the network. Cloud backend stays real (it's inert with
+// connect:false).
+jest.mock('../lib/TuyaAccessory', () => jest.fn().mockImplementation(function(props) {
+    this.context = {...props};
+    this.connected = false;
+    this.state = {};
+    this.update = jest.fn().mockReturnValue(true);
+    this.on = jest.fn();
+    this._connect = jest.fn();
+}));
+
+const EventEmitter = require('events');
+const TuyaDevice = require('../lib/TuyaDevice');
+const TuyaCloudDevice = require('../lib/TuyaCloudDevice');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+// A minimal stand-in for either backend (TuyaAccessory / TuyaCloudDevice): an
+// EventEmitter exposing the surface TuyaDevice routes through.
+function fakeBackend(extra = {}) {
+    const b = new EventEmitter();
+    b.connected = false;
+    b.state = {};
+    b.update = jest.fn().mockReturnValue(true);
+    b.codeByDpId = {};
+    b.dpIdByCode = {};
+    b._connect = jest.fn();
+    return Object.assign(b, extra);
+}
+
+function makeDevice(props = {}) {
+    return new TuyaDevice({id: 'dev1', key: 'k', name: 'Lamp', type: 'switch', log, connect: false, ...props});
+}
+
+// Attach fake backends to a device and wire their events (white-box, so the merge
+// / fallback logic can be exercised without any real network).
+function withBackends(dev, {lan, cloud} = {}) {
+    if (cloud) { dev.cloud = cloud; dev._wire(cloud, 'cloud'); }
+    if (lan) { dev.lan = lan; dev._wire(lan, 'lan'); }
+    return dev;
+}
+
+describe('TuyaDevice — connectivity', () => {
+    test('connected reflects either backend', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend();
+        const cloud = fakeBackend();
+        withBackends(dev, {lan, cloud});
+
+        expect(dev.connected).toBe(false);
+        lan.connected = true;
+        expect(dev.connected).toBe(true);
+        lan.connected = false;
+        cloud.connected = true;
+        expect(dev.connected).toBe(true);
+    });
+
+    test("'connect' is emitted once, on the first backend to connect", () => {
+        const dev = makeDevice();
+        const lan = fakeBackend();
+        const cloud = fakeBackend();
+        withBackends(dev, {lan, cloud});
+
+        let connects = 0;
+        dev.on('connect', () => connects++);
+        lan.emit('connect');
+        cloud.emit('connect');
+        expect(connects).toBe(1);
+    });
+});
+
+describe('TuyaDevice — pure LAN (no cloud) preserves legacy behaviour', () => {
+    test('update returns the synchronous boolean from the LAN backend', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true});
+        withBackends(dev, {lan});
+
+        lan.update.mockReturnValue(true);
+        expect(dev.update({'1': false})).toBe(true);
+        expect(lan.update).toHaveBeenCalledWith({'1': false});
+
+        lan.update.mockReturnValue(false);
+        expect(dev.update({'1': true})).toBe(false);
+    });
+
+    test('update is false when there is no transport at all', () => {
+        const dev = makeDevice();
+        expect(dev.update({'1': true})).toBe(false);
+    });
+});
+
+describe('TuyaDevice — state merge & registration', () => {
+    test('first change drives registration and exposes the merged state', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true, '2': 50}});
+        withBackends(dev, {lan});
+
+        const seen = [];
+        dev.on('change', (changes, state) => seen.push({changes, state}));
+        lan.emit('change');
+
+        expect(seen).toHaveLength(1);
+        expect(seen[0].state).toEqual({'1': true, '2': 50});
+    });
+
+    test('LAN wins over the cloud while connected; cloud-only DPs are kept; LAN is mirrored to codes', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true}});
+        const cloud = fakeBackend({
+            connected: true,
+            state: {'switch_led': false, '1': false, 'battery_percentage': 80},
+            codeByDpId: {'1': 'switch_led'},
+            dpIdByCode: {'switch_led': '1'}
+        });
+        withBackends(dev, {lan, cloud});
+
+        lan.emit('change');
+        expect(dev.state['1']).toBe(true);                 // LAN value wins
+        expect(dev.state['switch_led']).toBe(true);        // …mirrored to its code
+        expect(dev.state['battery_percentage']).toBe(80);  // cloud-only DP retained
+    });
+
+    test('when the LAN drops, the cloud takes over and the change is emitted', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true}});
+        const cloud = fakeBackend({connected: true, state: {'1': false}});
+        withBackends(dev, {lan, cloud});
+
+        lan.emit('change');
+        expect(dev.state['1']).toBe(true);
+
+        lan.connected = false; // LAN lost
+        const seen = [];
+        dev.on('change', changes => seen.push(changes));
+        cloud.emit('change');
+
+        expect(dev.state['1']).toBe(false);
+        expect(seen[0]).toEqual({'1': false});
+    });
+});
+
+describe('TuyaDevice — writes with fallback', () => {
+    test('LAN is used first when both backends are up', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true});
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {lan, cloud});
+
+        await expect(dev.update({'1': true})).resolves.toBe(true);
+        expect(lan.update).toHaveBeenCalledWith({'1': true});
+        expect(cloud.update).not.toHaveBeenCalled();
+    });
+
+    test('a failed LAN write falls back to the cloud', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, update: jest.fn().mockReturnValue(false)});
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {lan, cloud});
+
+        await expect(dev.update({'1': true})).resolves.toBe(true);
+        expect(cloud.update).toHaveBeenCalledWith({'1': true});
+    });
+
+    test('with the LAN down, writes go straight to the cloud (raw keys; the cloud translates)', async () => {
+        const dev = makeDevice();
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {cloud});
+
+        await expect(dev.update({'switch_led': true})).resolves.toBe(true);
+        expect(cloud.update).toHaveBeenCalledWith({'switch_led': true});
+    });
+
+    test('a code-style write is translated to numeric ids for the LAN', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, update: jest.fn().mockReturnValue(true)});
+        const cloud = fakeBackend({connected: true, dpIdByCode: {'switch_led': '1'}, codeByDpId: {'1': 'switch_led'}});
+        withBackends(dev, {lan, cloud});
+
+        await dev.update({'switch_led': true});
+        expect(lan.update).toHaveBeenCalledWith({'1': true});
+    });
+
+    test('update resolves false when nothing is reachable', async () => {
+        const dev = makeDevice();
+        const cloud = fakeBackend({connected: false, update: jest.fn()});
+        withBackends(dev, {cloud});
+        await expect(dev.update({'1': true})).resolves.toBe(false);
+    });
+});
+
+describe('TuyaDevice — registration source guard', () => {
+    test('a LAN-primary device defers cloud-driven registration until it has the map or the LAN grace elapses', () => {
+        const dev = makeDevice();                  // has a key → LAN-primary
+        dev.cloud = fakeBackend({codeByDpId: {}});  // cloud, but no numeric map yet
+
+        expect(dev._mayRegisterFrom('lan')).toBe(true);
+        expect(dev._mayRegisterFrom('cloud')).toBe(false);
+
+        dev.cloud.codeByDpId = {'1': 'switch_led'}; // map learned → safe
+        expect(dev._mayRegisterFrom('cloud')).toBe(true);
+
+        dev.cloud.codeByDpId = {};
+        dev._lanGraceElapsed = true;                // …or the LAN had its head start
+        expect(dev._mayRegisterFrom('cloud')).toBe(true);
+    });
+
+    test('a keyless (cloud-only) device registers off the cloud immediately', () => {
+        const keyless = makeDevice({key: undefined});
+        keyless.cloud = fakeBackend({codeByDpId: {}});
+        expect(keyless._mayRegisterFrom('cloud')).toBe(true);
+    });
+});
+
+describe('TuyaDevice — composition', () => {
+    test('a cloud backend is built when a shared cloud session is supplied', () => {
+        const api = {
+            isConfigured: () => true,
+            getStatus: jest.fn().mockResolvedValue([]),
+            getDeviceInfo: jest.fn().mockResolvedValue({online: true}),
+            sendCommands: jest.fn()
+        };
+        const dev = makeDevice({cloudApi: api});
+        expect(dev.cloud).toBeInstanceOf(TuyaCloudDevice);
+        expect(dev.lan).toBeNull();
+    });
+
+    test('no cloud backend without a shared session', () => {
+        const dev = makeDevice();
+        expect(dev.cloud).toBeNull();
+    });
+
+    test('attachLan builds the LAN backend with the discovered version (forceVersion still wins)', () => {
+        const dev = makeDevice({ip: '10.0.0.5'});
+        dev.attachLan({ip: '10.0.0.9', version: '3.3'});
+        expect(dev.lan).not.toBeNull();
+        expect(dev.lan.context.ip).toBe('10.0.0.9');
+        expect(dev.lan.context.version).toBe('3.3');
+
+        const forced = makeDevice({forceVersion: '3.5'});
+        forced.attachLan({ip: '10.0.0.9', version: '3.3'});
+        expect(forced.lan.context.version).toBe('3.5');
+    });
+
+    test('attachLan is a no-op without a local key (cloud-only device)', () => {
+        const dev = makeDevice({key: undefined});
+        dev.attachLan({ip: '10.0.0.9'});
+        expect(dev.lan).toBeNull();
+    });
+});

package/test/getCategory.test.js

@@ -23,6 +23,7 @@ const CLASS_DEF = {
     garagedoor: require('../lib/GarageDoorAccessory'),
     simplegaragedoor: require('../lib/SimpleGarageDoorAccessory'),
     simpledimmer: require('../lib/SimpleDimmerAccessory'),
+    wleddimmer: require('../lib/WledDimmerAccessory'),
     simpledimmer2: require('../lib/SimpleDimmer2Accessory'),
     simpleblinds: require('../lib/SimpleBlindsAccessory'),
     simpleheater: require('../lib/SimpleHeaterAccessory'),

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

@@ -15,7 +15,8 @@ If you are looking for verified configurations for your specific device, please
 |Barely Smart Power Strip|`Outlet`|Smart power strips that don't allow individual control of the outlets|
 |Air Conditioner|`AirConditioner`<sup>[6](#air-conditioners)</sup>|Cooling and heating devices <small>([instructions](#air-conditioners))</small>|
 |Heat Convector|`Convector`<sup>[7](#heat-convectors)</sup>|Heating panels <small>([instructions](#heat-convectors))</small>|
-|WLED Dimmer|`WledDimmer` (or legacy `SimpleDimmer`)<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control, with optional WLED sync <small>([instructions](#simple-dimmers))</small>|
+|Simple Dimmer|`SimpleDimmer`<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control <small>([instructions](#simple-dimmers))</small>|
+|WLED Dimmer|`WledDimmer`<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control, plus optional WLED brightness sync and preset-effect switches <small>([instructions](#simple-dimmers))</small>|
 |Simple Heater|`SimpleHeater`<sup>[9](#simple-heaters)</sup>|Heating solutions with only temperature control <small>([instructions](#simple-heaters))</small>|
 |Garage Door|`GarageDoor`<sup>[10](#garage-doors)</sup>|Smart garage doors or garage door openers <small>([instructions](#garage-doors))</small>|
 |Simple Garage Door|`SimpleGarageDoor`<sup>[10](#simple-garage-doors)</sup>|Sliding gate openers and garage door controllers with open/stop/close action DPs and a simple three-value status DP <small>([instructions](#simple-garage-doors))</small>|
@@ -345,14 +346,15 @@ If your signature doesn't have a variation of _low_ or _high_, `SimpleHeater` wo
 ```
 
 ### Simple Dimmers / WLED Dimmers
-These are switches that allow turning on and off, and dimming. Use type `WledDimmer` (legacy `SimpleDimmer` alias is also supported for backward compatibility).
+These are switches that allow turning on and off, and dimming. Two distinct types are available:
 
-When using with a WLED controller (e.g. a Tuya-based relay/dimmer feeding power to a WLED strip), you can use advanced sync options:
+- `SimpleDimmer` — a plain dimmer with power and brightness control.
+- `WledDimmer` — a dimmer that can additionally drive a [WLED](https://kno.wled.ge/) controller (e.g. a Tuya-based relay/dimmer feeding power to a WLED strip). With none of the WLED options below configured, it behaves exactly like a `SimpleDimmer`.
 
-- `syncBrightnessToWled`: set to 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%.
-- `presetEffects`: array of effect configs to expose as switches in HomeKit (each turns on a WLED fx preset, optionally with staticColor).
+The following options apply to `WledDimmer` only (they are ignored by `SimpleDimmer`):
 
-See the accessory source for full details on WLED integration.
+- `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
 {

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: