Homebridge Smart Irrigation

Description

Turn any electrical irrigation valve into a smart-valve.. or run your pumps on a smart schedule based on your climate!

This Homebridge plugin exposes a multi-zone irrigation sprinkler dummy control system to Apple's HomeKit.

Although a dummy, it brings smarts of an evapotranspiration[ETo] based climate/plant adaptive irrigation controller with the use of OpenWeatherMap API. All parameters can be configured from the Homebridge UI and the plugin offers granular control specific to every zone's individual requirements.

The plugin can optionally email you, and/or send you push notifications through Pushover and Pushcut, with the watering schedule it has calculated, or when a watering run is completed, along with the next 7-day weather forecast.

Added option to expose system controls to Homekit allowing a user to enable/disable irrigation, rechecks, push and email notifications from within the Home App. Associated WaterLevel Characteristic shows the % of watering cycle remaining.

Why?

Searching for an irrigation or sprinkler control plugin never showed any suitable option for my needs. The one that came closest, and is the inspiration and basis for this plugin is Tom Rodrigues's homebridge-web-sprinklers. But like many others, I didn't have the http hardware for it to control, or the inclination to rig it! What I did have access to, were some solenoid valves which I could power from a smart socket that was exposed to Homekit. So I stripped the code to just expose the dummy sprinkler accessories, reworked the irrigation logic - and then, one thing led to another.. in my quest to achieve a more granular control and incorporate more irrigation science to create a climate adaptive irrigation controller.

Basic use case..

1. Configure the plugin to expose the required number sprinkler accessories(zones)
2. Use the Eve app or another Homekit controller app to configure ANY other smart plug or outlet in your Homekit ecosystem to follow the state of the above exposed sprinklers
3. The smartplug/outlet/valve in their simplest configuration could be just driving the power of any solenoid valve that controls watering to a zone

Installation

1. Install Homebridge
2. Install this plugin:
   • Homebridge Config UI X: Search for homebridge-smart-irrigation plugin and install
   • Manually: Run sudo npm install -g homebridge-smart-irrigation from the terminal
3. Sign up at the OpenWeatherMap website and retrieve your API key (if you want adaptive control). The free tier allows 1000 API calls a day and this plugin will make no more than a couple on any day!
4. Gather the mean daily Solar Radiation figures for your location in kWh/day. Please read the settings section for more details
5. Configure the settings
6. Use the Eve app or any other Homekit controller app to setup automations for your smartplug or outlet to follow the state of the zones exposed by the plugin

Operating Principle

One of the primary factors affecting the water demand of plants is evapotranspiration, also denoted as ETo and expressed in mm. While the subject of irrigation is one of extensive global research and there is no end to the extent of complication one can end up with, this plugin chooses to focus on three - ETo, local rain and the crop characteristics of each of the zones configured.

ETo is calculated using the Penman-Monteith Evapotranspiration (FAO-56) Method. Those interested in a deeper understanding of the principles may head to this excellent resource of FAO. The factors used include the following (daily):

1. Min/Max Temperatures
2. Mean RH
3. Wind speed
4. Shortwave Solar Radiation [more on this later..]
5. Atmospheric Pressure (barometric)
6. Latitude
7. Elevation
8. Julian day

Rain is derived from OpenWeatherMap API along with some of the factors above using the latitude and longitude configured.

Crop characteristics use some of the understanding gained from the website of University of California, Division of Agriculture and Natural Resources and particularly from this document for calculating drip irrigation schedules. Specifically, it utilises the following based on the conditions of the particular zone being irrigated:

1. Crop coefficients [0.1 - 0.9] based on the type of plants Read here!
2. Planting Density [0.5 - 1.3]
3. Exposure Factor [0.5 - 1.4] based on the zone's microclimate

Additionally, information about the number of drip emitters, their discharge rate, area irrigated and efficiency is considered with the above factors.

Operating Logic & Scheduling

If masterDisable is not checked, the plugin will calculate the total watering durartion and check if watering can be completed today before sunrise or by the time as specified in sunriseOffset. If not, it will schedule the irrigation for the next day. Regardless of masterDisable it will gather the weather information and also send a notification email if emailEnable is set.

Forecasted low and high temperature higher than their respective thresholds must be met for the day being scheduled.

If adaptive watering is disabled for a zone, but scheduling remains enabled, the zone will be watered for the number of minutes specified by defDuration and not factor any other calculations.

The plugin schedules asynchronous zone watering - cycling sequentially through all the scheduled zones needing water one at a time and repeats the process the number of times specified by cycles.

Start times will vary daily as a result of changing sunrise times as well as the calculated watering time based on the weather factors.

