Although the different Tuya branded Zigbee valves may look the same, they are produced by different manufacturers and have different Zigbee commands implemented.
Most of the Tuya valves should work in HE stright away, using the inbuilt Sinope Water Valve driver.
In the cases when Sinope Water Valve driver does not work for your model, you can try this driver that is intended to provide support for several different Tuya modles.
SONOFF SWV / SWV-ZN / SWV-ZF2 : SONOFF smart water valves with custom 0xFC11 cluster
Standard Zigbee 3.0 (ZHA 1.2) valves
SONOFF SWV-ZF2 parent and child semantics
The two component children are the authoritative devices for independent valve automation. Child 1 controls endpoint 1 and child 2 controls endpoint 2. On the parent, valve1 and valve2 expose the individual endpoint states, while the standard valve and switch attributes are aggregate summaries: open/on if either endpoint is open, closed/off only when both endpoints are closed, and unknown when the combined state cannot be determined. Parent open()/close() control endpoint 1; use child 2 or setValve2() for endpoint 2.
Features
Standard "Valve" capability plus mirrored "Switch" for Alexa/Google Home/HomeKit
healthStatus (online/offline)
Battery reporting for battery-powered models
Auto-off (irrigation duration) timer
Irrigation capacity and mode (duration/capacity)
Irrigation start/end times, last duration, water consumed (model-dependent)
A Hubitat Elevation Zigbee driver for Tuya, Sonoff, GiEX, Saswell, Lidl/Parkside, FrankEver, TS0049 and related water valves and irrigation timers. It auto-detects the connected model, exposes a common valve/switch interface (for Alexa, Google Home and HomeKit), and adds model-specific irrigation features such as auto-off timers, capacity/duration modes, water metering and multi-valve control. The SONOFF SWV-ZF2 dual valve additionally creates two component child devices (requires the companion Tuya Zigbee Valve Component Child driver). Author: Krassimir Kossev (kkossev), Apache 2.0.
Commands
Command
Description
Open / Close
Open or close the valve, using each model's own command format. On the classic Sonoff SWV, Open also arms the device's built-in auto-close timer from the auto-off preference; on SWV-ZN/ZF2 the configured duration is sent to the device first; Saswell and GiEX re-send the configured duration a few seconds after opening. On the SWV-ZF2 these control the first channel; the summary valve state reports open if either channel is open.
On / Off
Alias of Open/Close via the switch capability, for voice-assistant and dashboard compatibility.
Refresh
Polls the device for its current valve/switch state, battery and metering values, using a model-specific set of queries. On the classic Sonoff SWV the valve-state poll is deliberately skipped while the valve is open, because it would cancel the device's auto-close countdown (a firmware bug workaround).
Configure
Re-applies the Zigbee configuration and default settings, and creates the two SWV-ZF2 component children. It runs automatically at pairing, on initialize, and every time preferences are saved — it rarely needs to be pressed manually.
Ping
Sends a quick test message to the device and reports the response time in the rtt attribute. If no reply arrives within 6 seconds, rtt is set to timeout.
initialize
Destructive full reset — wipes all settings, states, scheduled jobs and child devices, then re-initializes with defaults. Intended for use after switching from another driver; on a configured SWV-ZF2 the component children are deleted and recreated.
setIrrigationTimer
Sets the auto-off (irrigation duration) timer; value is in seconds for most models, minutes for SWV-ZN/ZF2 (0–719) and TZE284. Zero disables auto-off. The value is also stored into the Auto off timer preference and sent to the device one second later.
setIrrigationCapacity
Sets the auto-off water volume in liters (0–999), for Saswell and GiEX only. The value is stored into the Irrigation Capacity preference and sent to the device one second later; it takes effect when the irrigation mode is capacity.
setIrrigationMode
Selects whether irrigation stops by duration or by capacity (Saswell and GiEX). The mode is sent to the device immediately.
setValveOpenThreshold
Sets the valve open threshold in percent (0–100), for the FrankEver FK_V02 only. The value is rounded to the nearest 10%, saved to the matching preference and attribute, and sent to the device.
setValve2
Opens or closes the second valve of GiEX/TZE284 double valves and the SWV-ZF2. The command acts on the second valve channel directly.
updateZigbeeFirmware
Requests an over-the-air firmware update, for supported non-Tuya devices (e.g. Sonoff). The command is refused with a warning on Tuya devices, which do not support firmware updates through the hub.
Child device (SWV-ZF2 channels):setManualIrrigationDuration (1–719 min) and setManualIrrigationAmount (0–10000, unit from child preference) configure that channel's manual-irrigation defaults through the parent.
Current States
Which attributes appear depends on the connected model — only the ones the device actually reports are populated. Events triggered by a driver command are tagged digital; device-originated reports are tagged physical.
valve — the main valve state, open or closed (plus transient opening/closing when the experimental three-state option is on, reverting to unknown on command timeout). On the SWV-ZF2 this is a summary: open if either channel is open, closed only when both are closed.
switch — an on/off mirror of valve, kept in sync for Alexa / Google Home / HomeKit and dashboard compatibility.
battery — battery charge in percent, decoded from each model's own battery report (the TS0049 reports only three levels, shown as 33/66/100%). Forced to 0 when a battery-powered device is marked offline.
batteryVoltage — battery voltage in volts, for devices that report it.
powerSource — dc or battery per the detected device model; set to unknown while the device is offline.
healthStatus — online/offline presence indicator: any received message marks the device online, three missed 3-hourly health checks mark it offline.
rtt — round-trip time of the last Ping in milliseconds, or timeout if no reply arrived within 6 seconds.
lqi / rssi — Zigbee link quality and signal strength, reported by Sonoff valves.
rate — current water flow in m³/h (classic Sonoff SWV).
timerState — irrigation timer state (disabled, active (on), enabled (off)) reported by GiEX and Saswell timers.
timerTimeLeft — remaining irrigation time: in seconds for Saswell, in minutes for TZE284 (first valve) and TS0049.
timerTimeLeft2 — remaining countdown for the second TZE284 valve, in minutes.
lastValveOpenDuration — how long the (last) irrigation ran, in seconds (Saswell, TZE284 and Sonoff models). Reset to a *** placeholder when a Sonoff valve is commanded open.
lastValveOpenDuration2 — the same for the second TZE284 valve, in seconds.
weatherDelay — Saswell rain-delay setting: disabled, 24h, 48h or 72h.
irrigationStartTime / irrigationEndTime — when the last irrigation started/ended: a text value from GiEX or a formatted date/time from Sonoff. Reset to a ****-**-** placeholder when a Sonoff valve is commanded open.
lastIrrigationDuration — GiEX last-watering duration as a text value, e.g. 00:01:10,0.
waterConsumed — accumulated water usage in liters: GiEX total or Sonoff SWV daily volume.
irrigationVolume — real-time volume of the current Sonoff irrigation, in liters.
irrigationDuration — the configured auto-off duration as shown to the user (disabled when 0), updated by setIrrigationTimer; the FrankEver FK_V02 also reports it from the device, in seconds.
irrigationCapacity — the configured auto-off volume target in liters, echoed by the setIrrigationCapacity command (GiEX/Saswell).
valveStatus — valve fault/abnormal state: Sonoff models report normal, water shortage, leakage, fail-safe and their combinations; TZE284 models report manual, auto, idle and fault states. Pre-set to clear when a non-ZF2 Sonoff valve is commanded open after a fault.
valveStatus2 — the same fault/state report for the second TZE284 valve.
valveOpenThreshold — the configured FrankEver partial-opening threshold, in percent.
valveOpenPercentage — the actual valve opening the FrankEver device currently reports, in percent.
workState — classic Sonoff SWV working indicator, idle or working.
valve1 — the state of SWV-ZF2 channel 1 (open/closed/unknown), mirrored to the first component child device.
valve2 — the state of the second valve channel: SWV-ZF2 channel 2 (mirrored to the second child) or the TZE284 second valve.
waterMode — whether irrigation is limited by duration or capacity, reported by GiEX and TS0049.
sonoffAutoShutOff — the Sonoff lack-of-water auto shut-off timeout in minutes (firmware 1.0.4 or later).
manualIrrigationDuration / manualIrrigationMode / manualIrrigationAmountUnit / manualIrrigationAmount / manualFailSafe — the five manual-irrigation default settings read back from Sonoff ZN/ZF2 valves (duration in minutes, mode duration/capacity, unit US gallon/liter, amount, fail-safe minutes). On SWV-ZN models they appear on the parent and also sync the matching unit/fail-safe preferences; on the SWV-ZF2 they are mirrored to both component children instead.
Preferences
Description text logging / Debug logging — control info-level and troubleshooting log output (debug should be off in normal use). Debug logging turns itself off automatically 24 hours after it is enabled, so it can be left on temporarily while diagnosing an issue.
Power-On Behaviour — valve state after a power cycle: closed, open, or last state (hidden on models that don't support it). The selected value is sent to the device when preferences are saved, and defaults to last state.
Auto off timer (Irrigation Duration) — auto-close delay in seconds (most models) or minutes (SWV-ZN/ZF2, TZE284); zero disables it. Shown for Saswell, GiEX, Sonoff, FrankEver and TZE284; the value is transmitted to the device as part of every open command (and, with auto-send on, re-sent when a GiEX device reports a state change). Defaults to 0 (no auto-off).
Irrigation Capacity — auto-off volume in liters (0–999), for Saswell and GiEX. It only takes effect when the irrigation mode is set to capacity, and defaults to 99 liters.
Manual irrigation amount unit / fail-safe — default amount unit (US gallon or liter) and safety timeout for the SWV-ZN manual-irrigation commands. Both are required fields (defaults liter and 0 minutes, 0–719); on Save Preferences they are sent to the device only when their value actually changed.
Valve Open Threshold — FrankEver open percentage in 10% steps (note: adjusting it emits an event during preference rendering). Values are rounded to the nearest 10% when saved, and the preference defaults to 100% (fully open).
Advanced Options — reveals: Device Profile override (default Auto-detect), auto-send timeout on every command (GiEX), experimental three-state events, Sonoff Auto Shut Off minutes (needs firmware ≥ 1.0.4), and Ignore Duplicate Packets (skips repeated identical Sonoff ZN status reports during irrigation, reducing log noise). These are marked as normally driver-managed, and the sub-options each appear only for the matching device family (default profile Auto-detect, auto-send on for GiEX / off otherwise, three-state off, Sonoff auto shut-off 30 min, duplicate-packet filtering on).
Advanced Information
State Variables
state.deviceProfile — the device profile assigned at the last detection (e.g. TS0601_GIEX_VALVE). It is set during automatic model detection and used as a fallback when no separately-detected profile is stored.
state.detectedDeviceProfile — the profile matched from the physical model and manufacturer of the device. This is the preferred source for the active profile, taking precedence over state.deviceProfile unless a profile is forced in the preferences.
state.activeDeviceProfile — the profile currently in effect (the forced profile if set, otherwise the detected one). It drives every model-specific decision in the driver.
state.comment — a static human-readable note listing the device families the driver supports. It is written once during a full initialization and is purely informational.
state.driverVersion — the driver version and build timestamp last applied, used to trigger settings migration on upgrade. When it no longer matches the running code, the driver runs a non-destructive re-initialization (filling in any newly added settings and states without wiping existing ones) and reschedules the health check.
state.manualIrrigationSettings — a cache of the last-known Sonoff ZN/ZF2 manual-irrigation defaults (mode, duration, amount unit, amount, fail-safe) as read from the device. It is refreshed whenever the device reports them and is used to fill in unchanged fields when only one parameter is written, so a partial update never clobbers the others.
state.stats — a map of lifetime counters:
RxCtr — number of Zigbee messages received from the device. It is incremented for every inbound message the driver processes.
TxCtr — number of Zigbee commands sent to the device.
rejoinCtr — number of times the device has re-announced itself on the Zigbee network, so a rising value indicates an unstable connection.
state.states — a map of transient runtime flags:
isDigital — true while a command-initiated (digital) valve change is expected, so the resulting event is tagged digital rather than physical. It is armed by Open/Close and auto-cleared 3 seconds later.
isRefresh — true briefly after a Refresh, so a polled report is not misread as a real valve change on Sonoff models. It is armed by Refresh and cleared after 5 seconds.
debounce — guards against duplicate switch events within a 300 ms window. It is set when a switch event is processed and cleared by a short timer, collapsing rapid duplicate reports into one.
lastSwitch — the last switch value processed, used for debouncing. It lets the driver recognize and drop a repeated identical report.
lastBattery — the last battery percentage physically reported by the device (battery-powered models, initialized to 100). It is updated only on real (physical) battery reports, so driver-generated battery events — such as the forced 0% when the device goes offline — do not overwrite the last genuine reading.
notPresentCtr — consecutive missed health checks; three misses mark the device offline (healthStatus: offline, powerSource: unknown, battery forced to 0 on battery models). It is reset to 0 whenever any message is received from the device and incremented on each 3-hourly health-check run.
(Sonoff ZN keys, dynamically named) — cached data used to filter out duplicate irrigation status reports and to convert the device's internal timestamps to real dates and times.
state.lastRx — receive-side timing:
parseTime — the timestamp of the most recently received message. It records when the device was last heard from and underlies the presence/health tracking.
state.lastTx — transmit-side timing:
pingTime — the timestamp of the last Ping, used to compute the round-trip time. The difference between this and the ping response is reported in the rtt attribute.
ver. 1.2.0 2023-02-28 - added deviceProfiles; stats; Advanced Option to manually select device profile; dynamically generated fingerptints; added autOffTimer; added irrigationStartTime, irrigationEndTime, lastIrrigationDuration, waterConsumed; removed the doubled open/close commands for _TZE200_sh1btabb; renamed timer_time_left to timerTimeLeft, renamed last_valve_open_duration to lastValveOpenDuration; autoOffTimer value is sent as an attribute; added new _TZE200_a7sghmms GiEX manufacturer; sending the timeout 5 seconds both after the start and after the stop commands are received (both SASWELL and GiEX) ; added setIrrigationCapacity, setIrrigationMode; irrigationCapacity; irrigationDuration; added extraTuyaMagic for Lidl TS0601 _TZE200_htnnfasr 'Parkside smart watering timer'
ver. 1.2.1 2023-03-12 - bugfix: debug/info logs were enabled after each version update; autoSendTimer is made optional (default:enabled for GiEX, disabled for SASWELL); added tuyaVersion; added _TZ3000_5ucujjts + fingerprint bug fix;
ver. 1.2.2 2023-03-12 - _TZ3000_5ucujjts fingerprint model bug fix; parse exception logs everity changed from warning to debug; refresh() is called w/ 3 seconds delay on configure(); sendIrrigationDuration() exception bug fixed; added rejoinCtr
ver. 1.2.3 2023-03-26 - TS0601_VALVE_ONOFF powerSource changed to 'dc'; added _TZE200_yxcgyjf1; added EF01,EF02,EF03,EF04 logs; added _TZE200_d0ypnbvn; fixed TS0601, GiEX and Lidl switch on/off reporting bug
ver. 1.2.4 2023-04-09 - _TZ3000_5ucujjts deviceProfile bug fix; added rtt measurement in ping(); handle known E00X clusters
ver. 1.2.5 2023-05-22 handle exception when processing application version; Saswell _TZE200_81isopgh fingerptint correction; fixed Lidl/Parkside _TZE200_htnnfasr group; lables changed : timer is in seconds (Saswell) or in minutes (GiEX)
ver. 1.2.6 2023-07-28 - fixed exceptions in configure(), ping() and rtt commands; scheduleDeviceHealthCheck() was not scheduled on initialize() and updated(); UNKNOWN deviceProfile fixed; set deviceProfile preference to match the automatically selected one; fake deviceCommandTimeout fix;
This seems like exactly what I need and looks great, but it isn't working for me. My manufacturer is listed as "_TZE200_sh1btabb", is this the problem?
This Tuya manufacturer is not in the list of the known devices (yet).
Make sure the Debug option is turned on, then power the valve off, wait 10-15 seconds and power it on again.
Switch the valve for on/off from the device button.
Then post the debug logs (you can do this in. a PM )
P.S.
Have you tried the built in Sinope driver?
Also, when this Tuya driver is selected, pair the valve for a second time. Some Tuya and Aqara devices do not pair successfully to the hub from the first try,
I just searched for information about this device, and it is something very different than the simple water/gas shutter valve... It's a much more complex smart irrigation controller. Seems like the water flow can be regulated in 5% steps, not just fully opened/fully closed like the shutter valves.
Such a controller will require a custom driver to handle the specific Tuya commands for it, there is not a known driver for Hubitat yet.
Ok. I have a development background, can you help me get started? It's unclear to me how one determines what the commands are from interrogating the device.
Many of Tuya platform devices do not follow the Zigbee Cluster Library specifications, so the commands for each particular device are usually reverse-engineered by sniffing the traffic when connected to Tuya proprietary Zigbee coordinator. Often this work is already done by other home automation communities :), so it becomes a matter of finding the information on Github. Searching Github for _TZE200_sh1btabb" shows that this device is already supported in ZHA and Zigbee2MQTT, so the information on the commands ('data points' in Tuya terminology) is already there.
It shouldn't be so hard to add support for this device in Hubitat, the only problem is the time .. ;(
If you are sure that you want to dive into writing Zigbee drivers for Hubitat, I will surely help you to get started. The first step is to understand the debug logs that most of the HE drivers provide, so my proposal was to start from here.
I also found those pages in GitHub last night. I think I'm missing some sort of primer on zigbee drivers. I searched around a bit and mostly found official protocol documentation which would be laborious to consume. Can you recommend a good 101 guide?
If I'm understanding correctly, the mqtt work does not contain the zigbee commands themselves, rather the instructions to the Tuya hub to send the zigbee commands. Is that correct?
There is no way to communicate directly to Tuya zigbee hub, These communicate only to Tuya cloud. Tuya cloud provides API for integration to other systems - it is used in HE by this excellent project : [BETA] Tuya Cloud Driver (Limited device support)
This is one possible way to bring Tuya devices to HE, that do not have a Zigbee driver yet (or the devices use WiFi or BT communication to Tuya hub).
An MQTT broker does not directly talk to Tuya devices or Tuya Zigbee hub, In Home Assistant, the Zigbee2MQTT add-on communicates to a lot of Zigbee devices from one side and to HA MQTT broker on the other side.
Ok, that's interesting. I think the outcome is the same though; the information I need to write a zigbee driver is not contained within the mqtt code we both found on GitHub, meaning the only way for me to get it is to buy a Tuya hub, and a zigbee dongle and sniff the traffic. Correct?
Having a Tuya Zigbee hub and sniffing the traffic is very useful, but not absolutely necessary. I have it, but I use it relatively rarely, I call this approach 'the heavy artillery '
Usually, collaborators from Home Assistant or deConz, or other HA communities have already walked this way, so the information needed to add a particular device is already available on GitHub. As of today, searching GitHub for '_TZE200_sh1btabb' finds 3 issues (the request, discussions implementation, and test results of the same device in both ZHA and Zigbee2MQTT) and 1 'code' ( Zigbee2MQTT definitions for this Water irrigation valve). In our case we are lucky as almost all of the information can be found in this single giex.js file. Here we have all the Tuya 'data points' - parameters that are reported from the device (fzLocal) and commands / parameters that can be sent to the device (tzLocal ). We still have to guess what is the meaning of 'mode' vs 'state' vs 'irrigation_target', etc... In this case, I have not spent time reading more about this device, so most of parameters and commands are not very clear to me.
Next step is to start adding the new device commands and parameters to a new or better find an existing HE driver that is most close to the new device functions. This driver can be a good starting point, although this irrigation valve is much more complex that the simple on/off valve. But often not all of the particular Tuya device parameters needs to be implemented in Hubitat. Probably all these 'irrigation start', 'irrigation end', irrigation duration parameters (having a strange data type 'GMT+8' - this is the China central time zone ) are not needed in HE, because the operation of the valve will be controlled by Hubitat.
If you want to continue with writing the driver, let me know.
I absolutely do and this is super helpful, I think my mental model is almost complete enough to begin. One thing that's not clear just yet, wears the relationship between clusters (seemingly simple memory addresses or similar) and the human readable datapoints etc named in the above mentioned file?
More to the point, I'm under the impression that I need to send some specific magic numbers to the device and that those datapoints are convenience names. Seems like maybe that's where my disconnect is.
I would like to know if anyone has seen or worked with these. One of the three reviews says it doesn't work with Hubitat but I think it is pretty new and maybe nobody has it yet to sniff it out. If I were to purchase one, what would someone need to get it to work with a driver? It mentions it is a Tuya chipset and, right now, would require a Tuya hub. I would happily be the test rat if it means getting away from the Orbit setup I have now.
In the development branch ver. 1.0.2 (the link is in the second post) I have added basic On/Off control for the new Tuya Water Irrigation Valve. I do not have this device and am unsure whether it is only one model/manufacturer. If someone has this or a similar device please make some tests. There is no known way to automatically recognize whether the device is a simple valve or a more sophisticated water irrigation valve, so for each new manufacturer the new fingerprint must be added into this driver. Currently, _TZE200_sh1btabb is recognized as an irrigation valve.
This is a basic On/Off valve control only. There are other advanced features like irrigation timer start/end times, irrigation duration, etc.. which functionality is not clear to me. If someone has this device and can explain the meaning of these parameters and how these can be used in HE, please let me know.
Great! I purchsed it and should be here tomorrow. All I really care about is on/off really but my needs are probably far different than others. 5-10 second delay with Orbit is just too much for me to handle anymore for my situation.
When you have it, please send me the debug logs from the first pairing in a PM.
What is your use case, are you planning to use it for water irrigation (limited time on)?
My main doubt is whether this device can be switched on permanently or not.. It's a battery-powered device, so I have a doubt that these complex timers should be used, but we will understand after the tests...
Destructive full reset — wipes all settings, states, scheduled jobs and child devices, then re-initializes with defaults. Intended for use after switching from another driver; on a configured SWV-ZF2 the component children are deleted and recreated.