# ESP32 Hardware Development Workflow ## Entwicklungsumgebung Dieses Projekt wird mit Codex in einem Docker-Container auf einem VPS entwickelt. - Versionsverwaltung: Gitea - Build-System: PlatformIO - Framework: ESP-IDF 5.5.0 (aktueller getesteter Build) - PlatformIO-Plattform: `espressif32@6.12.0` - SDK-Paket: `platformio/framework-espidf@3.50500.0` - Hardwarezugriff: WireGuard + eingeschränktes SSH-Gateway - SSH-Alias im Codex-Container: `esp32` - Gateway-Rechner: Debian 13 Der ESP32 ist physisch am Debian-Rechner angeschlossen. Codex führt sämtliche Builds auf dem VPS aus und verwendet ausschließlich das SSH-Gateway zur Hardwarekommunikation. ## Board-Erkennung Vor jeder Hardwareoperation das Zielboard eindeutig bestimmen. ```bash ssh esp32 list ``` Bekanntes Testboard: - Chip: ESP32-C6FH8 - USB-Seriennummer: `CC:BA:97:F2:52:80` - Flash: 8 MB - Revision: v0.2 Weitere bekannte Hardware: - ESP32-C6FH8, 8 MB, Revision v0.2, USB-Seriennummer `CC:BA:97:F2:5F:7C`; SEN66 und Display-Profil am 09.11.2026 geprüft, aktuelles OTA-Layout statt früherer 1-MiB-Factory-Partition. - ESP32-C6FH4 - USB-Seriennummer: `9C:9E:6E:7B:5D:C0` - Flash: 4 MB Niemals anhand von `/dev/ttyACM0` oder `/dev/ttyUSB0` allein ein Board auswählen, da sich diese Gerätenamen ändern können. ## Gateway-Befehle ```bash ssh esp32 list ssh esp32 "info BOARD_ID" ssh esp32 "flash-id BOARD_ID" ssh esp32 "monitor BOARD_ID 30" ssh esp32 "send BOARD_ID HEXDATEN" ssh esp32 "read BOARD_ID OFFSET GROESSE" ssh esp32 "write BOARD_ID OFFSET GROESSE SHA256" ssh esp32 "erase BOARD_ID CONFIRM" ``` Alle boardbezogenen Hardwareoperationen müssen eine explizite Boardkennung verwenden. `list` dient ausschließlich der Erkennung und benötigt keine Boardkennung. Die `read`-Funktion liefert rohe Binärdaten über stdout. Die `write`-Funktion erhält die Firmwaredatei über stdin. Die erwartete Dateigröße und SHA-256-Prüfsumme werden vom Gateway geprüft. ## Build-Workflow Das PlatformIO-Projekt liegt unter `firmware/`. Das aktuelle Environment `esp32-c6-devkitc-1` ist für ESP32-C6 mit **8 MB Flash** konfiguriert. Diesen Build nicht auf das bekannte 4-MB-Board übertragen. Die aktive SDK-Konfiguration ist `firmware/sdkconfig.esp32-c6-devkitc-1`; Defaults stehen in `firmware/sdkconfig.defaults`, die Partitionstabelle in `firmware/partitions.csv`. Sensor und Peripherieprofil werden zentral in `firmware/components/hardware_config/hardware_config.h` gewählt. Unterstützte Sensoren: SEN54 und SEN66; vorhandene Profile: ESP32-C6 mit Display (Touch auf Hardware-I²C GPIO18/19) und ESP32-C6 ohne Display (Hardware-I²C GPIO7/8), jeweils 8 MB. SEN54 nutzt den Hardware-Bus des Profils. SEN66 bleibt immer auf GPIO7/8 und verwendet beim Display-Profil einen separaten Software-I²C-Bus; ohne Display verwendet er den Hardware-Controller. Die aktuelle Standardauswahl ist SEN66 mit Display. Die Software-I²C-Implementierung hat ACK/NACK-, Clock-Stretching- und Timeout-Tests; keine weiteren Sensorgeräte ohne Prüfung auf diesem Bus hinzufügen. Auswahl und Verdrahtung vor jedem Build prüfen; nicht vom angeschlossenen Port oder einer früheren Auswahl ableiten. Die Auswahl ersetzt keine Prüfung von PlatformIO-Chip, Flash-Größe und Partitionstabelle. Anleitung und Tests: `firmware/HARDWARE.md`. Der SEN66 verwendet den gepinnten offiziellen Sensirion-Treiber; Herkunft und Lizenz sind in `firmware/components/sen5x/SENSIRION-UPSTREAM.md` dokumentiert. Die gemeinsame Sensoranwendung heißt `air_sensor_app`; SEN66 ergänzt das Influx-Feld `co2`, SEN54 darf keine künstlichen CO₂-Werte erzeugen. Die Displayansicht bleibt auf Benutzerwunsch exakt die bisherige SEN54-Ansicht mit Schriftzug, PM, Temperatur, Feuchte, VOC und Statussymbolen. NOx und CO₂ vorerst nur für InfluxDB verarbeiten; keine zusätzlichen Displayfelder ohne neuen Auftrag hinzufügen. 1. Projektkonfiguration in `platformio.ini` prüfen. 2. PlatformIO-Environment für das Zielboard bestimmen. 3. Firmware kompilieren. 4. Build-Fehler beheben. 5. Firmware-Image und Flash-Layout prüfen. 6. Zielboard über das Gateway identifizieren. Build aus dem Repository-Hauptverzeichnis: ```bash pio run -d firmware -e esp32-c6-devkitc-1 -j 2 ``` `firmware/CMakeLists.txt` setzt `IDF_COMPONENT_CHECK_NEW_VERSION=0` vor dem Laden des ESP-IDF-Buildsystems. Dadurch bleibt die optionale Suche nach neueren Komponenten-Versionen auch bei Builds über VS Code deaktiviert; ein manuelles `export` ist nicht erforderlich. Die reguläre Abhängigkeitsauflösung und die Verwendung von `dependencies.lock` bleiben aktiv. Hintergrund ist ein bestätigter Build-Abbruch durch fehlende LVGL-Kconfig-Optionen bei eingeschalteter Update-Suche auf einem weiteren Entwicklungsrechner. Abhängigkeitsupdates getrennt und gezielt durchführen, nicht diese Einstellung ungeprüft entfernen. Die festgelegten Plattform-/SDK-Versionen erhalten. Der frühere Build mit ESP-IDF 6.1.0 scheiterte, weil `REQUIRES driver` dort `esp_driver_ledc` nicht mehr automatisch einbindet. Ein SDK-Upgrade ist eine gesonderte Migration; Versionen nicht ungeprüft anheben. Die aktuellen OTA-Partitionen reichen bis `0x740000` und passen in 8 MB. Image-Dateinamen und Flash-Adressen aus den tatsächlichen PlatformIO-Artefakten, `flasher_args.json` und gegebenenfalls `envdump` ermitteln. CMake kann logische Dateinamen angeben, während PlatformIO `firmware.bin`, `bootloader.bin` und `partitions.bin` erzeugt. ## Flash-Workflow Vor jedem Upload: 1. Board-Seriennummer überprüfen. 2. Chiptyp und Flash-Größe prüfen. 3. Firmware-SHA-256 berechnen. 4. Partitionstabelle und OTA-Auswahl prüfen. 5. Schreibadresse aus dem tatsächlichen Build und der aktiven Partitionierung ableiten. 6. Verifizieren, dass der gesamte Schreibbereich einschließlich betroffener Flash-Sektoren innerhalb der vorgesehenen Partition liegt. 7. Sicherstellen, dass ein gültiges Backup verfügbar ist. Nur notwendige Flash-Bereiche schreiben. Bootloader, Partitionstabelle, NVS und OTA-Auswahldaten nicht ohne technische Notwendigkeit überschreiben. PHY-Daten ebenfalls erhalten, sofern der konkrete Auftrag keine begründete Änderung vorsieht. Nach dem Flashen: 1. Geschriebenen Bereich vollständig zurücklesen. 2. Binärdaten bytegenau vergleichen. 3. SHA-256 verifizieren. 4. Bootverhalten kontrollieren. 5. Seriellen Monitor mindestens 60 Sekunden auswerten. 6. WLAN, Netzwerkdienste und Hardwareperipherie prüfen. Ein erfolgreicher Flash-Vorgang gilt erst nach bestandener Rückleseverifikation als technisch bestätigt. Die Anwendungsfunktion muss separat geprüft werden. ## Sicherheitsregeln - Keine normale SSH-Shell auf dem Debian-Rechner verwenden. - Keine Änderungen an WireGuard, SSH-Konfiguration oder Gateway vornehmen, außer wenn ausdrücklich beauftragt. - Kein vollständiges `erase` ohne ausdrückliche Freigabe. - Vor destruktiven Operationen Zielboard und Flash-Bereich erneut prüfen. - Operationen, die sämtliche gespeicherten Daten oder unbekannte persistente Bereiche unwiederbringlich zerstören können, benötigen eine ausdrückliche Benutzerfreigabe. - Keine automatischen wiederholten Flash-Versuche bei ungeklärten Fehlern. - Keine privaten SSH-Schlüssel oder Zugangsdaten ausgeben oder committen. - Private SSH-Schlüssel niemals in das Repository aufnehmen oder ohne gesonderten ausdrücklichen Sicherungsauftrag kopieren. - Keine Firmware auf ein anderes als das ausgewählte Board schreiben. - Hardwaretests und Schreiboperationen nicht parallel auf demselben seriellen Gerät ausführen. - Keine nicht dokumentierten Gateway-Befehle ausprobieren und keine Sicherheitsmechanismen umgehen. ## Erfolgreich getestetes Deployment Am 04.11.2026 wurde ein Firmware-Upload auf das Board `CC:BA:97:F2:52:80` erfolgreich durchgeführt. - Chip: ESP32-C6FH8 - Flash: 8 MB - Build-Environment: `esp32-c6-devkitc-1` - Framework: ESP-IDF 5.5.0 - Anwendungspartition: `ota_0` - Schreibadresse: `0x020000` - Firmwaregröße: 1.741.040 Bytes - Schreibvorgänge: 1 - Rückleseverifikation: erfolgreich - SHA-256: `ae6d2892c16e3ac7ced681ca4112a4dc8b5168af4a7b2c9d029db9c095be6fdd` - Boot: erfolgreich - WLAN: erfolgreich - Bootloader, Partitionstabelle, OTA-Auswahl und PHY-Daten: beim Upload unverändert - Serieller Monitor: 60 Sekunden, keine erkannten Panics oder Neustartschleifen Dieser Upload ist ein dokumentierter Referenzfall. Die genannten Adressen und Hashwerte dürfen nicht ungeprüft für zukünftige Firmware-Versionen wiederverwendet werden. ## Getestete SEN66-Migration (09.11.2026) - Ziel: `CC:BA:97:F2:5F:7C`, ESP32-C6FH8, 8 MB; Sensor SEN66 an SDA GPIO7/SCL GPIO8, mit Display und Touch auf separatem Hardware-I²C-Bus GPIO18/19. - Benutzer hat die Migration und neue Partitionierung ausdrücklich freigegeben. Nach vollständigem geprüftem Backup wurde ohne vollständiges Löschen auf das bestehende nanoPSX-8-MB-Layout mit zwei OTA-Partitionen migriert. Vorhandener gültiger IDF-5.5-Bootloader blieb unverändert. - Vier Schreibvorgänge, jeweils vollständiges bytegenaues Rücklesen und SHA256 erfolgreich: Anwendung `0x20000` (1.736.144 Bytes, SHA256 `59ee4120dbcdf2edda17bcf57c1f7a81d18b197e8d4413f0a28e283a7871eba9`), Inhalt der bisherigen PHY-Partition nach `0x11000` kopiert (4096 Bytes), OTA-Auswahl bei `0xF000` initialisiert (8192 Bytes), neue Partitionstabelle bei `0x8000` zuletzt aktiviert (3072 Bytes). - Abschließend vollständige 8 MB ausgelesen: keine Änderungen außerhalb geplanter Sektoren und regulärer NVS-/OTA-Laufzeitbereiche; Bootloader und kopierter PHY-Partitionsinhalt bytegenau erhalten. OTA-Auswahl gültig, Sequenz 1, Zustand 2, Auswahl `ota_0`. - NVS war vor Aktivierung bytegenau erhalten. Nach Start waren 2032 Rohbytes verändert; der offizielle SDK-NVS-Parser ordnet die logischen Änderungen ausschließlich `phy:cal_data` (Radio-Kalibrierungsblob) zu. Alle anderen vorhandenen logischen Einträge behalten identische Inhaltsfingerprints. Kein NVS-Reset durchgeführt. - Alle vier Sensor-/Board-Builds und native Hersteller-/Software-I²C-Tests erfolgreich. 60 Sekunden Monitor ohne erkannte Panic oder Sensor-I²C-Fehler; SEN66 erkannt und Messung gestartet, u.a. CO₂ 1149 ppm und PM2.5 7,2 µg/m³. Display initialisiert, kein Touch-Ausfall gemeldet. Eine sichtbare Prüfung des physischen Displays ist über das Gateway nicht möglich. - Setup-AP `nanoPSX`, Portal `http://192.168.4.1`; auf diesem Board wurde im Test noch keine STA-IP oder erfolgreiche Influx-Übertragung beobachtet. WLAN sowie Organisation/Bucket gegebenenfalls im Portal einrichten. SD-Karten-Timeout besteht weiter. - Diese Einzelfreigabe ist abgeschlossen und gilt nicht automatisch für erneute Migrationen oder andere Boards. Künftige App-Updates nach erneuter Layout-/OTA-Prüfung planen; keine erneute Migration anhand dieses historischen Eintrags ausführen. Nachfolgende Benutzerkorrektur am selben Tag: Die zusätzliche CO₂-Anzeige wurde wieder entfernt. Die EEZ-Displaydateien entsprechen bytegenau dem ursprünglichen Git-Stand; keine NOx-/CO₂-Widgets ergänzen, solange kein neuer Auftrag vorliegt. Die entsprechende SEN66-Anwendung wurde ausschließlich bei `0x20000` aktualisiert (1.735.776 Bytes, SHA256 `ed9cec4854c5c19eaaecf69c4a1f5c9740014caf8a2bcd88976bb0bbe7fba4dd`) und vollständig bytegenau/SHA256-verifiziert. Bootloader, Partitionstabelle, OTA-Auswahl und PHY-Partitionsinhalt unverändert. Anwendungseinstellungen in NVS behalten ihre Inhaltsfingerprints; normale Radio-Kalibrierungsänderungen wurden getrennt erfasst. Der anschließende 60-Sekunden-Monitor bestätigte laufende SEN66-Messungen und **55 erfolgreiche Influx-Schreibantworten mit HTTP 204**, keine Schreib-/Sensorfehler und keine Panic. NOx und CO₂ bleiben für InfluxDB erhalten. Der vorherige Setup-AP-Hinweis beschreibt den Zustand vor der inzwischen vom Benutzer eingerichteten WLAN-Verbindung. ## Bekannte Anwendungsprobleme Beim letzten Hardwaretest wurden festgestellt: - InfluxDB-Verbindung zu `10.8.0.4:8086` läuft in HTTP-Timeouts. Genauer: TCP-Verbindungsaufbau mit Timeout, keine HTTP-Antwort; `tls=0`, daher kein nachgewiesener TLS-Zertifikatsfehler. - SD-Karteninitialisierung meldet Timeout. - Display-Initialisierung meldet eine Warnung. - WLAN funktioniert, nutzt jedoch 802.11n statt eines höheren WLAN-Modus. - mDNS findet weder `_influxdb2._tcp` noch `_http._tcp`. Diese Anwendungsprobleme sind unabhängig vom erfolgreich getesteten Flash-Workflow zu untersuchen. Aktualisierung vom 07.11.2026: Für den NUC-WLAN-Access-Point ist die InfluxDB-Adresse `http://192.168.50.1:8086`. Die Einrichtung unter `linux-app/` kündigt `_influxdb2._tcp` über Avahi an. Den vorhandenen Avahi-Hostnamen verwenden; ein zusätzlicher statischer Alias auf dieselbe lokale IP verursachte in dieser Einrichtung `Local name collision`. Der Benutzer bestätigte die Auflösung auf dem WLAN und nach erneuter Konfiguration die funktionierende SEN54-Übertragung zu InfluxDB (Organisation `Home`, Bucket `nanoPSX`). Serielle Tests bestätigten zuvor die HTTP-Erreichbarkeit, aber Authentifizierungsfehler; die abschließende erfolgreiche Datenübertragung wurde vom Benutzer bestätigt. SD-Karten-Timeout und WLAN-Rückfall auf 11N wurden durch die Netzwerkeinrichtung nicht behoben. Tokens weiterhin ausschließlich lokal verwalten und nicht committen. Der Upload selbst schreibt nicht in NVS. Die Anwendung kann NVS aber zur Laufzeit verändern und löscht NVS bei `ESP_ERR_NVS_NO_FREE_PAGES` oder `ESP_ERR_NVS_NEW_VERSION_FOUND` während der Initialisierung (`firmware/src/main.c`, `firmware/components/storage/src/storage.c`). Keine absolute Unveränderlichkeit von NVS nach Anwendungsstart zusichern. Beim Referenztest änderten sich WLAN-Journal-Einträge für `opmode`; die gültigen Einstellungswerte blieben im Vor-/Nachvergleich gleich. ## Dokumentation Nach jedem erfolgreichen Hardwaretest dokumentieren: - Zielboard und USB-Seriennummer - Build-Environment - Firmware-Hash - Flash-Adressen - Prüfergebnisse - Boot- und Laufzeitlogs - Erforderliche nächste Schritte Temporäre Backups, Firmware-Binärdateien, SSH-Schlüssel und Logdateien dürfen nicht versehentlich in Git eingecheckt werden. Backups und Logs können Zugangsdaten enthalten und sind entsprechend geschützt außerhalb des Repositorys aufzubewahren. Maschinenspezifische SSH-Schlüsselpfade, Host-Fingerprints, Docker-Mounts und absolute Backup-/Logpfade werden in lokalen Ergänzungen außerhalb des Repositorys gepflegt. Keine privaten Zugangsdaten oder lokalen Binärartefakte in diese Datei übernehmen.