General configuration

Main page: Configuration
Previous: Guided setup
Next: Zone configuration

This page provides the following global settings:

Automatic weather data update

If enabled, specify how often sensor update should happen (minutes, hours, days). You can also set up an update delay to be used to delay the first update. THis is useful in case your sensors do not provide a value immediately after Home Assistant starts.

As calculation needs weatherdata make sure to update your weather data at least once before calculating.

Automatic duration calculation

If enabled, set the time of calculation (HH:MM). Calculation uses weatherdata that is collected in updates to determine irrigation duration.

Each zone reads only the readings that arrived since its own last calculation, and remembers how far it has read. Readings are dropped once every zone using that sensor group has consumed them, so two zones sharing a group can calculate at different times without either of them losing data.

Irrigation usually starts hours after the calculation, and it can rain in between. When the start trigger is reached, each automatic zone's duration is reworked against the rain collected since its calculation, so a night of rain shortens the run or cancels it instead of watering the full calculated amount on wet ground.

The bucket itself is left alone by that. It is a running balance: irrigation credits it by the water actually applied and the next calculation adds the whole interval's rain, so crediting the rain at the start as well would count it twice. A run is only ever shortened this way, never lengthened, and a dry night leaves the calculated duration exactly as it is.

Note that the run still starts at the time it was scheduled for. A trigger set to finish at sunrise works back from the duration known at calculation time, so a run shortened by rain finishes early rather than starting late.

Calculate evapotranspiration hour by hour (beta)

On for a new installation, off for one that already existed. A fresh installation starts on it, because it is the better arithmetic; an installation set up before it arrived keeps the daily equation until its owner switches, because the two give different numbers and nobody's watering should change on an update without being asked. When on, PyETO sums the FAO-56 hourly equation (Eq. 53) over each hour of the zone's window instead of running the daily equation on the window's averages. The daily form is biased by cloudiness, because an average day hides whether the sun and the heat came together; summing the hours removes most of that bias. Calculating hour by hour at all is an idea taken from JustChr's Irrigation Plus fork, which is where it was first tried on this integration; the equations here are written from FAO-56 itself and checked against the paper's own worked example.

It needs temperature, humidity and wind speed in the sensor group (a sensor or a weather service), and the site's coordinates.

It is worth having when readings arrive through the day. Each hour is priced from the readings of that hour, so an update interval of minutes or an hour is what the form is for. One update a day leaves a single reading held across twenty-four hours: it still runs, and it does not produce nonsense, but the hours then differ only by the sun and the result is no more trustworthy than the daily equation's on the same data. Measured on a synthetic clear day, which of the two lands closer to the truth in that case depends on the hour the samples fell in. If your sensor group updates once or twice a day, raise the update frequency before reading anything into either form.

Solar radiation without a sensor. The hourly equation needs the sun of each hour, and there are three ways it can have it. A group with a radiation or illuminance sensor reads its own, as before. A group without one whose weather service can be asked reads the service's own hourly history, which measures and models it: Open-Meteo publishes it, and OpenWeatherMap or Pirate Weather answer through the Open-Meteo fallback they already use for radiation.

An installation with neither, a set of plain sensors and no weather service, estimates it: the day's temperature range gives the day's radiation (FAO-56 Eq. 50, the same equation the daily form falls back on), and the sun's own path over that day says which hours received it. Summed over a day the estimate is exactly what the daily equation would have used, so the amount of sun credited does not change; what changes is that it is placed on the hours it belongs to, which is the bias the hourly form exists to remove. The calculation log records whether the sun of a run was measured or estimated.

A greenhouse is the exception and keeps the daily equation when it has no sensor of its own: no reading of the sky describes what reaches a plant under glass, so there is nothing to estimate from. A lux sensor on the inside answers that properly, and the sensor group takes one.

Forecast days. A zone whose engine looks ahead waters on the mean of today and the days to come, so a hot tomorrow raises today's run. Those days are now read hour by hour as well: each one is priced as its own 24 hours, and the measured window joins the average as the rate per day it implies. Every term of that mean is then hourly, which is the point, since averaging an hourly sum with a day computed from its own averages would put the bias straight back in.

