weather-station-dashboard

# weather-station-dashboard

Query and manage live weather sensor data from self-hosted stations with MQTT or HTTP ingest, WebSocket live updates, and SQLite-backed historical storage.

## When to Use

- Checking the current value of any sensor for a specific station
- Finding which stations are currently online or offline
- Querying historical readings for a date range
- Retrieving the daily summary (min/max/avg) for a specific day
- Listing active alert events or dismissing them
- Creating or updating alert thresholds

## Sensor Types

| Field | Unit | Description |
|---|---|---|
| temperature_c | C | Air temperature |
| humidity_pct | % | Relative humidity |
| pressure_hpa | hPa | Barometric pressure |
| rainfall_mm | mm | Rainfall accumulation |
| wind_speed_ms | m/s | Wind speed |
| wind_dir_deg | degrees | Wind direction (0=N, 90=E, 180=S, 270=W) |
| uv_index | - | UV index (0-12) |
| soil_temp_c | C | Soil temperature |
| soil_moisture_pct | % | Soil volumetric moisture |

## API Quick Reference

```bash
# List all stations with latest reading
curl http://localhost:3005/api/stations

# Get a specific station
curl http://localhost:3005/api/stations/{station_id}

# Recent readings for a station (default last 100)
curl "http://localhost:3005/api/stations/{station_id}/readings"

# Query readings with filters
curl "http://localhost:3005/api/readings?station_id={id}&from=2025-07-14T00:00:00Z&to=2025-07-20T23:59:59Z&limit=500"

# Daily summaries for a station
curl "http://localhost:3005/api/analytics/daily?station_id={id}&from=2025-07-01&to=2025-07-20"

# All-time or period extremes
curl "http://localhost:3005/api/analytics/extremes?station_id={id}"

# Monthly rainfall totals
curl "http://localhost:3005/api/analytics/rainfall-monthly?station_id={id}&year=2025"

# Active alert events (undismissed)
curl "http://localhost:3005/api/alert-events?dismissed=0"

# Dismiss an alert event
curl -X PUT http://localhost:3005/api/alert-events/{event_id}/dismiss

# Post a reading via HTTP
curl -X POST http://localhost:3005/api/readings \
  -H "Content-Type: application/json" \
  -d '{
    "station_id": "your-station-id",
    "temperature_c": 22.4,
    "humidity_pct": 68,
    "pressure_hpa": 1013.2,
    "rainfall_mm": 0.0,
    "wind_speed_ms": 3.1,
    "wind_dir_deg": 225
  }'
```

## Station Status

A station is considered online if a reading has been received within the last 10 minutes. The `last_seen` field on the station record holds the ISO 8601 timestamp of the most recent reading.

## Alert Threshold Logic

When a reading is ingested (via HTTP or MQTT), all enabled thresholds for that station are evaluated. If a threshold is crossed and no event with the same threshold_id has been triggered in the last 30 minutes, a new alert_event row is inserted and a WebSocket alert message is broadcast to connected clients.

```bash
# List thresholds for a station
curl "http://localhost:3005/api/alerts?station_id={id}"

# Create a threshold
curl -X POST http://localhost:3005/api/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "station_id": "your-station-id",
    "sensor": "temperature_c",
    "condition": "above",
    "threshold": 35,
    "severity": "alert"
  }'
```

## WebSocket Live Updates

Connect to `ws://localhost:3005/ws` to receive live messages:

```json
{ "type": "reading", "station_id": "abc123", "data": { "temperature_c": 22.4, ... } }
{ "type": "alert", "station_id": "abc123", "message": "temperature_c above 35", "severity": "alert" }
{ "type": "station_status", "station_id": "abc123", "online": false }
```

Send a subscribe message to filter to specific stations:
```json
{ "type": "subscribe", "station_ids": ["abc123", "def456"] }
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | HTTP port | 3005 |
| DATA_DIR | SQLite directory | ./data |
| AUTH_PASSWORD | Optional login password | (empty) |
| NODE_ENV | development or production | development |
| SESSION_SECRET | Required in production | (required) |
| MQTT_ENABLED | Enable MQTT ingest | 0 |
| MQTT_BROKER_URL | MQTT broker URL | mqtt://localhost:1883 |
| MQTT_TOPIC_PREFIX | Base topic prefix | farm/weather |
| DATA_RETENTION_DAYS | Days to keep raw readings | 365 |

## Troubleshooting

### Station shows offline but is sending data

Check that the station_id in the POST body matches the station's ID in the database. IDs are UUIDs - verify with `GET /api/stations`.

### Alert events not firing

Verify the threshold has `enabled: 1`. Check if a duplicate suppression window is active (same threshold triggered within 30 minutes).

### Daily summaries missing for a date

The cron job runs at 00:05 each night for the previous day. If the server was down, trigger it manually via `POST /api/analytics/daily/recompute?date=2025-07-19`.