Files
nanopsx_sen66/AGENTS.md
T
root 69bb47dda1 feat(firmware): support configurable SEN54 and SEN66 boards
Add the pinned Sensirion SEN66 driver, central sensor and board profiles, and a separate GPIO I2C bus for SEN66 with display. Preserve the original display layout and keep NOx and CO2 in InfluxDB. Include protocol tests, hardware workflow documentation and verified deployment results without credentials.
2026-11-09 21:44:04 +00:00

14 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-C6FH8, 8 MB, Revision v0.2, USB-Seriennummer CC:BA:97:F2:5F:7C; SEN66 und Display-Profil am 09.11.2026 geprüft, aktuelles OTA-Layout statt früherer 1-MiB-Factory-Partition.
  • 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.

Sensor und Peripherieprofil werden zentral in firmware/components/hardware_config/hardware_config.h gewählt. Unterstützte Sensoren: SEN54 und SEN66; vorhandene Profile: ESP32-C6 mit Display (Touch auf Hardware-I²C GPIO18/19) und ESP32-C6 ohne Display (Hardware-I²C GPIO7/8), jeweils 8 MB. SEN54 nutzt den Hardware-Bus des Profils. SEN66 bleibt immer auf GPIO7/8 und verwendet beim Display-Profil einen separaten Software-I²C-Bus; ohne Display verwendet er den Hardware-Controller. Die aktuelle Standardauswahl ist SEN66 mit Display. Die Software-I²C-Implementierung hat ACK/NACK-, Clock-Stretching- und Timeout-Tests; keine weiteren Sensorgeräte ohne Prüfung auf diesem Bus hinzufügen. Auswahl und Verdrahtung vor jedem Build prüfen; nicht vom angeschlossenen Port oder einer früheren Auswahl ableiten. Die Auswahl ersetzt keine Prüfung von PlatformIO-Chip, Flash-Größe und Partitionstabelle. Anleitung und Tests: firmware/HARDWARE.md. Der SEN66 verwendet den gepinnten offiziellen Sensirion-Treiber; Herkunft und Lizenz sind in firmware/components/sen5x/SENSIRION-UPSTREAM.md dokumentiert. Die gemeinsame Sensoranwendung heißt air_sensor_app; SEN66 ergänzt das Influx-Feld co2, SEN54 darf keine künstlichen CO₂-Werte erzeugen. Die Displayansicht bleibt auf Benutzerwunsch exakt die bisherige SEN54-Ansicht mit Schriftzug, PM, Temperatur, Feuchte, VOC und Statussymbolen. NOx und CO₂ vorerst nur für InfluxDB verarbeiten; keine zusätzlichen Displayfelder ohne neuen Auftrag hinzufügen.

  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.

