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

package/test/TuyaCloudMessaging.test.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const crypto = require('crypto');
+const TuyaCloudMessaging = require('../lib/TuyaCloudMessaging');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+// Encrypt exactly like Tuya's msg_encrypted_version 2.0 (AES-128-GCM):
+//   [ivLen(4 BE)][iv][ciphertext][tag(16)], key = password[8,24), AAD = 6-byte BE t.
+function encryptGCM(plaintext, password, t) {
+    const key = Buffer.from(('' + password).substring(8, 24), 'utf8');
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv('aes-128-gcm', key, iv);
+    const aad = Buffer.allocUnsafe(6); aad.writeUIntBE(Number(t), 0, 6); c.setAAD(aad);
+    const enc = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+    const tag = c.getAuthTag();
+    const ivLen = Buffer.allocUnsafe(4); ivLen.writeUIntBE(iv.length, 0, 4);
+    return Buffer.concat([ivLen, iv, enc, tag]).toString('base64');
+}
+
+// AES-128-ECB / PKCS7 (msg_encrypted_version 1.0).
+function encryptECB(plaintext, password) {
+    const key = Buffer.from(('' + password).substring(8, 24), 'utf8');
+    const c = crypto.createCipheriv('aes-128-ecb', key, null);
+    return Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]).toString('base64');
+}
+
+// A messaging instance that won't try to open a real connection.
+function makeIdle(password = 'abcdefgh0123456789WXYZ!!') {
+    const mq = new TuyaCloudMessaging({api: {}, log});
+    mq._started = true; // prevent start()
+    mq.config = {password};
+    return mq;
+}
+
+function envelope(payloadObj, password, {protocol = 4, t = Date.now(), mode = 'gcm'} = {}) {
+    const data = mode === 'ecb'
+        ? encryptECB(JSON.stringify(payloadObj), password)
+        : encryptGCM(JSON.stringify(payloadObj), password, t);
+    return Buffer.from(JSON.stringify({protocol, data, t}));
+}
+
+describe('TuyaCloudMessaging — decryption + dispatch', () => {
+    test('decrypts a GCM status frame and delivers it to the subscribed device', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+
+        const t = Date.now();
+        mq._onMessage('topic', envelope(
+            {devId: 'DEV1', status: [{code: 'switch_1', value: true, t}, {code: 'battery_percentage', value: 80, t}]},
+            mq.config.password, {t}
+        ));
+
+        expect(received).toHaveLength(1);
+        expect(received[0]).toEqual([{code: 'switch_1', value: true, t}, {code: 'battery_percentage', value: 80, t}]);
+    });
+
+    test('decrypts a legacy ECB (v1.0) frame too', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        mq._onMessage('topic', envelope({devId: 'DEV1', status: [{code: 'switch_2', value: true}]}, mq.config.password, {mode: 'ecb'}));
+        expect(received[0]).toEqual([{code: 'switch_2', value: true}]);
+    });
+
+    test('ignores messages for devices we did not subscribe', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        mq._onMessage('topic', envelope({devId: 'OTHER', status: [{code: 'switch_1', value: true}]}, mq.config.password, {}));
+        expect(received).toHaveLength(0);
+    });
+
+    test('a frame that cannot be decrypted is dropped without throwing', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        // Encrypted with the wrong password → auth/decrypt fails.
+        expect(() => mq._onMessage('topic', envelope({devId: 'DEV1', status: [{code: 'x', value: 1}]}, 'ZZZZZZZZwrongkeywrongkey', {}))).not.toThrow();
+        expect(received).toHaveLength(0);
+    });
+
+    test('malformed JSON envelope is ignored', () => {
+        const mq = makeIdle();
+        mq.subscribeDevice('DEV1', () => { throw new Error('should not be called'); });
+        expect(() => mq._onMessage('topic', Buffer.from('not json'))).not.toThrow();
+    });
+
+    test('reports whether realtime is available (mqtt installed)', () => {
+        // mqtt is an (optional) dependency of this project, so it should load.
+        expect(typeof TuyaCloudMessaging.isAvailable()).toBe('boolean');
+    });
+});

package/wiki/Supported-Device-Types.md

