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.
This commit is contained in:
@@ -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.
|
||||||
@@ -1,7 +1,10 @@
|
|||||||
[env:esp32-c6-devkitc-1]
|
[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
|
board = esp32-c6-devkitc-1
|
||||||
framework = espidf
|
framework = espidf
|
||||||
|
board_upload.flash_size = 8MB
|
||||||
monitor_speed = 115200
|
monitor_speed = 115200
|
||||||
monitor_dtr = 0
|
monitor_dtr = 0
|
||||||
monitor_rts = 0
|
monitor_rts = 0
|
||||||
|
|||||||
@@ -1,4 +1,7 @@
|
|||||||
CONFIG_IDF_TARGET="esp32c6"
|
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_COLOR_16_SWAP=y
|
||||||
CONFIG_LV_FONT_MONTSERRAT_12=y
|
CONFIG_LV_FONT_MONTSERRAT_12=y
|
||||||
CONFIG_LV_FONT_MONTSERRAT_16=y
|
CONFIG_LV_FONT_MONTSERRAT_16=y
|
||||||
|
|||||||
@@ -594,14 +594,14 @@ CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
|
|||||||
# CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set
|
# CONFIG_ESPTOOLPY_FLASHFREQ_20M is not set
|
||||||
CONFIG_ESPTOOLPY_FLASHFREQ="80m"
|
CONFIG_ESPTOOLPY_FLASHFREQ="80m"
|
||||||
# CONFIG_ESPTOOLPY_FLASHSIZE_1MB is not set
|
# 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_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_16MB is not set
|
||||||
# CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set
|
# CONFIG_ESPTOOLPY_FLASHSIZE_32MB is not set
|
||||||
# CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set
|
# CONFIG_ESPTOOLPY_FLASHSIZE_64MB is not set
|
||||||
# CONFIG_ESPTOOLPY_FLASHSIZE_128MB 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_HEADER_FLASHSIZE_UPDATE is not set
|
||||||
CONFIG_ESPTOOLPY_BEFORE_RESET=y
|
CONFIG_ESPTOOLPY_BEFORE_RESET=y
|
||||||
# CONFIG_ESPTOOLPY_BEFORE_NORESET is not set
|
# CONFIG_ESPTOOLPY_BEFORE_NORESET is not set
|
||||||
@@ -615,13 +615,13 @@ CONFIG_ESPTOOLPY_MONITOR_BAUD=115200
|
|||||||
#
|
#
|
||||||
# Partition Table
|
# 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_SINGLE_APP_LARGE is not set
|
||||||
# CONFIG_PARTITION_TABLE_TWO_OTA is not set
|
# CONFIG_PARTITION_TABLE_TWO_OTA is not set
|
||||||
# CONFIG_PARTITION_TABLE_TWO_OTA_LARGE 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_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_OFFSET=0x8000
|
||||||
CONFIG_PARTITION_TABLE_MD5=y
|
CONFIG_PARTITION_TABLE_MD5=y
|
||||||
# end of Partition Table
|
# end of Partition Table
|
||||||
@@ -2027,9 +2027,9 @@ CONFIG_PTHREAD_TASK_NAME_DEFAULT="pthread"
|
|||||||
#
|
#
|
||||||
# MMU Config
|
# MMU Config
|
||||||
#
|
#
|
||||||
CONFIG_MMU_PAGE_SIZE_32KB=y
|
CONFIG_MMU_PAGE_SIZE_64KB=y
|
||||||
CONFIG_MMU_PAGE_MODE="32KB"
|
CONFIG_MMU_PAGE_MODE="64KB"
|
||||||
CONFIG_MMU_PAGE_SIZE=0x8000
|
CONFIG_MMU_PAGE_SIZE=0x10000
|
||||||
# end of MMU Config
|
# end of MMU Config
|
||||||
|
|
||||||
#
|
#
|
||||||
|
|||||||
Reference in New Issue
Block a user