An OpenClaw skill for accessing BirdWeather PUC station data. Fetch bird species detections, live environmental sensor readings, and maintain a local history database for trend analysis and new species alerts.
- Daily summaries — detection counts, species count, top birds of the day
- Species lists — what's been heard over the past day/week/month
- Live sensors — AQI, temperature, humidity, pressure, eCO₂, sound dB from the PUC sensor
- SQLite history — log sensor readings and species catalog over time for trend analysis
- New species alerts — detect when a species is heard for the first time against your local catalog
- A BirdWeather PUC station (get one at birdweather.com)
- Your station token (free, read-only — find it in Station Settings at app.birdweather.com)
- Python 3.9+ (stdlib only, no pip installs needed)
- OpenClaw (for agent-driven usage)
clawhub install birdweather-pucAll commands output JSON.
# Today's summary — detections, species count, top birds, current sensors
python3 scripts/birdweather.py summary --token YOUR_TOKEN
# Recent detections with species name, confidence, and audio URL
python3 scripts/birdweather.py detections --token YOUR_TOKEN --limit 20
# Top species for a time period
python3 scripts/birdweather.py species --token YOUR_TOKEN --period week
# Current sensor readings (AQI, temp, humidity, pressure, eCO₂, dB)
python3 scripts/birdweather.py sensors --token YOUR_TOKEN
# Log a sensor snapshot + update species catalog to SQLite
python3 scripts/birdweather.py log --token YOUR_TOKEN --db ~/birdweather.db
# Find species detected today that aren't in your local catalog yet
python3 scripts/birdweather.py new-species --token YOUR_TOKEN --db ~/birdweather.dbWhen using --db, two tables are maintained automatically:
birdweather_species — cumulative species catalog:
| Column | Type | Description |
|---|---|---|
| species_id | INTEGER | BirdWeather species ID |
| common_name | TEXT | e.g. "House Finch" |
| scientific_name | TEXT | e.g. "Haemorhous mexicanus" |
| color | TEXT | Hex color from BirdWeather |
| thumbnail_url | TEXT | CDN image URL |
| first_detected_at | TEXT | ISO 8601 timestamp |
| detection_count | INTEGER | Cumulative total |
birdweather_sensor_history — time-series sensor log:
| Column | Type | Description |
|---|---|---|
| recorded_at | TEXT | ISO 8601 timestamp |
| temp_f | REAL | Temperature °F |
| humidity | REAL | Relative humidity % |
| pressure | REAL | Barometric pressure hPa |
| aqi | REAL | Air Quality Index |
| eco2 | REAL | Equivalent CO₂ ppm |
| sound_db | REAL | Sound pressure level dB |
| voc | REAL | Volatile organic compounds |
#!/bin/bash
NEW=$(python3 scripts/birdweather.py new-species --token $BW_TOKEN --db ~/birdweather.db)
COUNT=$(echo $NEW | python3 -c "import sys,json; print(len(json.load(sys.stdin)))")
if [ "$COUNT" -gt "0" ]; then
echo "New species detected: $NEW"
# Add your notification logic here (Telegram, email, etc.)
# Then log to DB to update the catalog
python3 scripts/birdweather.py log --token $BW_TOKEN --db ~/birdweather.db
fiOnce installed, your OpenClaw agent can use this skill automatically. Example prompts:
- "What birds have I heard today?"
- "Any new species in the backyard this week?"
- "What's the current AQI from my BirdWeather station?"
- "Show me the top 10 species from this month"
This skill uses the public BirdWeather API at app.birdweather.com/api/v1/stations/{token}. The token is a public read-only identifier — no OAuth or API keys required. See references/api.md for full endpoint documentation.
MIT