homebridge-tuya-plus 3.14.0-dev.26 → 3.14.0-dev.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/Readme.MD +39 -3
  2. package/package.json +1 -1
  3. package/wiki/Tuya-Cloud-Setup.md +104 -4
package/Readme.MD CHANGED
@@ -48,9 +48,30 @@ A community-maintained Homebridge plugin for controlling Tuya devices locally ov
48
48
  * Switches<sup>[15](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#switch)</sup>
49
49
  * Vertical Blinds<sup>[16](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Supported-Device-Types.md#vertical-blinds-with-tilt)</sup>
50
50
 
51
- ## Cloud fallback
51
+ Note: Motion, and other sensor types don't behave well with responce requests, so they will not be added.
52
52
 
53
- 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".
53
+ ## Supported Tuya Protocol Versions
54
+
55
+ The plugin speaks every published Tuya LAN protocol version:
56
+
57
+ | Tuya LAN protocol | Framing | Encryption | Status |
58
+ |---|---|---|---|
59
+ | 3.1 | `0x55AA` | AES-128-ECB (base64, control only) | ✅ Supported |
60
+ | 3.2 | `0x55AA` | AES-128-ECB | ✅ Supported |
61
+ | 3.3 | `0x55AA` | AES-128-ECB | ✅ Supported |
62
+ | 3.4 | `0x55AA` | AES-128-ECB, session key, HMAC-SHA256 | ✅ Supported |
63
+ | 3.5 | `0x6699` | AES-128-GCM, session key | ✅ Supported |
64
+ | 3.6 and newer | — | — | ✅ Forward-compatible (see below) |
65
+
66
+ The protocol version is auto-detected from the device's discovery broadcast, so you normally don't need to configure anything.
67
+
68
+ 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.
69
+
70
+ 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).
71
+
72
+ ## Cloud fallback (optional)
73
+
74
+ 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 one 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" irrigation timers). 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".
54
75
 
55
76
  See the **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** for credentials and setup.
56
77
 
@@ -69,7 +90,8 @@ sudo npm install -g homebridge-tuya-plus
69
90
  #### Bleeding-edge (`dev`) builds:
70
91
 
71
92
  Every commit to `main` is automatically published to npm under the `dev` tag — a
72
- separate, unstable channel. To try the latest in-development build:
93
+ separate, unstable channel. The stable release always stays on `latest`, so this
94
+ won't affect normal installs. To try the latest in-development build:
73
95
 
74
96
  ```
75
97
  sudo npm install -g homebridge-tuya-plus@dev
@@ -78,6 +100,20 @@ sudo npm install -g homebridge-tuya-plus@dev
78
100
  These are versioned like `3.14.0-dev.<n>` and may be unstable; use the default
79
101
  install above for production.
80
102
 
103
+ #### Testing a specific pull request:
104
+
105
+ Maintainers can publish an unmerged PR as a throwaway test build by commenting
106
+ `/publish` on it. The build goes to its own `pr-<number>` tag — never `latest`
107
+ or `dev` — so it never reaches normal installs. The bot replies on the PR with
108
+ the exact install command, e.g.:
109
+
110
+ ```
111
+ sudo npm install -g homebridge-tuya-plus@pr-57
112
+ ```
113
+
114
+ Each build also gets a unique, immutable version like `3.14.0-pr.57.<n>` that you
115
+ can pin or paste into the Homebridge UI's "Install Alternate Version" field.
116
+
81
117
  ## Configuration
82
118
  > UI
83
119
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "homebridge-tuya-plus",
3
- "version": "3.14.0-dev.26",
3
+ "version": "3.14.0-dev.27",
4
4
  "description": "A community-maintained Homebridge plugin for controlling Tuya devices in HomeKit. LAN-first, with an optional Tuya Cloud fallback for any device the LAN can't reach.",
5
5
  "main": "index.js",
6
6
  "scripts": {
package/wiki/Tuya-Cloud-Setup.md CHANGED
@@ -4,9 +4,12 @@ This plugin is **LAN-first** — every Tuya device is controlled locally wheneve
4
4
 
5
5
  It helps in two situations:
6
6
 
7
- > **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.)
7
+ > **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.)
8
8
 
9
- > **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.
9
+ > **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.
10
+
11
+ * Initial state + control go through the Tuya OpenAPI (signed HTTPS).
12
+ * Live updates (including physical button presses) arrive over Tuya's **MQTT** message service — no polling.
10
13
 
11
14
  ---
12
15
 
@@ -35,10 +38,107 @@ Still in the project: **Devices → Link App Account → Add App Account**, then
35
38
 
36
39
  ## 4. Find the device ID
37
40
 
38
- **Devices → All Devices** → click your device → copy its **Device ID** (a string like `bfae6739…tfx`). (You can also find it in Tuya/Smart Life apps: device → ✎/⚙ → *Device Information*.)
41
+ **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*.)
42
+
43
+ ---
44
+
45
+ ## 5. Configure the plugin
46
+
47
+ 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.
48
+
49
+ 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:
50
+
51
+ ### Smart Home project (recommended — what most people have)
52
+
53
+ Authenticates as your app account (username/password), so it sees exactly the devices linked in step 3.
54
+
55
+ ```json5
56
+ {
57
+ "platform": "TuyaLan",
58
+ "cloud": {
59
+ "accessId": "your-access-id",
60
+ "accessKey": "your-access-secret",
61
+ "region": "eu", // eu / us / cn / in / sg / eu-w / us-e
62
+ "username": "you@example.com", // your Tuya/Smart Life app login
63
+ "password": "your-app-password",
64
+ "countryCode": "48", // your phone country code (e.g. 1, 44, 48)
65
+ "schema": "tuyaSmart" // or "smartlife" if you use the Smart Life app
66
+ },
67
+ "devices": [
68
+ {
69
+ "name": "Garden Irrigation",
70
+ "type": "IrrigationSystem",
71
+ "id": "bfae6739xxxxxxxxxxxxxx", // the cloud Device ID
72
+ "valveCount": 4
73
+ // no "key" -> this device is reached over the cloud
74
+ }
75
+ ]
76
+ }
77
+ ```
78
+
79
+ ### Custom project
80
+
81
+ If you created a **Custom** project (devices linked by QR to the project's asset) just omit `username`/`password`/`countryCode`/`schema`:
82
+
83
+ ```json5
84
+ "cloud": {
85
+ "accessId": "your-access-id",
86
+ "accessKey": "your-access-secret",
87
+ "region": "eu"
88
+ }
89
+ ```
90
+
91
+ > 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`.
39
92
 
40
93
  ---
41
94
 
95
+ ## Data-points: numbers on the LAN, codes on the cloud
96
+
97
+ 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.
98
+
99
+ When a cloud device connects, the plugin **logs the data-points** it reports (code and numeric id), e.g.:
100
+
101
+ ```
102
+ 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
103
+ ```
104
+
105
+ 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:
106
+
107
+ ```json5
108
+ "valves": [
109
+ { "name": "Front Lawn", "dp": "switch_1", "defaultDuration": 900 },
110
+ { "name": "Back Lawn", "dp": "switch_2", "defaultDuration": 900 }
111
+ ],
112
+ "dpBattery": "battery_percentage"
113
+ ```
114
+
115
+ 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.).
116
+
117
+ ---
118
+
119
+ ## Realtime updates (MQTT)
120
+
121
+ 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:
122
+
123
+ ```
124
+ sudo npm install -g mqtt
125
+ ```
126
+
127
+ 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).
128
+
129
+ ---
130
+
131
+ ## Troubleshooting
132
+
133
+ | Symptom | Cause / fix |
134
+ |---|---|
135
+ | `Tuya Cloud connection failed: token request failed … (code 1004)` | Wrong **Access ID/Secret**, or host clock skew — the signature includes a timestamp, so keep the machine **NTP-synced**. |
136
+ | `… (code 1106) permission deny` / `(code 40001900) No space permission` | 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, or this specific device isn't linked to the project (step 3). The cloud backs every device as a fallback, so a single LAN-only device that isn't in the project logs this once — harmless if that device already works over the LAN. |
137
+ | 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). |
138
+ | `realtime disabled: the optional "mqtt" package is not installed` | Install `mqtt` (above), or ignore if you don't need live external updates. |
139
+ | Realtime never connects (control works, external changes don't) | Outbound **port 8883** blocked by a firewall. |
140
+ | Logs show different codes than expected | Use the codes from the startup log line shown above. |
141
+
42
142
  ### Security note
43
143
 
44
- 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.
144
+ 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.