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

package/wiki/Supported-Device-Types.md

@@ -15,7 +15,8 @@ If you are looking for verified configurations for your specific device, please
 |Barely Smart Power Strip|`Outlet`|Smart power strips that don't allow individual control of the outlets|
 |Air Conditioner|`AirConditioner`<sup>[6](#air-conditioners)</sup>|Cooling and heating devices <small>([instructions](#air-conditioners))</small>|
 |Heat Convector|`Convector`<sup>[7](#heat-convectors)</sup>|Heating panels <small>([instructions](#heat-convectors))</small>|
-|WLED Dimmer|`WledDimmer` (or legacy `SimpleDimmer`)<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control, with optional WLED sync <small>([instructions](#simple-dimmers))</small>|
+|Simple Dimmer|`SimpleDimmer`<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control <small>([instructions](#simple-dimmers))</small>|
+|WLED Dimmer|`WledDimmer`<sup>[8](#simple-dimmers)</sup>|Dimmer switches with power control, plus optional WLED brightness sync and preset-effect switches <small>([instructions](#simple-dimmers))</small>|
 |Simple Heater|`SimpleHeater`<sup>[9](#simple-heaters)</sup>|Heating solutions with only temperature control <small>([instructions](#simple-heaters))</small>|
 |Garage Door|`GarageDoor`<sup>[10](#garage-doors)</sup>|Smart garage doors or garage door openers <small>([instructions](#garage-doors))</small>|
 |Simple Garage Door|`SimpleGarageDoor`<sup>[10](#simple-garage-doors)</sup>|Sliding gate openers and garage door controllers with open/stop/close action DPs and a simple three-value status DP <small>([instructions](#simple-garage-doors))</small>|
@@ -223,7 +224,17 @@ Some smart power strips don't have sequential data-points. Using `CustomMultiOut
 ```
 
 ### Air Conditioners
-These devices have cooling and/or heating capabilities; they could also have _dry_, _fan_, or others modes but HomeKit's definition doesn't facilitate modes other than _heat_, _cool_, and _auto_. By default, _heat_ and _cool_ modes are enabled; to let the plugin know that a device doesn't have heating or cooling capabilities, add an additional parameter named `noHeat` or `noCool` and set it to `true`. Tuya devices don't follow a unified pattern for naming the modes, for example cooling mode is called _COOL_ on Kogan's KAPRA14WFGA and _cold_ on Igenix's IG9901WIFI; by default, the plugin uses the phrases _COOL_ and _HEAT_ while communicating with your device but to let the plugin know that a device has different phrases, add additional parameters using `cmdHeat` and `cmdCool`. Additional parameters can be found in the sample below.
+These devices have cooling and/or heating capabilities; they could also have _dry_, _fan_, or others modes but HomeKit's definition doesn't facilitate modes other than _heat_, _cool_, and _auto_. By default, _heat_, _cool_ and _auto_ modes are enabled; to let the plugin know that a device doesn't have heating, cooling or auto capabilities, add an additional parameter named `noHeat`, `noCool` or `noAuto` and set it to `true`.
+
+Tuya devices don't follow a unified pattern for naming the modes, for example cooling mode is called _COOL_ on Kogan's KAPRA14WFGA but _cold_ on Igenix's IG9901WIFI and most "standard" Tuya AC (category `kt`) firmwares. The phrases are also **case-sensitive**. By default, the plugin uses the phrases _COOL_, _HEAT_ and _AUTO_ while communicating with your device; if your device uses different phrases (a very common case — many ACs report lowercase `cold` / `hot` / `auto` / `wet` / `wind`), override them with `cmdCool`, `cmdHeat` and `cmdAuto`. If the modes don't switch at all, this is almost always the reason.
+
+> **Tip — finding the exact phrases.** The phrases are the raw values of the `mode` data-point (DP `4`). You can read them from the [Tuya IoT Platform](https://iot.tuya.com) → _Cloud → API Explorer → Query Things Data Model_ (or _Get Device Specification_) for your device. For example, a device whose `mode` enum range is `["auto","cold","wet","wind","hot"]` needs `cmdCool: "cold"`, `cmdHeat: "hot"`, `cmdAuto: "auto"`.
+
+The fan speed data-point (DP `5`, `windspeed`) is usually an **enum of string values** like `"1"`, `"2"`, `"3"`. Set `fanSpeedSteps` to the number of speeds (e.g. `3`); this both maps HomeKit's 0–100 % slider onto the right number of steps and — importantly — sends the speed as a string, which these firmwares require. Without it the fan may silently ignore speed changes.
+
+Many ACs have no child-lock data-point; if yours doesn't, set `noChildLock: true` so the plugin doesn't add a (non-functional) lock control. Likewise, set `noRotationSpeed: true` if the device has no fan-speed control.
+
+Additional parameters can be found in the sample below.
 
 ```json5
 {
@@ -242,12 +253,27 @@ These devices have cooling and/or heating capabilities; they could also have _dr
     /* This device has no heating function */
     "noHeat": true ,
 
-    /* Override cooling phrase */
+    /* This device has no auto function */
+    "noAuto": true,
+
+    /* Override cooling phrase (case-sensitive; e.g. "cold" on many devices) */
     "cmdCool": "COOL",
 
-    /* Override heating phrase */
+    /* Override heating phrase (case-sensitive; e.g. "hot" on many devices) */
     "cmdHeat": "HEAT",
 
+    /* Override auto phrase (case-sensitive; e.g. "auto" on many devices) */
+    "cmdAuto": "AUTO",
+
+    /* Number of fan speeds; also sends the speed as a string (required by most ACs) */
+    "fanSpeedSteps": 3,
+
+    /* This device has no fan-speed control */
+    "noRotationSpeed": true,
+
+    /* This device has no child-lock data-point */
+    "noChildLock": true,
+
     /* This device has no oscillation (swinging) function */
     "noSwing": true,
 
@@ -258,7 +284,10 @@ These devices have cooling and/or heating capabilities; they could also have _dr
     "maxTemperature": 40,
 
     /* Temperature change steps, in Celsius (°C) */
-    "minTemperatureSteps": 1
+    "minTemperatureSteps": 1,
+
+    /* Only if your firmware reports/accepts temperatures scaled by 10 (e.g. 170 = 17.0 °C) */
+    "temperatureDivisor": 10
 }
 ```
 
@@ -317,14 +346,15 @@ If your signature doesn't have a variation of _low_ or _high_, `SimpleHeater` wo
 ```
 
 ### Simple Dimmers / WLED Dimmers
-These are switches that allow turning on and off, and dimming. Use type `WledDimmer` (legacy `SimpleDimmer` alias is also supported for backward compatibility).
+These are switches that allow turning on and off, and dimming. Two distinct types are available:
 
-When using with a WLED controller (e.g. a Tuya-based relay/dimmer feeding power to a WLED strip), you can use advanced sync options:
+- `SimpleDimmer` — a plain dimmer with power and brightness control.
+- `WledDimmer` — a dimmer that can additionally drive a [WLED](https://kno.wled.ge/) controller (e.g. a Tuya-based relay/dimmer feeding power to a WLED strip). With none of the WLED options below configured, it behaves exactly like a `SimpleDimmer`.
 
-- `syncBrightnessToWled`: set to WLED device IP (e.g. "192.168.1.50" or "192.168.1.50:80") to sync HomeKit brightness changes directly to WLED over HTTP, keeping the Tuya dimmer at 100%.
-- `presetEffects`: array of effect configs to expose as switches in HomeKit (each turns on a WLED fx preset, optionally with staticColor).
+The following options apply to `WledDimmer` only (they are ignored by `SimpleDimmer`):
 
-See the accessory source for full details on WLED integration.
+- `syncBrightnessToWled`: set to the WLED device IP (e.g. "192.168.1.50" or "192.168.1.50:80") to sync HomeKit brightness changes directly to WLED over HTTP, keeping the Tuya dimmer at 100%. This talks to the WLED controller directly on your **LAN**, independently of how the Tuya dimmer is reached — so if the Tuya dimmer is ever on the cloud fallback (because the LAN is down), the WLED sync is best-effort and may not go through until the LAN is back.
+- `presetEffects`: array of effect configs to expose as switches in HomeKit (each turns on a WLED fx preset, optionally with staticColor).
 
 ```json5
 {
@@ -470,9 +500,10 @@ external stop, where close is accepted immediately), a close is sent as
     /* Optional. If set, exposes an extra stateful switch that mirrors
        whether the gate is currently open in HomeKit's view. Tapping it
        ON triggers a partial-open: the gate opens and then stops itself
-       this many milliseconds later, leaving the gate partially open.
-       Tapping it OFF triggers a standard full close. Useful for letting
-       someone pass through briefly. Leave unset to skip the switch. */
+       this many milliseconds after it actually starts moving, leaving the
+       gate partially open. Tapping it OFF triggers a standard full close.
+       Useful for letting someone pass through briefly. Leave unset to skip
+       the switch. */
     "partialOpenMs": 2000,
 
     /* Optional. Exposes extra Force Open and Force Close momentary
@@ -723,12 +754,11 @@ If the light, brightness and turning the fan **off** all work, but turning the f
 
 ### Irrigation Systems / Sprinklers
 
-Multi-valve Tuya irrigation/sprinkler controllers (the battery-powered Wi-Fi "faucet timers" that expose several `switch_*` valves, a `battery_percentage` and a `rain_sensor_state`) are exposed as a single, fully-fledged HomeKit **Irrigation System** accessory:
+Multi-valve Tuya irrigation/sprinkler controllers (the battery-powered Wi-Fi "faucet timers" that expose several `switch_*` valves and a `battery_percentage`) are exposed as a single, fully-fledged HomeKit **Irrigation System** accessory:
 
 * one **Irrigation System** tile that contains every zone,
 * one **Valve** per zone (`ValveType = Irrigation`) — each with its own on/off, its own **Duration** picker and a live countdown,
-* an optional **Battery** service (level, low-battery warning, and — for solar/USB-C rechargeable units that report it — live charging status),
-* an optional **rain sensor** (a Contact sensor by default).
+* an optional **Battery** service (level, low-battery warning, and — for solar/USB-C rechargeable units that report it — live charging status).
 
 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.
 
@@ -741,14 +771,13 @@ Because these devices are slow to respond, all zone changes that happen close to
     "type": "IrrigationSystem",
     "id": "bfae6739xxxxxxxxxxxxxx",   // the cloud Device ID
     "cloud": true,
-    "valveCount": 4,
-    "noRainSensor": true              // many battery timers have no rain sensor
+    "valveCount": 4
 }
 ```
 
 #### Minimal Configuration
 
-The defaults match the common 4-zone layout (valves A–D on data-points `1`–`4`, battery on `46`, rain on `49`):
+The defaults match the common 4-zone layout (valves A–D on data-points `1`–`4`, battery on `46`):
 
 ```json5
 {
@@ -763,19 +792,21 @@ The defaults match the common 4-zone layout (valves A–D on data-points `1`–`
 
 #### Per-zone timers and "indefinite" mode
 
-Each zone has its own **Duration**. When a zone is switched on it runs for that duration and the plugin closes it automatically (HomeKit's countdown is display-only — the plugin always enforces the shut-off, even after a Homebridge restart).
+Each zone has its own **Duration**. When a zone is switched on it runs for that duration and is then closed automatically. Two mechanisms enforce this together:
 
-* Set a zone's duration to **`0`** to make it run **indefinitely** (until it is switched off again) — handy for long, manual watering tasks.
+* a **software timer** in the plugin drives HomeKit's live countdown and the precise (sub-minute) shut-off while Homebridge is connected — it also closes a zone that was switched on at the device or that was already running when Homebridge restarted; and
+* the device's **own countdown timer**, when the controller exposes one (`countdown_1..n`, DP `17..` by default). When a zone is switched **on**, its run length (whole minutes) is sent to the hardware countdown in the *same command* as the switch, so the valve still closes on schedule **even if Homebridge or the network drops out while it's running** — the hardware closes itself. This is on by default whenever the device reports these data-points; set `nativeCountdown: false` to fall back to the software timer alone.
+
+> On these controllers the countdown is **not** a passive setting — *writing it starts a run and opens the zone*. So the plugin only ever sets it while switching a zone on (or for a zone that's already running); it is **never** written on connect or while a zone is off. The two mechanisms are belt-and-suspenders: the hardware countdown handles the offline case, and the software timer still switches the zone off after its Duration if the hardware countdown is unreliable. A zone switched on at the device with no usable countdown is given one (so it still auto-closes offline); a valid countdown the device set itself (e.g. a duration chosen in the Tuya app) is left alone.
+
+* Set a zone's duration to **`0`** to make it run **indefinitely** (until it is switched off again) — handy for long, manual watering tasks. (No finite hardware countdown is sent, so the device won't auto-close it either.)
+* The hardware countdown is whole **minutes**, capped by the device at **120 min**; HomeKit's Duration is in seconds. The value written is bounded by `maxDuration` (default `7200`s = 120 min) — lower `maxDuration` to e.g. `3600` to cap zone runs at 60 minutes.
 * Apple's Home app only offers duration presets up to **1 hour**. For longer runs (up to `maxDuration`) or to preset "indefinite" zones, set `defaultDuration` / the per-valve `defaultDuration` in the config, or use the Eve app.
 
 #### Master ("toggle all") switch
 
 Switching the whole Irrigation System tile **off** closes every open zone, and switching it **on** opens every zone — each as one combined command (mirroring the physical "all" button many of these controllers have). Either direction can be disabled with `masterTurnsOffAllZones` / `masterTurnsOnAllZones`.
 
-#### Rain sensor: Contact vs Leak
-
-By default the rain sensor is a **Contact sensor** (`raining → Open`). You can switch it to a **Leak sensor** (`raining → Leak Detected`) with `"rainSensorType": "leak"` — leak sensors read more naturally for rain and make "when it starts raining" automations obvious, **but HomeKit treats them as safety accessories and raises critical alerts that bypass Do-Not-Disturb on every rainfall**, which many people find too noisy. Use `rainInverted` if the wet/dry states appear reversed.
-
 #### Full Configuration
 
 ```json5
@@ -791,17 +822,23 @@ By default the rain sensor is a **Contact sensor** (`raining → Open`). You can
     /* Simple: number of valves on sequential data-points 1, 2, 3, … */
     "valveCount": 4,
     /* …or, for custom names / non-sequential data-points, define them explicitly
-       (this overrides valveCount). defaultDuration is in seconds; 0 = indefinite. */
+       (this overrides valveCount). defaultDuration is in seconds; 0 = indefinite.
+       dpCountdown is the device's built-in auto-off timer for the zone; it
+       defaults to the switch dp + 16 (so switch 1 → countdown 17) and only needs
+       setting for code-addressed or non-standard zones. */
     "valves": [
         { "name": "Front Lawn", "dp": 1, "defaultDuration": 900 },
         { "name": "Back Lawn",  "dp": 2, "defaultDuration": 900 },
         { "name": "Flower Beds","dp": 3, "defaultDuration": 600 },
-        { "name": "Drip Line",  "dp": 4, "defaultDuration": 0 }
+        { "name": "Drip Line",  "dp": 4, "defaultDuration": 0, "dpCountdown": 20 }
     ],
 
     /* --- Timers --- */
     "defaultDuration": 600,   /* default per-zone run time, seconds (0 = indefinite) */
     "maxDuration": 7200,      /* upper bound advertised to HomeKit, seconds */
+    "nativeCountdown": true,  /* mirror durations to the device's own countdown timer
+                                 (countdown_1.., DP 17..) so zones still auto-close
+                                 offline; set false for software-timer-only */
 
     /* --- Master switch behaviour --- */
     "masterTurnsOnAllZones": true,
@@ -813,12 +850,5 @@ By default the rain sensor is a **Contact sensor** (`raining → Open`). You can
     "lowBatteryThreshold": 20,
     "dpCharging": 101,   /* boolean charging-status DP (solar / USB-C); omit if not reported */
     /* "noBattery": true, */
-
-    /* --- Rain sensor (omit / set noRainSensor:true if not present) --- */
-    "dpRain": 49,
-    "rainSensorType": "contact", /* or "leak" */
-    "rainOnValue": "rain",       /* enum value reported while raining */
-    "rainInverted": false
-    /* "noRainSensor": true, */
 }
 ```

package/wiki/Tuya-Cloud-Setup.md

@@ -1,13 +1,12 @@
 # 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:
+This plugin is **LAN-first** — every Tuya device is controlled locally whenever it can be. Adding your Tuya Cloud credentials turns the cloud into a **transparent fallback for every device**: each accessory tries the LAN first, and only falls back to the cloud when the device can't be reached locally. It's **opt-in** (nothing happens unless you add credentials) and **local stays the preferred path**.
 
-> 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.)
+It helps in two situations:
 
-For these devices the plugin can talk to the **Tuya Cloud** instead. It is **opt-in, per device** — your other devices stay 100% local.
+> **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.)
 
-* 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.
+> **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.
 
 ---
 
@@ -21,32 +20,33 @@ For these devices the plugin can talk to the **Tuya Cloud** instead. It is **opt
 
 ## 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."*
+There are two types of projects: `Custom` and `Smart Home`. The difference between them is:
 
-## 3. Link your app account (so the project can see your devices)
+* The `Custom` project pulls devices from the project's assets.
+* The `Smart Home` project pulls devices from the user's home in the Tuya app.
 
-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**.
+If you are a personal user and are unsure which one to choose, please use the Smart Home project.
 
-## 4. Find the device ID
+In the project, go to **Service API → Go to Authorize** and make sure these are subscribed (all free):
 
-**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*.)
+* Authorization Token Management
+* Device Status Notification
+* IoT Core
+* IoT Video Live Stream (for cameras)
+* Industry Project Client Service (for the `Custom` project)
+* IR Control Hub Open Service (for IR devices)
+* Smart Home Scene Linkage (for scenes)
+* Smart Lock Open Service (for Lock devices)
 
----
+> **⚠️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).**
 
-## 5. Configure the plugin
+## 3. Link your app account (so the project can see your devices)
 
-Add a **top-level `cloud` block** with your credentials, and set **`"cloud": true`** on the device. There are two project styles:
+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**.
 
-### Smart Home project (recommended — what most people have)
+## 4. Configure the plugin
 
-Authenticates as your app account (username/password), so it sees exactly the devices linked in step 3.
+Add a **top-level `cloud` block** with your credentials:
 
 ```json5
 {
@@ -61,100 +61,23 @@ Authenticates as your app account (username/password), so it sees exactly the de
         "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)
+### Security note
 
-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:
+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.
 
-```
-sudo npm install -g mqtt
-```
+## Troubleshooting
 
-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).
+### A device reads fine over the cloud but won't accept commands (`command or value not support`, code `2008` / `2003`)
 
----
+The plugin controls devices through Tuya's current **`iot-03`** device API (`POST /v1.0/iot-03/devices/{id}/commands`), the same one tinytuya and the official Tuya Homebridge plugin use. That works for almost everything.
 
-## Troubleshooting
+Some **custom data-points** (e.g. a gate/garage controller's open/close/stop) aren't in the device's standard instruction set — `/commands` answers `2003`/`2008` for them — yet the cloud still models them as **thing-model properties** (their status reads fine, and the device acts on the same write over the LAN). For these, **you don't need to configure anything**: when a `/commands` write is rejected with `2008`/`2003`, the plugin automatically retries it through Tuya's thing-model endpoint (`POST /v2.0/cloud/thing/{id}/shadow/properties/issue`) — which is how Tuya's own app drives such a device — and remembers the working endpoint **per data-point**. So a device that mixes ordinary DPs (a switch) with custom ones (a trigger) drives each over the endpoint it accepts; the standard commands API is always tried first.
 
-| 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
+If a write fails on **both** endpoints, the data-point is genuinely **report-only** for that device (its Tuya product defines it that way), which only the manufacturer can change — there's no cloud workaround. Such devices still work normally over the **LAN**; only the cloud fallback can't drive them.
 
-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.
+The undocumented `debug.logCloudHttp` switch logs the full (credential-redacted) request/response for every cloud call if you want to see exactly what was sent and how the cloud replied.