From b10b96f1ae2d583fb0ecd0dfff5e8ebb730e5ffa Mon Sep 17 00:00:00 2001 From: root Date: Wed, 4 Nov 2026 22:36:05 +0000 Subject: [PATCH] build: pin ESP-IDF 5.5.0 for 8 MB ESP32-C6 Configure the active SDK and defaults for the existing OTA layout. Add repository hardware development instructions and the verified application upload reference. --- AGENTS.md | 171 ++++++++++++++++++++++++++ firmware/platformio.ini | 5 +- firmware/sdkconfig.defaults | 3 + firmware/sdkconfig.esp32-c6-devkitc-1 | 18 +-- 4 files changed, 187 insertions(+), 10 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a38b80e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,171 @@ +# 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. diff --git a/firmware/platformio.ini b/firmware/platformio.ini index f0d20d1..83af333 100644 --- a/firmware/platformio.ini +++ b/firmware/platformio.ini @@ -1,7 +1,10 @@ [env:esp32-c6-devkitc-1] -platform = espressif32 +platform = espressif32@6.12.0 +platform_packages = + platformio/framework-espidf@3.50500.0 board = esp32-c6-devkitc-1 framework = espidf +board_upload.flash_size = 8MB monitor_speed = 115200 monitor_dtr = 0 monitor_rts = 0 diff --git a/firmware/sdkconfig.defaults b/firmware/sdkconfig.defaults index ec2266a..1804015 100644 --- a/firmware/sdkconfig.defaults +++ b/firmware/sdkconfig.defaults @@ -1,4 +1,7 @@ CONFIG_IDF_TARGET="esp32c6" +CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" CONFIG_LV_COLOR_16_SWAP=y CONFIG_LV_FONT_MONTSERRAT_12=y CONFIG_LV_FONT_MONTSERRAT_16=y diff --git a/firmware/sdkconfig.esp32-c6-devkitc-1 b/firmware/sdkconfig.esp32-c6-devkitc-1 index 81ed559..b67f65a 100644 --- a/firmware/sdkconfig.esp32-c6-devkitc-1 +++ b/firmware/sdkconfig.esp32-c6-devkitc-1 @@ -594,14 +594,14 @@ CONFIG_ESPTOOLPY_FLASHFREQ_80M=y # CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set CONFIG_ESPTOOLPY_FLASHFREQ="80m" # CONFIG_ESPTOOLPY_FLASHSIZE_1MB is not set -CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y +# CONFIG_ESPTOOLPY_FLASHSIZE_2MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_4MB is not set -# CONFIG_ESPTOOLPY_FLASHSIZE_8MB is not set +CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y # CONFIG_ESPTOOLPY_FLASHSIZE_16MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set # CONFIG_ESPTOOLPY_FLASHSIZE_128MB is not set -CONFIG_ESPTOOLPY_FLASHSIZE="2MB" +CONFIG_ESPTOOLPY_FLASHSIZE="8MB" # CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE is not set CONFIG_ESPTOOLPY_BEFORE_RESET=y # CONFIG_ESPTOOLPY_BEFORE_NORESET is not set @@ -615,13 +615,13 @@ CONFIG_ESPTOOLPY_MONITOR_BAUD=115200 # # Partition Table # -CONFIG_PARTITION_TABLE_SINGLE_APP=y +# CONFIG_PARTITION_TABLE_SINGLE_APP is not set # CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE is not set # CONFIG_PARTITION_TABLE_TWO_OTA is not set # CONFIG_PARTITION_TABLE_TWO_OTA_LARGE is not set -# CONFIG_PARTITION_TABLE_CUSTOM is not set +CONFIG_PARTITION_TABLE_CUSTOM=y CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" -CONFIG_PARTITION_TABLE_FILENAME="partitions_singleapp.csv" +CONFIG_PARTITION_TABLE_FILENAME="partitions.csv" CONFIG_PARTITION_TABLE_OFFSET=0x8000 CONFIG_PARTITION_TABLE_MD5=y # end of Partition Table @@ -2027,9 +2027,9 @@ CONFIG_PTHREAD_TASK_NAME_DEFAULT="pthread" # # MMU Config # -CONFIG_MMU_PAGE_SIZE_32KB=y -CONFIG_MMU_PAGE_MODE="32KB" -CONFIG_MMU_PAGE_SIZE=0x8000 +CONFIG_MMU_PAGE_SIZE_64KB=y +CONFIG_MMU_PAGE_MODE="64KB" +CONFIG_MMU_PAGE_SIZE=0x10000 # end of MMU Config #