Irrigation Unlimited
This integration is for irrigation systems large and small. It can offer some complex arrangements without large and messy scripts. This integration will complement many other irrigation projects.
Home Assistant makes automating switches easy with the built in tools available. So why this project? You have a system in place but now you have extended it to have a number of zones. You don't want all the zones on at once because of water pressure issues. Maybe you would like each zone to have a number of schedules say a morning and evening watering. What about water restrictions that limit irrigation systems to certain days of the week or days in the month, odd or even for example. Perhaps you would like different schedules for winter and summer. Now you would like to adjust the times based on weather conditions, past, present or future. Let's turn a zone or even a controller off for system maintenance. Starting to sound more like your system? Finally what's going on now and what's up next.
Each controller has an associated (master) sensor which shows on/off status and other attributes. The master will be on when any of its zones are on. The master sensor can have a pre and post amble period to activate or warm up the system like charge up a pump, enable WiFi or turn on a master valve. The master sensor has a number of service calls available to enable/disable all the zones it controls.
Zones also have an associated sensor which, like the master, shows on/off status and various attributes. Zones sensors have service calls that can enable/disable and provide manual runs. Also adjust run times in automation scripts using information from integrations that collect weather data like OpenWeatherMap, BOM, weatherunderground and many others. Go crazy with projects like HAsmartirrigation.
Features
- Unlimited controllers.
- Unlimited zones.
- Unlimited schedules. Schedule by absolute time or sun events (sunrise/sunset). Select by days of the week (mon/tue/wed...). Select by days in the month (1/2/3.../odd/even). Select by months in the year (jan/feb/mar...). Overlapped schedules.
- Unlimited sequences. Operate zones one at a time in a particular order with a delay in between.
- Hardware independant. Use your own switches/valve controllers.
- Software independant. Pure play python.
*Practicle limitations will depend on your hardware.
Structure
Irrigation Unlimited is comprised of controllers, zones and schedules in a tree like formation. Each controller has one or more zones and each zone has one or more schedules. Controllers and zones will have a binary sensor associated with each one so they can be intregrated with Home Assistant.
└── Irrigation Unlimited
└── Controller 1 -> binary_sensor.irrigation_unlimited_c1_m
└── Zone 1 -> binary_sensor.irrigation_unlimited_c1_z1
└── Schedule 1
└── Schedule 2
...
└── Schedule N
└── Zone 2 -> binary_sensor.irrigation_unlimited_c1_z2
...
└── Zone N -> binary_sensor.irrigation_unlimited_c1_zN
...
└── Controller 2 -> binary_sensor.irrigation_unlimited_c2_m
...
└── Controller N -> binary_sensor.irrigation_unlimited_cN_m
...
Controllers and zones can specify an entity such as a switch or light, basically anything that turns on or off the system can control it. This is the irrigation valve. If this does not go far enough for your purposes then track the state of the binary sensors in an automation and do your own thing like run a script or scene.
This component will set up the following platforms.
| Platform | Description |
|---|---|
binary_sensor |
Show a valve On or Off |
A binary sensor is associated with each controller and zone. Controller or master sensors are named binary_sensor.irrigation_unlimited_cN_m and zone sensors binary_sensor.irrigation_unlimited_cN_zN. These sensors show the state of the master or child zones. Attributes show additional information like current schedule and next run time and duration.
Installation
Install from HACS
- Just search for Irrigation Unlimited integration in HACS and install it.
- Add Irrigation Unlimited to your configuration.yaml file. See configuration examples below.
- Restart Home Assistant.
Manual installation
- Using the tool of choice open the directory (folder) for your HA configuration (where you find
configuration.yaml). - If you do not have a
custom_componentsdirectory (folder) there, you need to create it. - In the
custom_componentsdirectory (folder) create a new folder calledirrigation_unlimited. - Download all the files from the
custom_components/irrigation_unlimited/directory (folder) in this repository. - Place the files you downloaded in the new directory (folder) you created.
- Restart Home Assistant
- In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Irrigation"
Using your HA configuration directory (folder) as a starting point you should now also have this:
custom_components/irrigation_unlimited/__init__.py
custom_components/irrigation_unlimited/binary_sensor.py
custom_components/irrigation_unlimited/const.py
custom_components/irrigation_unlimited/entity.py
custom_components/irrigation_unlilmited/irrigation_unlimited.py
custom_components/irrigation_unlimited/manifest.json
custom_components/irrigation_unlimited/service.py
custom_components/irrigation_unlimited/services.yaml
Configuration
Configuration is done by yaml.
The time type is a string in the format HH:MM. Time type must be a positive value. Seconds can be speicified but they will be rounded down to the system granularity. The default granularity is whole minutes (60 seconds). All times will be syncronised to these boundaries.
| Name | Type | Default | Description |
|---|---|---|---|
controllers |
list | Controller Objects | Controller details (Must have at least one) |
granularity |
number | 60 | System time boundaries in seconds |
testing |
object | Testing Object | Used for testing setup |
Controller Objects
This is the controller or master object and manages a collection of zones. There must be at least one controller in the system. The controller state reflects the state of its zones. The controller will be on if any of its zones are on and off when all zones are off.
| Name | Type | Default | Description |
|---|---|---|---|
zones |
list | Zone Objects | Zone details (Must have at least one) |
sequences |
list | Sequence Objects | Sequence details |
name |
string | Controller N | Friendly name for the controller |
enabled |
bool | true | Enable/disable the controller |
preamble |
time | '00:00' | The time master turns on before any zone turns on |
postamble |
time | '00:00' | The time master remains on after all zones are off |
entity_id |
string | Entity ID (switch.my_master_valve1) |
Zone Objects
The zone object manages a collection of schedules. There must be at least one zone for each controller.
| Name | Type | Default | Description |
|---|---|---|---|
schedules |
list | Schedule Objects | Schedule details (Must have at least one) |
zone_id |
string | N | Zone reference. Used for sequencing. |
name |
string | Zone N | Friendly name for the zone |
enabled |
bool | true | Enable/disable the zone |
minimum |
time | '00:01' | The minimum run time |
maximum |
time | The maximum run time | |
entity_id |
string | Entity ID (switch.my_zone_valve1) |
Schedule Objects
Schedules are future events, not dates for example Mondays. There must be at least one schedule for each zone.
The parameters weekday, day and month are date filters. If not specified then all dates qualify.
| Name | Type | Default | Description |
|---|---|---|---|
time |
time/Sun Event | Required | The start time. Either a time (07:30) or sun event |
duration |
time | Required | The length of time to run |
name |
string | Schedule N | Friendly name for the schedule |
weekday |
list | The days of week to run [mon, tue...sun] | |
day |
list | Days of month to run [1, 2...31]/odd/even | |
month |
list | Months of year to run [jan, feb...dec] |
Sun Event
Leave the time value in the Schedule Objects blank and add the following object. An optional before or after time can be specified.
| Name | Type | Default | Description |
|---|---|---|---|
sun |
string | Required | sunrise or sunset |
before |
time | '00:00' | Time before the event |
after |
time | '00:00' | Time after the event |
Sequence Objects
Sequences allow zones to run one at a time in a particular order with a delay in between.
| Name | Type | Default | Description |
|---|---|---|---|
schedules |
list | Schedule Objects | Schedule details (Must have at least one). Note: duration is ignored |
zones |
list | Sequence Zone Objects | Zone details (Must have at least one) |
delay |
time | Required | Delay between zones |
name |
string | Run N | Friendly name for the sequence |
Sequence Zone Objects
The sequence zone is a reference to the actual zone defined in the Zone Objects. Ensure the zone_id's match between this object and the zone object. The zone may appear more than once in the case of a split run.
| Name | Type | Default | Description |
|---|---|---|---|
zone_id |
string | Required | Zone reference. This must match the zone_id in the Zone Objects |
duration |
time | Required | The length of time to run |
Testing Object
The testing object is useful for running through a predetermined regime. Note: the speed value does not alter the system clock in any way. It is accomplished by an internal 'virtual clock'.
| Name | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true | Enable/disable testing |
speed |
number | 1.0 | Test speed. A value less than 1 will slow down the system. Values above 1 will speed up tests. A value of 2 will double the speed, 60 will turn minutes to seconds and 3600 will turn hours to seconds. Upper limit will depend on individual systems. |
times |
list | Test Time Objects | Test run times |
Test Time Objects
This is the test time object. Test times do not alter the system clock so there is no danger of disruption to the Home Assistant system.
| Name | Type | Default | Description |
|---|---|---|---|
name |
string | Test N | Friendly name for the test |
start |
datetime | The virtual start time (YYYY-mm-dd HH:MM) | |
end |
datetime | The virtual end time (YYYY-mm-dd HH:MM) |
Configuration examples
Minimal configuration
# Example configuration.yaml entry
irrigation_unlimited:
controllers:
zones:
entity_id: 'switch.my_switch'
schedules:
- time: '06:00'
duration: '00:20'
Sun event example
# Example configuration.yaml entry
# Run 20 minutes before sunrise for 30 minutes
irrigation_unlimited:
controllers:
zones:
schedules:
- name: 'Before sunrise'
time:
sun: 'sunrise'
before: '00:20'
duration: '00:30'
Sequence example
# Example configuration.yaml entry
irrigation_unlimited:
controllers:
zones:
- name: "Front lawn"
entity_id: "switch.my_switch_1"
- name: "Vege patch"
entity_id: "switch.my_switch_2"
- name: "Flower bed"
entity_id: "switch.my_switch_3"
sequences:
- delay: "00:01"
schedules:
- name: "Sunrise"
time:
sun: "sunrise"
- name: "After sunset"
time:
sun: "sunset"
after: "00:30"
zones:
- zone_id: 1
duration: "00:10"
- zone_id: 2
duration: "00:02"
- zone_id: 3
duration: "00:01"
For a more comprehensive example refer to here.
Services
The binary sensor associated with each controller and zone provide several services. The sensors offer the following services:
enabledisabletogglemanual_runadjust_time
If a controller sensor is targetted then it will effect all its children zones.
Services enable, disable and toggle
Enables/disables/toggles the controller or zone respectively.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
no | Controller or zone to enable/disable/toggle. |
Service manual_run
Turn on the controller or zone for a period of time.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
no | Controller or zone to run. |
time |
no | Controller or zone to run. |
Service adjust_time
Adjust the run times. Calling this service will override any previous adjustment i.e. it will not make adjustments on adjustments. For example, if the scheduled duration is 30 minutes calling percent: 150 will make it 45 minutes then calling percent 200 will make it 60 minutes. Must have one and only one of actual, percentage, increase, descrease or reset.
Tip
Use forecast and observation data collected by weather integrations in automations to adjust the run times. See below for more information.
| Service data attribute | Optional | Description |
|---|---|---|
entity_id |
no | Controller or zone to run. |
actual |
yes | Specify a new time time. This will replace the existing duration. A time value is required '00:30'. |
percentage |
yes | Adjust time by a percentage. A positive float value. Values less than 1 will decrease the run time while values greater than 1 will increase the run time. |
increase |
yes | Increase the run time by the specified time. A value of '00:10' will increase the duration by 10 minutes. Value will be capped by the maximum setting. |
descrease |
yes | Decrease the run time by the specified time. A value of '00:05' will decrease the run time by 5 minutes. Value will be limited by the minimum setting. |
reset |
yes | Reset adjustment back to the original schedule time (Does not effect minimum or maximum settings). |
minimum |
yes | Set the minimum run time. Minimum run time is 1 minute and will be limited to this. Use the disable service to turn off. |
maximum |
yes | Set the maximum run time. Note: The default is no limit. |
Service reload
Reload the YAML configuration file. Do not add or delete controllers or zones, they will not work because of the associated entities which are created on startup. This may be addressed in a future release, however, suggested work around is to set enabled to false to effectively disable/delete. All other settings can be changed including schedules. You will find the control in Configuration -> Server Controls -> YAML configuration reloading.
Frontend
Because this is an integration there is no frontend. For an out-of-the-box vanilla solution, simply put the master and zone binary sensors onto an entity card to see what is going on. However, for some inspiration and a compact card try this.
and it expands to:
Note: This card uses some custom cards multiple-entity-row, fold-entity-row, logbook-card and at the moment card-mod for styles.
For watering history information here is a sample card.
.
Note: At time of writing this requires a pre-released version of mini-graph-card.
Although not really part of the integration but to get you started quickly here is a temperature card.
.
And a rainfall card. Note how the watering times reduced as rainfall started. More on this below in Automation.
.
Finally, a system event log.
.
Putting it all together, here is the complete picture.
.
This configuration is three vertical stacks and works well on mobile devices.
Automation
Due to the many weather integrations available and their relevance to your situation, there is realistically no way to provide a built in 'auto-adjustment' feature. Therefore, no attempt has been made to include a solution and this also makes the integration more independant and flexible. Run time adjustment is achieved by setting up sensor(s) that consume weather information such as rainfall and temperature but could factor in wind speed, solar radiation etc. to determine if more or less watering time is required. You might also consider using forecast information... A service call is then made to irrigation unlimited to adjust the run times. This does mean some knowledge of creating automations is required.
On a personal note, I use the national weather service BOM for my forecast information but find their observation data not relevant due to the extreme regional variations in my situation. There are many micro climates (mountains) and a few kilometers in any direction makes a lot of difference, down pour to a few drops. To this end I have a Personal Weather Station (PWS) that feeds Weather Underground where I use the WUnderground integration to retrieve the data.
You will find my adjustment automation here which feeds off the temperature and rainfall observation data. There is a card here which displays this information (uses multiple-entity-row). Some ideas were gleaned from kloggy's work.
Troubleshooting
Please set your logging for the custom_component to debug:
logger:
default: info
logs:
custom_components.irrigation_unlimited: debug
Notes
- All feature requests, issues and questions are welcome.
Contributions are welcome
If you want to contribute to this please read the Contribution guidelines.
Credits
Code template was mainly taken from @Ludeeus's integration_blueprint template.
Some inspiration was taken from kloggy's work.
![[Question] HAsmartirrigation Integration](https://avatars.githubusercontent.com/u/4199295?v=4)
5 Jan 1, 2022
4 Oct 20, 2022
13 Jun 7, 2022
216 Dec 26, 2022
152 Dec 31, 2022
4 Feb 28, 2022
175 Dec 29, 2022
1 Oct 30, 2021
3 Aug 19, 2022
10 Dec 26, 2022
9 Nov 22, 2022
4 Aug 30, 2022
16 Aug 30, 2022
364 Dec 28, 2022
133 Jan 5, 2023
89 Dec 10, 2022
8 Apr 16, 2022
1 Oct 15, 2022
1 Dec 29, 2021