Files
nanopsx_sen66/AGENTS.md
T
root 3dcfdedc18 fix(build): disable optional component update checks
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.
2026-11-07 13:57:12 +00:00

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.

  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:

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.