View on GitHub

Smart Irrigation

A Home Assistant integration to optimize irrigation

Closed-loop watering

Main page: Configuration

By default Smart Irrigation runs open loop: it calculates a duration and fires an event, but it does not know whether (or how much) watering actually happened, so you reset the water balance from an automation. The closed-loop features remove that guesswork. They are all opt-in and configured in the panel under General.

Observed watering (credit the water balance automatically)

When enabled, Smart Irrigation watches each zone's linked valve/switch. Whenever it runs (a manual tap, an automation, or Smart Irrigation itself), the zone's water balance is credited from the run time and the zone's throughput (depth_mm = throughput_L_per_min x minutes / size_m2). No more manual reset.

To set it up:

  1. In General, turn on Enable observed watering.
  2. In Zones, set each zone's Linked valve/switch to the entity that waters that zone (a switch, valve or input_boolean).

Important: when observed watering is on it becomes the only thing crediting the water balance. Remove any set_bucket or reset_bucket call from your irrigation automation, otherwise the water balance is accounted twice.

Optional: a cumulative volume meter (more precise)

For exact accounting you can also set a zone's Cumulative volume meter. The applied depth is then taken from the measured volume delivered during the run (meter_at_close - meter_at_open) instead of throughput x time.

It must be a cumulative water-meter total (state class total_increasing), not an instant flow rate. The unit is read automatically from the sensor (L, mL, m³, gal, ft³). An instant flow-rate sensor (for example L/min) will not work; if your hardware only exposes a rate, feed it through a Riemann-sum Integration helper first to get a cumulative total.

What the meter tells us about your throughput

Every irrigation duration is derived from the zone's configured throughput: the water balance says how many mm are missing, the size turns that into litres, and the throughput turns litres into minutes. A throughput copied off a datasheet rather than measured at the tap is one of the quietest ways to water twice as long as intended, or half as long, for a whole season.

A zone with a volume meter gives the answer for free, since a run knows both how many litres came out and how long the valve was open. Smart Irrigation divides one by the other, smooths the result over several runs, and raises a repair notice in Settings > Repairs when it drifts more than 25% from what you configured. Runs shorter than two minutes are ignored: filling the pipe dominates them.

It only ever tells you. The zone's throughput is never rewritten, because pressure varies, a meter can sit upstream of more than one zone, and silently changing how long valves stay open is not something to do behind your back. If the measurement looks right, copy it into the zone yourself.

Direct valve control (let Smart Irrigation run the valves)

With Let Smart Irrigation control the valve on, Smart Irrigation opens each zone's linked valve, waits the calculated duration, then closes it. No execution automation needed. The start event still fires, so external executors keep working too.

It stands on its own: the zone's Linked valve/switch can be set with direct valve control alone, without observed watering. The two answer different questions, and the difference matters when the same valve is used for other things -- filling a paddling pool, hosing the terrace. Direct valve control credits the water balance for the runs it performs, since it knows exactly what it delivered. Observed watering credits any run of that valve, which is what you want for a tap somebody opens by hand to water the same lawn, and not what you want if that valve also does something else. Leave observed watering off in that case.

Safety: if Home Assistant goes down for a long time during a run, the physical valve stays open and keeps watering, because Home Assistant is no longer there to close it. Give your valve a hardware failsafe (a maximum runtime on the device itself). Smart Irrigation also caps the credited time at the zone's maximum duration. For an MQTT valve, the integration can arm that failsafe for you on every run -- see below.

Watering one zone by hand

Enabling direct valve control also adds the Irrigate now button entities for existing zones and Irrigate all on the hub, without reloading the integration or restarting Home Assistant. Switching it off makes those buttons unavailable; switching it on again restores them with the same entity IDs.

With direct valve control on, each zone with a linked valve has a Water button on its card in the Zones page. It asks for minutes, and left empty it waters the run the planning shows. The valve opens straight away, or takes its turn behind what is watering, and the water is credited to the zone's balance like any run of ours. It is the smart_irrigation.water_zone action, which an automation can call with the zone's entity or its zone_id.

Hardware auto-off (MQTT on_time dead-man)

The closing of the valve normally happens in Home Assistant: the run opens the valve, waits, and closes it. If Home Assistant stops in that window and never comes back, nothing sends the close and the valve keeps watering. (A restart does recover: an in-flight run is resumed and closed when Home Assistant comes back. The gap is Home Assistant staying down.)

For a valve controlled over MQTT -- a zigbee2mqtt device, for instance -- Smart Irrigation can close that gap with a hardware dead-man. On each pass it publishes an on with timed off command to the device, so the device's own firmware shuts the valve off after the run even if Home Assistant is no longer there. It is armed only after the valve is confirmed open, and it is additive: the normal close still runs, the on_time is set a little longer than the pass so it lands just after, as a failsafe rather than the primary off.

Three optional per-zone fields configure it (advanced panel, shown only with direct valve control on and a linked valve set). The first two are empty by default, so nothing changes until you fill them in:

With those set, a pass that holds the valve for 300 seconds publishes {"state_l1": "ON", "on_time": 330} to the topic (the run time plus a 30-second margin). The device closes its own valve after on_time seconds whatever happens to Home Assistant.

Device support varies. on_time ("on with timed off") is honoured by the device firmware, not by Smart Irrigation, and not every device implements it. Test it before you rely on it: start a run, stop Home Assistant while the valve is open, and confirm the valve closes itself after on_time. Some devices need an off_wait_time alongside on_time to behave.

