Living Room Air Monitor

intent

automate hourly collection of air quality metrics (temperature, humidity, PM2.5, CO2) from an IKEA Dirigera-connected ALPSTUGA sensor in your living room. use this skill when you need to set up continuous monitoring, query historical readings, generate trend charts, calculate daily/monthly averages, or send air quality reports via email or WhatsApp. the skill handles data storage, incomplete readings, and multi-channel delivery so you don't have to.

inputs

Dirigera Hub Connection:

• IP address: 192.168.1.100 (network-accessible, no auth required if on same network)
• Sensor model: ALPSTUGA air quality sensor
• Auth token: stored at ~/.openclaw/workspace/.dirigera_token (required for API calls, obtained from Dirigera hub during initial setup)

Database Storage:

• location: ~/.openclaw/workspace/skills/living-room-air-monitor/data/air_quality.db
• auto-created on first data collection; manual init via python3 scripts/collect_air_data.py

Contact Configuration:

• file: ~/.openclaw/workspace/CONTACTS.json
• format: JSON with keys name, email, whatsapp
• required for email/WhatsApp reports; whatsapp number must be international format (e.g., +614xxxxxxxxx)

External CLIs (pre-configured):

• gog for email delivery
• wacli for WhatsApp delivery

Cron Scheduling:

• hourly execution via crontab (user adds entry; see procedure step 2)

Edge Case Inputs:

• incomplete readings (any null sensor value) are skipped, not stored
• network timeouts to Dirigera hub (default timeout: 10 seconds, script continues on failure)
• auth token expiry (detected on 401 response; user must refresh token manually)
• date range queries outside available data return empty result sets

procedure

1. Initialize database schema on first run

   • input: path to ~/.openclaw/workspace/skills/living-room-air-monitor/
   • execute: python3 scripts/collect_air_data.py
   • output: SQLite database created at data/air_quality.db with columns (id, datetime, temperature, humidity, pm25, co2, created_at); indexed on datetime
   • note: safe to re-run; does not overwrite existing data

2. Set up hourly data collection via cron

   • input: user's system python3 path (typically /opt/homebrew/bin/python3 on macOS or /usr/bin/python3 on Linux)
   • execute: add line to crontab: 0 * * * * /path/to/python3 /Users/username/.openclaw/workspace/skills/living-room-air-monitor/scripts/collect_air_data.py >> /tmp/air_quality_cron.log 2>&1
   • output: cron job scheduled; each hour at minute 0, script runs and appends status to /tmp/air_quality_cron.log
   • verify: check log file with tail -f /tmp/air_quality_cron.log after one hour has passed

3. Collect single air quality reading (manual or cron-triggered)

   • input: Dirigera hub IP (192.168.1.100), auth token from ~/.openclaw/workspace/.dirigera_token
   • execute: python3 scripts/collect_air_data.py
   • steps: a. fetch current temperature, humidity, PM2.5, co2 from Dirigera API b. if any value is None, log warning and skip save (incomplete reading) c. if all values present, insert row with ISO datetime and metrics into air_quality table d. print collected values to stdout (e.g., "2026-02-24T14:00:00 | temp=21.3 | humidity=45.2 | pm25=8.1 | co2=520")
   • output: single row added to database OR skip logged to cron.log if incomplete

4. Query historical air quality data

   • input: query type (--day, --month, --avg-day, --avg-month, --range), date(s), optional metric name
   • execute: python3 scripts/query_data.py [options]
   • examples:
     • --day 2026-02-24 returns all readings for that date (rows sorted by datetime)
     • --month 2026-02 returns all readings in February 2026
     • --avg-day 2026-02-24 returns average of all 4 metrics for that day
     • --avg-day 2026-02-24 --metric temperature returns only temp average for that day
     • --avg-month 2026-02 returns all metric averages for the month
     • --range returns (earliest_datetime, latest_datetime) in database
   • output: stdout formatted as JSON or table, or direct Python function return for programmatic use
   • python API also supports: get_reading_by_datetime(dt), get_readings_by_interval(start, end), get_readings_by_day(date), get_readings_by_month(year, month), get_average_by_day(date, metric), get_average_by_month(year, month, metric), get_all_averages_by_day(date), get_all_averages_by_month(year, month), get_date_range()

5. Generate line charts for time periods

   • input: time period (--day, --week, --month, --3month, --6month, --year), date(s), optional output directory
   • execute: python3 scripts/generate_chart.py [options]
   • examples:
     • --day 2026-02-24 generates chart for that single day
     • --week 2026-02-24 generates chart for 7-day week ending on that date
     • --month 2026-02 generates chart for February 2026
     • --3month 2026-02-24 generates chart for 3 months ending on that date
     • --6month 2026-02-24 generates chart for 6 months ending on that date
     • --year 2026 generates chart for all of 2026
     • --output ~/charts saves PNG to custom directory instead of default /tmp/air_charts/
   • output: PNG file with 4 line subplots (temperature, humidity, PM2.5, CO2) saved to output directory; filename includes period (e.g., air_quality_2026-02-24_day.png)
   • python API: generate_day_chart(date, output_dir), generate_week_chart(end_date, output_dir), generate_month_chart(year, month, output_dir), generate_3month_chart(end_date, output_dir), generate_6month_chart(end_date, output_dir), generate_year_chart(year, output_dir), generate_chart(start_dt, end_dt, output_path, title)

