Hunter Hydrawise

Driver: hydrawise

Cloud integration with Hunter Hydrawise irrigation controllers via the Hydrawise v2 GraphQL API. The driver signs in with the account email and password (OAuth2 password grant), polls per-zone watering state, and supports run, stop, suspend, and resume actions per zone or controller-wide.

:::info No API key required Unlike the legacy v1 REST integration, this driver does not use an API key. It works for accounts that cannot generate one — including trial and simulated controllers. The bearer token from sign-in expires after about an hour and is refreshed automatically. :::

Prerequisites

• A Hydrawise account email and password.
• At least one controller on the account — physical or simulated/trial; both are visible over the GraphQL API.

Setup

1. In GEM, System → Devices → Add Device with driver hydrawise.
2. Enter the Hydrawise account email and password (the password is stored encrypted).
3. If the account has more than one controller, set controller_id (run get_controllers to list them). With a single controller this is auto-detected.
4. Save. The driver logs in, resolves controllers, and begins polling zone state.
5. Run get_zones to list the available zone id values, then create one GEM zone per zone under the irrigation subsystem with address set to the Hydrawise zone id (not the physical valve number).

Attributes

Device

Attribute	Required	Default	Description
email	yes	—	Email used to sign in to the Hydrawise app.
password	yes	—	Password used to sign in (stored encrypted).
controller_id	no	—	Required when the account has more than one controller (from get_controllers). Auto-detected for single-controller accounts.
default_run_seconds	no	300	Default run duration when seconds is not supplied to a run command.
min_poll_interval	no	60	Polling cadence (seconds) against the GraphQL API.

Zone

zone.address is the Hydrawise zone id from get_zones. Driver-managed state attributes:

Attribute	Description
state	on while scheduledRuns.currentRun is present, off otherwise.
time_remaining	Seconds left in the current run (currentRun.remainingTime); 0 when idle.
next_run	Seconds until the next programmed run (from nextRun.startTime); meaningful when idle.
next_run_str	Human-readable schedule summary (mirrors the API's scheduledRuns.summary).
suspended_until	Epoch seconds the zone is suspended until, or 0 if not suspended.

Commands

Command	Args	Effect
on / run	address, optional seconds	Start a manual run on the zone.
off / stop	address	Stop the zone.
suspend	address, hours	Suspend the zone for the given number of hours.
resume	address	Resume a suspended zone (native resumeZone).
runall	optional seconds	Start all zones on the controller.
stopall	—	Stop all zones on the controller.
suspendall	hours	Suspend all zones for the given number of hours.
resumeall	—	Resume all zones on the controller (native resumeAllZones).
get_controllers	—	List controllers visible to the account (id, name, online, serial).
get_zones	—	List zones with their id, number, name, and controller.

The controller-wide commands (runall, stopall, suspendall, resumeall) require a resolved controller — set controller_id on multi-controller accounts.

Known limitations

• Token lifetime. The OAuth bearer token expires after ~1 hour and is refreshed automatically, falling back to a fresh login if the refresh token is rejected.
• Suspend date format unverified. suspend / suspendall send the suspension end time as an ISO-8601 UTC string in the GraphQL until argument. The exact accepted format could not be validated against live hardware (the test account had no zones). If a site reports suspend failures, capture the Hydrawise web app's suspendZone request to confirm the format.

Troubleshooting

Symptom	Check
Driver never connects / missing email or password	Verify the email and password device attributes are set and correct.
All-zone commands return controller_id required	The account has multiple controllers — set controller_id (run get_controllers to list them).
Zone commands do nothing	zone.address must be the Hydrawise zone id from get_zones, not the physical valve number.
Login fails after working previously	The account password may have changed, or the account may be locked. Re-enter the password.