With any other module, or when the hours cannot be reconstructed (no readings, a field missing everywhere, a greenhouse with no radiation or illuminance sensor, or fewer forecast days available than the engine asks for), the daily equation keeps being used, so switching it on never leaves a zone without a calculation. The calculation explanation says which form was used.

Automatic weather data pruning (removed)

Weather data used to be cleared on a timer, and that setting no longer does anything.

It existed to stop the collected data growing without end, which pruning after each calculation now handles by itself. What it also did was throw away readings nobody had consumed: the clear ran at a fixed time while the calculation time is yours to choose, so moving the calculation earlier silently lost everything collected between the two, every night. A calculation at 18:55 against the default clear at 23:59 discarded five hours of evaporation a day, and the next calculation was short by that much.

Readings are also capped at a week, so nothing accumulates even if a zone stops calculating. The Clear all weather data action is still there for a deliberate reset.

Days between irrigation events

Configure the minimum number of days that must pass between irrigation events. This setting allows you to control how frequently irrigation can occur, which is useful for:

• Water conservation: Ensure adequate time between watering sessions
• Plant health: Allow soil to partially dry between irrigations
• Local restrictions: Comply with watering schedules or restrictions

How it works:

• Default value: 0 (no restriction - maintains current behavior)
• Range: 0-365 days
• When set to 0: Irrigation events can fire daily if conditions are met (default behavior)
• When set to a value > 0: Irrigation events will only fire if the specified number of days have passed since the last irrigation event

The value is the length of the watering cycle in calendar days: set to N, irrigation happens every N days.

Example scenarios:

• Set to 1: Allow irrigation every day (one calendar day between events)
• Set to 3: Allow irrigation every 3 days
• Set to 7: Weekly irrigation

The system automatically tracks the number of days since the last irrigation event. The counter is incremented once per calendar day, at midnight, whether or not irrigation happened that day. If an irrigation trigger occurs but insufficient days have passed, the event is skipped and the counter simply keeps running. When enough days have passed, the next trigger will fire the irrigation event and reset the counter to 0.

This feature works alongside existing precipitation forecasting - if both restrictions apply, both must be satisfied for irrigation to occur.

Skipping a run

A start trigger can be held back by the conditions below, all off by default. They are checked once a day, when the first start trigger is reached, and the Info page shows each of them with its numbers: whether it is off, could not be checked, is not blocking or is blocking. When a run is skipped, the smart_irrigation_irrigation_skipped event fires with the reason.

A condition that cannot be checked, because its sensor is unavailable or the weather service cannot be read, never stops a run: watering goes ahead as it would without it.

• Rain forecast. Skip when the weather service forecasts at least the threshold of rain for today and tomorrow. Zones in a greenhouse sensor group still water.

• Rain sensor. Skip while a binary sensor that is on in the rain says it is raining.

  On the advanced panel, that same sensor can do more than veto today: shorten runs after recent rain reads its history over the last five days, weighted so that yesterday counts for more than four days ago, and shortens the run by the result. A day of reported rain today takes the whole run, four days ago takes a tenth of it, and a wet week takes everything.

  It is for one case and it applies to one case: a zone whose sensor group reports no rain in millimetres at all, neither a gauge's depth nor a service's rate. Where millimetres exist, the water balance already carries them, decides for itself how long rain keeps counting, and this stays out of the way.

  It never touches the balance, because it does not know how much fell. The deficit stays where it was and is watered off once the weather turns, which is the safe direction: a run that was shortened too much is made up tomorrow, while water that was never owed cannot be taken back out of the ground. It needs a sensor that stays on while it rains; one that pulses briefly per bucket tip spends almost no time on and will barely register.

  The idea of weighting rain over a few rolling days comes from kloggy's HA-Irrigation-Version2 package, which does it with history_stats over five 24-hour windows.

• Freeze. Skip when the temperature is at or below the threshold, 2 °C (36 °F) unless you set one. It reads the sensor you choose, or the weather service's current temperature when none is set.

