Files
nanopsx_sen66/AGENTS.md
T
root b10b96f1ae 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.
2026-11-04 22:36:05 +00:00

172 lines
7.8 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
```
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.