6. Send air quality report via email or WhatsApp

   • input: time period (--day, --week, --month), date(s), channel (email or whatsapp), optional --no-chart flag
   • execute: python3 scripts/send_report.py [options]
   • examples:
     • --day 2026-02-24 sends today's report via email (default channel)
     • --week 2026-02-24 --channel whatsapp sends week report via WhatsApp
     • --month 2026-02 --channel email sends month report via email
     • --day 2026-02-24 --no-chart sends text-only report without PNG attachment
   • steps: a. generate text report with period summary, average values, quality thresholds, and all readings b. optionally generate chart PNG for the period c. deliver via gog CLI (email) or wacli CLI (WhatsApp) using contact from CONTACTS.json
   • output: report sent to recipient email or WhatsApp number; confirmation printed to stdout
   • python API: send_report(start_dt, end_dt, channel, include_chart, chart_path), send_daily_report(date, channel='email'), send_weekly_report(end_date, channel='email'), send_monthly_report(year, month, channel='email'), generate_text_report(start_dt, end_dt)

decision points

if Dirigera hub is unreachable (network down, IP wrong, or timeout > 10 seconds):

• cron job logs error to /tmp/air_quality_cron.log and exits gracefully (does not crash, does not save incomplete reading)
• user must verify hub is online and token is valid before next collection attempt
• no alert sent; user discovers issue via log review or missing data points

if auth token in ~/.openclaw/workspace/.dirigera_token is missing or expired:

• collect_air_data.py exits with error message to stdout and cron log
• no data is saved
• user must manually refresh token from Dirigera hub and update file

if any sensor value is None or null:

• entire reading is skipped (not saved to database)
• reason logged to cron output (e.g., "skipped incomplete reading: co2=None")
• next hourly collection will try again

if query requests data outside the date range in the database:

• return empty result set (JSON array [] or empty table)
• script does not error; user sees zero rows

if CONTACTS.json is missing or malformed (invalid JSON):

• send_report.py exits with error before attempting CLI calls
• user must create or fix CONTACTS.json with valid email and/or whatsapp fields
• alternate: script can skip that channel (email fails silently if email key missing, whatsapp fails if whatsapp key missing) , behavior defined by implementation

if chart generation fails (matplotlib missing, no data for period, disk full):

• send_report.py with --no-chart flag still sends text report
• with default (include chart), script exits with error and does not send partial report

if email or WhatsApp delivery fails (gog/wacli timeout, invalid number, network down):

• send_report.py prints error to stdout and exits
• user must verify contact is valid and retry

output contract

database output:

• file: ~/.openclaw/workspace/skills/living-room-air-monitor/data/air_quality.db
• schema: 5 columns (id, datetime, temperature, humidity, pm25, co2) with datetime as unique key; index on datetime
• row format on insertion: datetime as ISO 8601 string, temperature as float (celsius), humidity as float (percent), pm25 as float (micrograms/m3), co2 as float (ppm)

query output (CLI):

• format: stdout as JSON (default) or human-readable table (if --table flag)
• example JSON: [{"datetime": "2026-02-24T14:00:00", "temperature": 21.3, "humidity": 45.2, "pm25": 8.1, "co2": 520}]
• averages: {"temperature": {"avg": 20.5, "min": 19.2, "max": 22.1}, "humidity": {"avg": 48.3, ...}, "pm25": {...}, "co2": {...}}

chart output:

• file format: PNG (8-bit color, 1920x1080 pixels, 4 subplots in 2x2 grid)
• location: /tmp/air_charts/ by default or user-specified output directory
• naming: air_quality_YYYY-MM-DD_[day|week|month|3month|6month|year].png
• content: 4 line plots (temperature in celsius, humidity in percent, PM2.5 in µg/m3, CO2 in ppm) with x-axis as datetime and legend

report output:

• delivery: email (via gog CLI to recipient in CONTACTS.json) or WhatsApp (via wacli CLI)
• text content: period summary, data point count, average values with ranges, air quality assessment (Good/Moderate/Poor/Unhealthy), all individual readings with timestamps
• optional attachment: PNG chart file
• success indication: CLI returns 0, report confirmation printed to stdout (e.g., "Report sent to your@email.com")

PM2.5 air quality thresholds:

• good: <= 12 µg/m3
• moderate: 12.1 - 35 µg/m3
• unhealthy: > 35 µg/m3

CO2 air quality thresholds:

• good: <= 1000 ppm
• moderate: 1001 - 2000 ppm
• poor: > 2000 ppm

outcome signal

data collection success:

• cron job runs silently; new row appears in database each hour when queried (query_data.py --range shows latest datetime updated)
• /tmp/air_quality_cron.log contains no errors for the past hour
• manual collect_air_data.py prints 4 metric values to stdout before exiting code 0

query success:

• query_data.py returns non-empty JSON or table for valid date ranges
• averages match manual calculation (sum of readings / count)
• --range output shows earliest and latest datetime in database

chart success:

• PNG file is created at expected path in /tmp/air_charts/ or custom output directory
• file size > 50KB (confirms image data written, not empty stub)
• 4 distinct line plots visible when opened in image viewer; axes labeled with metric names and units

report delivery success:

• send_report.py exits code 0 and prints confirmation (e.g., "Report sent to +614xxxxxxxxx via WhatsApp")
• recipient receives email or WhatsApp message within 60 seconds
• message contains period summary and at least 2 average values (temp and humidity or PM2.5 and CO2)
• if --no-chart flag used, message has only text and no attachment; if chart included, attachment is PNG file

integration success (end-to-end):

• user sets cron once; wakes up next day and runs query_data.py --avg-day $(date -v-1d +%Y-%m-%d) to see yesterday's averages with no manual intervention
• user asks "email me this week's air quality chart" → runs generate_chart.py --week $(date +%Y-%m-%d) && send_report.py --week $(date +%Y-%m-%d) → receives email with chart within 2 minutes