# Hydrawise Binding

![API Key](doc/logo.png)

The Hydrawise binding allows monitoring and control of [Hunter Industries's](https://www.hunterindustries.com/) line of [Hydrawise](https://www.hydrawise.com) internet connected irrigation systems.

## Supported Things

- `account`: Bridge type represents the user's account on the Hydrawise cloud service. The bridge can have one or more child [Controllers](#controller-thing) linked.
An account must be manually added and configured.
- `controller` Things are automatically discovered once an account Bridge is properly configured. [more details](#local-thing)
- `local` Things use an undocumented API that allows direct HTTP access to an irrigation controller on the user's network. [more details](#local-thing)

### `controller` Thing

The Controller Thing type is the primary way most users will control and monitor their irrigation system.
This allows full control over zones, sensors and weather forecasts.<br>
Changes made through this Thing type will be reflected in the Hydrawise mobile and web applications as well as in their reporting modules.
Controller Things require a parent `account` Bridge

### `local` Thing

The Local Thing type uses an undocumented API that allows direct HTTP access to an irrigation controller on the user's network.
This provides a subset of features compared to the Cloud Thing type, limited to basic zone control.
Controlling zones through the local API will not be reported back to the cloud service or the Hydrawise mobile/web applications, and reporting functionality will not reflect the locally controlled state.

Local control may not be available on later Hydrawise controller firmware versions.

Use Cases

- The Local Thing can be useful when testing zones, as there is no delay when starting/stopping zones as compared to the cloud API, which can take anywhere between 5-15 seconds.
- This is also useful if you wish to not use the cloud scheduling at all and use openHAB as the irrigation scheduling system.

## Thing Configuration

### `account` Bridge Configuration

| Configuration Name | type    | required | Comments                                                                                                                  |
|--------------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------|
| userName           | String  | False    | The Hydrawise account user name                                                                                           |
| password           | String  | False    | The Hydrawise account password                                                                                            |
| savePassword       | Boolean | False    | By default the password will not be persisted after the first login attempt unless this is true, defaults to false        |
| refresh            | Integer | False    | Defaults to a 60 second polling rate, more frequent polling may cause the service to deny requests                        |
| refreshToken       | Boolean | False    | An oAuth refresh token, this will be automatically configured after the first login and updated as the token is refreshed |

### `controller` Thing Configuration

| Configuration Name | type    | required | Comments             |
|--------------------|---------|----------|----------------------|
| controllerId       | Integer | True     | ID of the controller |

### `local` Thing Configuration

| Configuration Name | type    | required | Comments                                                                                                        |
|--------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
| host               | String  | True     | IP or host name of the controller on your network                                                               |
| username           | String  | True     | User name (usually admin) set on the touch panel of the controller                                              |
| password           | String  | True     | Password set on the touch panel of the controller.  This can be found under the setting menu on the controller. |
| refresh            | Integer | True     | Defaults to a 30 seconds polling rate                                                                           |

## Channels and Groups

### Channel Groups

### Controller Thing Supported Channel Groups

| channel group ID                      |
|---------------------------------------|
| [Controller](#controller-thing)       |
| [Zones](#zone-channel-group)          |
| [All Zones](#all-zones-channel-group) |
| [Sensor](#sensor-channel-group)       |
| [Forecast](#forecast-channel-group)   |

#### Local Thing Supported Channel Groups

| channel group ID                      |
|---------------------------------------|
| [Zones](#zone-channel-group)          |
| [All Zones](#all-zones-channel-group) |

#### System Channel Group

| channel group ID | Description                     |
|------------------|---------------------------------|
| system           | System status of the controller |

#### Zone Channel Group

Up to 36 total zones are supported per Local or Cloud Thing

| channel group ID | Description               |
|------------------|---------------------------|
| zone1            | Zone 1 channel group      |
| zone2            | Zone 2 channel group      |
| ...              | Zone 3 - 35 channel group |
| zone36           | Zone 36 channel group     |

#### Sensor Channel Group

Up to 4 total sensors are supported per Cloud Thing

| channel group ID | Description            |
|------------------|------------------------|
| sensor1          | Sensor 1 channel group |
| sensor2          | Sensor 2 channel group |
| sensor3          | Sensor 3 channel group |
| sensor4          | Sensor 4 channel group |

#### Forecast Channel Group

Up to 3 total weather forecasts are supported per Cloud Thing

| channel group ID | Description     |
|------------------|-----------------|
| forecast1        | Todays Forecast |
| forecast2        | Day 2 Forecast  |
| forecast3        | Day 3 Forecast  |

#### All Zones Channel Group

A single all zone group are supported per Cloud or Local Thing

| channel group ID | Description            |
|------------------|------------------------|
| allzones         | commands for all zones |

### Channels

Channels uses across zones, sensors and forecasts

| channel ID                 | type               | Groups         | description                                   | Read Write |
|----------------------------|--------------------|----------------|-----------------------------------------------|------------|
| name                       | String             | zone, sensor   | Descriptive name                              | R          |
| icon                       | String             | zone           | Icon URL                                      | R          |
| type                       | Number             | zone           | Zone type                                     | R          |
| run                        | Switch             | zone, allzones | Run/Start zone                                | RW         |
| runcustom                  | Number:Time        | zone, allzones | Run zone for custom length                    | W          |
| suspend                    | Switch             | zone, allzones | Suspend zone                                  | RW         |
| suspenduntil               | DateTime           | zone, allzones | Suspend zone unitl specified date             | RW         |
| nextrun                    | DateTime           | zone           | Next date and time this zone will run         | R          |
| timeleft                   | Number:Time        | zone           | Amount of time left for the running zone      | R          |
| input                      | Number             | sensor         | Sensor input type                             | R          |
| timer                      | Number             | sensor         | Sensor timer                                  | R          |
| offtimer                   | Number:Time        | sensor         | Sensor off timer                              | R          |
| offlevel                   | Number             | sensor         | Sensor off level                              | R          |
| active                     | Switch             | sensor         | Is sensor active / triggered                  | R          |
| temperaturehigh            | Number:Temperature | forecast       | Daily high temperature                        | R          |
| temperaturelow             | Number:Temperature | forecast       | Daily low temperature                         | R          |
| conditions                 | String             | forecast       | Daily conditions description                  | R          |
| day                        | DateTime           | forecast       | Day of week of forecast (Mon-Sun)             | R          |
| humidity                   | Number             | forecast       | Daily humidity percentage                     | R          |
| wind                       | Number:Speed       | forecast       | Daily wind speed                              | R          |
| evapotranspiration         | Number             | forecast       | Daily evapotranspiration amount               | R          |
| precipitation              | Number             | forecast       | Daily precipitation amount                    | R          |
| probabilityofprecipitation | Number             | forecast       | Daily probability of precipitation percentage | R          |

## Full Example

## `demo.things` Example

```java
Bridge hydrawise:account:myaccount "Hydrawise Cloud" [ userName="my-username", password="my-password", savePassword=true, refresh=120 ] {
    Thing controller irrigation1 "Frontyard Controller" [ controllerId="12345" ]
    Thing controller irrigation2 "Backyard Controller" [ controllerId="67890" ]
}

Thing local directIrrigation "Garden Controller" [ host="host-ip", username="my-username", password="my-password", refresh="30" ]
```

## `demo.items` Example

```java
Group Sprinkler             "Sprinkler"
Group SprinklerController   "Controller"    (Sprinkler)
Group SprinklerZones        "Zones"         (Sprinkler)
Group SprinklerSensors      "Sensors"       (Sprinkler)
Group SprinkerForecast      "Forecast"      (Sprinkler)

String SprinkerControllerStatus "Status [%s]" (SprinklerController) {channel="hydrawise:controller:myaccount:123456:controller#status"}
Number SprinkerControllerLastContact "Last Contact [%d]" (SprinklerController) {channel="hydrawise:controller:myaccount:123456:controller#lastcontact"}

Switch SprinklerSensor1 "Sprinler Sensor" (SprinklerSensors) {channel="hydrawise:controller:myaccount:123456:sensor1#active"}

Group SprinkerForecastDay1 "Todays Forecast" (SprinkerForecast)
Number:Temperature SprinkerForecastDay1HiTemp "High Temp [%d]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#temperaturehigh"}
Number:Temperature SprinkerForecastDay1LowTemp "Low Temp [%d]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#temperaturelow"}
String SprinkerForecastDay1Conditions "Conditions [%s]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#conditions"}
String SprinkerForecastDay1Day "Day [%s]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#day"}
Number SprinkerForecastDay1Humidity "Humidity [%d%%]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#humidity"}
Number:Speed SprinkerForecastDay1Wind "Wind [%s]" (SprinkerForecastDay1) {channel="hydrawise:controller:myaccount:123456:forecast1#wind"}

Group  SprinklerZone1 "1 Front Office Yard" (SprinklerZones)
String SprinklerZone1Name "1 Front Office Yard name" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#name"}
Switch SprinklerZone1Run "1 Front Office Yard Run" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#run"}
Switch SprinklerZone1RunLocal "1 Front Office Yard Run (local)" (SprinklerZone1) {channel="hydrawise:local:home:zone1#run"}
Number SprinklerZone1RunCustom "1 Front Office Yard Run Custom" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#runcustom"}
DateTime SprinklerZone1StartTime "1 Front Office Yard Start Time [%s]" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#nextruntime"}
Number SprinklerZone1TimeLeft "1 Front Office Yard Time Left" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#timeleft"}
String SprinklerZone1Icon "1 Front Office Yard Icon" (SprinklerZone1) {channel="hydrawise:controller:myaccount:123456:zone1#icon"}

Group  SprinklerZone2 "2 Back Circle Lawn" (SprinklerZones)
String SprinklerZone2Name "2 Back Circle Lawn name" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#name"}
Switch SprinklerZone2Run "2 Back Circle Lawn Run" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#run"}
Switch SprinklerZone2RunLocal "2 Back Circle Lawn Run (local)" (SprinklerZone2) {channel="hydrawise:local:home:zone2#run"}
Number SprinklerZone2RunCustom "2 Back Circle Lawn Run Custom" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#runcustom"}
DateTime SprinklerZone2StartTime "2 Back Circle Lawn Start Time" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#nextruntime"}
Number SprinklerZone2TimeLeft "2 Back Circle Lawn Time Left" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#timeleft"}
String SprinklerZone2Icon "2 Back Circle Lawn Icon" (SprinklerZone2) {channel="hydrawise:controller:myaccount:123456:zone2#icon"}

Group  SprinklerZone3 "3 Left of Drive Lawn" (SprinklerZones)
String SprinklerZone3Name "3 Left of Drive Lawn name" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#name"}
Switch SprinklerZone3Run "3 Left of Drive Lawn Run" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#run"}
Switch SprinklerZone3RunLocal "3 Left of Drive Lawn Run (local)" (SprinklerZone3) {channel="hydrawise:local:home:zone3#run"}
Number SprinklerZone3RunCustom "3 Left of Drive Lawn Run Custom" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#runcustom"}
DateTime SprinklerZone3StartTime "3 Left of Drive Lawn Start Time" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#nextruntime"}
Number SprinklerZone3TimeLeft "3 Left of Drive Lawn Time Left" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#timeleft"}
String SprinklerZone3Icon "3 Left of Drive Lawn Icon" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#icon"}
```
