Hunter Hydrawise Driver

v1.0 - Custom Control Drivers LLC

A feature-rich SDK driver for Hunter Hydrawise irrigation controllers. Polls the Hydrawise cloud API for live zone state, exposes per-zone run, stop, suspend, and resume commands, and surfaces every detail an integrator needs to build a professional irrigation control interface — without the bugs of pre-SDK donor patterns.

Requirements

· A Hunter Hydrawise controller commissioned and reporting to the Hydrawise cloud.

A Hydrawise account with API access enabled. Find your API key at https://app.hydrawise.com/config/account-details under My Account, Account Details.

An RTI XP processor with internet access. The driver talks to api.hydrawise.com over HTTPS (port 443).

An XP processor running firmware that supports script engine v24 or higher (driver encryption baseline).

Setup

Step 1: Get your API key

1. Sign in to https://app.hydrawise.com on a desktop browser.

2. Click your account name in the upper right and choose My Account.

3. Open the Account Details tab.

4. Copy the API key. It is a long alphanumeric string — paste it as-is into the driver settings.

Step 2: Driver Properties

· API Key — paste the value from step 1.

Controller ID (optional) — leave blank if you only have one controller. If you manage multiple, paste the numeric controller ID for the one this driver instance should target.

Poll Interval — choose 30 seconds (aggressive), 60 seconds (recommended), 2 minutes (gentle), or 5 minutes (very gentle). The Hydrawise API caps you at 5 requests per rolling minute; 60 seconds keeps you well under the limit with headroom for on-demand commands.

Honor API Poll Hint — leave on. The Hydrawise cloud asks for longer poll intervals when nothing is happening, which conserves your rate-limit budget.

Step 3: Zone Naming

The driver auto-discovers every zone configured on your controller. By default the driver displays the zone names you set in the Hydrawise app.

If you want to override those names for the RTI panel (for example, to use shorter names that fit your buttons), open the Zone Naming category and fill in Zone 1 Name. The slot for Zone 2 Name reveals after slot 1 is filled, and so on up to Zone 36.

Zone numbers map directly to the physical relay numbers on the controller — Zone 1 in the driver is relay 1 in the Hydrawise app.

Step 4: License Key

A 120-minute trial runs as soon as the driver successfully reaches the cloud. Paste your purchased license key into Licence Key to remove the trial cap. Keys are bound to the processor's MAC address.

Features

Live Zone State

Every poll updates one sysvar group per zone — running flag, suspend flag, next-run text, time remaining, elapsed time, progress percent. The Running flag and progress bar update once per second locally between polls so the panel never feels frozen.

Master Now-Playing Sysvars

A separate Controller category mirrors the active zone's state into a single set of sysvars (RunningZoneName, RunningZoneRemainingText, RunningZoneProgressPercent, etc.). Bind these to a single hero panel on your home screen and it always shows whichever zone is currently running.

Suspend Presets

Per zone, seven boolean sysvars track whether the zone is suspended for 1, 6, 12, 24, 48, 72 hours, or one week. Wire these to button highlight states so the user can see at a glance which suspend duration is active.

By-Name Commands

Every zone command exists in a parameterized form (zone number) and a by-name form (zone display name, case-insensitive). The by-name form is useful when you want a single panel button to act on a fixed-name zone, regardless of which relay number it lives on.

Auto-Reconnect with Backoff

The driver monitors poll success. After a network error or rate-limit response, it backs off using an exponential schedule (30 s, 60 s, 120 s, 300 s, 300 s) and resumes normal polling once the next request succeeds.

Debug Console

Telnet to the processor IP on the configured Debug Console Port (default 12508). Type help for the full list of commands. Available commands:

· help — list commands

state — dump driver state and last-known zone values

zones — list every detected zone and its state

license — show license status and trial time remaining

config — print active configuration

poll — force a status poll immediately

force-reconnect — cancel current poll cycle and re-init

clear-cache — wipe persistent cache

log off|low|med|high — set runtime log level

quit — close debug session

Standard SDK Universal Sysvars

Every driver from this template line exposes the same baseline:

· ConnectionState — true when the driver has had a successful poll within the watchdog window.

LastError — most recent error text. Empty when healthy.

LastPollText / LastPollEpoch — human-readable clock time / epoch of the last successful poll.

