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

package/Readme.MD

@@ -14,7 +14,7 @@
 
 
 
-A community-maintained Homebridge plugin for controlling Tuya devices locally over LAN. Control your supported Tuya accessories locally in HomeKit.
+A community-maintained Homebridge plugin for controlling Tuya devices locally over LAN. Control your supported Tuya accessories locally in HomeKit, with an optional Tuya Cloud fallback for devices the LAN can't reach.
 
 * [Supported Device Types](#supported-device-types)
 * [Supported Tuya Protocol Versions](#supported-tuya-protocol-versions)
@@ -38,7 +38,7 @@ A community-maintained Homebridge plugin for controlling Tuya devices locally ov
 * Fan v2<sup>[7](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md)</sup>
 * Garages<sup>[8](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#garage-doors)</sup>
 * Heaters<sup>[9](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md)</sup>
-* Irrigation Systems / Sprinklers<sup>[17](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#irrigation-systems--sprinklers)</sup> (multi-valve, per-zone timers, rain sensor, battery)
+* Irrigation Systems / Sprinklers<sup>[17](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#irrigation-systems--sprinklers)</sup> (multi-valve, per-zone timers, battery)
 * Lights
   * On/Off<sup>[10](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md)</sup>
   * Brightness<sup>[11](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#tunable-white-light-bulbs)</sup>
@@ -48,34 +48,11 @@ A community-maintained Homebridge plugin for controlling Tuya devices locally ov
 * Switches<sup>[15](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#switch)</sup>
 * Vertical Blinds<sup>[16](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#vertical-blinds-with-tilt)</sup>
 
-Note: Motion, and other sensor types don't behave well with responce requests, so they will not be added. 
+## Cloud fallback
 
-## Supported Tuya Protocol Versions
+The plugin is LAN-first — everything is controlled locally by default. If you add Tuya Cloud credentials in a top-level `cloud` block, it keeps a cloud session in the background and uses it as a fallback: each device is tried on the LAN first, and only falls back to the cloud when it can't be reached locally — a brief LAN hiccup, or hardware that never appears on the LAN at all (e.g. battery-powered "sleepy" devices). It's opt-in and local always comes first, and existing configs need no changes — so it's also a handy fix if some devices occasionally show as "No Response".
 
-The plugin speaks every published Tuya LAN protocol version:
-
-| Tuya LAN protocol | Framing | Encryption | Status |
-|---|---|---|---|
-| 3.1 | `0x55AA` | AES-128-ECB (base64, control only) | ✅ Supported |
-| 3.2 | `0x55AA` | AES-128-ECB | ✅ Supported |
-| 3.3 | `0x55AA` | AES-128-ECB | ✅ Supported |
-| 3.4 | `0x55AA` | AES-128-ECB, session key, HMAC-SHA256 | ✅ Supported |
-| 3.5 | `0x6699` | AES-128-GCM, session key | ✅ Supported |
-| 3.6 and newer | — | — | ✅ Forward-compatible (see below) |
-
-The protocol version is auto-detected from the device's discovery broadcast, so you normally don't need to configure anything.
-
-Protocol **3.5** is currently the newest Tuya LAN protocol in existence: it is the latest version implemented by Tuya's own open-source device SDK ([TuyaOpen](https://github.com/tuya/TuyaOpen)) and by the reference reverse-engineered implementations ([tinytuya](https://github.com/jasonacox/tinytuya/blob/master/PROTOCOL.md)). No device firmware speaking a "3.6" protocol has been observed in the wild so far.
-
-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.
+See the **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** for credentials and setup.
 
 ## Installation Instructions
 
@@ -92,14 +69,13 @@ sudo npm install -g homebridge-tuya-plus
 #### Bleeding-edge (`dev`) builds:
 
 Every commit to `main` is automatically published to npm under the `dev` tag — a
-separate, unstable channel. The stable release always stays on `latest`, so this
-won't affect normal installs. To try the latest in-development build:
+separate, unstable channel. To try the latest in-development build:
 
 ```
 sudo npm install -g homebridge-tuya-plus@dev
 ```
 
-These are versioned like `3.13.1-dev.<n>` and may be unstable; use the default
+These are versioned like `3.14.0-dev.<n>` and may be unstable; use the default
 install above for production.
 
 ## Configuration
@@ -134,7 +110,7 @@ If you have new accessory logic for a new device, please add a function defined
 
 #
 
-Go check out my other Homebridge plugins:
+Check out my other Homebridge plugins:
 
 * [homebridge-futurehome](https://github.com/adrianjagielak/homebridge-futurehome) ([npm](https://npmjs.com/package/homebridge-futurehome))
 * [homebridge-tuya-plus](https://github.com/adrianjagielak/homebridge-tuya-plus) ([npm](https://npmjs.com/package/homebridge-tuya-plus))

package/config.schema.json

@@ -21,8 +21,8 @@
       },
       "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.",
+        "title": "Tuya Cloud fallback (optional)",
+        "description": "<a href='https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md'>Tuya Cloud API Setup</a>.",
         "properties": {
           "accessId": {
             "type": "string",
@@ -69,12 +69,6 @@
               { "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."
           }
         }
       },
@@ -96,7 +90,7 @@
                 {
                   "title": "Switch Gang / Basic Switch",
                   "enum": ["Switch"]
-                },                
+                },
                 {
                   "title": "Smart Plug / Barely Smart Power Strip",
                   "enum": ["Outlet"]
@@ -197,16 +191,7 @@
             "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.",
+              "description": "The device's local key. Required for normal (LAN) devices. A device with no key is treated as cloud-only and is reached through the Tuya Cloud session configured above (e.g. a battery-powered 'sleepy' irrigation timer).",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -318,9 +303,9 @@
               "title": "Sync brightness to WLED (IP[:port])",
               "placeholder": "192.168.1.100",
               "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['WledDimmer', 'SimpleDimmer'].includes(model.devices[arrayIndices].type);"
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['WledDimmer'].includes(model.devices[arrayIndices].type);"
               }
-            },            
+            },
             "dpColorTemperature": {
               "type": "integer",
               "placeholder": "3",
@@ -421,6 +406,12 @@
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
               }
             },
+            "noAuto": {
+              "type": "boolean",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
+              }
+            },
             "cmdCool": {
               "type": "string",
               "placeholder": "COOL",
@@ -435,6 +426,32 @@
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
               }
             },
+            "cmdAuto": {
+              "type": "string",
+              "placeholder": "AUTO",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
+              }
+            },
+            "noRotationSpeed": {
+              "type": "boolean",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
+              }
+            },
+            "fanSpeedSteps": {
+              "type": "integer",
+              "placeholder": "3",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
+              }
+            },
+            "noChildLock": {
+              "type": "boolean",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner', 'Convector'].includes(model.devices[arrayIndices].type);"
+              }
+            },
             "noSwing": {
               "type": "boolean",
               "condition": {
@@ -569,30 +586,31 @@
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['Convector'].includes(model.devices[arrayIndices].type);"
               }
             },
