homebridge-tuya-watering

A Homebridge plugin that exposes Tuya watering and irrigation devices to HomeKit — local-first over the tuya-local protocol (no cloud round trip for control), with an optional per-device cloud fallback for low-power firmwares that do not support LAN control at all.

Features

• Local control via tuyapi (protocol 3.1–3.5), with persistent connections, event-driven state, exponential reconnect backoff and automatic IP re-resolution when DHCP moves a device.
• Cloud fallback through the Tuya OpenAPI for deep-sleep battery devices that never open a local port.
• Generic DP mapping — no hardcoded models. Any watering device can be described in config: switch DP, duration DP (seconds or minutes), battery, leak/rain sensors, multi-zone selectors.
• HomeKit-native services: Valve (irrigation type) for single-outlet devices, IrrigationSystem with linked zone valves for multi-zone devices, SetDuration/RemainingDuration with live countdown, battery level and low-battery alerts, leak and rain sensors.
• Import wizard (custom UI) in Homebridge Config UI X: scans the LAN, enumerates every device on your Tuya account (keys included — you never type a device ID or local key), fetches each device's DP model and auto-generates the config mapping.

Requirements

• A Tuya IoT Platform cloud project (iot.tuya.com) linked to your Smart Life / Tuya Smart app account. The project's Access ID / Access Secret power the import wizard and cloud-mode devices. This is the only way Tuya exposes device local keys; a plain app login cannot retrieve them.
• Devices you want to control locally must be reachable on the same LAN as Homebridge.

Installation

npm install -g homebridge-tuya-watering

Then open the plugin settings in Homebridge Config UI X, enter your cloud credentials and run Import devices.

Configuration

The custom UI generates this for you; shown here for reference and manual editing.

{
  "platform": "TuyaWatering",
  "cloud": { "accessKey": "…", "secretKey": "…", "region": "us" },
  "pollInterval": 60,
  "debugMode": false,
  "devices": [
    {
      "id": "…",
      "name": "Balcony",
      "type": "valve",
      "connection": { "mode": "local", "ip": "…", "localKey": "…", "version": "3.5" },
      "switchDp": "1",
      "duration": { "dp": "11", "unit": "seconds", "max": 3600, "defaultSeconds": 240 },
      "battery": { "dp": "7", "lowThreshold": 20 },
      "sensors": [{ "type": "leak", "dp": "101", "activeValue": true }]
    }
  ]
}

Device fields

| Field | Description | |---|---| | type | valve (single outlet) or irrigation (multi-zone system) | | openMode | switch (default): a boolean DP opens/closes. durationTrigger: writing seconds to the duration DP starts a run, 0 stops it; running state derives from the live remaining DP | | connection.mode | local (requires ip, localKey, version) or cloud | | switchDp | Master on/off DP (switch mode) | | zones | Zone list for irrigation; each zone may carry its own switchDp (independent outlets) | | zoneSelector | Shared-pump paradigm: enum DP selecting the outlet(s); map keys are comma-joined 1-based zone indexes ("1", "1,2") | | duration | dp, unit (seconds/minutes), max (device units), remainingDp (live countdown DP), defaultSeconds | | battery | dp, lowThreshold, optional chargingDp | | sensors | type (leak/rain/contact), dp, activeValue, optional name | | beforeOpen / afterClose | Extra DP writes merged into the open/close frames (e.g. switching a dual-pump device to manual mode and back) | | sequentialWrites | Send one DP per frame, in order, for firmwares that mishandle multi-DP frames |

Firmware quirks this plugin handles

• sfkzq timers: writing the countdown DP (re)starts watering — even in the same frame as switch: false. Close frames therefore never carry the duration DP, and SetDuration changes are only written at open time. These devices also do not decrement their countdown DP while running, so RemainingDuration is driven by a local timer.
• Dual-pump wk-category controllers: the switch DP only arms the built-in weekly schedule. Manual runs are triggered by writing seconds to the runtime DP (in manual mode) and stopped by writing 0; a separate DP reports the live countdown. Use openMode: "durationTrigger" — the import wizard detects this pattern automatically. The device's own schedule keeps working: the plugin restores auto mode after every run.
• Deep-sleep battery devices (e.g. LYAI-17): cloud-online but never reachable on the LAN, even when awake. Use connection.mode: "cloud".

Notes

• HomeKit caps SetDuration at 3600 s; devices accepting longer runs are clamped to one hour.
• Tuya firmwares accept a single local TCP client. Don't point two local-protocol integrations at the same device.

Development

npm install
npm run build        # tsc → dist/
npm run lint
npm run smoke:local -- --id <id> --ip <ip> --key <key> --version 3.3
npm run smoke:cloud -- --id <id>   # TUYA_ACCESS_KEY / TUYA_SECRET_KEY env

License

Apache-2.0