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

package/Changelog.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/).
 
+## Unreleased
+
+* [+] **Tuya Cloud support for devices that can't be reached over the LAN** — most notably battery-powered "sleepy" irrigation/sprinkler timers, which sleep almost all the time and only ever talk to Tuya's cloud, so the local protocol can never reach them. The plugin stays LAN-first: cloud is strictly opt-in. Add a top-level `cloud` credentials block (or a per-device `cloud` object) and set `"cloud": true` on the device.
+  * Realtime updates arrive over Tuya's **MQTT** message service (via the optional `mqtt` dependency, installed automatically); initial state and control use the Tuya OpenAPI. There is no polling.
+  * Works with both **Custom** and **Smart Home** Cloud projects (the latter via app-account login).
+  * The existing **IrrigationSystem** accessory works unchanged over the cloud — its data-points are simply addressed by Tuya "code" (e.g. `switch_1`, `battery_percentage`) instead of a numeric id; the device logs its codes on startup. Battery-only controllers with no rain sensor: set `"noRainSensor": true`.
+  * See the wiki: **[Tuya Cloud Setup](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)**.
+
 ## 2.0.1 (2021-03-25)
 This update includes the following changes:
 

package/Readme.MD

@@ -69,6 +69,14 @@ Protocol **3.5** is currently the newest Tuya LAN protocol in existence: it is t
 
 This plugin is nevertheless **3.6-ready**: if a device reports a newer protocol version (e.g. `3.6`) in its broadcast, the plugin automatically talks to it using the newest (3.5/GCM) protocol stack while tagging payloads with the device's reported version — the same forward-compatibility strategy used by tinytuya. Should such a device misbehave, you can pin it to a specific protocol with the `forceVersion` device option (e.g. `"forceVersion": "3.5"`), or use `version` to set a protocol for devices that can't be discovered (e.g. on another subnet).
 
+## Cloud devices (for hardware that can't be controlled locally)
+
+This is a **LAN-first** plugin — virtually every Tuya device is controlled locally, which is faster, more private, and keeps working without internet. A few devices, though, simply **can't** be reached over the LAN: battery-powered "sleepy" devices — for example the **irrigation / faucet timers** — sleep almost all the time and only ever connect out to Tuya's cloud, so they never answer on the local network.
+
+For exactly these cases the plugin can talk to a device through the **Tuya Cloud** instead — strictly **opt-in, per device**. You add your Tuya Cloud project credentials once and set `"cloud": true` on the device; everything else works the same.
+
+👉 **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** — how to get credentials and configure a cloud device.
+
 ## Installation Instructions
 
 #### Option 1: Install via Homebridge Config UI X:

package/config.schema.json

@@ -19,12 +19,71 @@
         "placeholder": "Timeout (millisecond) for device IP address discovery",
         "default": 60000
       },
