irrigation-scheduler

# 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

```bash
# 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.