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
2026-10-19 22:33:36 +02:00
1 parent 7cf9f71a15
commit ac5a556c11
@@ -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.
@@ -0,0 +1,72 @@
+# ESPHome configuration for the ESP32-C3 CO2 & environment sensor board.
+#
+# This is the SHARED TEMPLATE. Copy it to esp-sensair.yaml (git-ignored) and keep
+# all credentials in secrets.yaml (git-ignored). Never commit real keys.
+#
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2026 Hannes Gehrmann
+
+esphome:
+  name: esp32c3-bme280
+  friendly_name: esp32c3-bme280
+
+esp32:
+  board: esp32-c3-devkitm-1
+  framework:
+    type: esp-idf
+
+logger:
+
+api:
+  encryption:
+    key: !secret api_encryption_key
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: true
+
+  manual_ip:
+    static_ip: !secret static_ip
+    gateway: !secret gateway
+    subnet: !secret subnet
+    dns1: !secret dns1
+
+  # Fallback hotspot if the Wi-Fi connection fails
+  ap:
+    ssid: "Esp32C3-Bme280 Fallback Hotspot"
+    password: !secret ap_password
+
+captive_portal:
+
+# BME280 on I2C - SDA on GPIO7, SCL on GPIO8 (board nets /SDA, /SCL)
+i2c:
+  sda: GPIO7
+  scl: GPIO8
+  scan: true
+
+# Sensirion S8 on UART - 9600 baud, 8N1 (board nets /TX, /RX)
+uart:
+  tx_pin: GPIO21   # ESP32-C3 TX -> S8 RX
+  rx_pin: GPIO20   # ESP32-C3 RX <- S8 TX
+  baud_rate: 9600
+
+sensor:
+  - platform: bme280_i2c
+    address: 0x76
+    temperature:
+      name: "BME280 Temperature"
+    pressure:
+      name: "BME280 Pressure"
+    humidity:
+      name: "BME280 Humidity"
+    update_interval: 60s
+
+  - platform: senseair
+    co2:
+      name: "Senseair S8 CO2"
+    update_interval: 60s
@@ -0,0 +1,14 @@
+# Copy to firmware/secrets.yaml (git-ignored) and fill in your own values.
+#
+# Generate a Home Assistant API encryption key with:
+#   python3 -c "import base64,os; print(base64.b64encode(os.urandom(32)).decode())"
+
+wifi_ssid: YourNetworkSSID
+wifi_password: YourNetworkPassword
+api_encryption_key: REPLACE_WITH_GENERATED_32_BYTE_BASE64_KEY
+ota_password: REPLACE_WITH_AN_OTA_PASSWORD
+ap_password: REPLACE_WITH_A_FALLBACK_HOTSPOT_PASSWORD
+static_ip: 192.168.1.50
+gateway: 192.168.1.1
+subnet: 255.255.255.0
+dns1: 192.168.1.1