Local HTTP & Cloud WebSocket API Guide
The Intellidwell Sprinkler Controller exposes a local REST API at http://sprinklers.local (or your controller's LAN IP) as well as a real-time bidirectional WebSocket & Cloud REST API via https://sprinklers.intellidwell.net.
Local HTTP REST API
All local REST calls are served directly by the ESP32's built-in Microdot web server on port 80. Any state-changing call automatically triggers a debounced Cloud Shadow sync if the controller is paired.
1. Fetch System Status
Returns the current state of all 10 relays, active zone countdown timers (in seconds), and sequential run queue metrics.
GET http://<CONTROLLER_IP>/api/status
{
"firmware_version": "2.1.28",
"relay_states": [0, 1, 0, 0, 0, 0, 0, 0, 0, 0],
"timers": {
"1": 248
},
"queue": {
"active": false,
"steps": [],
"current_index": -1,
"remaining_seconds": 0
},
"weather": {
"rain_today_in": 0.0,
"source": "Home Assistant Weather",
"delay_days": 2,
"temp": 64.5,
"updated_at": 1731948000
}
}
2. Activate Zone with Timer & Cancel Timer
Starts or cancels a timed zone irrigation cycle. Zone indexes are 0-indexed (0 to 9). If a Master Valve is configured in Settings, it activates automatically 1 second before the target zone.
# Start a timer (duration in minutes, 1–240)
GET http://<CONTROLLER_IP>/relay-timer/<zone_index>/<duration_minutes>
# Cancel an active timer and turn off the zone
GET http://<CONTROLLER_IP>/cancel-timer/<zone_index>
3. Direct Relay Control
Directly toggle a relay state manually. State parameter must be on or off.
GET http://<CONTROLLER_IP>/relay/<zone_index>/<state>
4. Sequential Runs Queue
Start or stop a multi-zone sequential watering run.
POST http://<CONTROLLER_IP>/start-run-queue
Content-Type: application/json
{
"queue": [
{ "pin": 0, "duration_mins": 10 },
{ "pin": 1, "duration_mins": 15 }
]
}
# Stop active sequential run queue
POST http://<CONTROLLER_IP>/stop-run-queue
5. Schedules Management (Get, Add, Edit, Toggle, Delete)
Read or modify the on-device schedules.json configuration for all 10 zones.
# Fetch all 10 zone schedule arrays
GET http://<CONTROLLER_IP>/get-schedules
# Add a new schedule to a zone (0–9)
POST http://<CONTROLLER_IP>/add-schedule
{ "zone": 0, "days": ["Mon", "Wed", "Fri"], "onTime": "06:00", "offTime": "06:20" }
# Edit an existing schedule by ID
POST http://<CONTROLLER_IP>/edit-schedule
{ "zone": 0, "id": "sch_12345", "days": ["Tue", "Thu"], "onTime": "07:00", "offTime": "07:20" }
# Enable/Disable a specific schedule item or entire zone
POST http://<CONTROLLER_IP>/toggle-schedule-item
{ "zone": 0, "id": "sch_12345", "enabled": true }
POST http://<CONTROLLER_IP>/toggle-schedule
{ "zone": 0, "enabled": true }
# Delete a schedule item
POST http://<CONTROLLER_IP>/delete-schedule
{ "zone": 0, "id": "sch_12345" }
6. Set Rain Delay, Push Local Weather, Logs & Cloud Connection Status
# Set Rain Delay manually (0 to 5 days)
GET http://<CONTROLLER_IP>/set-rain-delay/<days>
# Push local weather telemetry & rain delay from Home Assistant
# Note: delay_days is applied automatically when cloud_enabled == 0
# or when the Cloud Server sets ha_rain_delay == 1 (Controller Pushed mode).
POST http://<CONTROLLER_IP>/api/weather
Content-Type: application/json
{
"rain_today_in": 0.32,
"source": "Home Assistant Weather",
"delay_days": 2,
"temp": 62.4
}
# Check Cloud WebSocket connection status
GET http://<CONTROLLER_IP>/api/cloud/status
# Fetch or clear controller logs
GET http://<CONTROLLER_IP>/get-logs
POST http://<CONTROLLER_IP>/clear-logs
# Trigger OTA firmware pull update (version = "beta" or "stable")
POST http://<CONTROLLER_IP>/ota/pull?version=beta
GET http://<CONTROLLER_IP>/ota/status
# Reboot Controller
POST http://<CONTROLLER_IP>/restart
Cloud WebSocket & Command API (sprinklers.intellidwell.net)
When paired, the ESP32 establishes an outbound WebSocket connection to ws://sprinklers.intellidwell.net/v1/device/ws authenticated via X-Device-Id and X-Device-Key headers. To prevent lwIP TCP send-buffer exhaustion (ERR_MEM) or heap fragmentation on standard ESP32 boards, state synchronization is split into three compact JSON frames (status, settings, and schedules) written in 512-byte chunks.
// POST https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/commands
// Supported command_type values:
// "start_zone" | "stop_zone" | "stop_all" | "start_run_queue" | "stop_run_queue"
// "set_rain_delay" | "update_schedule" | "delete_schedule" | "update_device_config"
// "clear_logs" | "start_ota" | "reboot" | "sync"
{
"command_type": "start_zone",
"zone_id": 0,
"runtime_seconds": 600,
"payload": {
"zone_id": 0,
"runtime_seconds": 600
}
}
Cloud Official Weather & Rain Delay Specifications Endpoints
# Configure controller location by ZIP Code, City/State, or GPS coordinates
POST https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/site/lookup
{ "query": "84050" }
# Discover nearby NWS & Ambient Weather Network stations for the property
GET https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/weather/stations
# Select Weather Source Preference ("ambient", "nws", "auto", or "controller_pushed")
# Automatically syncs ha_rain_delay (0 or 1) to all controllers on the property!
PUT https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/weather-settings
{
"weather_source_preference": "ambient",
"observation_provider_preference": "ambient",
"preferred_station_id": "48:3F:DA:56:DB:BD"
}
# Fetch Official NWS / Ambient Forecast, Collected Inches & Rain Delay Evaluation
GET https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/weather?refresh=true
# Save Rain Delay Specifications (Collected/Anticipated Inches & Rain Probability Thresholds)
PUT https://sprinklers.intellidwell.net/v1/app/devices/<device_id>/rain-delay-specs
{
"auto_apply": true,
"collected_24h_threshold_in": 0.25,
"collected_48h_threshold_in": 0.50,
"anticipated_24h_threshold_in": 0.15,
"anticipated_48h_threshold_in": 0.30,
"pop_24h_threshold_pct": 60,
"heavy_total_threshold_in": 0.50,
"standard_delay_days": 2,
"heavy_delay_days": 3,
"apply_now": false
}
Multi-Controller Properties & Contractor Sharing Endpoints
# List all owned and contractor-shared properties
GET https://sprinklers.intellidwell.net/v1/app/properties
# Create a new physical property (auto-geocodes address/zip)
POST https://sprinklers.intellidwell.net/v1/app/properties
{
"name": "Main Residence",
"query": "84050",
"notes": "Gate code #1234. Main shutoff on west exterior wall."
}
# Update property details
PUT https://sprinklers.intellidwell.net/v1/app/properties/<property_id>
{
"name": "Updated Property Name",
"notes": "New gate code"
}
# Assign a controller to a property
POST https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/devices
{ "device_id": "<device_id>" }
# Unlink a controller from a property
DELETE https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/devices/<device_id>
# Share property access with a contractor by username or email
POST https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/shares
{
"username_or_email": "contractor_mike",
"role": "contractor"
}
# Revoke contractor access (Owner) or leave shared property (Contractor)
DELETE https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/shares/<member_id_or_me>
# --- 2D Yard Map & Graphical Controller API ---
# Get yard map geometry & relay links for a property (returns starter template if not yet drawn)
GET https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/yard-map
# Save customized 2D yard map layout (lot boundary, structures, zones, and relay pins)
PUT https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/yard-map
{
"yard_map": {
"version": 1,
"lot_boundary": [[80, 80], [920, 80], [920, 920], [80, 920]],
"structures": [
{
"id": "struct_house",
"name": "Main Residence",
"type": "house",
"color": "#475569",
"points": [[300, 320], [700, 320], [700, 680], [300, 680]]
}
],
"zones": [
{
"id": "zone_front",
"name": "Front Yard Turf",
"type": "turf",
"color": "#10b981",
"zone_id": 0,
"device_id": "<device_id>",
"points": [[100, 700], [660, 700], [660, 900], [100, 900]]
}
]
}
}
# Scan satellite aerial screenshot with Google Gemini Vision AI to generate lot & zone polygons
POST https://sprinklers.intellidwell.net/v1/app/properties/<property_id>/yard-map/generate-from-ai
{
"image_base64": "data:image/png;base64,iVBORw...",
"gemini_api_key": "AIzaSy..."
}
Serial Reprogramming Guide
If you need to manually flash MicroPython or install raw firmware modules, you can connect to the controller's internal header pins using a USB-to-UART serial bridge (such as an FTDI adapter).
Header Pin Configuration:
- VCC: Connect to 3.3V power (Do not use 5V)
- GND: Connect to Common Ground
- TX: Connect to UART Bridge RX
- RX: Connect to UART Bridge TX
- IO0: Tie to Ground during boot to enter flashing mode
Flashing MicroPython with esptool:
# 1. Erase flash
esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
# 2. Write firmware image
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 esp32-20250912-v1.22.bin