Getestete SEN66-Migration (09.11.2026)

  • Ziel: CC:BA:97:F2:5F:7C, ESP32-C6FH8, 8 MB; Sensor SEN66 an SDA GPIO7/SCL GPIO8, mit Display und Touch auf separatem Hardware-I²C-Bus GPIO18/19.
  • Benutzer hat die Migration und neue Partitionierung ausdrücklich freigegeben. Nach vollständigem geprüftem Backup wurde ohne vollständiges Löschen auf das bestehende nanoPSX-8-MB-Layout mit zwei OTA-Partitionen migriert. Vorhandener gültiger IDF-5.5-Bootloader blieb unverändert.
  • Vier Schreibvorgänge, jeweils vollständiges bytegenaues Rücklesen und SHA256 erfolgreich: Anwendung 0x20000 (1.736.144 Bytes, SHA256 59ee4120dbcdf2edda17bcf57c1f7a81d18b197e8d4413f0a28e283a7871eba9), Inhalt der bisherigen PHY-Partition nach 0x11000 kopiert (4096 Bytes), OTA-Auswahl bei 0xF000 initialisiert (8192 Bytes), neue Partitionstabelle bei 0x8000 zuletzt aktiviert (3072 Bytes).
  • Abschließend vollständige 8 MB ausgelesen: keine Änderungen außerhalb geplanter Sektoren und regulärer NVS-/OTA-Laufzeitbereiche; Bootloader und kopierter PHY-Partitionsinhalt bytegenau erhalten. OTA-Auswahl gültig, Sequenz 1, Zustand 2, Auswahl ota_0.
  • NVS war vor Aktivierung bytegenau erhalten. Nach Start waren 2032 Rohbytes verändert; der offizielle SDK-NVS-Parser ordnet die logischen Änderungen ausschließlich phy:cal_data (Radio-Kalibrierungsblob) zu. Alle anderen vorhandenen logischen Einträge behalten identische Inhaltsfingerprints. Kein NVS-Reset durchgeführt.
  • Alle vier Sensor-/Board-Builds und native Hersteller-/Software-I²C-Tests erfolgreich. 60 Sekunden Monitor ohne erkannte Panic oder Sensor-I²C-Fehler; SEN66 erkannt und Messung gestartet, u.a. CO₂ 1149 ppm und PM2.5 7,2 µg/m³. Display initialisiert, kein Touch-Ausfall gemeldet. Eine sichtbare Prüfung des physischen Displays ist über das Gateway nicht möglich.
  • Setup-AP nanoPSX, Portal http://192.168.4.1; auf diesem Board wurde im Test noch keine STA-IP oder erfolgreiche Influx-Übertragung beobachtet. WLAN sowie Organisation/Bucket gegebenenfalls im Portal einrichten. SD-Karten-Timeout besteht weiter.
  • Diese Einzelfreigabe ist abgeschlossen und gilt nicht automatisch für erneute Migrationen oder andere Boards. Künftige App-Updates nach erneuter Layout-/OTA-Prüfung planen; keine erneute Migration anhand dieses historischen Eintrags ausführen.

Nachfolgende Benutzerkorrektur am selben Tag: Die zusätzliche CO₂-Anzeige wurde wieder entfernt. Die EEZ-Displaydateien entsprechen bytegenau dem ursprünglichen Git-Stand; keine NOx-/CO₂-Widgets ergänzen, solange kein neuer Auftrag vorliegt. Die entsprechende SEN66-Anwendung wurde ausschließlich bei 0x20000 aktualisiert (1.735.776 Bytes, SHA256 ed9cec4854c5c19eaaecf69c4a1f5c9740014caf8a2bcd88976bb0bbe7fba4dd) und vollständig bytegenau/SHA256-verifiziert. Bootloader, Partitionstabelle, OTA-Auswahl und PHY-Partitionsinhalt unverändert. Anwendungseinstellungen in NVS behalten ihre Inhaltsfingerprints; normale Radio-Kalibrierungsänderungen wurden getrennt erfasst. Der anschließende 60-Sekunden-Monitor bestätigte laufende SEN66-Messungen und 55 erfolgreiche Influx-Schreibantworten mit HTTP 204, keine Schreib-/Sensorfehler und keine Panic. NOx und CO₂ bleiben für InfluxDB erhalten. Der vorherige Setup-AP-Hinweis beschreibt den Zustand vor der inzwischen vom Benutzer eingerichteten WLAN-Verbindung.

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.

Aktualisierung vom 07.11.2026: Für den NUC-WLAN-Access-Point ist die InfluxDB-Adresse http://192.168.50.1:8086. Die Einrichtung unter linux-app/ kündigt _influxdb2._tcp über Avahi an. Den vorhandenen Avahi-Hostnamen verwenden; ein zusätzlicher statischer Alias auf dieselbe lokale IP verursachte in dieser Einrichtung Local name collision. Der Benutzer bestätigte die Auflösung auf dem WLAN und nach erneuter Konfiguration die funktionierende SEN54-Übertragung zu InfluxDB (Organisation Home, Bucket nanoPSX). Serielle Tests bestätigten zuvor die HTTP-Erreichbarkeit, aber Authentifizierungsfehler; die abschließende erfolgreiche Datenübertragung wurde vom Benutzer bestätigt. SD-Karten-Timeout und WLAN-Rückfall auf 11N wurden durch die Netzwerkeinrichtung nicht behoben. Tokens weiterhin ausschließlich lokal verwalten und nicht committen.

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.