Versions since v0.0.30 introduced a number of bugs. As a result we have reverted back to v0.0.29 and implemented bug fixes only from there. Versions from v0.0.40 onwards should work correctly. Change percentage feature has been removed while we work on bringing it back later. You will see references to it in the code as it has been temporarily removed from the options screen and any calculations. We apologize for any inconvenience caused.
Smart Irrigation custom component for Home Assistant. Partly based on the excellent work at https://github.com/hhaim/hass/. This component calculates the time to run your irrigation system to compensate for moisture lost by evaporation / evapotranspiration. Using this component you water your garden, lawn or crops precisely enough to compensate what has evaporated. It takes into account precipitation (rain,snow) and adjusts accordingly, so if it rains or snows less or no irrigation is required. By adding multiple instances of this component multiple zones can be supported as each zone will have its own sprinkler and flow configuration.
Note - use this component at your own risk - we do not assume responsibility for any inconvience caused by using this component. Always use common sense before deciding to irrigate using the calculations this component provides. For example, irrigating during excessive rainfall might cause flooding. Again - we assume no responsibility for any inconvience caused.
Note If you want to go back and change your settings afterwards, you can either delete the instance and re-create it or edit the entity registry under config/.storage at your own risk.
The component keeps track of hourly precipitation and at 23:00 (11:00 PM) local time stores it in a daily value.
It then calculates the exact runtime in seconds to compensate for the net evaporation.
Note that this is the default behavior and this can be disabled if you want more control. Also, the time auto refresh happens (if not disabled) is configurable.
This is all the component does, and this is on purpose to provide maximum flexibility. Users are expected to use the value of sensor.smart_irrigation.daily_adjusted_run_time to interact with their irrigation system and afterwards call the smart_irrigation.reset_bucket service. See the example automations below.
This component uses reference evapotranspiration values and calculates base schedule indexes and water budgets from that. This is an industry-standard approach. Information can be found at https://www.rainbird.com/professionals/irrigation-scheduling-use-et-save-water, amongst others. The component uses the PyETo module to calculate the evapotranspiration value (fao56). Also, please see the How this works Wiki page.
- Snow and rain fall on the ground add moisture. This is tracked /predicted hourly depending on the operation mode by the
rainandsnowattributes Together, this makes up theprecipitation. - Sunshine, temperature, wind speed, place on earth and other factors influence the amount of moisture lost from the ground(
evapotranspiration). This is tracked / predicted hourly depending on the operation mode. - The difference between
precipitationandevapotranspirationis thenetto precipitation: negative values mean more moisture is lost than gets added by rain/snow, while positive values mean more moisture is added by rain/snow than what evaporates. - Once a day (time is configurable) the
netto precipitationis added/substracted from thebucket,which starts as empty. If thebucketis below zero, irrigation is required. - Irrigation should be run for
daily_adjusted_run_time, which is 0 ifbucket>=0. Afterwards, thebucketneeds to be reset (usingreset_bucket). It's up to the user of the component to build the automation for this final step.
There are many more options available, see below. To understand how precipitation, netto precipitation, the bucket and irrigation interact, see example behavior on the Wiki.
You can use this component in various modes:
- Full Open Weather Map. In this mode all data comes from the Open Weather Map service. You will need to create and provide an API key. See Getting Open Weater Map API Key below for instructions.
- Full Sensors. Using sensors. In this mode all data comes from sensors such as a weather station. When specificying a sensor for precipitation, note that it needs to be a cumulative daily sensor. Open Weather Map is not used and you do not need an API key.
- Mixed. A combination of 1) and 2). In this mode part of the data is supplied by sensors and part by Open Weather Map. In this mode you will need to create and provide an API key. See Getting Open Weater Map API Key below for instructions. When specificying a sensor for precipitation, note that it needs to be a cumulative daily sensor.
- Not calculating. This mode allows you to skip the calculations of evapotranspiration all together and instead rely on a sensor to provide this value. In this mode, you will need to specify a precipitation sensor as well. Both of these need to be a cumulative daily sensor.
When planning to set up mode 2) (Full Sensors), 3) (Mixed) or 4) (Not Calculating) see Measurements and Units for more information on the measurements and units expected by this component.
In order to get the most accurate results using sensors is preferable either from your own weather station or from another, from example through Weatherflow Smart Weather. If you have a weather station that provides evapotranspiration (ET) values, use that (mode 4). If you do not have that, use sensors including solar radiation (mode 3). If you do not have access to a sensor that provides solar radiation, let this component estimate it but use sensors for the other inputs (modified mode 3). If you do have access to limited amount of sensors (say only temperature) use that and use Open Weather Map for the rest (mode 2). If you do not have access to any sensors at all use Open Weather Map (mode 1).
Since this component provides multiple configuration options it might get confusing about in which scenario what behavior can be expected and what input is required. In the table below we summarize the configuration modes, their accuracy, the required input and how daily adjusted run time is calculated. Keep in mind that daily adjusted run time is based on the netto precipitation (precipitation - evapotranspiration) and the bucket value for previous days.
| Mode | Accuracy | Input | How adjusted run time is calculated |
|---|---|---|---|
| Mode 1 - Full Open Weather Map | Low | No sensor input required, just an API key for Open Weather Map | Average of precipitation and evapotranspiration. |
| Mode 2 - Full Sensor, but calculating evapotranspiration | High | Sensors are required for all inputs. All inputs are expected to be point-in-time, except precipitation. That sensor is normally provided by a weather station or weather service as a daily accumulative / 'total precipitation today' sensor and that is what is expected by the component | Most recent value for precipitation and average of evapotranspiration. |
| Mode 3 - Mixed | Medium | API key is required for any inputs that have not been provided sensors. All inputs are expected to be point-in-time, except precipitation. That sensor is normally provided by a weather station or weather service as a 'total precipitation today' sensor and that is what is expected by the component | If a sensor is provided for precipitation, most recent value for precipitation is used. Otherwise the average of both precipitation and evapotranspiration. |
| Mode 4 -Not calculating | Very high | In this mode, just two sensors are required: one for precipitation and one for evapotranspiration. Both are expected to be daily accumulative sensors ('total today'), as is normally the case when provided by a weather service or weather station. | Most recent value of both precipitation and evapotranspiration. |
In this section:
- One-time set up
- List of events, services entities and attributes created
- Example automation
- Optional settings
Install the custom component (preferably using HACS) and then use the Configuration --> Integrations pane to search for 'Smart Irrigation'. You will need to specify the following:
- Names of sensors that supply required measurements (optional). Only required in mode 2) and 3). See Measurements and Units for more information on the measurements and units expected by this component.
- API Key for Open Weather Map (optional). Only required in mode 1) and 3). See Getting Open Weater Map API Key below for instructions.
- Reference Evapotranspiration for all months of the year. See Getting Monthly ET values below for instructions. Note that you can specify these in inches or mm, depending on your Home Assistant settings.
- Number of sprinklers in your irrigation system
- Flow per spinkler in gallons per minute or liters per minute. Refer to your sprinkler's manual for this information.
- Area that the sprinklers cover in square feet or m2
Multi-zone support: For irrigation systems that have multiple zones which you want to run in series (one after the other), you need to add an instance of this integration for each zone. Of course, the configuration should be done for each zone, including the area the zone covers and the sprinkler settings.
When entering any values in the configuration of this component, keep in mind that the component will expect inches, sq ft, gallons, gallons per minute, or mm, m2, liters, liters per minute respectively depending on the settings in Home Assistant (imperial vs metric system). For sensor configuration take care to make sure the unit the component expects is the same as your sensor provides.
If you want to go back and change your settings afterwards, you can either delete the instance and re-create it or edit the entity registry under
config/.storageat your own risk.
After successful configuration, you should end up with three entities and their attributes, listed below as well as three services.
For each instance of the component the following services will be available:
| Service | Description |
|---|---|
smart_irrigation.[instance]_calculate_daily_adjusted_run_time |
Triggers the calculation of daily adjusted run time. Use only if you disabled automatic refresh in the options. |
smart_irrigation.[instance]_calculate_hourly_adjusted_run_time |
Triggers the calculation of hourly adjusted run time. Use for debugging only. |
smart_irrigation.[instance]_enable_force_mode |
Enables force mode. |
smart_irrigation.[instance]_disable_force_mode |
Disables force mode. |
smart_irrigation.]instance]_reset_bucket |
Resets the bucket to 0. Needs to be called after done irrigating (see below). |
smart_irrigation.[instance]_set_bucket |
Sets the bucket to the provided value. Use for debugging only. |
The component uses a number of events internally that you do not need to pay attention to unless you need to debug things. The exception is the _start event.
| Event | Description |
|---|---|
[instance]_start |
Fires depending on daily_adjusted_run_time value and sunrise. You can listen to this event to optimize the moment you irrigate so your irrigation starts just before sunrise and is completed at sunrise. See below for examples on how to use this. |
[instance]_bucketUpd |
Fired when the bucket is calculated. Happens at automatic refresh time or as a result of the reset_bucket, set_bucket or calculate_daily_adjusted_run_time service. |
[instance]_forceModeTog |
Fired when the force mode is disabled or enabled. Result of calling enable_force_mode or disable_force_mode |
[instance]_hourlyUpd |
Fired when the hourly adjusted run time is calculated. Happens approximately every hour and when calculate_hourly_adjusted_run_time service is called. |
The number of seconds the irrigation system needs to run assuming maximum evapotranspiration and no rain / snow. This value and the attributes are static for your configuration. Attributes:
| Attribute | Description |
|---|---|
number of sprinklers |
number of sprinklers in the system |
flow |
amount of water that flows through a single sprinkler in liters or gallon per minute |
throughput |
total amount of water that flows through the irrigation system in liters or gallon per minute. |
reference evapotranspiration |
the reference evapotranspiration values provided by the user - one for each month. |
area |
the total area the irrigation system reaches in m2 or sq ft. |
precipitation rate |
the output of the irrigation system across the whole area in mm or inch per hour |
base schedule index minutes |
the value of the entity in minutes instead of seconds |
auto refresh |
indicates if automatic refresh is enabled. |
auto refresh time |
time that automatic refresh will happen, if enabled. |
force mode duration |
duration of irrigation in force mode (seconds). |
Sample screenshot:
The adjusted run time in seconds to compensate for any net moisture losses that are not compensated by rain. Updated approx. every 60 minutes. In contrast to the daily adjusted run time, no lead time is added and no capping to any maximum is applied. Attributes:
| Attribute | Description |
|---|---|
rain |
the predicted (when using Open Weather Map) or cumulative daily (when using a sensor) rainfall in mm or inch |
snow |
the predicted (when using Open Weather Map, will be 0 when using a sensor) snowfall in mm or inch |
precipitation |
the total precipitation (which is the sum of rain and snow in mm or inch) |
evapotranspiration |
the expected evapotranspiration |
netto precipitation |
the net evapotranspiration in mm or inch, negative values mean more moisture is lost than gets added by rain/snow, while positive values mean more moisture is added by rain/snow than what evaporates, equal to precipitation - evapotranspiration |
water budget |
percentage of expected evapotranspiration vs peak evapotranspiration |
adjusted run time minutes |
adjusted run time in minutes instead of seconds. |
Sample screenshot:
The adjusted run time in seconds to compensate for any net moisture lost. Updated every day at 11:00 PM / 23:00 hours local time. Use this value for your automation (see step 3, below). Attributes:
| Attribute | Description |
|---|---|
water budget |
percentage of net precipitation / base schedule index |
bucket |
running total of net precipitation. Negative values mean that irrigation is required. Positive values mean that more moisture was added than has evaporated yet, so irrigation is not required. Should be reset to 0 after each irrigation, using the smart_irrigation.reset_bucket service |
lead_time |
time in seconds to add to any irrigation. Very useful if your system needs to handle another task first, such as building up pressure. |
maximum_duration |
maximum duration in seconds for any irrigation, including any lead_time. |
adjusted run time minutes |
adjusted run time in minutes instead of seconds. |
Sample screenshot:
You will use sensor.smart_irrigation_daily_adjusted_run_time to create an automation (see step 3, below).
The How this works Wiki page describes the entities, the attributes and the calculations.
Since this component does not interface with your irrigation system directly, you will need to use the data it outputs to create an automation that will start and stop your irrigation system for you. This way you can use this custom component with any irrigation system you might have, regardless of how that interfaces with Home Assistant. In order for this to work correctly, you should base your automation on the value of sensor.smart_irrigation_daily_adjusted_run_time as long as you run your automation after it was updated (11:00 PM / 23:00 hours local time). If that value is above 0 it is time to irrigate. Note that the value is the run time in seconds. Also, after irrigation, you need to call the smart_irrigation.reset_bucket service to reset the net irrigation tracking to 0.
The last step in any automation is very important, since you will need to let the component know you have finished irrigating and the evaporation counter can be reset by calling the
smart_irrigation.reset_bucketservice
Here is an example automation that runs when the smart_irrigation_start event is fired. It checks if sensor.smart_irrigation_daily_adjusted_run_time is above 0 and if it is it turns on switch.irrigation_tap1, waits the number of seconds as indicated by sensor.smart_irrigation_daily_adjusted_run_time and then turns off switch.irrigation_tap1. Finally, it resets the bucket by calling the smart_irrigation.reset_bucket service. If you have multiple instances you will need to adjust the event, entities and service names accordingly.
- alias: Smart Irrigation
description: 'Start Smart Irrigation at 06:00 and run it only if the adjusted_run_time is >0 and run it for precisely that many seconds'
trigger:
- event_data: {}
event_type: smart_irrigation_start
platform: event
condition:
- above: '0'
condition: numeric_state
entity_id: sensor.smart_irrigation_daily_adjusted_run_time
action:
- data: {}
entity_id: switch.irrigation_tap1
service: switch.turn_on
- delay:
seconds: '{{states("sensor.smart_irrigation_daily_adjusted_run_time")}}'
- data: {}
entity_id: switch.irrigation_tap1
service: switch.turn_off
- data: {}
service: smart_irrigation.reset_bucket
See more advanced examples in the Wiki.
After setting up the component, you can use the options flow to configure the following:
| Option | Description | Default |
|---|---|---|
| Lead time | Time in seconds to add to any irrigation. Very useful if your system needs to handle another task first, such as building up pressure. | 0 |
| Maximum duration | Maximum duration in seconds for any irrigation, including any lead_time. -1 means no maximum. |
-1 |
| Show units | If enabled, attributes values will show units. By default units will be hidden for attribute values. | False |
| Automatic refresh | By default, automatic refresh is enabled. Disabling it will require the user to call smart_irrigation.calculate_daily_adjusted_run_time manually. |
True |
| Automatic refresh time | Specifies when to do the automatic refresh if enabled. | 23:00 |
| Initial update delay | Delay before first sensor update after reboot. This is useful if using sensors that do not have a status right after reboot. | 30 |
| Coastal | If the location you are tracking is situated on or adjacent to coast of a large land mass or anywhere else where air masses are influenced by a nearby water body, enable this setting. | False |
| Solar Radiation calculation | From v0.0.50 onwards, the component estimates solar radiation using temperature, which seems to be more accurate. If for whatever reason you wanted to revert back to the pre v0.0.50 behavior (which used a estimation of sun hours) disable this. | True |
This Wiki page provides insight into how this component should behave in certain weather conditions. With this you should be able to do a sanity check against your configuration and make sure everything is working correctly.
The component provides the following services:
| Service | Description |
|---|---|
smart_irrigation.reset_bucket |
this service needs to be called after any irrigation so the bucket is reset to 0. |
smart_irrigation.set_bucket |
call this service to set the bucket to the value you provide. This service should only be used for debugging purposes. |
smart_irrigation.calculate_daily_adjusted_run_time |
calling this service results in the smart_irrigation.daily_adjusted_run_time entity and attributes to be updated right away. |
smart_irrigation.calculate_hourly_adjusted_run_time |
calling this service results in the smart_irrigation.hourly_adjusted_run_time entity and attributes to be updated right away. |
smart_irrigation.enable_force_mode |
Enables force mode. In this mode, smart_irrigation.daily_adjusted_run_time will also be set to the configured force mode duration. |
smart_irrigation.disable_force_mode |
Disables force mode. Normal operation resumes. |
Go to https://openweathermap.org and create an account. You can enter any company and purpose while creating an account. After creating your account, go to API Keys and get your key. If the key does not work right away, no worries. The email you should have received from OpenWeaterMap says it will be activated 'within the next couple of hours'. So if it does not work right away, be patient a bit. You will need to sign up for the paid (but free for limited API calls) OneCall API 3.0 plan if you do not have a key already. You can use a key for the 3.0 and 2.5 version of the API.
To get the monthly ET values use Rainmaster (US only), World Water & Climate Institute (worldwide) or another source that has this information for your area.
When entering the ET values in the configuration of this component, keep in mind that the component will expect inches or mm depending on the settings in Home Assistant (imperial vs metric system).
Go to http://www.rainmaster.com/historicET.aspx and enter your 5-digit zipcode and click 'Find'. The values you are looking for are listed for each month in inch/day:
Unfortunately the atlas linked below seems to be offline. Please refer to this wiki page for country specific information and feel free to reach out to add your country specific info!
Go to http://wcatlas.iwmi.org/ and create an account. Once logged in, enter the locations you are interested in and click 'Submit'. Be sure to select N/S and E/W according to your coordinates:
The values you are looking for are in the last column (Penman ETo (mm/day)):
