iobroker.fid-smartlife 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fiducerion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+<img src="admin/fid-smartlife.png" alt="logo" width="120" align="right"/>
+
+# ioBroker.fid-smartlife
+
+Tuya / Smart Life cloud + local LAN adapter for ioBroker.
+
+> ⚠️ **ALPHA / EXPERIMENTAL** ⚠️
+>
+> This adapter is in active development on a single production system.
+> Breaking changes between versions are expected. There is no support
+> guarantee. Issues are welcome but response time is voluntary. Use at
+> your own risk.
+
+## Features
+
+- Reads device list, schemas and live status from the Tuya OpenAPI v2
+- Local LAN control (Tuya protocol 3.3) — most write commands run without
+  hitting the cloud, no quota burn even for blink scripts
+- LAN-Discovery picks up device IPs automatically from broadcast announces
+- Cloud-IP-Import command as fallback when discovery doesn't catch a device
+- Online state based on actual local reachability with hysteresis (50 fails
+  or 60 minutes without local-OK before flipping to offline) — battery /
+  sub-devices fall back to cloud-reported online state
+- Optional Pulsar/MQTT push subscriber for cloud status events (experimental,
+  off by default)
+- Schema database with ~8000 entries as fallback for devices where the cloud
+  spec is sparse
+- Bitmap, RGB-color and energy-plug enhanced derived states (compatible with
+  the iobroker.tuya state layout: state under both code-name and DPS-id)
+
+## Requirements
+
+1. A Tuya Smart / Smart Life account (the same one used by the mobile app)
+2. A Tuya IoT Platform cloud project (free, see "Tuya account setup" below)
+3. ioBroker with js-controller 5+ and Node.js 18+
+
+## Tuya account setup
+
+You need a Tuya Developer cloud project with your Smart Life app account
+linked. This is the same procedure as for `iobroker.tuya`'s cloud mode.
+
+1. Sign in at https://platform.tuya.com (or `iot.tuya.com`)
+2. **Cloud → Development → Create Cloud Project**
+   - Name: anything you like
+   - Industry: *Smart Home*
+   - Development Method: *Smart Home*
+   - Data Center: pick the one matching your Smart Life region (Central
+     Europe → EU, North America → US, ...)
+3. After creating, the project shows **Access ID** and **Access Secret** —
+   copy both.
+4. **Service API** tab → make sure these API services are subscribed and
+   authorized to the project:
+   - **IoT Core** (required)
+   - **Authorization** (required)
+   - **Smart Home Basic Service** (required)
+   - **Device Status Notification** (only needed for the optional Pulsar
+     push subscriber)
+5. **Devices → Link Tuya App Account → Add App Account** — scan the QR with
+   your Smart Life app. After confirming, your devices appear under
+   *All Devices*.
+
+If you have a Tuya **Trial Edition** (the default for new accounts), the
+"controllable device pool quota" is limited — typically renewed monthly.
+With many devices, prefer local control (which fid-smartlife uses by
+default) to keep cloud calls minimal.
+
+## Installation
+
+### Option A: via Admin UI (recommended for testing)
+
+In ioBroker admin: *Adapters → Install via URL* and enter:
+
+```
+https://github.com/fiducerion/ioBroker.fid-smartlife
+```
+
+ioBroker pulls the latest commit on `main` and installs it.
+
+### Option B: via CLI
+
+```bash
+iobroker url https://github.com/fiducerion/ioBroker.fid-smartlife
+```
+
+### Option C: pin a specific release tag
+
+```bash
+iobroker url https://github.com/fiducerion/ioBroker.fid-smartlife/tarball/v0.7.7
+```
+
+## Configuration
+
+Open the instance settings in the admin UI:
+
+- **Access ID** + **Access Secret** + **Region**: from the Tuya cloud project
+- **Polling interval**: how often to refresh status from devices (default 60s).
+  Lower for faster updates, but more cloud calls.
+- **Enable LAN discovery**: should stay on — without it no local IPs
+- **Enable Pulsar/MQTT Push** (experimental): subscribe to device status
+  push from Tuya cloud. Default off. Requires "Device Status Notification"
+  API in the cloud project.
+
+After saving, the adapter discovers all devices from the cloud and creates
+states under:
+
+```
+fid-smartlife.0.<deviceId>.<dpId>          # primary state, matches iobroker.tuya layout
+fid-smartlife.0.<deviceId>.<codeName>      # alias for the same data point
+fid-smartlife.0.<deviceId>.ip              # local IP (set by LAN-Discovery)
+fid-smartlife.0.<deviceId>.localKey        # AES key for local control
+fid-smartlife.0.<deviceId>.online          # local reachability with hysteresis
+fid-smartlife.0.<deviceId>.noLocalConnection  # set to true to disable local writes
+fid-smartlife.0.<deviceId>._noCloudStatusPoll # set to true to skip cloud polling
+```
+
+Plus diagnostic states under `fid-smartlife.0.info.*`:
+
+```
+info.connection            # adapter healthy
+info.cloudQuotaPaused      # Tuya quota guard active (60min backoff)
+info.pulsarConnected       # Pulsar/MQTT push subscriber active
+info.pulsarMessages        # decrypted push messages counter
+info.localResetV065        # one-time migration marker (don't touch)
+```
+
+## Diagnostic sendto commands
+
+```bash
+# How many writes went local vs cloud, plus list of devices without local IP
+iobroker sendto fid-smartlife.0 writeStats
+
+# Import IPs from cloud for devices that LAN discovery hasn't caught
+iobroker sendto fid-smartlife.0 importCloudIPs
+
+# Find devices that used to be in the cloud but aren't anymore
+iobroker sendto fid-smartlife.0 findMissingDevices
+
+# Raw device list from Tuya cloud
+iobroker sendto fid-smartlife.0 listDevicesRaw
+```
+
+## Heavy switching scripts (alarm blink, etc)
+
+If you have scripts that rapidly toggle devices (e.g. blink lights every
+3 seconds during an alarm), make sure those devices:
+
+1. Have a `local.ip` set (check with `iobroker state get
+   fid-smartlife.0.<deviceId>.ip`)
+2. Are reachable from the ioBroker host (no VLAN/firewall isolation)
+3. Optionally have `_noCloudStatusPoll = true` to skip the periodic cloud
+   status read
+
+If `local.ip` is empty, run `importCloudIPs` once. After that the adapter
+writes locally and burns no cloud quota for these scripts.
+
+## Internet block as quota protection
+
+A nice trick: block internet access to specific Tuya devices in your
+router (e.g. AVM FRITZ!Box → Network → Devices → tick "deny internet").
+The device stays reachable locally, broadcasts its presence to the LAN,
+and `fid-smartlife` controls it via the local protocol. Tuya cloud will
+report the device as offline (which is fine — the local online state
+based on reachability is authoritative). No more accidental cloud calls
+for that device, ever.
+
+## What is NOT supported (yet)
+
+- Tuya protocol v3.4 (HMAC-SHA256 handshake + session key) — affects a
+  small number of newer devices, they fall back to cloud-only
+- Camera streams (RTSPS allocation, snapshot URLs)
+- Tuya Bluetooth gateway sub-devices via local protocol (cloud only)
+- Multi-instance setups
+
+## License
+
+MIT

