irrigation-scheduler

name

irrigation-scheduler

description

Schedule and monitor irrigation zones with weather-aware skip rules and water usage tracking. Use when asked to manage irrigation timing, set up zone schedules, configure rain-based skip rules, check water usage, trigger manual watering, or apply seasonal duration presets. Triggers include "irrigation", "sprinkler schedule", "watering zones", "skip when raining", "water usage tracking", "manual run irrigation", or any task involving automated watering management.

irrigation-scheduler

Schedule irrigation zones with weather-aware automatic skips and water usage tracking.

When to Use

• Setting up irrigation schedules for multiple zones
• Configuring weather-based skip rules (rain forecast, recent rain, freeze protection)
• Triggering manual irrigation runs
• Checking water usage by zone and time period
• Applying seasonal duration presets (Summer 1.5x, Fall 0.75x, etc.)
• Reviewing irrigation history and skip events

Prerequisites

1. irrigation-scheduler running (Docker or local)
2. At least one zone configured
3. Location coordinates set in Settings (for weather integration)

Key Concepts

Zones

Each zone represents one physical irrigation circuit. Zones have:

• Name and description
• Flow rate (GPH) for water usage calculation
• Coverage area (sqft) for reporting
• One or more schedules
• One or more skip rules

Schedules

A schedule defines when a zone runs: days of week, start time, and duration in minutes. A zone can have multiple schedules (e.g., one for weekdays, one for weekends). Duration multiplier from season presets is applied on top of the base duration.

Skip Rules

Rule Type	Description
rain_forecast	Skip if rain forecast exceeds N mm in next H hours
rain_yesterday	Skip if rain fell yesterday exceeding N mm
temperature_below	Skip if temperature is below N degrees (freeze protection)

Skip rules only apply to scheduled runs. Manual runs always proceed.

Season Presets

Apply a multiplier to all zone durations at once. Example: Summer preset (1.5x) makes a 30-minute schedule run for 45 minutes. Removing a preset restores base durations.

API Reference

Quick Examples

# List all zones
curl http://localhost:3001/api/zones

# Trigger a manual run (zone_id + duration in minutes)
curl -X POST http://localhost:3001/api/runs/manual \
  -H "Content-Type: application/json" \
  -d '{"zone_id": "uuid-here", "duration_min": 20}'

# Stop a running zone
curl -X PUT http://localhost:3001/api/runs/{run-id}/stop

# Get skip preview for today
curl http://localhost:3001/api/weather/skip-preview

# Check water usage
curl "http://localhost:3001/api/runs?limit=30"

Environment Variables

Variable	Description	Default
PORT	HTTP port	3001
DATA_DIR	SQLite and data directory	./data
AUTH_PASSWORD	Optional login password	(empty)
NODE_ENV	development or production	development
SESSION_SECRET	Required in production	(required)
DEFAULT_LATITUDE	Initial latitude for weather	0
DEFAULT_LONGITUDE	Initial longitude for weather	0

Boolean env vars use 0 (false) and 1 (true).

Troubleshooting

Zone not running at scheduled time

1. Confirm zone is enabled: GET /api/zones/:id - check enabled: 1
2. Confirm schedule days_of_week includes today (0=Sun)
3. Check if a skip rule triggered: GET /api/runs?status=skipped
4. Verify server timezone matches your local timezone in Settings

Skip rules not triggering

Weather data requires valid latitude/longitude in Settings. Check GET /api/weather returns data. If weather fetch fails, the scheduler falls back to run as scheduled (safe default).

Water usage shows 0

Flow rate must be set on the zone for usage calculation. Update via PUT /api/zones/:id with flow_rate_gph value.