Orbit B-hyve

Cloud REST integration for the Orbit B-hyve line of smart irrigation hardware — the Wi-Fi sprinkler controllers (Indoor / Outdoor, XR Pro, XD) and the Smart Hose Faucet Timer family. One B-hyve account becomes one GEM device row; each watering station (one per sprinkler-controller channel, or one per hose timer) becomes a zone.

What this integration covers

• Manual zone start with a per-call run-time (minutes), capped at 240 minutes (Orbit hardware limit).
• Stop — cancels the active watering run on the controller. (Orbit has no per-station stop; stopping any zone stops all.)
• Rain delay — applies a controller-wide rain delay in hours; pass 0 to clear.
• Status polling of watering state (which station is currently active), connectivity (online / offline), and battery level for hose timers.

What this integration does NOT cover (yet)

• Program / schedule management. Building, editing, or pausing scheduled programs from GEM is not wired — use the B-hyve mobile app.
• WebSocket push events. Orbit publishes a live event stream at wss://api.orbitbhyve.com/v1/events. GEM polls the cloud on a timer instead, so a manual start from the B-hyve app shows up at the next poll (within status_interval) rather than instantly. Live push is not wired up.
• Per-station stop. Orbit's API has no stop_station event — the stop command is controller-wide. This is a vendor-side limitation.
• Soil-moisture sensors / smart-watering decisions. The driver only surfaces what the controller is doing, not the decisions B-hyve's cloud made.
• Spray-runtime calibration and historical usage reports.

Prerequisites

• A free B-hyve account at https://bhyve.orbitonline.com or via the B-hyve mobile app.
• Each controller or hose timer paired into the account using the B-hyve mobile app — this driver does not onboard hardware.
• Outbound HTTPS reachability from the GEM controller to api.orbitbhyve.com.

Setup steps

1. Pair every B-hyve controller and hose timer into the account using the B-hyve mobile app.
2. In GEM, go to System → Devices → Add Device (Open Devices) and pick Orbit B-hyve as the driver.
3. Enter the B-hyve account email and password (the password is stored encrypted).
4. Save. After a few seconds the device row should show as Connected — the driver signs in, reads the account's device list, then starts polling.
5. Run the get_devices command. Each entry shows the Orbit deviceId, the device type, and its station count — you need the deviceId to build the zone addresses in the next step.
6. For each watering station you want to control, create a zone bound to this B-hyve device, under the Water subsystem (see the note below), with address = "<deviceId>:<station>". For a single-station hose timer the bare deviceId also works (station defaults to 1). The driver does not create these zones for you — add one per station by hand.
7. (Optional) Set the zone's default_run_minutes to override the device-level default for that specific station.

Subsystem placement

GEM seeds a Water subsystem out of the box — there is no separate "irrigation" subsystem. This driver hints irrigation, which does not match any seeded subsystem name, so the New Zone editor does not pre-select a subsystem for you: choose Water yourself from the Subsystem picker. The subsystem only controls how the zone is grouped and presented in the UI — it does not affect whether watering commands work.

Attribute reference

Device attributes

Name	Type	Required	Description
email	string	yes	B-hyve account email.
password	string	yes	B-hyve account password. Stored encrypted.
api_base	string	no	Override https://api.orbitbhyve.com/v1. Leave empty unless directed.
default_run_minutes	int	no	Run-time used when a start command supplies no duration (default 10, max 240).
status_interval	int	no	Poll cadence in ms (default 30000; min 10000, max 600000).
request_timeout	int	no	Per-request timeout (default 15000 ms).

Zone attributes

Name	Type	Description
address	string	"<deviceId>:<station>" (required).
default_run_minutes	int	Per-zone override of device.default_run_minutes.
state	string	Maintained by the driver: on while this station is actively watering, off otherwise.
connection_state	string	connected / offline — mirrors device.is_connected from the B-hyve cloud.
battery	int	Hose timers only — battery percentage (0–100). Absent on mains-powered controllers.

The driver writes state, connection_state, and battery live as it polls, and all three are cataloged in the Attribute registry — they autocomplete in the Attribute editor and can drive attribute triggers (for example, alert when a hose-timer battery drops below 20, or when a station's connection_state becomes offline). The two default_run_minutes defaults are entered as device/zone settings rather than read back from the controller.

Zone address format

"<deviceId>:<station>", e.g. abcd1234-ef56-7890-abcd-ef1234567890:3. deviceId is the Orbit UUID from get_devices; station is the 1-based channel number on the controller (1 for a hose timer; 1..8 on Indoor / Outdoor; 1..16 on XR Pro). For a single-station hose timer the bare deviceId is also accepted.

Commands

Command	Args	Notes
on / start_zone	address, optional duration	Start the addressed station. duration is in minutes (default = zone or device default_run_minutes). Capped at 240 by Orbit.
off / stop	address	Stop watering on the addressed station's controller. Controller-wide — stops all stations on that controller.
rain_delay	address, hours	Apply a rain delay to the addressed controller. Pass 0 to clear. Per-controller, not per-zone.
get_devices	—	Enumerate every controller / timer on the account.
get_status	optional address	Read live state for the addressed station's controller, or every controller if address omitted.
refresh_token	—	Force a re-login (debug).

Known limitations

• Cloud-only. Orbit hardware speaks only to api.orbitbhyve.com; when Orbit has an outage every zone goes offline.
• 240-minute run-time cap per manual start — enforced by the controller firmware, not the driver. Requests beyond 240 are silently clamped by Orbit.
• No per-station stop. Stopping any zone stops the whole controller. This is an Orbit API limitation, not a driver simplification.
• Rain delay is controller-wide. Setting rain_delay on any zone applies to the whole controller — there is no per-zone delay.
• API is reverse-engineered. This is the same cloud API the official B-hyve mobile app uses (and the same one the long-running open-source pybhyve / homebridge-bhyve / OpenHAB integrations rely on), stable in practice, but Orbit does not formally publish it as a customer-facing API. If an Orbit firmware update changes a response shape, the integration may need an update — capture the device log and contact support.

Troubleshooting

• login rejected (HTTP 401/403) — wrong email / password. Confirm in the B-hyve mobile app, then re-enter on the device row.
• HTTP 401 after running fine for weeks — the session token expired (~30 days of inactivity). The driver auto-re-logs-in on the next request; if it persists, run refresh_token.
• address must be "<deviceId>:<station>" (or bare deviceId for a single-station hose timer) — the zone address is malformed. Run get_devices to find the deviceId, then set address = "<deviceId>:<station>".
• Zone never updates — confirm get_status returns the controller. If the controller shows is_connected: false, the timer is offline (out of Wi-Fi range, battery dead, or unplugged). The B-hyve cloud cannot start watering on a disconnected device.
• Stop appears to do nothing — check that something is actually watering. Stopping an idle controller returns success but has no observable effect.
• Rain delay clears unexpectedly — Orbit decrements the controller-side delay every hour; setting a fresh delay overwrites the existing one. The B-hyve app and this driver share the same delay value.

Related documentation

• Devices — adding and configuring the B-hyve device row.
• Zones — creating one zone per watering station and binding it to the device.
• Subsystems — the Water subsystem these zones belong to.
• Commands — running get_devices, start_zone, stop, and rain_delay from the admin UI or a macro.