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.
174 lines
8.5 KiB
Markdown
174 lines
8.5 KiB
Markdown
# 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
|
|
```
|
|
|
|
`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.
|
|
|
|
## 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.
|