Smart Irrigation

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.

Visual representation of what this component does

1. Snow and rain fall on the ground add moisture. This is tracked /predicted hourly depending on the operation mode by the rain and snow attributes Together, this makes up the precipitation.
2. 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.
3. The difference between precipitation and evapotranspiration is the netto 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.
4. Once a day (time is configurable) the netto precipitation is added/substracted from the bucket, which starts as empty. If the bucket is below zero, irrigation is required.
5. Irrigation should be run for daily_adjusted_run_time, which is 0 if bucket>=0. Afterwards, the bucket needs to be reset (using reset_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.

Operation modes

You can use this component in various modes:

1. 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.
2. 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.
3. 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.
4. 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.

Getting the best results

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.

Configuration

In this section:

• One-time set up
• List of events, services entities and attributes created
• Example automation
• Optional settings

Step 1: configuration of component

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 m²

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, m², 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/.storage at your own risk.

Step 2: checking services, events and entities

After successful configuration, you should end up with three entities and their attributes, listed below as well as three services.

Services

For each instance of the component the following services will be available:

Events

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.

Entities

sensor.smart_irrigation_base_schedule_index

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:

Sample screenshot:

sensor.smart_irrigation_hourly_adjusted_run_time

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:

Sample screenshot:

sensor.smart_irrigation_daily_adjusted_run_time

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:

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.

Showing other attributes as entities (sensors)

See the Wiki for more information on how to expose other values this components calculates as sensors.

Step 3: creating automation

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_bucket service

Example automation 1: one valve, potentially daily irrigation

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.

Step 4: configuring optional settings

After setting up the component, you can use the options flow to configure the following:

Example behavior in a week

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.

Available services

The component provides the following services:

How this works

See the Wiki.

Getting Open Weather Map API key

Go to https://openweathermap.org and create an account. You can enter any company and purpose while creating an account. After creating your account, 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. Then, 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 can use a key for the 3.0 and 2.5 version of the API. If you are worried about the cost of the API, You can put a rate limit below the paid threshold in the "Billing plans" page of your profile.

Getting Monthly ET values

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).

Using Rainmaster (US only)

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:

World Water & Climate Institute (International)

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)):