Verified: a Sonoff SWV (firmware 1.0.4) on zigbee2mqtt, topic zigbee2mqtt/<friendly name>/set, state key state: with the Zigbee coordinator unplugged in the middle of a run, the valve closed by itself at the end of it (reported in #893).

Valves on ZHA can be armed too. The linked valve must be a ZHA entity (found through the entity registry): each pass then sends the device an on with timed off command (On/Off cluster, command 0x42) through zha.issue_zigbee_cluster_command, right after the normal open (a Sonoff SWV is the exception, see below). The unit of the time differs between devices, so the safety off mode matters:

A Sonoff SWV is opened by that same command. On a real valve, on with timed off sent to a closed SWV both opens it and starts its own timer, so there is no moment when it is open without a timer. For a SWV in auto mode (no MQTT topic, mode auto; in zha or off mode the normal open is used), Smart Irrigation therefore opens the linked valve with that single command instead of the normal open: the time is the pass length rounded up plus the 30-second margin, in seconds (at most 65535). The rest is unchanged: the open is confirmed the same way (an open that has to be repeated sends the same command), the close at the normal time also clears the device's timer, a cycle-and-soak pass opens again and so restarts the timer, and a run resumed after a restart opens the same way with the time that remains. The extra valves keep the normal open. Each attempt is short (6 seconds, because a battery valve is asleep most of the time and would otherwise hold the start for about 16 seconds), and the command is tried once. If it fails (ZHA not set up, an error, a valve that does not answer), a warning is logged once for the zone and the valve is opened the normal way, followed by the separate arm described above: the watering is never prevented. Any other valve (another ZHA model, the explicit zha mode on an unknown model, MQTT, other platforms) is opened and armed exactly as before.

This timed off is separate from, and different from, the valve's own water shortage auto close, which does not cover Home Assistant stopping in the middle of a run. A failure to send the command never breaks the run: it is logged as a warning the first time for a zone, then at debug level.

The per-zone safety off mode picks the behaviour: auto (the default) uses the MQTT topic if there is one, else arms a Sonoff SWV on ZHA, and otherwise nothing; zha also arms a ZHA valve when there is no topic; off never arms a dead-man for that zone, topic included. Only the zone's linked valve is armed, not its extra valves.

Other valves (Wi-Fi switches, ESPHome, Tuya, or anything that is neither MQTT with a topic nor ZHA) get no automatic dead-man: leave the fields empty and the run behaves exactly as before. For those, set the failsafe on the device itself, which is more reliable than Home Assistant sending it every run: a Shelly has an Auto-off timer, Tasmota has PulseTime, ESPHome can turn a switch off after a delay, and many Tuya Wi-Fi switches have a countdown function.

Cycle and soak, and the pause between zones

Two settings on the advanced panel, both off by default, for an installation that is already tuned.

Water in several passes splits a run into shorter passes with a pause between them. Clay and compacted soil have an infiltration rate: past it the water runs off or puddles, and the zone is billed for water the roots never see. Three passes of five minutes with fifteen minutes of soaking deliver the same water as one run of fifteen minutes, and the soil keeps more of it. Guidance: sand takes water as fast as you can give it, so leave this at one pass; loam rarely needs more than two; clay and slopes are what it is for.

The plan is fixed when the run starts, and a run too short to split is left alone (no pass shorter than a minute). Each pass is credited as it closes, so a restart in the middle of a run never credits water twice and never leaves a valve open.

Pause between zones waits between two zones of a sequential run, for the line pressure to recover or for a slow valve to finish closing before the next one opens.

Both lengthen the run without adding water to it, and a start trigger that has to finish at sunrise works back from the whole thing, soaking and pauses included: three zones of half an hour in three passes with fifteen minutes of soaking occupy two and a half hours, not an hour and a half. Watch that against the hour you want to be finished by. When an executor of your own opens the valves instead, neither setting applies and the run length is the watering alone.

Events for your own automations

Direct valve control fires events you can use to notify or react, so you do not need one automation per zone:

Example: a single end-of-watering report for all zones.

alias: Watering report
triggers:
  - trigger: event
    event_type: smart_irrigation_irrigation_finished
actions:
  - variables:
      zones: "{{ trigger.event.data.zones }}"
      problems: "{{ trigger.event.data.problems }}"
  - action: notify.mobile_app_your_phone
    data:
      title: "{{ '🚨' if problems | count > 0 else '🌱' }} Watering finished"
      message: >-
        {% set l = namespace(t=[]) %}
        {% for z in zones %}
          {% set l.t = l.t + [z.zone ~ ": " ~ (z.seconds / 60) | round(1) ~ " min, " ~ z.volume_l ~ " L"] %}
        {% endfor %}
        {% for p in problems %}
          {% set l.t = l.t + ["WARNING " ~ p.zone ~ ": " ~ p.reason] %}
        {% endfor %}
        {{ l.t | join("\n") }}
mode: single

If you previously had one automation per zone that opened the valve and called set_bucket or reset_bucket, remove them once direct valve control is on: Smart Irrigation now opens the valves and credits the water balance itself, so the old automations would double up. Keep only report/notification automations like the one above.

The legacy smart_irrigation_start_irrigation_all_zones event still fires too (it carries the trigger identity), for setups that drive watering from their own automation or an external executor instead of direct valve control.

When does it run? The active start trigger

Irrigation starts on a single active trigger, chosen in General under the start triggers. The triggers you define are the pool of options; only the selected one starts watering, so a run happens once per day.

The default, Default: done by sunrise, times the run so it finishes right at sunrise. Add custom triggers (sunset, solar azimuth, offsets) below and pick one as the active trigger if you prefer.

Main page: Configuration