homebridge-tuya-plus 3.14.0-dev.3 → 3.14.0-dev.30

package/test/index.test.js

@@ -0,0 +1,183 @@
+'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 TuyaAccessory = require('../lib/TuyaAccessory');
+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(), unregisterPlatformAccessories: 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);
+    });
+});
+
+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();
+    });
+});
+
+describe('TuyaLan — duplicate device ids', () => {
+    // Two entries sharing an id resolve to one accessory UUID; configuring it twice
+    // used to crash the child bridge (addAccessory read back its own wrapper and
+    // tried to unregister it). The repeat must be dropped with a warning instead.
+    test('a repeated id is configured once and warns', () => {
+        const platform = run({devices: [SW(), SW()]});
+        expect(TuyaDevice).toHaveBeenCalledTimes(1);
+        expect(platform.addAccessory).toHaveBeenCalledTimes(1);
+        expect(platform.log.warn).toHaveBeenCalled();
+    });
+
+    test('distinct ids are all configured', () => {
+        run({devices: [SW(), SLEEPY()]});
+        expect(TuyaDevice).toHaveBeenCalledTimes(2);
+    });
+
+    test('a repeated fake id is configured once', () => {
+        run({devices: [SW({fake: true}), SW({fake: true})]});
+        expect(TuyaAccessory).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('TuyaLan — removeAccessory hardening', () => {
+    function platformWith(PlatformAccessory) {
+        let cls;
+        factory({platformAccessory: PlatformAccessory, hap: makeHap(), registerPlatform: (n, p, c) => { cls = c; }});
+        return new cls(makeLog(), {devices: [SW()]}, makeApi());
+    }
+    const PlatformAccessoryStub = function(name, uuid) { this.displayName = name; this.UUID = uuid; };
+
+    test('a non-PlatformAccessory (e.g. an accessory wrapper) is never unregistered', () => {
+        const platform = platformWith(PlatformAccessoryStub);
+        expect(() => platform.removeAccessory({accessory: {}})).not.toThrow();
+        expect(platform.api.unregisterPlatformAccessories).not.toHaveBeenCalled();
+        expect(platform.log.warn).toHaveBeenCalled();
+    });
+
+    test('a real PlatformAccessory is unregistered and dropped from the cache', () => {
+        const platform = platformWith(PlatformAccessoryStub);
+        const accessory = new PlatformAccessoryStub('Real', 'uuid:x');
+        platform.cachedAccessories.set('uuid:x', accessory);
+        platform.removeAccessory(accessory);
+        expect(platform.api.unregisterPlatformAccessories).toHaveBeenCalledTimes(1);
+        expect(platform.cachedAccessories.has('uuid:x')).toBe(false);
+    });
+});

package/test/support/mocks.js

@@ -34,6 +34,7 @@ const HAP = {
         ProgramMode: { UUID: 'D1', NO_PROGRAM_SCHEDULED: 0, PROGRAM_SCHEDULED: 1, PROGRAM_SCHEDULED_MANUAL_MODE: 2 },
         IsConfigured: { UUID: 'D6', NOT_CONFIGURED: 0, CONFIGURED: 1 },
         ServiceLabelIndex: { UUID: 'CB' },
+        ServiceLabelNamespace: { UUID: 'CD', DOTS: 0, ARABIC_NUMERALS: 1 },
         ConfiguredName: { UUID: 'E3' },
         BatteryLevel: { UUID: '68' },
         StatusLowBattery: { UUID: '79', BATTERY_LEVEL_NORMAL: 0, BATTERY_LEVEL_LOW: 1 },
@@ -65,6 +66,7 @@ const HAP = {
         LockMechanism: { UUID: '45' },
         Valve: { UUID: 'D0' },
         IrrigationSystem: { UUID: 'CF' },
+        ServiceLabel: { UUID: 'CC' },
         Battery: { UUID: '96' },
         ContactSensor: { UUID: '80' },
         LeakSensor: { UUID: '83' },
@@ -73,6 +75,17 @@ const HAP = {
     },
     Formats: { FLOAT: 'float', UINT32: 'uint32', UINT16: 'uint16' },
     Perms: { READ: 'pr', NOTIFY: 'ev', WRITE: 'pw' },
+    // Subset of hap-nodejs HAPStatus + the HapStatusError class, so accessories
+    // can signal "No Response" the proper way (throw a HapStatusError from a
+    // get/set handler) and tests can assert on it.
+    HAPStatus: { SUCCESS: 0, SERVICE_COMMUNICATION_FAILURE: -70402 },
+    HapStatusError: class HapStatusError extends Error {
+        constructor(hapStatus) {
+            super('HapStatusError: ' + hapStatus);
+            this.name = 'HapStatusError';
+            this.hapStatus = hapStatus;
+        }
+    },
     // Mirrors hap-nodejs Categories. Intentionally kept faithful to the real
     // enum (no FANLIGHT, no bare DEHUMIDIFIER) so getCategory() regressions are
     // caught here instead of in production (see issue #45).

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>|
@@ -223,7 +224,17 @@ Some smart power strips don't have sequential data-points. Using `CustomMultiOut
 ```
 
 ### Air Conditioners
-These devices have cooling and/or heating capabilities; they could also have _dry_, _fan_, or others modes but HomeKit's definition doesn't facilitate modes other than _heat_, _cool_, and _auto_. By default, _heat_ and _cool_ modes are enabled; to let the plugin know that a device doesn't have heating or cooling capabilities, add an additional parameter named `noHeat` or `noCool` and set it to `true`. Tuya devices don't follow a unified pattern for naming the modes, for example cooling mode is called _COOL_ on Kogan's KAPRA14WFGA and _cold_ on Igenix's IG9901WIFI; by default, the plugin uses the phrases _COOL_ and _HEAT_ while communicating with your device but to let the plugin know that a device has different phrases, add additional parameters using `cmdHeat` and `cmdCool`. Additional parameters can be found in the sample below.
+These devices have cooling and/or heating capabilities; they could also have _dry_, _fan_, or others modes but HomeKit's definition doesn't facilitate modes other than _heat_, _cool_, and _auto_. By default, _heat_, _cool_ and _auto_ modes are enabled; to let the plugin know that a device doesn't have heating, cooling or auto capabilities, add an additional parameter named `noHeat`, `noCool` or `noAuto` and set it to `true`.
+
+Tuya devices don't follow a unified pattern for naming the modes, for example cooling mode is called _COOL_ on Kogan's KAPRA14WFGA but _cold_ on Igenix's IG9901WIFI and most "standard" Tuya AC (category `kt`) firmwares. The phrases are also **case-sensitive**. By default, the plugin uses the phrases _COOL_, _HEAT_ and _AUTO_ while communicating with your device; if your device uses different phrases (a very common case — many ACs report lowercase `cold` / `hot` / `auto` / `wet` / `wind`), override them with `cmdCool`, `cmdHeat` and `cmdAuto`. If the modes don't switch at all, this is almost always the reason.
+
+> **Tip — finding the exact phrases.** The phrases are the raw values of the `mode` data-point (DP `4`). You can read them from the [Tuya IoT Platform](https://iot.tuya.com) → _Cloud → API Explorer → Query Things Data Model_ (or _Get Device Specification_) for your device. For example, a device whose `mode` enum range is `["auto","cold","wet","wind","hot"]` needs `cmdCool: "cold"`, `cmdHeat: "hot"`, `cmdAuto: "auto"`.
+
+The fan speed data-point (DP `5`, `windspeed`) is usually an **enum of string values** like `"1"`, `"2"`, `"3"`. Set `fanSpeedSteps` to the number of speeds (e.g. `3`); this both maps HomeKit's 0–100 % slider onto the right number of steps and — importantly — sends the speed as a string, which these firmwares require. Without it the fan may silently ignore speed changes.
+
+Many ACs have no child-lock data-point; if yours doesn't, set `noChildLock: true` so the plugin doesn't add a (non-functional) lock control. Likewise, set `noRotationSpeed: true` if the device has no fan-speed control.
+
+Additional parameters can be found in the sample below.
 
 ```json5
 {
@@ -242,12 +253,27 @@ These devices have cooling and/or heating capabilities; they could also have _dr
     /* This device has no heating function */
     "noHeat": true ,
 
-    /* Override cooling phrase */
+    /* This device has no auto function */
+    "noAuto": true,
+
+    /* Override cooling phrase (case-sensitive; e.g. "cold" on many devices) */
     "cmdCool": "COOL",
 
-    /* Override heating phrase */
+    /* Override heating phrase (case-sensitive; e.g. "hot" on many devices) */
     "cmdHeat": "HEAT",
 
+    /* Override auto phrase (case-sensitive; e.g. "auto" on many devices) */
+    "cmdAuto": "AUTO",
+
+    /* Number of fan speeds; also sends the speed as a string (required by most ACs) */
+    "fanSpeedSteps": 3,
+
+    /* This device has no fan-speed control */
+    "noRotationSpeed": true,
+
+    /* This device has no child-lock data-point */
+    "noChildLock": true,
+
     /* This device has no oscillation (swinging) function */
     "noSwing": true,
 
@@ -258,7 +284,10 @@ These devices have cooling and/or heating capabilities; they could also have _dr
     "maxTemperature": 40,
 
     /* Temperature change steps, in Celsius (°C) */
-    "minTemperatureSteps": 1
+    "minTemperatureSteps": 1,
+
+    /* Only if your firmware reports/accepts temperatures scaled by 10 (e.g. 170 = 17.0 °C) */
+    "temperatureDivisor": 10
 }
 ```
 
@@ -317,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
 {
@@ -470,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
@@ -723,18 +754,30 @@ If the light, brightness and turning the fan **off** all work, but turning the f
 
 ### Irrigation Systems / Sprinklers
 
-Multi-valve Tuya irrigation/sprinkler controllers (the battery-powered Wi-Fi "faucet timers" that expose several `switch_*` valves, a `battery_percentage` and a `rain_sensor_state`) are exposed as a single, fully-fledged HomeKit **Irrigation System** accessory:
+Multi-valve Tuya irrigation/sprinkler controllers (the battery-powered Wi-Fi "faucet timers" that expose several `switch_*` valves and a `battery_percentage`) are exposed as a single, fully-fledged HomeKit **Irrigation System** accessory:
 
 * one **Irrigation System** tile that contains every zone,
 * one **Valve** per zone (`ValveType = Irrigation`) — each with its own on/off, its own **Duration** picker and a live countdown,
-* an optional **Battery** service (level, low-battery warning, and — for solar/USB-C rechargeable units that report it — live charging status),
-* an optional **rain sensor** (a Contact sensor by default).
+* an optional **Battery** service (level, low-battery warning, and — for solar/USB-C rechargeable units that report it — live charging status).
 
 Because these devices are slow to respond, all zone changes that happen close together — turning the whole system on/off, or running a scene that toggles several zones — are merged into a **single** Tuya command instead of a burst of them.
 
+> **⚠️ Can't connect locally?** Most of these are battery-powered **"sleepy"** devices that **cannot be controlled over the LAN at all** — they sleep to save battery and only ever reach Tuya's cloud. If discovery never finds yours (or it won't connect), control it over the **[Tuya Cloud](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** instead: add cloud credentials once and set `"cloud": true` on the device. Everything below works the same — data-points are just addressed by their Tuya *code* (e.g. `switch_1`), which the plugin logs on startup.
+
+```json5
+// Cloud example (also needs a top-level "cloud" credentials block — see the Tuya Cloud Setup guide)
+{
+    "name": "Garden Irrigation",
+    "type": "IrrigationSystem",
+    "id": "bfae6739xxxxxxxxxxxxxx",   // the cloud Device ID
+    "cloud": true,
+    "valveCount": 4
+}
+```
+
 #### Minimal Configuration
 
-The defaults match the common 4-zone layout (valves A–D on data-points `1`–`4`, battery on `46`, rain on `49`):
+The defaults match the common 4-zone layout (valves A–D on data-points `1`–`4`, battery on `46`):
 
 ```json5
 {
@@ -758,10 +801,6 @@ Each zone has its own **Duration**. When a zone is switched on it runs for that
 
 Switching the whole Irrigation System tile **off** closes every open zone, and switching it **on** opens every zone — each as one combined command (mirroring the physical "all" button many of these controllers have). Either direction can be disabled with `masterTurnsOffAllZones` / `masterTurnsOnAllZones`.
 
-#### Rain sensor: Contact vs Leak
-
-By default the rain sensor is a **Contact sensor** (`raining → Open`). You can switch it to a **Leak sensor** (`raining → Leak Detected`) with `"rainSensorType": "leak"` — leak sensors read more naturally for rain and make "when it starts raining" automations obvious, **but HomeKit treats them as safety accessories and raises critical alerts that bypass Do-Not-Disturb on every rainfall**, which many people find too noisy. Use `rainInverted` if the wet/dry states appear reversed.
-
 #### Full Configuration
 
 ```json5
@@ -799,12 +838,5 @@ By default the rain sensor is a **Contact sensor** (`raining → Open`). You can
     "lowBatteryThreshold": 20,
     "dpCharging": 101,   /* boolean charging-status DP (solar / USB-C); omit if not reported */
     /* "noBattery": true, */
-
-    /* --- Rain sensor (omit / set noRainSensor:true if not present) --- */
-    "dpRain": 49,
-    "rainSensorType": "contact", /* or "leak" */
-    "rainOnValue": "rain",       /* enum value reported while raining */
-    "rainInverted": false
-    /* "noRainSensor": true, */
 }
 ```

package/wiki/Tuya-Cloud-Setup.md

@@ -0,0 +1,71 @@
+# Tuya Cloud Setup
+
+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**.
+
+It helps in two situations:
+
+> **Devices that are never on the LAN.** Some devices, most notably some battery-powered **"sleepy"** ones, 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.
+
+---
+
+## 1. Create a Tuya Cloud project
+
+1. Sign up / log in at **[iot.tuya.com](https://iot.tuya.com/)** (the Tuya IoT Development Platform).
+2. **Cloud → Development → Create Cloud Project.**
+   * **Development Method:** choose **Smart Home**.
+   * **Data Center:** pick the region your **Tuya Smart / Smart Life app account** is in (App → *Me → Settings → Account and Security → Region*). This matters — cross-region API calls are rejected.
+3. After it's created, open the project — the **Overview** tab shows your **Access ID / Client ID** and **Access Secret / Client Secret**. You'll need both.
+
+## 2. Authorize the required API services
+
+There are two types of projects: `Custom` and `Smart Home`. The difference between them is:
+
+* The `Custom` project pulls devices from the project's assets.
+* The `Smart Home` project pulls devices from the user's home in the Tuya app.
+
+If you are a personal user and are unsure which one to choose, please use the Smart Home project.
+
+In the project, go to **Service API → Go to Authorize** and make sure these are subscribed (all free):
+
+* Authorization Token Management
+* Device Status Notification
+* IoT Core
+* IoT Video Live Stream (for cameras)
+* Industry Project Client Service (for the `Custom` project)
+* IR Control Hub Open Service (for IR devices)
+* Smart Home Scene Linkage (for scenes)
+* Smart Lock Open Service (for Lock devices)
+
+> **⚠️Remember to extend the API trial period every 6 months here: [Tuya IoT Platform > Cloud > Cloud Services > IoT Core](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1) (the first-time subscription only gives you 1 month).**
+
+## 3. Link your app account (so the project can see your devices)
+
+Still in the project: **Devices → Link App Account → Add App Account**, then in the **Tuya Smart / Smart Life** app go to **Me → ⊞ (scan icon, top-right)** and scan the QR code. Your irrigation timer should now appear under **Devices → All Devices**.
+
+## 4. Configure the plugin
+
+Add a **top-level `cloud` block** with your credentials:
+
+```json5
+{
+    "platform": "TuyaLan",
+    "cloud": {
+        "accessId": "your-access-id",
+        "accessKey": "your-access-secret",
+        "region": "eu",                         // eu / us / cn / in / sg / eu-w / us-e
+        "username": "you@example.com",          // your Tuya/Smart Life app login
+        "password": "your-app-password",
+        "countryCode": "48",                    // your phone country code (e.g. 1, 44, 48)
+        "schema": "tuyaSmart"                   // or "smartlife" if you use the Smart Life app
+    },
+    "devices": [
+      // ...
+    ]
+}
+```
+
+### 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.