# 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-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`. 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 ``` 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. ## 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. 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.