# KnowCO₂ - Open Source Portable CO₂ Monitor

> Open-source, portable CO₂ monitor built on the Adafruit ESP32-S3 Reverse TFT Feather with a swappable CO₂ sensor architecture (SCD41 default) for makers, educators, and anyone who cares about indoor air quality.

## Project Overview

KnowCO₂ is a fully open-source hardware and software platform for monitoring indoor CO₂ levels in real-time. The project provides:

- **Hardware**: ESP32-S3 based device with a swappable NDIR CO₂ sensor (SCD41 default)
- **Firmware**: CircuitPython-based, fully customizable, with a pluggable sensor driver registry
- **Cloud Platform**: Optional telemetry and historical data storage
- **Web Portal**: Real-time monitoring and device management
- **Home Assistant Integration**: Official HACS custom integration (local polling, no broker required)
- **Browser Simulator**: The actual device firmware running in-browser via WebAssembly

## Why CO₂ Monitoring Matters

Indoor CO₂ levels are a proxy for:
- **Ventilation quality**: Rising CO₂ indicates stale air buildup
- **Cognitive performance**: High CO₂ (>1000 ppm) can impair focus and decision-making
- **Health**: Proper ventilation reduces airborne pathogen transmission

## Technical Specifications

### Hardware
- **MCU**: Adafruit ESP32-S3 Reverse TFT Feather (dual-core, Wi-Fi + BLE)
- **Sensor**: Sensirion SCD41 NDIR CO₂ sensor (default, ±30 ppm accuracy), swappable over STEMMA QT / I²C
- **Supported sensors**: SCD40, SCD41 (and other SCD4x variants), SCD30
- **Sensors in testing**: Senseair Sunrise, Sensirion STCC4
- **Sensor architecture**: open driver registry — adding a new CO₂ sensor requires one driver file and one registry line; supported hardware keeps growing
- **Display**: 240×135 pixel TFT with three display modes: text, big number, rolling graph
- **Power**: LiPo battery with USB-C charging, MAX17048 fuel gauge
- **Enclosure**: 3D-printable case with sensor airflow path

### Firmware Features (current: RC-43 series, CircuitPython 10.x)
- Real-time CO₂, temperature, and humidity readings
- Pluggable sensor driver registry with automatic sensor detection on boot
- Three display modes: detailed text, large CO₂ number, rolling bar graph
- Color-coded alerts with configurable thresholds (default: 800/1200/1500 ppm)
- Colorblind-safe display palette option (Wong palette), on device and web dashboard
- Low-power mode (hold button A): reduced sample rate, dimmed display, throttled uploads
- Scheduled display dimming (NTP-based)
- Up to three stored Wi-Fi networks with automatic fallback and AP setup mode
- Web configuration portal translated into 22 languages with full accessibility (ARIA, keyboard navigation)
- Home Assistant: official HACS integration (REST polling) plus MQTT auto-discovery
- Wi-Fi telemetry: HMAC-authenticated cloud upload, generic MQTT, Adafruit IO
- OTA updates: single-file or full ZIP package via the local web portal
- Automatic Self-Calibration (ASC), manual Forced Recalibration (FRC), altitude/pressure compensation
- Automatic sensor fault detection and recovery (CRC checks, staleness watchdog, hardware watchdog)
- FCC e-label regulatory screen on device

### Home Assistant
- Official HACS custom integration: https://github.com/knowco2-project/knowco2-hacs
- Local polling of the device's /status endpoint — no MQTT broker required
- Sensors: CO₂ (ppm), temperature, humidity, battery
- MQTT auto-discovery also available for broker-based setups

### Cloud Platform (Optional)
- Device provisioning with HMAC authentication
- Real-time latest readings, historical charts and analytics
- Device management portal at https://cloud.knowco2.com
- Tiered plans: Free (7-day history), Home ($4.99/mo, 90-day history, up to 5 devices), Lab ($12.99/mo, 2-year history, up to 10 devices)

## Use Cases

- **Schools & Classrooms**: Monitor ventilation to optimize learning
- **Offices**: Ensure adequate fresh air for productivity
- **Home Labs**: Track air quality in workshops and maker spaces
- **Smart Homes**: Native Home Assistant integration for automation
- **Research**: Collect data for indoor air quality studies