+      "cloud": {
+        "type": "object",
+        "title": "Tuya Cloud (optional — only for devices that can't be reached over the LAN)",
+        "description": "This plugin is LAN-first. A few devices — notably battery-powered 'sleepy' irrigation timers — sleep most of the time and only ever talk to Tuya's cloud, so they cannot be controlled locally. Create a free Cloud project at iot.tuya.com, enter its credentials here, then tick 'Control via Tuya Cloud' on each such device. See the wiki for step-by-step setup.",
+        "properties": {
+          "accessId": {
+            "type": "string",
+            "title": "Access ID / Client ID"
+          },
+          "accessKey": {
+            "type": "string",
+            "title": "Access Secret / Client Secret"
+          },
+          "region": {
+            "type": "string",
+            "title": "Data center / region",
+            "default": "us",
+            "description": "Must match the region your Tuya / Smart Life app account is registered in.",
+            "oneOf": [
+              { "title": "Central Europe", "enum": ["eu"] },
+              { "title": "Western Europe (Azure)", "enum": ["eu-w"] },
+              { "title": "Western America", "enum": ["us"] },
+              { "title": "Eastern America (Azure)", "enum": ["us-e"] },
+              { "title": "China", "enum": ["cn"] },
+              { "title": "India", "enum": ["in"] },
+              { "title": "Singapore", "enum": ["sg"] }
+            ]
+          },
+          "username": {
+            "type": "string",
+            "title": "App account email/phone (Smart Home projects only)",
+            "description": "For 'Smart Home' Cloud projects: the Tuya / Smart Life app account that owns the devices. Leave blank for 'Custom' projects (which link devices by QR scan)."
+          },
+          "password": {
+            "type": "string",
+            "title": "App account password (Smart Home projects only)"
+          },
+          "countryCode": {
+            "type": "string",
+            "title": "Country calling code (Smart Home projects only)",
+            "placeholder": "e.g. 1, 44, 48"
+          },
+          "schema": {
+            "type": "string",
+            "title": "App (Smart Home projects only)",
+            "default": "tuyaSmart",
+            "oneOf": [
+              { "title": "Tuya Smart", "enum": ["tuyaSmart"] },
+              { "title": "Smart Life", "enum": ["smartlife"] }
+            ]
+          },
+          "realtime": {
+            "type": "boolean",
+            "title": "Realtime updates (MQTT)",
+            "default": true,
+            "description": "Receive instant updates over Tuya's MQTT message service (uses the 'mqtt' package, installed automatically). If disabled, devices stay controllable and show their state at startup, but external changes (physical buttons, the device's own timers) won't be reflected until restart."
+          }
+        }
+      },
       "devices": {
         "type": "array",
         "orderable": false,
         "items": {
           "type": "object",
-          "required": ["type", "name", "id", "key"],
+          "required": ["type", "name", "id"],
           "properties": {
             "type": {
               "type": "string",
@@ -136,8 +195,18 @@
               }
             },
             "key": {
-              "title": "Tuya Key",
+              "title": "Tuya Key (local key — required for LAN devices)",
               "type": "string",
+              "description": "The device's local key. Required for normal (LAN) devices. Not needed for cloud devices (tick 'Control via Tuya Cloud' below).",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
+              }
+            },
+            "cloud": {
+              "type": ["boolean", "object"],
+              "title": "Control via Tuya Cloud (instead of the LAN)",
+              "default": false,
+              "description": "Enable for devices that can't be reached locally (e.g. battery-powered irrigation timers). Uses the platform-level 'cloud' credentials above. Advanced: instead of a checkbox you can set this to an object with per-device { accessId, accessKey, region, … } to use different credentials for this one device.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -648,7 +717,7 @@
               "type": "integer",
               "title": "Number of Valves / Zones",
               "placeholder": 4,
-              "description": "How many valves/zones the controller has. They are assumed to be on data-points 1, 2, 3, … For non-sequential data-points use the 'valves' list instead.",
+              "description": "How many valves/zones the controller has. They are assumed to be on data-points 1, 2, 3, … (or, for cloud devices, on the codes switch_1, switch_2, …). For non-sequential data-points use the 'valves' list instead.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
               }
@@ -662,7 +731,7 @@
                 "type": "object",
                 "properties": {
                   "name": { "type": "string", "title": "Zone name", "placeholder": "Lawn" },
-                  "dp": { "type": "integer", "title": "Data-point", "placeholder": 1 },
+                  "dp": { "type": ["integer", "string"], "title": "Data-point (numeric id, or cloud code)", "placeholder": "1 or switch_1" },
                   "defaultDuration": { "type": "integer", "title": "Default run time (seconds, 0 = run indefinitely)", "placeholder": 600 }
                 }
               },
@@ -724,9 +793,9 @@
               }
             },
             "dpBattery": {
-              "type": "integer",
-              "placeholder": 46,
-              "title": "Battery data-point",
+              "type": ["integer", "string"],
+              "placeholder": "46 or battery_percentage",
+              "title": "Battery data-point (numeric id, or cloud code)",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noBattery;"
               }