recheckTime instructs the plugin to reassess the watering times based on the most current forecast available 15, 30 or 60 minutes prior to the scheduled run - if this is of no use to you set it to 0. But for many living in tropical regions where climate modeling is far too complex to give accurate forecasting, this can be helpful as the forecasts change frequently or significantly.

1. Gather weather forecast for the next 7-day period
2. Using the above and Solar Radiation data, calculate projected ETo for the next 7 days
3. If the zone is enabled & adaptive, calculate the total ETo until the next watering day
4. If rainFactoring is enabled, calculate the total projected rainfall till the zone's next watering day
5. Calculate the net irrigation requirement of a zone based on total ETo and total rain till the zone's next watering schedule
6. Calculate zone specific time required based on that zone's irrigation infrastructure and crop profile
7. Schedule the watering run and send notification email if emailEnable
8. Reassess recheckTime minutes before the scheduled run

Example config block:

{
            "accessory": "SmartSprinklers",
            "name": "Irrigation",
            "exposeControls": true,
            "verbosed": true,
            "masterDisable": false,
            "recheckTime": 15,
            "latitude": 25.009243,
            "longitude": 77.73491,
            "altitude": 390,
            "keyAPI": "yOuR_OWM_key",
            "cycles": 2,
            "sunriseOffset": 0,
            "lowThreshold": 8,
            "highThreshold": 18,
            "emailEnable": true,
            "senderName": "💦 Irrigation Control",
            "senderEmail": "[email protected]",
            "sendTo": "[email protected]",
            "smtpHost": "smtp.gmail.com",
            "smtpPort": 587,
            "portSecure": false,
            "userID": "[email protected]",
            "userPwd": "password",
            "pushEnable": true,
            "userPO": "your---user---key",
            "tokenPO": "your---app---token",
            "devicePO": "iphone",
            "priorityPO": 0,
            "soundPO": "pushover",
            "pcEnable": true,
            "pcKey": "abcdXXXXabcd",
            "pcDevices": "iPad,iPhone",
            "pcWeatherChecked": "Test Checked",
            "pcWeatherCheckedSound": "system",
            "pcWateringStart": "Test Start",
            "pcWateringStartSound": "system",
            "pcWateringEnd": "Test End",
            "pcWateringEndSound": "jobDone",
            "JanRad": 5.4,
            "FebRad": 6.3,
            "MarRad": 7,
            "AprRad": 7.3,
            "MayRad": 7.2,
            "JunRad": 5.7,
            "JulRad": 5,
            "AugRad": 5.1,
            "SepRad": 5.5,
            "OctRad": 5.7,
            "NovRad": 5.2,
            "DecRad": 5,
            "zones": [
                {
                    "zoneName": "Flowerbed",
                    "enabled": true,
                    "adaptive": true,
                    "rainFactoring": true,
                    "defDuration": 30,
                    "maxDuration": 60,
                    "rainThreshold": 2.5,
                    "tweakFactor": 100,
                    "dripLPH": 8,
                    "dripNos": 23,
                    "dripArea": 2.7,
                    "efficiency": 100,
                    "cropCoef": 0.6,
                    "plantDensity": 1.1,
                    "expFactor": 1,
                    "wateringMonths": [
                        "Jan",
                        "Feb",
                        "Mar",
                        "Apr",
                        "May",
                        "Jun",
                        "Jul",
                        "Aug",
                        "Sep",
                        "Oct",
                        "Nov",
                        "Dec"
                    ],
                    "wateringWeekdays": [
                        "Sunday",
                        "Monday",
                        "Tuesday",
                        "Wednesday",
                        "Thursday",
                        "Friday",
                        "Saturday"
                    ]
                },
                {
                    "zoneName": "Pots",
                    "enabled": true,
                    "adaptive": true,
                    "rainFactoring": true,
                    "defDuration": 10,
                    "maxDuration": 30,
                    "rainThreshold": 2.5,
                    "tweakFactor": 100,
                    "dripLPH": 2,
                    "dripNos": 1,
                    "dripArea": 0.05,
                    "efficiency": 100,
                    "cropCoef": 0.6,
                    "plantDensity": 0.5,
                    "expFactor": 0.9,
                    "wateringMonths": [
                        "Jan",
                        "Feb",
                        "Mar",
                        "Apr",
                        "May",
                        "Jun",
                        "Jul",
                        "Aug",
                        "Sep",
                        "Oct",
                        "Nov",
                        "Dec"
                    ],
                    "wateringWeekdays": [
                        "Sunday",
                        "Tuesday",
                        "Thursday",
                        "Friday"
                    ]
                }
            ]
        }