-            "noChildLock": {
+            "noTemperatureUnit": {
               "type": "boolean",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['Convector'].includes(model.devices[arrayIndices].type);"
               }
             },
-            "noTemperatureUnit": {
-              "type": "boolean",
+            "temperatureDivisor": {
+              "type": "integer",
+              "placeholder": "1",
               "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['Convector'].includes(model.devices[arrayIndices].type);"
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleHeater', 'AirConditioner'].includes(model.devices[arrayIndices].type);"
               }
             },
-            "temperatureDivisor": {
+            "currentTemperatureDivisor": {
               "type": "integer",
               "placeholder": "1",
               "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleHeater'].includes(model.devices[arrayIndices].type);"
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['AirConditioner'].includes(model.devices[arrayIndices].type);"
               }
             },
             "thresholdTemperatureDivisor": {
               "type": "integer",
               "placeholder": "1",
               "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleHeater'].includes(model.devices[arrayIndices].type);"
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleHeater', 'AirConditioner'].includes(model.devices[arrayIndices].type);"
               }
             },
             "temperatureOffset": {
@@ -717,7 +735,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, … (or, for cloud devices, on the codes switch_1, switch_2, …). 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, … (over the cloud these map to the codes switch_1, switch_2, … automatically). For non-sequential data-points use the 'valves' list instead.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
               }
