weather-integration

# weather-integration

Connect irrigation-scheduler to live weather data from Open-Meteo for automatic rain and freeze skip rules.

## When to Use

- Setting up your first weather-based skip rule
- Tuning rain forecast thresholds for your local climate
- Diagnosing why a zone ran despite rain
- Diagnosing why a zone was skipped unexpectedly
- Understanding the weather cache and refresh cycle
- Previewing which zones will skip today before schedules fire

## How It Works

irrigation-scheduler fetches hourly forecast data from the Open-Meteo API every 30 minutes. The raw response is stored in `weather_cache` in SQLite. When the cron scheduler evaluates a zone before each run, it reads the cached weather data and evaluates every active skip rule for that zone in order. If any rule matches, the run is recorded as `skipped` with the rule name and reason.

Manual runs bypass all skip rule evaluation.

## Prerequisites

1. Latitude and longitude set in Settings (`PUT /api/settings` with `latitude` and `longitude`)
2. At least one skip rule attached to a zone
3. Server has outbound HTTPS access to `api.open-meteo.com`

## Open-Meteo Fields Used

| Field | Used For |
|---|---|
| `precipitation_sum` (daily) | `rain_yesterday` rule: yesterday total in mm |
| `precipitation_probability_max` + `precipitation` (hourly) | `rain_forecast` rule: sum over next H hours |
| `temperature_2m_min` (daily) | `temperature_below` rule: freeze protection |

All values are in metric units (mm for precipitation, Celsius for temperature).

## Skip Rule Reference

### rain_forecast

Skips if the sum of forecast precipitation over the next N hours exceeds a threshold.

```json
{
  "rule_type": "rain_forecast",
  "threshold_mm": 5.0,
  "window_hours": 24
}
```

**Tuning guide:**
- Dry climates: lower threshold (2-3mm) to skip on any meaningful rain
- Humid climates: higher threshold (8-12mm) to avoid over-skipping
- Drip irrigation: lower threshold since plants need less supplemental water
- Lawn irrigation: higher threshold since lawns need more volume

### rain_yesterday

Skips if measured precipitation from the previous calendar day exceeded a threshold.

```json
{
  "rule_type": "rain_yesterday",
  "threshold_mm": 10.0
}
```

**Tuning guide:**
- Sandy soil drains fast: lower threshold (6-8mm)
- Clay soil retains moisture: higher threshold (15-20mm)
- Raised beds: lower threshold (5-8mm)
- In-ground lawn: higher threshold (12-18mm)

### temperature_below

Skips if the forecasted minimum temperature is below a threshold. Used for freeze protection.

```json
{
  "rule_type": "temperature_below",
  "threshold_celsius": 2.0
}
```

Set to 2C (35F) for a safety margin above 0C (32F) to account for sensor variation.

## API Quick Reference

```bash
# Check current weather cache
curl http://localhost:3001/api/weather

# Get skip preview for today (which zones will skip and why)
curl http://localhost:3001/api/weather/skip-preview

# Force a weather cache refresh
curl -X POST http://localhost:3001/api/weather/refresh

# List skip rules for a zone
curl http://localhost:3001/api/zones/{zone-id}/skip-rules

# Add a skip rule to a zone
curl -X POST http://localhost:3001/api/zones/{zone-id}/skip-rules \
  -H "Content-Type: application/json" \
  -d '{"rule_type":"rain_forecast","threshold_mm":5,"window_hours":24}'

# Update a skip rule
curl -X PUT http://localhost:3001/api/zones/{zone-id}/skip-rules/{rule-id} \
  -H "Content-Type: application/json" \
  -d '{"threshold_mm":8}'

# Delete a skip rule
curl -X DELETE http://localhost:3001/api/zones/{zone-id}/skip-rules/{rule-id}
```

## Skip Preview Response

The skip preview endpoint returns per-zone evaluation before any runs fire:

```json
{
  "evaluated_at": "2025-04-14T06:00:00Z",
  "weather_source": "cache",
  "weather_age_minutes": 12,
  "zones": [
    {
      "zone_id": "...",
      "zone_name": "Garden Beds",
      "scheduled_today": true,
      "will_skip": true,
      "skip_reason": "Rain forecast 12.4mm in next 24h exceeds threshold 5.0mm",
      "rule_type": "rain_forecast"
    },
    {
      "zone_id": "...",
      "zone_name": "Front Lawn",
      "scheduled_today": true,
      "will_skip": false,
      "skip_reason": null
    }
  ]
}
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| DEFAULT_LATITUDE | Initial latitude loaded into settings | 0 |
| DEFAULT_LONGITUDE | Initial longitude loaded into settings | 0 |
| WEATHER_CACHE_TTL_MIN | Minutes before weather cache is considered stale | 30 |

Set `DEFAULT_LATITUDE` and `DEFAULT_LONGITUDE` at first launch to avoid needing to manually configure Settings before skip rules can evaluate.

## Troubleshooting

### Weather data shows zeros or empty

1. Confirm coordinates are set: `GET /api/settings` - check `latitude` and `longitude` are non-zero
2. Test Open-Meteo directly: `curl "https://api.open-meteo.com/v1/forecast?latitude=YOUR_LAT&longitude=YOUR_LON&daily=precipitation_sum&timezone=auto"`
3. Check server logs for HTTP errors on the weather fetch

### Zone ran despite rain forecast

1. Check skip preview before the scheduled run time: `GET /api/weather/skip-preview`
2. Confirm the skip rule is attached to the zone: `GET /api/zones/:id/skip-rules`
3. Confirm `enabled` is `1` on both the zone and the skip rule
4. Check that `window_hours` covers the time of rain: if rain is forecast at hour 30 but your window is 24, it will not trigger
5. Verify the weather cache was fresh at run time: check `GET /api/weather` for `fetched_at`

### Zone skipped when it should not have

1. Check the `skip_reason` in run history: `GET /api/runs?status=skipped`
2. Adjust the skip rule threshold upward and re-evaluate
3. If the threshold seems correct, verify units: Open-Meteo returns mm, not inches

### Weather fetch fails silently

When Open-Meteo is unreachable, the scheduler falls back to running as scheduled (safe-to-water default). Check server logs for `WEATHER_FETCH_ERROR` entries. No zones will be skipped if weather data cannot be refreshed within the cache TTL.