@@ -741,9 +810,9 @@
               }
             },
             "dpCharging": {
-              "type": "integer",
-              "placeholder": 101,
-              "title": "Charging-status data-point",
+              "type": ["integer", "string"],
+              "placeholder": "101 or charge_state",
+              "title": "Charging-status data-point (numeric id, or cloud code)",
               "description": "Boolean data-point reporting whether the battery is charging (e.g. solar / USB-C units). HomeKit shows Charging / Not Charging; if your controller doesn't report this, it shows Not Chargeable.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noBattery;"
@@ -778,9 +847,9 @@
               }
             },
             "dpRain": {
-              "type": "integer",
-              "placeholder": 49,
-              "title": "Rain sensor data-point",
+              "type": ["integer", "string"],
+              "placeholder": "49 or rain_sensor_state",
+              "title": "Rain sensor data-point (numeric id, or cloud code)",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noRainSensor;"
               }

package/index.js

@@ -1,5 +1,8 @@
 const TuyaAccessory = require('./lib/TuyaAccessory');
 const TuyaDiscovery = require('./lib/TuyaDiscovery');
+const TuyaCloudApi = require('./lib/TuyaCloudApi');
+const TuyaCloudDevice = require('./lib/TuyaCloudDevice');
+const TuyaCloudMessaging = require('./lib/TuyaCloudMessaging');
 
 const OutletAccessory = require('./lib/OutletAccessory');
 const SimpleLightAccessory = require('./lib/SimpleLightAccessory');
@@ -36,6 +39,13 @@ const PLATFORM_NAME = 'TuyaLan';
 const UUID_SEED = 'homebridge-tuya';
 const DEFAULT_DISCOVER_TIMEOUT = 60000;
 