DriverVersion — version of this driver.

LicenseValid — true when licensed or trial time remains.

LicenseStatusText — human-readable license / trial status.

TrialMinutesRemaining — integer minutes left in the trial period.

Build a generic banner panel that watches LastError and LicenseStatusText and you have a uniform health indicator across every driver in your project.

Controller Sysvars

Beyond the master Now-Playing sysvars, the Controller category also exposes:

· ControllerName — your Hydrawise controller's name.

ZonesDetected — count of zones the API reported for this controller.

AnyZoneRunning / NoZoneRunning — inverse boolean pair for hero panel highlights.

SensorActive — true when any wired sensor (rain/freeze) is asserting.

SuspendAllActive — true after a Suspend All Hours or Suspend All Until Epoch call, cleared by Resume All.

Per-Zone Sysvars (each zone, sourceid Zone1..Zone36)

Every zone exposes a complete state surface for direct UI binding:

· Zone N Available — boolean, true when the API has reported this relay.

Zone N Display Name — the name shown in your panel (Zone Naming override or the auto-discovered name).

Zone N Discovered Name — the raw name from the Hydrawise app.

Zone N Relay ID — the numeric relay ID the Hydrawise API uses for this zone.

Zone N Running / Suspended / Idle — booleans for state-light bindings.

Zone N Next Run Text / Next Run Seconds — when this zone is next scheduled to fire.

Zone N Suspended Until Text / Suspended Hours — current suspension target + duration.

Zone N Set Duration — the duration the spinner has parked for this zone (used by Run With Set Duration).

Zone N Time Remaining Seconds / Time Remaining Text — countdown while running.

Zone N Elapsed Seconds / Elapsed Text — count-up since this run started.

Zone N Progress Percent / Remaining Percent — for filling progress bars.

Zone N Suspend 1H / 6H / 12H / 24H / 48H / 72H / 1Week Active — boolean per preset duration; bind to button highlight states so the customer sees which suspend duration is active.

Suspend Workaround

The Hydrawise personal API does not accept a true cancel-suspend command. The driver works around this by overwriting any active suspend with a one-second micro-suspend that expires before the next poll. The end result is identical from the user's perspective — Resume Zone clears the suspend immediately.

Rate Limit Behavior

The Hydrawise cloud API caps each account at 5 requests in any rolling minute. The driver's default 60-second poll plus on-demand commands stays well under this limit, but if you trigger many manual commands in rapid succession (or reload the driver multiple times in a short window) the cloud may return a rate-limit error. The driver detects these (the response body begins with Exceeded maximum number of requests) and handles them differently per request type:

· Status polls: the rate-limited poll is skipped silently and the next poll fires on the normal cadence. The driver does not accelerate polling, since a faster retry would land back inside the rolling 60-second limiter window and re-trip it.

Initial customer-details requests (driver startup): exponential backoff at 30 s, 60 s, 120 s, 300 s, 300 s until one succeeds. Polling can only begin after init completes.

Zone commands (Run / Stop / Suspend / Resume): the command fails with the OnAPIError event signaled. Wait roughly 60 seconds and try again.

Every rate-limit response also signals the Rate Limited event so a panel can flash a warning banner. If you find yourself stuck in a sustained rate-limit loop, stop the driver and wait at least 5 minutes with no requests; the limiter window will clear and the driver will resume cleanly on the next reload.

Licensing

License keys are bound to the processor's MAC address. Purchase keys at https://customcontroldrivers.com or contact sales for multi-processor pricing.

A 120-minute trial is included so you can verify compatibility before purchase. Trial time accrues only while the driver is successfully polling — configure the API key, verify it works, paste your license, and you never burn trial time.

To migrate a license to a new processor, contact support with the new processor's MAC address.

Support

· Driver Store: https://customcontroldrivers.com

Privacy Policy: https://customcontroldrivers.com/privacy

Email: support@customcontroldrivers.com

Terms of Service

This driver is provided as is without warranty of any kind. You use this software entirely at your own risk. A free trial is included so you can verify compatibility with your hardware before purchasing. Do not purchase a licence if you have not tested the driver on your system. For full terms, visit https://customcontroldrivers.com/terms.

Copyright 2026 Custom Control Drivers LLC. All rights reserved.