Raspberry Pi 4 · SCD41 · Docker

Air You Dying For

CO₂, temperature, and humidity monitoring for your home — runs in Docker, exposes Prometheus metrics.

View on GitHub Pull from GHCR
What we measure

Three metrics, no guessing

The SCD41 reads every 2 seconds. All three are Prometheus gauges, ready to scrape.

💨
CO₂
co2_ppm

The headline number. Outdoor air sits around 420 ppm. Stuffy rooms climb fast.

0 – 800 ppm — Fresh
800 – 1000 ppm — Acceptable
1000 – 1500 ppm — Poor
1500+ ppm — Open a window
🌡️
Temperature
temperature_celsius

Reported in °C. Mount the sensor away from the Pi — the board adds heat.

< 18 °C — Too cold
18 – 24 °C — Comfortable
24 – 28 °C — Warm
28 – 32 °C — Hot
32+ °C — Very hot
💧
Humidity
humidity_percent

Relative humidity as a percentage. The comfort sweet spot is 30 – 60 %.

< 30 % — Too dry
30 – 60 % — Comfortable
60 – 70 % — Slightly damp
70 – 80 % — Damp
80+ % — Very humid
Preview

Grafana dashboard

Included dashboard JSON — import it straight into Grafana. Stats, sparklines, and threshold lines out of the box.

Grafana dashboard showing Temperature, CO2, and Humidity panels

Live data — 29.7 °C · 522 ppm CO₂ · 51.0 % humidity · 5 s refresh

Architecture

How it works

Four components, zero cloud dependency.

🔬
SCD41
Sensirion sensor
→
🥧
Raspberry Pi 4
via I²C
→
📦
Docker
Python exporter
→
📊
Prometheus
scrapes :8000
→
📈
Grafana
dashboard
Get started

Quick start

Enable I²C on the Pi, verify the i2c group GID, then run.

Prerequisites 
# Enable I2C
sudo raspi-config
# Interface Options → I2C → Enable

# Verify i2c group GID
getent group i2c | cut -d: -f3
# Update group_add in docker-compose.yml
Run with Docker 
# Pull from GHCR
docker pull ghcr.io/just5ky/air-you-dying-for:main

# Or build and run locally
docker compose up -d