+// Lenient boolean coercion (matches BaseAccessory._coerceBoolean) so config
+// values like true / "true" / 1 all read as true.
+const coerceBoolean = (b, df = false) =>
+    typeof b === 'boolean' ? b :
+    typeof b === 'string' ? b.toLowerCase().trim() === 'true' :
+    typeof b === 'number' ? b !== 0 : df;
+
 const CLASS_DEF = {
     outlet: OutletAccessory,
     simplelight: SimpleLightAccessory,
@@ -82,6 +92,11 @@ class TuyaLan {
         [this.log, this.config, this.api] = [...props];
 
         this.cachedAccessories = new Map();
+        // Shared Tuya Cloud clients, keyed by credential set, so several
+        // cloud devices on the same project share one token + one realtime
+        // (MQTT) connection. Empty unless cloud devices are configured.
+        this.cloudApis = new Map();
+        this.cloudMessagers = new Map();
         this.api.hap.EnergyCharacteristics = require('./lib/EnergyCharacteristics')(this.api.hap);
 
         if(!this.config || !this.config.devices) {
@@ -100,10 +115,12 @@ class TuyaLan {
         const devices = {};
         const connectedDevices = [];
         const fakeDevices = [];
+        const cloudDevices = [];
         this.config.devices.forEach(device => {
             try {
                 device.id = ('' + device.id).trim();
-                device.key = ('' + device.key).trim();
+                // Cloud devices don't need a local key; only trim when present.
+                if (device.key != null) device.key = ('' + device.key).trim();
                 device.type = ('' + device.type).trim();
 
                 device.ip = ('' + (device.ip || '')).trim();
@@ -112,12 +129,20 @@ class TuyaLan {
             if (!device.type) return this.log.error('%s (%s) doesn\'t have a type defined.', device.name || 'Unnamed device', device.id);
             if (!CLASS_DEF[device.type.toLowerCase()]) return this.log.error('%s (%s) doesn\'t have a valid type defined.', device.name || 'Unnamed device', device.id);
 
-            if (device.fake) fakeDevices.push({name: device.id.slice(8), ...device});
+            if (this._isCloudDevice(device)) cloudDevices.push({name: device.id.slice(8), ...device});
+            else if (device.fake) fakeDevices.push({name: device.id.slice(8), ...device});
             else devices[device.id] = {name: device.id.slice(8), ...device};
         });
 
+        // Cloud devices are reached over the internet, not the LAN, so they need
+        // no discovery — wire them up right away.
+        cloudDevices.forEach(config => this._addCloudAccessory(config));
+
         const deviceIds = Object.keys(devices);
-        if (deviceIds.length === 0) return this.log.error('No valid configured devices found.');
+        if (deviceIds.length === 0) {
+            if (cloudDevices.length === 0) this.log.error('No valid configured devices found.');
+            return; // cloud-only (or empty) configuration: nothing to discover over LAN
+        }
 
         this.log.info('Starting discovery...');
 
@@ -176,6 +201,70 @@ class TuyaLan {
         }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
     }
 
+    /* ------------------------------------------------------------------ *
+     *  Tuya Cloud helpers (for devices that can't be reached over the LAN,
+     *  e.g. battery-powered "sleepy" irrigation timers). This plugin stays
+     *  LAN-first; these paths are only exercised by devices opting in with
+     *  `cloud: true` (or a per-device `cloud` credentials object).
+     * ------------------------------------------------------------------ */
+
+    _isCloudDevice(device) {
+        return !!(device && (device.cloud === true || (typeof device.cloud === 'object' && device.cloud)));
+    }
+
+    // Effective cloud credentials/options for a device: the platform-level
+    // `cloud` block, overlaid with any per-device `cloud` object.
+    _resolveCloudConfig(device) {
+        const platform = (this.config.cloud && typeof this.config.cloud === 'object') ? this.config.cloud : {};
+        const perDevice = (typeof device.cloud === 'object' && device.cloud) ? device.cloud : {};
+        return {...platform, ...perDevice};
+    }
+
+    // One TuyaCloudApi per credential set, so multiple cloud devices on the
+    // same Tuya project share a single token.
+    _getCloudApi(cloudCfg) {
+        const key = TuyaCloudApi.keyFor(cloudCfg);
+        if (!this.cloudApis.has(key)) {
+            this.cloudApis.set(key, new TuyaCloudApi({...cloudCfg, log: this.log}));
+        }
+        return this.cloudApis.get(key);
+    }
+
+    // One shared realtime (MQTT) stream per credential set, unless realtime is
+    // disabled. Returns null when realtime is off — the device then shows its
+    // initial state and stays controllable, but won't receive live updates.
+    _getCloudMessaging(api, cloudCfg) {
+        const realtime = cloudCfg.realtime === undefined ? true : coerceBoolean(cloudCfg.realtime, true);
+        if (!realtime) return null;
+        const key = TuyaCloudApi.keyFor(cloudCfg);
+        if (!this.cloudMessagers.has(key)) {
+            this.cloudMessagers.set(key, new TuyaCloudMessaging({api, log: this.log}));
+        }
+        return this.cloudMessagers.get(key);
+    }
+
+    _addCloudAccessory(config) {
+        const cloudCfg = this._resolveCloudConfig(config);
+        if (!cloudCfg.accessId || !cloudCfg.accessKey) {
+            return this.log.error('%s (%s) is configured for the Tuya Cloud, but no credentials were found. Add a top-level "cloud" block (accessId, accessKey, region) or a per-device "cloud" object.', config.name, config.id);
+        }
+
+        const api = this._getCloudApi(cloudCfg);
+        const messaging = this._getCloudMessaging(api, cloudCfg);
+
+        this.log.info('Adding cloud device: %s (%s) via %s', config.name, config.id, api.endpoint);
+
+        this.addAccessory(new TuyaCloudDevice({
+            ...config,
+            cloud: true, // normalise so accessories can detect cloud mode
+            cloudApi: api,
+            messaging,
+            log: this.log,
+            UUID: UUID.generate(UUID_SEED + ':' + config.id),
+            connect: false
+        }));
+    }
+
     registerPlatformAccessories(platformAccessories) {
         this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, Array.isArray(platformAccessories) ? platformAccessories : [platformAccessories]);
     }

package/lib/IrrigationSystemAccessory.js

@@ -45,15 +45,20 @@ class IrrigationSystemAccessory extends BaseAccessory {
         // Self-contained (no reliance on instance state) so it is safe to call
         // both during early service reconciliation and later when wiring
         // characteristics.
+        const cloud = this._isCloud();
         const defaultDuration = isFinite(this.device.context.defaultDuration) ? parseInt(this.device.context.defaultDuration) : 600;
 
         if (Array.isArray(this.device.context.valves) && this.device.context.valves.length) {
             return this.device.context.valves.map((valve, i) => {
-                if (!valve || !isFinite(valve.dp) || parseInt(valve.dp) <= 0) {
-                    throw new Error(`The valve definition #${i + 1} is missing a valid 'dp': ${JSON.stringify(valve)}`);
+                // A data-point may be a numeric LAN id (1, 2, …) or a Tuya Cloud
+                // code (e.g. "switch_1"). Accept either; only an empty value is
+                // invalid.
+                const dp = (valve && valve.dp !== undefined && valve.dp !== null) ? ('' + valve.dp).trim() : '';
+                if (!dp) {
+                    throw new Error(`The valve definition #${i + 1} is missing a 'dp': ${JSON.stringify(valve)}`);
                 }
                 return {
-                    dp: String(parseInt(valve.dp)),
+                    dp,
                     name: (('' + (valve.name || '')).trim()) || ('Zone ' + (i + 1)),
                     index: i + 1,
                     duration: isFinite(valve.defaultDuration) ? parseInt(valve.defaultDuration) : defaultDuration
@@ -66,7 +71,9 @@ class IrrigationSystemAccessory extends BaseAccessory {
         const configs = [];
         for (let i = 0; i < count; i++) {
             configs.push({
-                dp: String(i + 1),
+                // Cloud devices address valves by code (switch_1, switch_2, …);
+                // LAN devices by numeric data-point id (1, 2, …).
+                dp: cloud ? ('switch_' + (i + 1)) : String(i + 1),
                 name: 'Valve ' + (letters[i] || (i + 1)),
                 index: i + 1,
                 duration: defaultDuration
@@ -75,6 +82,21 @@ class IrrigationSystemAccessory extends BaseAccessory {
         return configs;
     }
 
+    // True when this device is reached over the Tuya Cloud (data-points keyed by
+    // string code) rather than the LAN (numeric data-point ids).
+    _isCloud() {
+        return this._coerceBoolean(this.device.context.cloud, false);
+    }
+
+    // Resolve a configurable data-point that may be given as a numeric LAN id or
+    // a Tuya Cloud code, falling back to a sensible default for the active
+    // transport.
+    _resolveDP(value, cloudDefault, lanDefault) {
+        const v = (value === undefined || value === null) ? '' : ('' + value).trim();
+        if (v !== '') return v;
+        return this._isCloud() ? cloudDefault : lanDefault;
+    }
+
     _hasBattery() {
         return !this._coerceBoolean(this.device.context.noBattery, false);
     }
@@ -186,9 +208,11 @@ class IrrigationSystemAccessory extends BaseAccessory {
         this._cascadeOn = this._coerceBoolean(this.device.context.masterTurnsOnAllZones, true);
         this._cascadeOff = this._coerceBoolean(this.device.context.masterTurnsOffAllZones, true);
 
-        this.dpBattery = this._getCustomDP(this.device.context.dpBattery) || '46';
-        this.dpCharging = this._getCustomDP(this.device.context.dpCharging) || '101';
-        this.dpRain = this._getCustomDP(this.device.context.dpRain) || '49';
+        // Data-points accept a numeric LAN id or a Tuya Cloud code; defaults
+        // differ per transport (cloud uses the standard Tuya codes).
+        this.dpBattery = this._resolveDP(this.device.context.dpBattery, 'battery_percentage', '46');
+        this.dpCharging = this._resolveDP(this.device.context.dpCharging, 'charge_state', '101');
+        this.dpRain = this._resolveDP(this.device.context.dpRain, 'rain_sensor_state', '49');
         this._rainOnValue = ('' + (this.device.context.rainOnValue || 'rain')).trim();
         this._rainInverted = this._coerceBoolean(this.device.context.rainInverted, false);