Configure the active SDK and defaults for the existing OTA layout. Add repository hardware development instructions and the verified application upload reference.
7.8 KiB
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.
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
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.
- Projektkonfiguration in
platformio.iniprüfen. - PlatformIO-Environment für das Zielboard bestimmen.
- Firmware kompilieren.
- Build-Fehler beheben.
- Firmware-Image und Flash-Layout prüfen.
- Zielboard über das Gateway identifizieren.
Build aus dem Repository-Hauptverzeichnis:
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:
- Board-Seriennummer überprüfen.
- Chiptyp und Flash-Größe prüfen.
- Firmware-SHA-256 berechnen.
- Partitionstabelle und OTA-Auswahl prüfen.
- Schreibadresse aus dem tatsächlichen Build und der aktiven Partitionierung ableiten.
- Verifizieren, dass der gesamte Schreibbereich einschließlich betroffener Flash-Sektoren innerhalb der vorgesehenen Partition liegt.
- 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:
- Geschriebenen Bereich vollständig zurücklesen.
- Binärdaten bytegenau vergleichen.
- SHA-256 verifizieren.
- Bootverhalten kontrollieren.
- Seriellen Monitor mindestens 60 Sekunden auswerten.
- 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
eraseohne 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:8086lä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._tcpnoch_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.