@@ -730,9 +748,27 @@
               "items": {
                 "type": "object",
                 "properties": {
-                  "name": { "type": "string", "title": "Zone name", "placeholder": "Lawn" },
-                  "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 }
+                  "name": {
+                    "type": "string",
+                    "title": "Zone name",
+                    "placeholder": "Lawn"
+                  },
+                  "dp": {
+                    "type": ["integer", "string"],
+                    "title": "Data-point (numeric id, or cloud code)",
+                    "placeholder": "1 or switch_1"
+                  },
+                  "dpCountdown": {
+                    "type": ["integer", "string"],
+                    "title": "Countdown data-point (numeric id, or cloud code)",
+                    "description": "Optional. The device's built-in auto-off timer for this zone. Defaults to the switch data-point + 16 (so switch 1 → countdown 17). Set this only for code-addressed or non-standard zones.",
+                    "placeholder": "17 or countdown_1"
+                  },
+                  "defaultDuration": {
+                    "type": "integer",
+                    "title": "Default run time (seconds, 0 = run indefinitely)",
+                    "placeholder": 600
+                  }
                 }
               },
               "condition": {
@@ -752,7 +788,16 @@
               "type": "integer",
               "title": "Maximum Run Time (seconds)",
               "placeholder": 7200,
-              "description": "Upper bound advertised to HomeKit for the duration picker (HAP default is 3600 / 1h). Apple's Home app only offers presets up to 1h regardless; longer values can be set from the config or apps like Eve.",
+              "description": "Upper bound advertised to HomeKit for the duration picker (HAP default is 3600 / 1h). Apple's Home app only offers presets up to 1h regardless; longer values can be set from the config or apps like Eve. Also bounds the hardware countdown: a device countdown longer than this (or the 120-min hardware cap) is corrected on connect.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
+              }
+            },
+            "nativeCountdown": {
+              "type": "boolean",
+              "title": "Use the device's built-in countdown timer",
+              "placeholder": true,
+              "description": "When the controller exposes per-zone countdown data-points (countdown_1.., DP 17.. by default), mirror each zone's duration to the hardware timer so a zone still auto-closes on schedule even if Homebridge or the network drops out mid-run. Disable to fall back to the software-timer-only behaviour. Has no effect on devices that don't report a countdown data-point.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
               }
@@ -817,55 +862,10 @@
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noBattery;"
               }
-            },
-            "noRainSensor": {
-              "type": "boolean",
-              "title": "No rain sensor",
-              "description": "Disable the rain sensor (use if your controller doesn't report 'rain_sensor_state').",
-              "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
-              }
-            },
-            "rainSensorType": {
-              "type": "string",
-              "title": "Rain sensor type",
-              "default": "contact",
-              "oneOf": [
-                { "title": "Contact sensor (Open / Closed)", "enum": ["contact"] },
-                { "title": "Leak sensor (Leak Detected / Dry — note: fires critical alerts)", "enum": ["leak"] }
-              ],
-              "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noRainSensor;"
-              }
-            },
-            "rainInverted": {
-              "type": "boolean",
-              "title": "Invert rain sensor",
-              "description": "Flip the reported state if 'raining' and 'dry' appear reversed in HomeKit.",
-              "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noRainSensor;"
-              }
-            },
-            "dpRain": {
-              "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;"
-              }
-            },
-            "rainOnValue": {
-              "type": "string",
-              "placeholder": "rain",
-              "title": "Rain sensor 'raining' value",
-              "description": "The enum value the device reports when it is raining (default 'rain').",
-              "condition": {
-                "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noRainSensor;"
-              }
             }
           }
         }
       }
     }
   }
-}
+}