Primary Setup

Expose Controls - exposeControls - exposes up to 5 additional related switch services allowing a user basic control of the system from within the Home App:

• Master: If exposed, this switch allows enabling or disabling irrigation. When disabled it will cancel any scheduled watering cycles - although the system will continue routine weather checks(and notifications if enabled). Re-enabling will trigger recalculation and rescheduling.
• Recheck: This is exposed only if the recheckTime has been set to a non-zero value. When disabled it will cancel any scheduled rechecks - although the system will proceed with the scheduled watering cycles. Re-enabling will trigger recalculation and rescheduling.
• Email Notify: This is exposed only if emailEnable has been set. Enable/disable email notifications.
• Pushover Notify: This is exposed only if pushEnable has been set. Enable/disable Pushover notifications.
• Pushcut Notify: This is exposed only if pcEnable has been set. Enable/disable Pushcut notifications.

These switch settings are persistent across plugin/Homebridge restarts, so you shouldn't have to reset your preferences in the Home App!

| Key | Description | Default | | --- | --- | --- | | name | Name that appears in the Home app | N/A | | exposeControls | Expose controls to Homekit | true | | verbosed | Verbose Calculations and Extended Climate data | true | | masterDisable | Disable scheduling all irrigation | false | | recheckTime | Reassess - minutes before runtime | 0 | | cycles | Number of cycles per watering run | 2 | | sunriseOffset | Minutes before sunrise that watering should get over by | 0 | | lowThreshold | Skip scheduling when forecasted minimum temperature falls below this | 5 | | highThreshold | Skip scheduling when forecasted maximum temperature stays below this | 10 | | keyAPI | Your OpenWeatherMap API Key | N/A | | latitude | Enter the latitude in decimals including '-' if in the southern hemisphere | N/A | | longitude | Your decimal longitude | N/A | | altitude | Enter the altitude in meters | 0 |

Email Notifications Setup

Currently this supports basic authentication. If using Gmail, you will need to go to the security settings of your account to enable less secure app access. It might be best to create a specific ID for this purpose to avoid security risks to your main account!

| Key | Description | Default | | --- | --- | --- | | emailEnable | Enable Notifications | false | | senderName | Sender Name | N/A | | senderEmail | Sender Email ID | N/A | | sendTo | Receiver Email ID | N/A | | smtpHost | SMTP Host | N/A | | smtpPort | SMTP Port | N/A | | portSecure | Secure Port | false | | userID | SMTP Username | N/A | | userPwd | SMTP Password | N/A |

Pushover Notifications Setup

Push notifications using Pushover are supported.

| Key | Description | Default | | --- | --- | --- | | pushEnable | Enable Push Notifications | false | | userPO | Your user key | N/A | | tokenPO | Your application token | N/A | | devicePO | Receiving devices | all | | priorityPO | Message Priority | 0 | | soundPO | Notification sound | pushover |

Pushcut Notifications Setup

Push notifications using Pushcut are supported. While HomeKit automations and shortcuts can always be triggered based on service or zone states, this opens up a host of possibilities! Do note that this operates in a slightly different manner compared to Pushover. Notifications are sent for the following events:

• Weather Check: This is the notification defined by you in the Pushcut App which will receive a weather check notification with one of two input strings [Scheduled / Not Scheduled]. This is a compulsory field if Pushcut is enabled.
• Watering Start: This is the notification defined by you to receive the watering start notification - if left blank, this notification will be sent to your "Weather Check" notification. The input string attached to this notification is the watering duration in minutes.
• Watering End: This is the notification defined by you to receive the watering end notification - if left blank, this notification will be sent to your "Weather Check" notification.

This also meaans that on completion of a watering run, 2 notifications Weather Check & Watering End will be sent.

| Key | Description | Default | | --- | --- | --- | | pcEnable | Enable Pushcut Notifications | false | | pcKey | Your API key | N/A | | pcDevices | Device list seperated by comma - WITHOUT SPACE after comma! | all | | pcWeatherChecked | Your "Weather Checked" notification name | N/A | | pcWeatherCheckedSound | Notification sound | system | | pcWateringStart | Your "Watering Start" notification name | N/A | | pcWateringStartSound | Notification sound | system | | pcWateringEnd | Your "Watering End" notification name | N/A | | pcWateringEndSound | Notification sound | jobDone |

Monthly data of Mean Daily Solar Radiation [kWh/day]

There are several sources but the one that I used is Weatherspark. Search for your location. Scroll to the bottom of the page to the Solar Energy section and note the figures for each month(the months are clickable!) in kWh/day which is the daily mean figure for the month. Feel free to use an alternate source that you trust but keep in mind the unit of measurment - kWh/day!