package/admin/i18n/de/translations.json

@@ -0,0 +1,7 @@
+{
+  "Tuya Cloud (IoT Platform)": "Tuya Cloud (IoT Platform)",
+  "Polling": "Polling",
+  "Schreiben (Commands)": "Schreiben (Commands)",
+  "Geraete-Eigenheiten": "Geräte-Eigenheiten",
+  "Debug": "Debug"
+}

package/admin/i18n/en/translations.json

@@ -0,0 +1,7 @@
+{
+  "Tuya Cloud (IoT Platform)": "Tuya Cloud (IoT Platform)",
+  "Polling": "Polling",
+  "Schreiben (Commands)": "Write (Commands)",
+  "Geraete-Eigenheiten": "Device quirks",
+  "Debug": "Debug"
+}

package/admin/jsonConfig.json

@@ -0,0 +1,195 @@
+{
+  "type": "panel",
+  "i18n": true,
+  "items": {
+    "_header_cloud": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Tuya Cloud (IoT Platform)"
+    },
+    "_info_cloud": {
+      "newLine": true,
+      "type": "staticText",
+      "text": "Lege dir auf iot.tuya.com einen Cloud-Project an, linke deine SmartLife-App und kopiere Access ID / Access Secret hierher. Die Region muss zu deinem App-Account passen.",
+      "style": { "fontStyle": "italic", "marginBottom": "12px", "color": "#666" }
+    },
+    "clientId": {
+      "newLine": true,
+      "type": "text",
+      "label": "Access ID (Client ID)",
+      "help": "Dein Tuya Cloud Access ID",
+      "sm": 12, "md": 6
+    },
+    "clientSecret": {
+      "type": "password",
+      "label": "Access Secret (Client Secret)",
+      "help": "Dein Tuya Cloud Access Secret",
+      "sm": 12, "md": 6
+    },
+    "region": {
+      "newLine": true,
+      "type": "select",
+      "label": "Region",
+      "options": [
+        { "value": "eu", "label": "Europe (openapi.tuyaeu.com)" },
+        { "value": "us", "label": "America (openapi.tuyaus.com)" },
+        { "value": "cn", "label": "China (openapi.tuyacn.com)" },
+        { "value": "in", "label": "India (openapi.tuyain.com)" }
+      ],
+      "sm": 12, "md": 4
+    },
+    "_header_poll": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Polling"
+    },
+    "pollIntervalSec": {
+      "newLine": true,
+      "type": "number",
+      "min": 10,
+      "max": 3600,
+      "label": "Poll-Intervall (Sekunden)",
+      "help": "Wie oft Geraetestatus aus der Cloud abgerufen wird. Default 60.",
+      "sm": 12, "md": 3
+    },
+    "rediscoverIntervalMin": {
+      "type": "number",
+      "min": 0,
+      "max": 10080,
+      "label": "Rediscovery (Minuten)",
+      "help": "0 = keine periodische Rediscovery. Default 720 (alle 12 Stunden).",
+      "sm": 12, "md": 3
+    },
+    "maxParallelPolls": {
+      "type": "number",
+      "min": 1,
+      "max": 5,
+      "label": "Parallele Polls",
+      "help": "Wie viele Geraete gleichzeitig gepollt werden. Default 1 (sequentiell, schonend).",
+      "sm": 12, "md": 3
+    },
+    "requestTimeoutMs": {
+      "type": "number",
+      "min": 2000,
+      "max": 60000,
+      "label": "Request-Timeout (ms)",
+      "help": "HTTP-Timeout fuer einzelne Cloud-Aufrufe. Default 12000.",
+      "sm": 12, "md": 3
+    },
+    "_header_write": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Schreiben (Commands)"
+    },
+    "writeDebounceMs": {
+      "newLine": true,
+      "type": "number",
+      "min": 0,
+      "max": 5000,
+      "label": "Write-Debounce (ms)",
+      "help": "Zusammenfassen schnell aufeinanderfolgender Writes. Default 400.",
+      "sm": 12, "md": 4
+    },
+    "optimisticAck": {
+      "type": "checkbox",
+      "label": "Optimistic ACK",
+      "help": "Beim Schreiben den State sofort mit ack=true zurueckschreiben, bevor das Geraet bestaetigt. Schnelle UI-Reaktion. Default an.",
+      "sm": 12, "md": 4
+    },
+    "_header_quirks": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Geraete-Eigenheiten"
+    },
+    "noCloudStatusPollIds": {
+      "newLine": true,
+      "type": "text",
+      "label": "Geraete-IDs ohne Cloud-Status-Poll",
+      "help": "Komma-getrennte Liste von deviceIds die NICHT regelmaessig per Cloud gepollt werden sollen (z.B. weil sie 'function not support' werfen). Default enthaelt zwei bekannte Problemgeraete.",
+      "sm": 12, "md": 12,
+      "noTranslation": true
+    },
+    "_header_local": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Lokale Steuerung (LAN, Tuya v3.3)"
+    },
+    "_info_local": {
+      "newLine": true,
+      "type": "staticText",
+      "text": "Pro Geraet kann via fid-smartlife.0.<deviceId>._local.preferLocal=true aktiviert werden, dass Schreibbefehle ueber LAN statt Cloud gehen. localKey wird aus der Cloud-Discovery uebernommen. IP+Version koennen aus tuya.0 importiert werden, falls dieser Adapter noch parallel laeuft, oder per UDP-Broadcast erkannt werden.",
+      "style": { "fontStyle": "italic", "marginBottom": "12px", "color": "#666" }
+    },
+    "enableLanDiscovery": {
+      "newLine": true,
+      "type": "checkbox",
+      "label": "LAN-Discovery aktivieren (UDP 6666/6667/7000)",
+      "help": "Lauscht auf Tuya-Geraete-Broadcasts und uebernimmt IP+Version automatisch in die _local-States.",
+      "sm": 12, "md": 6
+    },
+    "importLocalFromTuyaAdapter": {
+      "type": "checkbox",
+      "label": "Import lokaler IPs aus tuya.0",
+      "help": "Falls iobroker.tuya parallel laeuft, werden lokale IPs/Versionen beim Start uebernommen.",
+      "sm": 12, "md": 6
+    },
+    "_header_pulsar": {
+      "newLine": true,
+      "type": "header",
+      "text": "Pulsar / MQTT Push (experimentell)",
+      "size": 4
+    },
+    "_help_pulsar": {
+      "newLine": true,
+      "type": "staticText",
+      "text": "Wenn aktiviert, verbindet sich der Adapter via MQTT mit dem Tuya-Pulsar-Broker und empfaengt Device-Status-Updates per Push (statt per Polling). Voraussetzung: In der Tuya IoT Platform muss unter dem Cloud-Project der Message Service abonniert sein. Spart massiv Cloud-Quota - besonders fuer Battery-/Subdevices wichtig.",
+      "style": { "fontStyle": "italic", "marginBottom": "12px", "color": "#666" }
+    },
+    "enablePulsar": {
+      "newLine": true,
+      "type": "checkbox",
+      "label": "Pulsar/MQTT Push aktivieren",
+      "help": "Voraussetzung: Message Service in Tuya IoT Platform abonniert. Status sichtbar unter info.pulsarConnected.",
+      "sm": 12, "md": 6
+    },
+    "localTimeoutMs": {
+      "newLine": true,
+      "type": "number",
+      "min": 500,
+      "max": 30000,
+      "label": "Lokales Timeout (ms)",
+      "help": "TCP-Timeout fuer Local-Schreibbefehle. Default 2500.",
+      "sm": 12, "md": 3
+    },
+    "_header_compat": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "State-Layout"
+    },
+    "_info_compat": {
+      "newLine": true,
+      "type": "staticText",
+      "text": "Datenpunkte werden nach iobroker.tuya-Konvention angelegt: <device>.<dps-id> mit common.name = Code-Name. Bestehende Skripte/VIS-Bindings die 'tuya.0.<dev>.20' lesen koennen 1:1 auf 'fid-smartlife.0.<dev>.20' umgestellt werden. Zusaetzlich gibt es lesbare Aliase pro Geraet (on, brightness, temperature, ...) wo sinnvoll. Lokale Settings sind direkt unter dem Geraet: <dev>.ip, <dev>.noLocalConnection, <dev>.localKey, <dev>.localVersion, <dev>.localPort.",
+      "style": { "fontStyle": "italic", "marginBottom": "12px", "color": "#666" }
+    },
+    "_header_debug": {
+      "newLine": true,
+      "type": "header",
+      "size": 3,
+      "text": "Debug"
+    },
+    "debug": {
+      "newLine": true,
+      "type": "checkbox",
+      "label": "Debug-Logging aktivieren",
+      "help": "Zusaetzliche Debug-Meldungen. Loglevel muss auf 'debug' stehen.",
+      "sm": 12, "md": 4
+    }
+  }
+}