• Wind. Skip when the wind is at or above the threshold, 20 km/h (12 mph) unless you set one: in strong wind a sprinkler waters the path rather than the bed. It reads the sensor you choose, or the weather service's current wind. The weather service's wind is stored at 2 m for the evaporation, and is taken back up to the 10 m that forecasts and wind limits are quoted at.

• Days between irrigation, above.

Thresholds are entered in your unit system and a sensor is read in its own unit, so a sensor in °F works on a metric installation.

Soil moisture is set on each zone rather than here. Give a zone a soil moisture sensor and a threshold in %, 50 unless you set one, and while the reading is at or above it that zone sits the run out and the others water. Its duration for that run goes to 0 and its bucket is kept, so the deficit rolls over to the next run.

Continuous updates (experimental)

Continuous updates is an experimental feature that tries to capture more granular weather data to avoid missing chunks of weather patterns. For a zone to be continuous updated, it needs to:

• be set to automatic
• use a sensor group that does not rely on a weather service (none of the data has its source set to weather service).
• not use forecasting, as it relies on weather services. Set forecast days for PyETO to 0.

Any zone that does not meet the above requirements is not included in the continuous updates and instead will be included in the automatic update and calculation at the time configured. Any zone that does meet this requirement will not be included in the automatic update and calculation.

A sensor debounce setting is also provided to provide control over the speed of continuous updates.

Please note that this is experimental right now and will have bugs.

For continous updates, in the future, it will likely use specific set of aggregates (last for all data points except for solar radiation which will use average of riemann integral) and also requires current precipitation to be mapped in the sensor group.

Calculation log

Two days with what looks like nearly identical weather can produce very different watering volumes, and once a calculation has run there is normally no way to see why. Enable Calculation log to append one record per zone calculation to config/smart_irrigation/calc_log.jsonl (one JSON object per line, in metric units), so days can be compared afterwards instead of reconstructed by hand.

Each record holds the complete chain:

• Identification: local and UTC timestamp, zone, sensor group, calculation module, integration version.
• Inputs: the interval used (start, end, hours) and, per field, the aggregated value, the aggregation method applied (average / sum / minimum / maximum / riemann sum / delta / ...), how many records went into it, their minimum and maximum, the source (sensor, weather service, static) and whether the value was carried over from the last entry.
• Module intermediates: for PyETO the latitude, elevation, coastal flag, day of year, et_rad, cs_rad, sol_rad (and whether it was provided or estimated from temperature), net_in_sol_rad, avp, net_out_lw_rad, net_rad and eto, per day, plus the deltas list and its mean. The Passthrough and Static modules record their (fewer) inputs the same way.
• Outputs: ET deficiency, interval multiplier, precipitation, delta, bucket before and after, maximum bucket, drainage rate and drainage, precipitation rate, resulting duration and the volume in m³.

Dry runs (the dry_run option of the calculate services) are logged too - they are exactly when you ask "why this number?" - but every record carries a dry_run flag, so a dry run is never mistaken for a real calculation.

The setting is off by default. The file is capped at 2 MB and rotated (one backup kept), so it can be left on for a whole season. The most recent records are also included in the diagnostics download with coordinates rounded and entity ids removed, so they can be attached to an issue in one step.

To compare two days, for example with jq:

jq -c 'select(.zone.name == "Lawn") | {t: .timestamp, eto: .module.days[0].eto, sol_rad: .module.days[0].sol_rad, estimated: .module.days[0].sol_rad_estimated, bucket: .outputs.bucket_after, duration: .outputs.duration}' calc_log.jsonl

Unit System Responsiveness

Smart Irrigation automatically detects and responds to changes in your Home Assistant unit system setting (metric/imperial). When you change the unit system in Home Assistant:

• All sensor entities immediately update to display values in the new units
• The web interface refreshes to show measurements in the correct units
• Stored configurations like precipitation thresholds maintain their values but display in appropriate units
• No restart or integration reload is required

This ensures seamless transitions between unit systems without losing your configuration data.

Main page: Configuration
Previous: Guided setup
Next: Zone configuration