Rain Bird (LNK WiFi)

Driver: rainbird

Local control of Rain Bird irrigation controllers through the LNK WiFi module. GEM talks directly to the LNK module on the controller's LAN IP using the shared device password — all traffic is AES-encrypted and stays on the local network, with no Rain Bird cloud account in the middle. Supported controllers include the ESP-ME3, ESP-ME, ESP-TM2, ESP-RZXe, and other LNK-compatible models.

Use it to start and stop individual stations (valves), set per-run durations, kick off a controller program, and read the controller's rain sensor for automation.

One device, many stations

One Rain Bird controller is one device in GEM. Each physical station — the valve wired to terminal 1, 2, 3, … — becomes its own zone, addressed by its station number. Unlike some other irrigation integrations, this driver does not auto-create those zones; you add one zone per station yourself (see Setup).

Prerequisites

• A Rain Bird controller with the LNK WiFi module installed and online on the same LAN the GEM controller can reach.
• The LNK device password — set in the Rain Bird mobile app under Advanced Settings → Password. This is the password GEM uses to connect, not your Rain Bird account login.
• Give the LNK module a static IP or a DHCP reservation. The integration addresses the controller by IP, so a moving lease takes it offline.

Setup

1. Open Devices and add a new device. Pick the Rain Bird (LNK WiFi) driver.
2. In Controller IP enter the LNK module's LAN IP (e.g. 192.168.1.50), and in LNK Password enter the device password from the Rain Bird app. The password is stored encrypted.
3. Enable the device. On connect the driver negotiates the controller model and firmware and enumerates the available station numbers; the log shows the detected model, version, and station count.
4. Run the get_info command on the device's Commands page to list the controller's available station numbers (it returns model, version, serial, and the zones array of valid station numbers).
5. For each physical station, open Zones and add a zone:
   • Select this Rain Bird device.
   • The Subsystem is pre-selected to irrigation (an irrigation subsystem ships with GEM by default). Leave it there, or re-home as needed.
   • Set the zone address to the 1-based station number that matches the physical valve wiring (1, 2, 3, …) — the address field hint reminds you this is the Rain Bird station number.
6. Assign the new zones to a UI as you would any other zone. The driver then polls the controller and keeps each zone's on/off state and time remaining current.

Address is the station number, not a discovered id

A zone's address must be the integer station number wired at the controller. A zone whose address isn't one of the numbers returned by get_info is treated as not connected and never updates. Run get_info to confirm the valid numbers for your controller model.

Running stations vs. program enable/disable

There are two different ways the driver touches a station, and they are not the same thing:

• Manual run / stop — on (or run) starts the station watering for a duration; off (or stop) stops it. This is direct, immediate control of the valve.
• Program enable / disable — enable and disable are meant to change whether the station participates in the controller's programs, and never turn the valve on or off. In the current release they do not reach the controller: the underlying library only raises an internal event for them and sends nothing, so the command answers success without changing anything. Change program participation on the controller (or in the Rain Bird app) until this is wired up.

For ad-hoc manual watering, always use on/run and off/stop.

Run duration

When you send on/run without a seconds argument, the driver uses a default duration:

1. the zone's own Default Run Duration (default_run_seconds) if set, else
2. the device's Default Run Duration (default_run_seconds, default 300 seconds).

Pass an explicit seconds argument to override both for a single run — e.g. a macro step that runs station 3 for 600 seconds.

The controller takes run times in whole minutes: the value is rounded to the nearest minute on the way out, so a run shorter than 30 seconds goes to the controller as 0 minutes, and the longest run it can be sent is 255 minutes (15,299 seconds). Use a macro with several runs for longer watering.

A run/on/off/stop for a station number the controller did not report is refused with unknown station: <n> and nothing is sent.

State and the rain sensor

While the device is enabled, the driver polls the controller (every Refresh Rate seconds) and writes back to each zone:

• state — on while the station is watering, off otherwise.
• time_remaining — seconds left in the current run; 0 when idle.

At the device (controller) level it tracks one sensor reading for use as an automation trigger source:

• rain_sensor — true when the controller's rain sensor is holding watering. It is written when the driver connects and again whenever the reading changes.

Point a trigger at the device's rain_sensor attribute to, for example, suppress a scheduled run or send a notification when rain is detected.

Connection and polling

If the controller doesn't answer within 90 seconds of the driver starting (it is offline, or the password is wrong), the device shows disconnected while the driver keeps trying, and turns connected when the controller answers. If the startup reads fail outright, the driver starts over after 30 seconds, doubling the wait up to 5 minutes until it connects. If status polls stop coming back while connected, the device is marked disconnected and the driver asks for a fresh poll, backing off to one try every 5 minutes; the first good poll marks it connected again. Repeated library errors from an unreachable controller are logged once, not every retry (turn on Log Request/Response to see every line).

Single-session LNK module

The LNK WiFi module accepts only one client session at a time. If the Rain Bird mobile app is connected at the same time as GEM, either side may see stale state. Keep the Refresh Rate at its default (15 s) or higher, and avoid hammering the controller from multiple apps at once. The driver also serializes station activations internally, so starting several stations at once queues them rather than interleaving.

