# Firmware

ESPHome firmware for the ESP32-C3 CO₂ & environment sensor board.

## Files

| File | In git | Purpose |
|---|---|---|
| `esp-sensair.yaml.example` | yes | configuration template, all credentials as `!secret` references |
| `secrets.yaml.example` | yes | secrets template with placeholders |
| `esp-sensair.yaml` | **no** (git-ignored) | your flashed configuration |
| `secrets.yaml` | **no** (git-ignored) | your Wi-Fi, API, OTA and hotspot credentials |

Setup:

```bash
cp firmware/esp-sensair.yaml.example firmware/esp-sensair.yaml
cp firmware/secrets.yaml.example     firmware/secrets.yaml
# fill in firmware/secrets.yaml
esphome run firmware/esp-sensair.yaml
```

Generate the Home Assistant API encryption key with:

```bash
python3 -c "import base64,os; print(base64.b64encode(os.urandom(32)).decode())"
```

## Target

| Item | Value |
|---|---|
| Chip | ESP32-C3 (RISC-V, single core, Wi-Fi) |
| ESPHome board | `esp32-c3-devkitm-1` |
| Framework | ESP-IDF |
| Flashing | USB-C on the devkit module (ESPHome OTA after first flash) |

## Peripherals

| Peripheral | Bus | Pins | Notes |
|---|---|---|---|
| Sensirion S8 (NDIR CO₂) | UART, 9600 baud 8N1 | `TX = GPIO21`, `RX = GPIO20` | 5 V supply, ~30 s preheat; the S8's own `bCal_in` pin carries the on-board calibration button |
| BME280 (T / RH / P) | I²C, address `0x76` | `SDA = GPIO7`, `SCL = GPIO8` | powered from the module's 3.3 V output, pull-ups on the breakout |
| SW1 | — | not on the MCU | wired to the S8 `bCal_in` input with a 1 kΩ / 100 nF RC network |

Update interval for both sensors: 60 s.

## Home Assistant

Exposed as native ESPHome entities: CO₂, temperature, relative humidity, pressure. API connection is
encrypted (noise protocol), OTA updates enabled, static IP with a fallback hotspot and captive portal
if the Wi-Fi connection fails.

## Ideas for v2

- Trigger the S8 background calibration from Home Assistant (`senseair` platform actions) in addition
  to the hardware button, and log the calibration events.
- Automatic baseline calibration window tuned to the room's nightly CO₂ minimum.
- Report Wi-Fi signal strength and device uptime as sensors for diagnostics.