Hey all,
I wanted to share a custom integration I've been building over the past few weeks for Rain Bird IQ4 cloud-connected irrigation controllers.
The backstory
Like some of you, I fell into the classic trap: I updated the Rain Bird app to 2.0, which prompted a firmware upgrade on my ESP-TM2, and suddenly the official Rain Bird integration started to experience constant desconnections. After this I found out in the documentation of the integration that the integration was not compatible with the new firmaware, that a roll back was not possible and that next time I should read the documentation before performing updates...
After spending some time in this GitHub issue and reading a great comment from Niek that outlined how the IQ4 cloud API works, I decided to try to build a new integration that talks directly to the Rain Bird IQ4 cloud instead of the local network of the controller.
How it works
The integration authenticates with the Rain Bird IQ4 cloud (the same backend as the IQ4 app) and polls it for data. It uses three separate polling coordinators at different (configurable) intervals so it doesn't hammer the API unnecessarily:
- Every 30 seconds — zone status, connection state, alarms
- Every 5 minutes — rain delay, forecast settings, controller mode
- Every hour — programs, schedules, seasonal adjust
What you get
Sensors:
- Zone status (idle / running / paused) with last run times
- Program status (scheduled / not scheduled / disabled) with schedule details, weather adjust method and seasonal adjust %
- Rain delay (days remaining)
- Controller mode and alarm counts
Binary sensors:
- Cloud connection status
- Forecast rain delay enabled/disabled (with threshold attributes)
Calendar showing upcoming irrigation events per program
7 actions for full control:
- Start/stop zones manually
- Set rain delay
- Enable/disable forecast-based rain delay
- Set weather adjust to automatic or manual (with seasonal adjust %)
Refresh button to force an immediate update
Stability notes
The integration has been running on my ESP-TM2 for the last couple of days without issues. It handles transient API errors gracefully; it tolerates up to 3 consecutive failures before marking entities as unavailable, so brief Rain Bird cloud hiccups don't cause false unavailable states.
One technical detail worth knowing: the Rain Bird cloud is protected by AWS WAF, which blocks standard HTTP clients during the login process. The integration works around this using curl_cffi to impersonate a browser. Tokens are cached and auto-refreshed every ~2 hours.
How to install
Add as a custom repository in HACS:
https://github.com/davidsuarez82/rainbird_iq4
Or copy the custom_components/rainbird_iq4 folder manually.
Setup is simple; just enter your Rain Bird IQ4 username and password and the integration discovers your controller automatically.
Tested hardware
- Rain Bird ESP-TM2 (firmware 2.29.0)
- Rainbird LNK2 WiFi module (firmware 4.136)
Other IQ4-compatible controllers may work but haven't been tested. Happy to hear if it works on other models!
A note on the approach
This uses the unofficial IQ4 cloud API, so it could theoretically break if Rain Bird changes their backend. That said, it's been stable so far. The integration was developed with help from Claude AI for code generation and debugging, which made the whole process much faster.
GitHub: GitHub - davidsuarez82/rainbird_iq4: Integration with Rain Bird IQ4 Cloud · GitHub
Would love to hear if it works for others, especially those with controllers other than the ESP-TM2!
.
. I'll fix it in the next release.
