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

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 +4 -40
  2. package/package.json +1 -1
  3. package/wiki/Tuya-Cloud-Setup.md +7 -91
package/Readme.MD CHANGED
@@ -48,30 +48,9 @@ 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
- Note: Motion, and other sensor types don't behave well with responce requests, so they will not be added.
51
+ ## Cloud fallback
52
52
 
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".
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".
75
54
 
76
55
  See the **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** for credentials and setup.
77
56
 
@@ -90,8 +69,7 @@ sudo npm install -g homebridge-tuya-plus
90
69
  #### Bleeding-edge (`dev`) builds:
91
70
 
92
71
  Every commit to `main` is automatically published to npm under the `dev` tag — a
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:
72
+ separate, unstable channel. To try the latest in-development build:
95
73
 
96
74
  ```
97
75
  sudo npm install -g homebridge-tuya-plus@dev
@@ -100,20 +78,6 @@ sudo npm install -g homebridge-tuya-plus@dev
100
78
  These are versioned like `3.14.0-dev.<n>` and may be unstable; use the default
101
79
  install above for production.
102
80
 
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
-
117
81
  ## Configuration
118
82
  > UI
119
83
 
@@ -146,7 +110,7 @@ If you have new accessory logic for a new device, please add a function defined
146
110
 
147
111
  #
148
112
 
149
- Go check out my other Homebridge plugins:
113
+ Check out my other Homebridge plugins:
150
114
 
151
115
  * [homebridge-futurehome](https://github.com/adrianjagielak/homebridge-futurehome) ([npm](https://npmjs.com/package/homebridge-futurehome))
152
116
  * [homebridge-tuya-plus](https://github.com/adrianjagielak/homebridge-tuya-plus) ([npm](https://npmjs.com/package/homebridge-tuya-plus))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "homebridge-tuya-plus",
3
- "version": "3.14.0-dev.27",
3
+ "version": "3.14.0-dev.29",
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,12 +4,9 @@ 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.** 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.)
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.)
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 — 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.
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.
13
10
 
14
11
  ---
15
12
 
@@ -30,27 +27,15 @@ In the project, go to **Service API → Go to Authorize** and make sure these ar
30
27
  * **Smart Home Basic Service**
31
28
  * **Device Status Notification** ← needed for realtime MQTT updates
32
29
 
33
- > ⚠️ 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."*
30
+ > **⚠️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).**
34
31
 
35
32
  ## 3. Link your app account (so the project can see your devices)
36
33
 
37
34
  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**.
38
35
 
39
- ## 4. Find the device ID
40
-
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
36
+ ## 4. Configure the plugin
46
37
 
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.
38
+ Add a **top-level `cloud` block** with your credentials:
54
39
 
55
40
  ```json5
56
41
  {
@@ -65,80 +50,11 @@ Authenticates as your app account (username/password), so it sees exactly the de
65
50
  "schema": "tuyaSmart" // or "smartlife" if you use the Smart Life app
66
51
  },
67
52
  "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
- }
53
+ // ...
75
54
  ]
76
55
  }
77
56
  ```
78
57
 
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`.
92
-
93
- ---
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
-
142
58
  ### Security note
143
59
 
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.
60
+ 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.