Set IDF_COMPONENT_CHECK_NEW_VERSION before loading ESP-IDF so PlatformIO and VS Code builds do not require a shell export. Document the LVGL Kconfig workaround while preserving the dependency lockfile.
8.5 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
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:
- 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.