Home

Awesome

<p align="center"> <a href="https://github.com/homebridge/homebridge"><img src="https://raw.githubusercontent.com/homebridge/branding/master/logos/homebridge-color-round-stylized.png" height="140"></a> </p> <span align="center">

homebridge-web-sprinklers

npm npm

</span>

Description

This homebridge plugin exposes a web-based sprinkler system to Apple's HomeKit. Using HTTP requests, the plugin allows you to turn on/off individual sprinkler zones. With the use of the OpenWeatherMap API, the plugin can also provide water scheduling.

Find script samples for the sprinkler controller in the examples folder.

Installation

  1. Install homebridge
  2. Install this plugin: npm install -g homebridge-web-sprinklers
  3. Sign up (for free) to the OpenWeatherMap API and retrieve your API key (if you want scheduling)
  4. Update your config.json file

Configuration

Accessory with scheduling

"accessories": [
     {
       "accessory": "WebSprinklers",
       "name": "Sprinklers",
       "apiroute": "http://myurl.com",
       "latitude": 0000000000,
       "longitude": 0000000000,
       "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
       "zones": 6,
       "restrictedMonths": [0, 1, 2, 10, 11],
       "zonePercentages": [100, 75, 100, 100, 50, 100]
     }
]

Accessory without scheduling

"accessories": [
     {
       "accessory": "WebSprinklers",
       "name": "Sprinklers",
       "apiroute": "http://myurl.com",
       "disableScheduling": true
     }
]

Core

KeyDescriptionDefault
accessoryMust be WebSprinklersN/A
nameName to appear in the Home appN/A
apirouteRoot URL of your deviceN/A
latitudeYour decimal latitudeN/A
longitudeYour decimal longitudeN/A
keyYour OpenWeatherMap API keyN/A
zonesNumber of sprinkler zones6

Optional fields

KeyDescriptionDefault
disableSchedulingWhether to disable water schedulingfalse
sunriseOffsetMinutes before sunset to finish watering by0
defaultDurationDefault total watering time per zone (minutes)20
cyclesNumber of cycles per zone (watering is spread between cycles)2
restrictedDaysDays of the week when watering should not take place (Sunday is 0, Monday is 1, and so on)N/A
restrictedMonthsMonths of the year when watering should not take place (January is 0, February is 1, and so on)N/A
zonePercentagesPercentage of calculated zone watering time that a specific zone will receive (do not exceed 100%)100
disableAdaptiveWateringWhether to disable adaptive watering and use defaultDuration insteadfalse
maxDurationThe highest number of minutes that adaptiveWatering can set30
lowThresholdForecasted low temperature (°C) below which watering will not take place10
highThresholdForecasted high temperature (°C) below which watering will not take place20
rainThresholdForecasted rainfall (mm) above which watering will not take place2.3

Additional options

KeyDescriptionDefault
pollIntervalTime (in seconds) between device polls300
listenerWhether to start a listener to get real-time changes from the devicefalse
timeoutTime (in milliseconds) until the accessory will be marked as Not Responding if it is unreachable3000
portPort for your HTTP listener (if enabled)2000
usernameUsername if HTTP authentication is enabledN/A
passwordPassword if HTTP authentication is enabledN/A
http_methodHTTP method used to communicate with the deviceGET
modelAppears under the Model field for the accessoryplugin
serialAppears under the Serial field for the accessoryapiroute
manufacturerAppears under the Manufacturer field for the accessoryauthor
firmwareAppears under the Firmware field for the accessoryversion

Scheduling

When scheduling is enabled, the plugin will see if watering can be completed today by however many minutes before sunrise specified in sunriseOffset, if not, it will schedule the relevant time for the next day.

The day selected must match the following criteria for watering to place:

If adaptive watering is disabled, but scheduling remains enabled, each zone will be watered for a percentage (specified in zonePercentages) of the number of minutes specified in defaultDuration

The plugin schedules asynchronous zone watering times (no more than one zone on at a given time), as most systems are incapable of supplying sufficient pressure to water multiple zones simultaneously.

Start times will vary daily as a result of changing sunrise times.

Adaptive watering

When adaptive watering is enabled, a zone's total watering duration will be calculated as a percentage (specified in zonePercentages) of the calculation below:

highDiff = waterDay.max - highThreshold
lowDiff = highThreshold - waterDay.min
cloudPercentage = 100 - (waterDay.clouds / 3)
zoneMaxDuration = (((defaultDuration + (highDiff - lowDiff)) / 100) * cloudPercentage) - waterDay.rain

API Interfacing

Your API should be able to:

  1. Return JSON information when it receives /status:
[
  {
    "zone": 1,
    "state": 0
  },
  {
    "zone": 2,
    "state": 0
  },
  {
    "zone": 3,
    "state": 0
  },
  ...
]
  1. Set zone state when it receives:
/setState?zone=ZONE_INT_VALUE&value=INT_VALUE

Optional (if listener is enabled)

  1. Update state following a manual zone override by messaging the listen server:
/state?zone=ZONE_INT_VALUE&value=INT_VALUE

Notes

To-do