Going forward, it will be great to extract live daily shortwave radiation data/forecast through an API instead of relying on historical averages.. hopefully will get there soon!

| Key | Description | Default | | --- | --- | --- | | xxxRad | Mean Daily Solar Radiation [kWh/day] for the month xxx| 6 |

Zones setup

This is where multiple zones can be configured - with a limit of 16 zones at the moment.

Crop Coefficient - Read here for reference! This is based on the crop type or species and their water needs. [0.1 - 0.9]

Planting Density Low—sparse: 0.5 - 0.9 Average—moderate coverage: 1 High--complete coverage: 1.1 - 1.3

Exposure Factor The microclimate or exposure factor [0.5 - 1.4] Average--open field: 1.0 Low--moderate wind, part sun: 0.5 - 0.9 High--stronger winds and greater exposure: 1.1 - 1.4 A protected, shady location would use a lower factor.

| Key | Description | Default | | --- | --- | --- | | zoneName | Friendly zone name | N/A | | enabled | Zone Enabled | true | | adaptive | Climate Adaptive Zone | true | | rainFactoring | Factor rain amount in watering & respect the set threshold to skip irrigation for this zone| true | | defDuration | Default zone duration in minutes when not adaptive [max 180] | 20 | | maxDuration | Maximum duration settable in minutes [max 180]| 30 | | rainThreshold | Rain Threshold[mm] above which watering skipped for this zone | 2.5 | | tweakFactor | The human factor to tweak proposed watering in % [max:200] | 100 | | dripLPH | Drip emitter discharge rate in LPH (of a single emitter)| 2 | | dripNos | Number of drip emitters used in this zone | 1 | | dripArea | Irrigation area in m2| 1 | | efficiency | Irrigation system efficiency - usually 90% for drip | 90 | | cropCoef | Crop Coefficient [0.1 - 0.9] | 0.5 | | plantDensity | Plantation Density [0.5 - 1.3] | 1 | | expFactor | Exposure Factor [0.5 - 1.4] | 1 | | wateringWeekdays | Weekdays to water - at least 1! | ALL | | wateringMonths | Watering Months - uncheck to skip watering in that month | ALL |

Notes & Suggestions

• For any of the smart outlets/sockets you intend to use by following the zone states for driving irrigation valves, do setup an additional automation in Homekit to switch them off after a preset time - this can be a kind of failsafe in case the plugin crashes for any reason and leaves the zone turned on indefinately.

• The plugin pairs very well with multi-channel devices such as the 4CHPRO from Sonoff which has dry contacts to relay low voltage AC/DC to control solenoid valves and also has a wide operating voltage range. I use 2 of these mounted in an IP65 outdoor enclosure to run a 8-zone 12VDC configuration. The plugin used to expose the 4CHPRO is homebridge-ewelink plugin from Ben, who somehow manages to squeeze more than 24 hours in a day giving support, adding features and fixing bugs!

• Maximum run time up to 5 hours with each zone upto 3 hours can be set. defDuration & maxDuration can be upto 180 minutes.

• If you are using a zone to water a set of pots, each with a single drip emitter, a reasonable way to configure would be to set dripArea as the area of a single pot and dripNos to 1. The rest of the zone settings to be configured as per requriement.

• If you are using a zone to water in a protected space, consider disabling rainFactoring for that zone - since the plants never receive any rainfall, and the reduction in ETo is already factored in calculating the zone timing, you should be good to go!

• Use tweakFactor to modulate what the system calculates as the requirement for a zone. Do start with 100%, which means no change and then go lower or higher based on whether you feel the system is overestimating or underestimating the zone's water requirement.

• The Set Duration of the service is set at the total watering duration on every calculation. The individual zones are set at the corresponding zone's single-cycle time. When the watering run starts, the Remaining Duration of the service counts down to 0 through the runtime while the active zone displays the Remaining Duration of that cycle.

Way forward..

• [ ] Use live daily shortwave solar radiation data/forecast through an API instead of relying on having to feed historical averages.. the only service I am aware of which has a free option is Solcast which offers 10 API calls a day. Any suggestions if its worth doing this?

• [ ] Integrate Telegram notifications

• [ ] Integration of FakeGato

• [ ] Prettier HTML email notifications!

Support/Contribution

A ⭐️ star would be great!

I dont have a great deal of programming experience so the biggest help and contribution you can make is helping with the code or "Way forward.." items!

If financial contribution is on your agenda, may I humbly redirect you to Homebridge which makes this community possible. Also consider supporting several fine developers who offer an incredible amount of their time and effort in supporting the community and creating extraordinary plugins.