@@ -732,6 +732,20 @@ Multi-valve Tuya irrigation/sprinkler controllers (the battery-powered Wi-Fi "fa
 
 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,
+    "noRainSensor": true              // many battery timers have no rain sensor
+}
+```
+
 #### Minimal Configuration
 
 The defaults match the common 4-zone layout (valves A–D on data-points `1`–`4`, battery on `46`, rain on `49`):

package/wiki/Tuya-Cloud-Setup.md

@@ -0,0 +1,160 @@
+# 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:
+
+> 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.)
+
+For these devices the plugin can talk to the **Tuya Cloud** instead. It is **opt-in, per device** — your other devices stay 100% local.
+
+* 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.
+
+---
+
+## 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
+
+In the project, go to **Service API → Go to Authorize** and make sure these are subscribed (all free):
+
+* **IoT Core**
+* **Authorization**
+* **Smart Home Basic Service**
+* **Device Status Notification** ← needed for realtime MQTT updates
+
+> ⚠️ The free trial of *IoT Core* lasts ~6 months, after which you must click **Extend Trial Period** (Cloud → My Services). If it lapses you'll see *"No permissions. Your subscription … has expired."*
+
+## 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. Find the device ID
+
+**Devices → All Devices** → click your device → copy its **Device ID** (a string like `bfae6739…tfx`). (You can also find it in the Smart Life app: device → ✎/⚙ → *Device Information*.)
+
+---
+
+## 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:
+
+### Smart Home project (recommended — what most people have)
+
+Authenticates as your app account (username/password), so it sees exactly the devices linked in step 3.
+
+```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": [
+        {
+            "name": "Garden Irrigation",
+            "type": "IrrigationSystem",
+            "id": "bfae6739xxxxxxxxxxxxxx",      // the cloud Device ID
+            "cloud": true,
+            "valveCount": 4,
+            "noRainSensor": true                 // most battery timers have no rain DP
+        }
+    ]
+}
+```
+
+### Custom project
+
+If you created a **Custom** project (devices linked by QR to the project's asset) just omit `username`/`password`/`countryCode`/`schema`:
+
+```json5
+"cloud": {
+    "accessId": "your-access-id",
+    "accessKey": "your-access-secret",
+    "region": "eu"
+}
+```
+
+### 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.
+
+---
+
+## Data-points are addressed by "code" 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`). When a cloud device connects, the plugin **logs the exact codes** it reports, 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
+```
+
+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:
+
+```json5
+"valves": [
+    { "name": "Front Lawn", "dp": "switch_1", "defaultDuration": 900 },
+    { "name": "Back Lawn",  "dp": "switch_2", "defaultDuration": 900 }
+],
+"dpBattery": "battery_percentage",
+"noRainSensor": true                  // or: "dpRain": "rain_sensor_state"
+```
+
+See **[Irrigation Systems / Sprinklers](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#irrigation-systems--sprinklers)** for all options (per-zone durations, master switch, etc.).
+
+---
+
+## Realtime updates (MQTT)
+
+Live updates use Tuya's MQTT message service via the **`mqtt`** package, which is an *optional dependency* installed automatically. If it's missing (or `"realtime": false`), cloud devices still work and stay controllable, but external changes (a physical button, the device's own timer) won't show up until Homebridge restarts. To force-install it:
+
+```
+sudo npm install -g mqtt
+```
+
+The realtime stream connects out to Tuya's broker on **port 8883** — make sure your firewall allows that outbound (it's open on normal home networks).
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `failed to connect to Tuya Cloud: token request failed … (code 1004)` | Wrong **Access ID/Secret**, or host clock skew — the signature includes a timestamp, so keep the machine **NTP-synced**. |
+| `… (code 1106) permission deny` / `No permissions` | API service not authorized or **trial expired** (step 2), or **wrong region**, or you logged in with the developer account instead of the **app** account. |
+| Device connects but shows nothing / `0` devices | **Region mismatch**, or the device isn't linked to the project (step 3), or the linked account isn't the device's **owner** (shared/guest access hides devices). |
+| `realtime disabled: the optional "mqtt" package is not installed` | Install `mqtt` (above), or ignore if you don't need live external updates. |
+| Realtime never connects (control works, external changes don't) | Outbound **port 8883** blocked by a firewall. |
+| Logs show different codes than expected | Use the codes from the startup log line shown above. |
+
+### 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 — and you can always reset the Access Secret on the Tuya IoT platform.