Add ESPHome firmware templates, GND pour notes, v2 lessons learned

- firmware/: config + secrets templates committed, flashed config git-ignored
- README: document the GND pour on F.Cu/B.Cu and the module keep-out rule areas
- README: correct the calibration button wiring (S8 bCal_in, not an MCU GPIO)
- README: v2 list - dedicated 5 V power input, decoupling, mounting holes,
  I2C pull-ups, schematic annotation, RoHS finish, project name, antenna keep-out

firmware/README.md

@@ -1,31 +1,59 @@
 # Firmware
 
-ESPHome configuration for the ESP32-C3 CO₂ & environment sensor board.
+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 + BLE) |
-| Framework | ESPHome (`esp32` platform, `framework: esp-idf` or `arduino`) |
-| Board | this project's board, flashed via the module's UART/USB boot pins |
+| 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 | Notes |
-|---|---|---|
-| Sensirion S8 (NDIR CO₂) | UART, 9600 baud 8N1 | needs 5 V supply, ~30 s preheat; `bCal_in` starts a manual background calibration |
-| BME280 (T / RH / P) | I²C, address `0x76` (some breakouts `0x77`) | powered from the module's 3.3 V output; pull-ups come from the breakout |
-| SW1 | GPIO, active low with 1 kΩ / 100 nF RC debounce | calibration button |
+| 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 |
 
-## Add here
-
-- `esp-sensair.yaml` — the ESPHome configuration actually flashed to the board
-- `secrets.yaml` — **do not commit** (Wi-Fi credentials, Home Assistant token); keep
-  `secrets.yaml.example` with placeholders
-- flashing notes: `esptool` / `esphome flash`, boot-mode entry on the module
+Update interval for both sensors: 60 s.
 
 ## Home Assistant
 
-The device is exposed as native ESPHome entities: `co2`, `temperature`, `relative_humidity`,
-`pressure`, plus the calibration button as a sensor event.
+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.