## Interactive Demo (Real Firmware in the Browser)

https://knowco2.com/interactive-demo.html runs the **actual KnowCO₂ CircuitPython
firmware** in the browser via WebAssembly (Pyodide) — not a mock-up. The same
code that ships on the device drives a pixel-accurate render of the 240×135
display, overlaid on a photo of the real device, placed in a virtual room with
a physics-based air model (people, window, door, ventilation in air changes
per hour). Visitors can:

- Press and hold the device's A/B/C buttons (all hold gestures work: low-power
  mode, Wi-Fi AP/STA switching, regulatory e-label screen)
- Open the window or door to ventilate and watch CO₂ decay on the rolling graph
- Watch the full network sequence: Wi-Fi connect → NTP time sync → cloud
  telemetry posts, with the device's T/W/C status indicators lighting in turn
- Inject a sensor fault to watch the firmware's CRC recovery routine fire
- Toggle the colorblind-safe display palette

## Getting Started

Documentation is available at https://knowco2.com:

- **Getting Started guide**: https://knowco2.com/getting-started.html — offline use, Wi-Fi setup, cloud integration
- **Calibration guide**: https://knowco2.com/calibration.html — ASC, FRC, altitude compensation
- **Interactive Demo**: https://knowco2.com/interactive-demo.html — the real firmware running in-browser via WebAssembly, in a virtual room
- **Device Learning Simulator**: https://knowco2.com/device-simulator.html — learn the monitor hands-on in a walkable 3D facility; the wall-mounted device runs the real firmware, with outdoor FRC calibration and its live web portal
- **CO₂ Information**: https://knowco2.com/co2-interactive.html — context on CO₂ levels and health effects

### For Builders
1. Order parts: Adafruit ESP32-S3 Reverse TFT Feather + Sensirion SCD41 (~$60 total)
2. 3D print enclosure (STL files in repo)
3. Install CircuitPython 10.x, then flash the latest firmware release (RC-51 series)
4. Configure Wi-Fi and thresholds via the captive portal (22 languages)
5. Optional: Create cloud account at https://cloud.knowco2.com for telemetry

### For Users
- Visit https://knowco2.com for build guides and documentation
- Try the real firmware in your browser at https://knowco2.com/interactive-demo.html
- Add the device to Home Assistant via HACS: https://github.com/knowco2-project/knowco2-hacs
- Join community discussions on GitHub
- Access cloud portal at https://cloud.knowco2.com

## Open Source

**Everything is open:**
- Hardware schematics and PCB files
- Firmware source code (CircuitPython, modular `knowco2/` package)
- Sensor driver API — contribute support for new CO₂ sensors with one file
- 3D enclosure models (STL + CAD)
- Cloud infrastructure (Terraform)
- Web portal code (JavaScript)

**Licenses:**
- Hardware: CERN-OHL-S v2
- Software: MIT License
- Documentation: CC BY-SA 4.0

**OSHWA Certification:**
- Certified by the Open Source Hardware Association (OSHWA)
- UID: US002828 (certified 2026-06-12)
- Listing: https://certification.oshwa.org/us002828.html

## Repository

GitHub: https://github.com/knowco2-project

## Contact

- Website: https://knowco2.com
- Support: support@knowco2.com
- Cloud Portal: https://cloud.knowco2.com

## Key Features Summary

- ✅ Real-time CO₂ monitoring with on-device rolling graph
- ✅ Swappable CO₂ sensors with an open, growing driver registry
- ✅ Portable battery-powered design with low-power mode
- ✅ Visual alerts on TFT display (colorblind-safe option)
- ✅ Home Assistant integration (HACS) + MQTT + Adafruit IO + cloud
- ✅ OTA firmware updates over Wi-Fi
- ✅ Fully open source (hardware + software) — OSHWA certified (UID US002828)
- ✅ Browser demo runs the actual device firmware (WebAssembly)
- ✅ 22-language, accessible configuration portal

---

*Last updated: 2026-07-23*
*Project status: Active development — first production run in preparation*
*Firmware version: RC-51 series (CircuitPython 10.2.x)*