Attributes

Set these in the Attribute editor for the device or zone; the labeled device/zone fields also appear in the device and zone forms.

Device

Attribute	Type	Required	Default	Description
ip	string	yes	—	LAN IP of the LNK WiFi module. Shown as Controller IP.
password	string	yes	—	LNK device password from the Rain Bird app. Shown as LNK Password; stored encrypted.
refresh_rate	int	no	15	Refresh Rate (seconds) — how often the driver polls the controller for status. Minimum 5; keep at 15 or higher (single-session module).
sync_time	bool	no	false	Sync Time — when on, sync the controller clock to GEM's clock at startup and hourly.
default_run_seconds	int	no	300	Default Run Duration (seconds) — run length used when on/run is sent without a seconds argument.
show_request_response	bool	no	false	Log Request/Response — verbose protocol logging; enable only for troubleshooting.
rain_sensor	bool	—	—	Driver-written. true when the controller's rain sensor is holding watering. Usable as an automation trigger source.

Zone

zone.address is the 1-based station number matching the physical valve wiring. Driver-written state attributes:

Attribute	Type	Description
state	string	on while the station is watering, off otherwise.
time_remaining	int	Seconds left in the current run; 0 when idle.

You can also set one configurable attribute per zone (in the zone's Attributes editor or zone form):

Attribute	Type	Default	Description
default_run_seconds	int	falls back to the device's default_run_seconds (300)	Default Run Duration (seconds) — run length used when on/run is sent to this station without an explicit seconds argument. Overrides the device default for this zone only.

Commands

These are the commands the driver declares and keeps current, so they appear automatically on the device's Commands page and can be tested there. The address argument resolves to the zone's station number.

Command	Args	What it does
on / run	address, optional seconds	Start the station watering for seconds (or the default run duration).
off / stop	address	Stop the station.
stopall	—	Stop all irrigation on the controller.
enable	address	Intended to include the station in the controller's programs. Currently sends nothing to the controller (see above).
disable	address	Intended to exclude the station from the controller's programs. Currently sends nothing to the controller (see above).
start_program	program	Start a controller program by its letter: A, B, C … (case doesn't matter). Anything that doesn't start with a letter is refused.
get_info	—	Return the controller model, version, serial, the valid station zones array, and whether the rain set point has been reached.
refresh	—	Force an immediate status poll of the controller.

Driver-managed commands

The rows above are rewritten by the driver every time the system starts. Add your own commands if you need them, but don't hand-edit the templates or args of these — your changes are overwritten on the next restart.

Known limitations

• Single-session module. The LNK module serves one client at a time; running the Rain Bird app alongside GEM can produce stale readings on either side. Keep the refresh rate at 15 s or higher.
• Serialized activations. Station activations are queued one at a time, so starting several stations in quick succession does not interleave — they run in order.
• Older controllers. Some older models don't report live station state directly; the driver falls back to inferring state from the controller's program state automatically. Reported timing on those models is approximate.
• Whole-minute run times. Runs are sent in minutes (rounded), so under 30 s is sent as 0 and the maximum is 255 minutes.
• Program start and stop all aren't confirmed. The underlying library doesn't pass the controller's accept/refuse reply back, so start_program answers success once the request is answered at all. Both start_program and stopall read status right after; if that read fails they answer an error even though the request already went out — check the zone states before resending.
• Controller turned off. If irrigation is switched off at the controller's front panel, stations never show active even though the connection is healthy — the controller simply won't run them.

Troubleshooting

Symptom	Check
Device shows disconnected and the log repeats rainbird connect error	The controller didn't answer at startup. The driver keeps retrying (30 s, doubling to 5 min); check the module is online and the IP is right.
Device drops to disconnected with rainbird status polling stalled	Status polls stopped coming back. The driver keeps asking and reconnects on the first good poll; check the module's WiFi signal and that no other app holds its session.
Device never connects; log shows rainbird missing ip or rainbird missing password	The Controller IP (ip) and/or LNK Password (password) attribute is blank. Set both.
Connect fails with an auth error	The LNK Password doesn't match the module. Confirm it in the Rain Bird app under Advanced Settings → Password and re-enter it.
Zones never show active	Irrigation may be off at the controller's front panel — the controller won't run stations. Turn irrigation on, then send a manual run.
A zone never updates / shows disconnected	Its address isn't a valid station number for this controller. Run get_info to list the valid numbers and set the zone address to one of them.
Manual run works but stations don't water on schedule	The station may be disabled from programs. Check the program setup on the controller or in the Rain Bird app — GEM's enable command does not currently reach the controller.
State looks stale or laggy	Lower contention on the single-session module — close the Rain Bird app while GEM is connected — and confirm the Refresh Rate is at a sensible value (15 s default).

Related documentation

• Devices — add the Rain Bird controller and set its IP and LNK password.
• Zones — add one irrigation zone per station, addressed by station number.
• Subsystems — the irrigation subsystem these zones live on.
• Commands — where run / stop / start_program / get_info appear and can be tested.
• Triggers — use the device's rain_sensor attribute as an automation trigger source.
• Hunter Hydrawise — the other irrigation-controller integration in GEM.