Project 01 · dadaLab
airpi
An open-source indoor air quality monitor that measures CO2, PM2.5, temperature, humidity, and VOCs. Data is served over a local web dashboard with zero cloud dependency — no accounts, no subscriptions, no data leaves your home.
Under development Sensor firmware is implemented and host-tested; physical validation is pending.
What it is
airpi is a hand-solderable monitor built around an ESP32-S3 microcontroller and three sensor modules. Assemble it from off-the-shelf parts, flash the firmware, and see real-time air quality on any device in your home.
CO2 · temp · humidity
Sensirion SCD41
Photoacoustic CO2 sensing plus temperature and humidity, CRC-verified over I2C. Currently the primary reading on the dashboard.
PM1.0 · PM2.5 · PM10
Plantower PMS5003
Laser-scattering particulate matter sensor over UART. Reports PM1.0, PM2.5, and PM10 concentrations.
VOC index · temp · humidity
Bosch BME688
Metal-oxide gas sensor producing a VOC index, with temperature and humidity, over I2C on its own address.
Brain
ESP32-S3-DevKitC-1
WiFi, dual-core processing, and USB-C flashing. The device is discoverable at airpi.local via mDNS, and readings are served entirely on the local network.
Why it matters
Indoor air is the air we mostly breathe, and the tools sold to measure it often depend on services that can disappear.
The problem
4.2 million
premature deaths per year are linked to air pollution (WHO, 2024). Indoor air can be 2–5× more polluted than outdoor air (US EPA), yet people spend 90% of their time indoors.
The trap
Cloud bricking
Consumer monitors cost $200–$300 and depend on cloud services that may shut down — Awair filed for bankruptcy in 2024, bricking users' hardware. If you can't run it without a company, you don't own it.
The answer
Local-first
airpi rivals $300 commercial monitors in sensor coverage at a verified build cost of $156.42, runs entirely on your local network, and uses standard, replaceable modules.
For parents of children with asthma, households in wildfire country, remote workers wondering if their office air is safe, or anyone who has asked "is the air in this room healthy?" — airpi answers that question without a subscription or a service that might shut down.
How it works
Everything runs on your network. The firmware reads all three sensors every 5 seconds and reports an honest state for each one.
- First boot: airpi creates a airpi-setup Wi-Fi network with a captive portal. Join it, enter your home Wi-Fi credentials, and the device reconnects automatically.
- Discovery: after setup, the device advertises airpi.local over mDNS. No app, no account.
- Status page: a dependency-free page at http://airpi.local shows live CO2, PM2.5, and VOC index cards with reading age, temperature, and humidity.
- Local API: GET /api/current returns the same observation as JSON for local integrations.
- Honest states: each sensor reports initializing, valid, stale, error, or missing — a stale reading is labelled as not current, and missing data is never displayed as zero.
- Recovery: if the network disappears, the device retries with bounded backoff without rebooting, and the setup network returns if needed.
Credentials are stored only on the device and never printed or sent anywhere. Responses are local-only and served with Cache-Control: no-store. The firmware never generates simulated air-quality readings.
Current status
airpi is under development. Sensor firmware for CO2, PM2.5, and VOC is implemented, wired into the device runtime, and host-tested. The physical build is not yet assembled.
| Area | What exists today | Status |
|---|---|---|
| SCD41 (CO2, temp, humidity) | CRC-verified decoding, lifecycle states, 5-second sampling in the device runtime | Done |
| PMS5003 (PM2.5) | UART frame decoding, PM1.0/PM2.5/PM10, wired into the runtime and status page | Done |
| BME688 (VOC) | I2C driver, calibration, VOC index, wired into the runtime and status page | Done |
| Wi-Fi setup & discovery | Captive portal on first boot, mDNS airpi.local, saved credentials, bounded reconnect | Done |
| Local status page & API | Dependency-free page and /api/current JSON endpoint | Done |
| BOM & wiring | Verified bill of materials with current pricing and a pin-level wiring map | Done |
| Physical validation | Hardware bringup checklist written; first physical unit not yet assembled | Next |
| Data logging & history | microSD CSV logging, 24-hour trends and history served by /api/history; data export via CSV download (/api/export) and a Prometheus /metrics endpoint | Done |
| PCB & enclosure | KiCad PCB design and 3D-printable enclosure | Planned |
| Future variant | airpi with an on-device e-ink display, on the roadmap | Planned |
Build it yourself
A verified recommended build costs $156.42 in parts. Prices were verified in the project on July 29, 2026; the project's BOM doc lists a lower-cost generic-module configuration at $103.58.
| Item | Component | Verified cost |
|---|---|---|
| Microcontroller | ESP32-S3-DevKitC-1 (Adafruit #5364) | $19.95 |
| PM sensor | Plantower PMS5003 (Adafruit #3686) | $39.95 |
| CO2 + temp/humidity | Sensirion SCD41 (Adafruit #5190) | $49.95 |
| VOC + temp/humidity | Bosch BME688 (Adafruit #5046) | $19.95 |
| Data logging | MicroSD SPI breakout (Adafruit #4682) | $3.50 |
| Storage | 16 GB microSD card | $10.49 |
| Prototyping | JLCPCB fabrication (five PCBs) | $5.00 |
| Enclosure | 3D-printed PLA (~30 g) | $0.40 |
| Power | USB-C cable | $2.50 |
| Power | 5 V, 2 A USB adapter | $3.98 |
| Assembly | 4.7 kΩ resistors and hookup wire | $0.75 |
| Total | $156.42 |
The general shape of a build:
- Solder header pins to the ESP32-S3 DevKit and the sensor modules.
- Wire the sensors to the ESP32-S3 (PMS5003 over UART, SCD41 and BME688 over I2C, microSD over SPI).
- Flash the firmware from the project's firmware directory.
- On first boot, join the airpi-setup network and enter your Wi-Fi credentials.
- Open http://airpi.local on any device and read your air.
Full build, flash, wiring, and verification instructions live in the airpi project directory in this repository, alongside the firmware, host tests, and docs.
What's next
Work proceeds through the project's ordered milestone plan. Each slice is verified independently before the next begins.
Immediate
Physical validation
Assemble the first unit and run the hardware bringup checklist: power and continuity, sensor communication, Wi-Fi setup, and a soak test.
Later
PCB & enclosure
Design a hand-solderable two-layer PCB and a 3D-printable enclosure with sensor ventilation, then document the final build guide.
Future variant
E-ink display model
A later airpi variant with an on-device display, keeping the lab focused on one indoor air quality product line.