Files
nanopsx_sen66/firmware/HARDWARE.md
T

13 KiB
Raw Blame History

Sensor und Board auswählen

Die zentrale Konfiguration steht in components/hardware_config/hardware_config.h. Es handelt sich um eine Build-Konfiguration: Nach Änderungen neu kompilieren und die passende Firmware übertragen. Das Webportal verwaltet weiterhin WLAN und InfluxDB; es ändert den Sensortreiber nicht zur Laufzeit.

Die zwei Auswahleinstellungen

Aktueller Standard: SEN66 mit Display, Sensor weiterhin an GPIO7/8:

#define NANOPSX_SENSOR NANOPSX_SENSOR_SEN66
#define NANOPSX_BOARD NANOPSX_BOARD_C6_DISPLAY_8MB

Für einen SEN66 an GPIO7/8 ohne Display:

#define NANOPSX_SENSOR NANOPSX_SENSOR_SEN66
#define NANOPSX_BOARD NANOPSX_BOARD_C6_DEVKIT_8MB

Für den bisher getesteten SEN54 am nanoPSX-Display-Board:

#define NANOPSX_SENSOR NANOPSX_SENSOR_SEN54
#define NANOPSX_BOARD NANOPSX_BOARD_C6_DISPLAY_8MB

Diese beiden Zeilen im jeweiligen #ifndef-Block der Konfigurationsdatei ändern. Sensor und Board sind unabhängig wählbar: Auch ein SEN54 am Devkit oder ein SEN66 am gemeinsamen Display-Bus sind möglich, wenn die Verdrahtung dem ausgewählten Profil entspricht.

Boardprofil Hardware-I²C SDA Hardware-I²C SCL I²C-Port Peripherie
NANOPSX_BOARD_C6_DISPLAY_8MB GPIO18 GPIO19 0 Bestehendes LCD, Touch, SD, Batterie und Taste
NANOPSX_BOARD_C6_DEVKIT_8MB GPIO7 GPIO8 0 Sensor, WLAN, Konfigurationsportal, InfluxDB; keine Display-/SD-/Tasteninitialisierung
Sensor I²C-Adresse Takt Messgrößen
SEN54 0x69 400 kHz PM1/2.5/4/10, Temperatur, Feuchte, VOC
SEN66 0x6b 100 kHz PM1/2.5/4/10, Temperatur, Feuchte, VOC, NOx, CO₂

SEN54 verwendet die Hardware-I²C-Pins aus dem Boardprofil. SEN66 bleibt unabhängig vom Profil an SDA GPIO7 / SCL GPIO8. Beim Display-Profil benutzt der Touchscreen den Hardware-I²C-Controller auf GPIO18/19; der SEN66 erhält einen separaten Software-I²C-Bus auf GPIO7/8. Damit muss der Sensor beim Wechsel zum Display-Profil nicht umgesteckt werden. Ohne Display wird für GPIO7/8 der Hardware-Controller verwendet.

Der Software-Bus nutzt ausschließlich Open-Drain-Ausgänge mit internen Pull-ups, ACK/NACK-Prüfung, Clock-Stretching mit begrenztem Timeout und einen Mutex. Der Solltakt beträgt 100 kHz; GPIO-Aufrufe und Interrupts können den tatsächlichen Takt verringern. Die elektrische Verdrahtung und externe Pull-ups entsprechend dem Sensordatenblatt prüfen. GPIO-Nummern sind keine Steckkontakt-Nummern.

Ein fehlender Touchcontroller wird nach Reset per ACK-Probe erkannt. Die Firmware protokolliert dies und aktiviert den LVGL-Toucheingang nur bei vorhandenem Controller. LCD, Sensor und Netzwerk können ohne Touch weiterlaufen.

Kompilieren

Aus dem Repository-Hauptverzeichnis:

pio run -d firmware -e esp32-c6-devkitc-1 -j 2

Die bekannten Profile setzen ESP32-C6 und 8 MB Flash voraus. PlatformIO bleibt auf espressif32@6.12.0 und ESP-IDF 5.5.0 festgelegt. Der Build bricht ab, wenn ein unbekanntes Profil, ein anderer Chip oder eine SDK-Konfiguration für eine andere Flash-Größe ausgewählt wurde. Ein Profil ersetzt keine Boarderkennung.

Für weitere Boards einen neuen expliziten Profilzweig mit eigener Pinbelegung und Peripherieauswahl hinzufügen. Bei anderen ESP32-Chips oder Flash-Größen zusätzlich ein passendes PlatformIO-Environment, SDK-Defaults und eine passende Partitionstabelle einrichten und prüfen. Die aktuelle 8-MB-Partitionstabelle nicht auf das bekannte 4-MB-Board übertragen. Die zwei vorhandenen Profile sind keine pauschale Freigabe für andere ESP32-Modelle.

Treiber und Daten

Der SEN66 verwendet den offiziellen Sensirion-C-Treiber. Der genaue Quellstand, die Lizenz und die unverändert übernommenen Dateien stehen in SENSIRION-UPSTREAM.md. Der Verzeichnisname sen5x bleibt aus Kompatibilität bestehen; darin liegen beide Treiber und die gemeinsame Anwendung air_sensor_app.c.

Die Sensoren teilen sich den ESP-IDF-HAL und die Verarbeitung für Anzeige und InfluxDB. Die Messreihe bleibt air, bestehende Felder bleiben pm1, pm2_5, pm4, pm10, temp, rh, voc, nox. SEN66 ergänzt co2 in ppm. Nicht verfügbare Messgrößen und die vom Sensor definierten ungültigen Rohwerte werden ausgelassen, nicht als Null übertragen. Insbesondere erzeugt SEN54 keine künstlichen CO₂-Werte. Die Displayoberfläche entspricht der bisherigen SEN54-Ansicht einschließlich Schriftzug und Statussymbolen. NOx und CO₂ werden vorerst nicht auf dem Display angezeigt. Diese Werte bleiben für InfluxDB verfügbar; CO₂ erscheint außerdem in den seriellen SEN66-Messwertmeldungen. Eine erweiterte Displayansicht ist für einen späteren Auftrag vorgesehen.

Die Anwendung prüft die Datenbereitschaft etwa einmal pro Sekunde und protokolliert alle zehn erfolgreichen Messungen einen Datensatz ohne Zugangsdaten. Beim Start meldet sie Boardprofil, Sensor, Pins und Takt; beim SEN66 wird zusätzlich der Produktname gelesen und geprüft. Sensorkalibrierung, CO₂-Zwangskalibrierung und Sensoreinstellungen werden nicht automatisch geändert.

Tests

Mit einem nativen C-Compiler auf Linux, aus dem Repository-Hauptverzeichnis:

bash firmware/test/sensors/run.sh

Diese Tests verwenden die echten SEN54-/SEN66-Treiber mit einer simulierten I²C-HAL. Sie prüfen Geräteadressen, verschiedene Messbefehle, Datenrahmen, vorzeichenbehaftete Werte, ungültige Rohwerte, CRC-Fehler und Übertragungsfehler. Der separate Software-Bus wird zusätzlich auf START/STOP, Adress-/Datenbits, ACK/NACK, Clock-Stretching, begrenzten Timeout und Freigabe der Leitungen geprüft. Alle vier Kombinationen der Board-/Sensorauswahl und die Zurückweisung unbekannter Profile werden ebenfalls geprüft. Das ersetzt keine elektrische oder vollständige Hardwareprüfung.

Für vollständige ESP-IDF-Builds der Referenzkombinationen kann die Auswahl vorübergehend pro Prozess überschrieben werden, ohne die Konfigurationsdatei zu ändern:

PLATFORMIO_BUILD_FLAGS='-DNANOPSX_SENSOR=54 -DNANOPSX_BOARD=1' pio run -d firmware -e esp32-c6-devkitc-1 -j 2
PLATFORMIO_BUILD_FLAGS='-DNANOPSX_SENSOR=66 -DNANOPSX_BOARD=2' pio run -d firmware -e esp32-c6-devkitc-1 -j 2

Die letzte Kompilierung bestimmt den Inhalt von .pio/build/.../firmware.bin. Vor einem Upload immer Auswahl, Build-Erfolg und Image-Hash neu prüfen.

Vor einem Upload

Den Workflow aus ../AGENTS.md einhalten: Board über USB-Seriennummer auswählen, vollständiges Backup bereitstellen und das tatsächlich aktive Partitionslayout lesen. Eine andere Sensorauswahl benötigt normalerweise nur ein App-Update; NVS mit WLAN-/Influx-Einstellungen muss dafür nicht gelöscht werden.

Das bekannte Board CC:BA:97:F2:5F:7C hatte zunächst eine einzelne Factory-Partition von 1 MiB bei 0x10000. Nach ausdrücklicher Freigabe wurde es am 09.11.2026 ohne vollständiges Löschen auf das nanoPSX-8-MB-Layout mit ota_0 bei 0x20000 umgestellt. Die neue Partitionstabelle wurde zuletzt aktiviert; NVS und Bootloader wurden erhalten und der alte PHY-Partitionsinhalt an die neue Adresse kopiert. Der gültige OTA-Datensatz wählt ota_0.

Für einen weiteren Upload das aktuelle Layout trotzdem erneut auslesen. Adressen, Images und frühere Einzelfreigaben niemals ungeprüft übernehmen. Ein vollständiges Löschen ist für einen Sensorwechsel nicht nötig und nicht automatisch freigegeben.

Prüfstand vom 09.11.2026

  • Vollständige ESP-IDF-Builds für alle vier Kombinationen (SEN54/SEN66, jeweils Devkit ohne Display/Display-Board): erfolgreich. Dabei wurde die Auswahl direkt in der zentralen Konfigurationsdatei gewechselt. Die fertigen ELF-Dateien enthalten jeweils nur den gewählten Sensortreiber. Abschließend wurden die Standardauswahl und das zugehörige Build-Artefakt wiederhergestellt.
  • Native Treiber-/CRC-/Fehlertests und Auswahltests: erfolgreich.
  • Hardwaretest auf CC:BA:97:F2:5F:7C, ESP32-C6FH8, 8 MB: neue SEN66-Firmware mit Display migriert und alle vier geschriebenen Bereiche vollständig bytegenau sowie per SHA256 bestätigt. Eine vollständige Rückleseprüfung der 8 MB bestätigt zusätzlich den Schutz der übrigen Flash-Bereiche.
  • 60 Sekunden Laufzeit ohne erkannte Panic oder Sensor-I²C-Fehler. SEN66 identifiziert, laufende Messungen über Software-I²C GPIO7/8, Displayinitialisierung erfolgreich, kein Touch-Ausfall gemeldet. Die Anzeige entspricht nach Benutzerkorrektur wieder der bisherigen SEN54-Ansicht, ohne zusätzliche NOx-/CO₂-Felder. Die sichtbare Anzeige muss am Gerät beurteilt werden, da das Gateway kein Displaybild liefert.
  • Standardauswahl ist jetzt SEN66 mit Display. Der bisherige separate Standalone-SEN66-Build ist auf diesem Board ersetzt. Ein vollständiges Backup liegt geschützt außerhalb des Repositorys vor.
  • Der SD-Karten-Timeout besteht weiter. Im Test war der Setup-AP nanoPSX mit Portal http://192.168.4.1 aktiv; keine STA-IP oder erfolgreichen Influx-Schreibvorgänge beobachtet. WLAN und bei Bedarf Organisation Home / Bucket nanoPSX im Portal einstellen; Tokens lokal eingeben.

Displayseiten und Bedienung

Die vier EEZ-Seiten sind Main (bisherige Messwertansicht), Page_2 (Raumluft), History (Verlauf) und Device (Gerät). Nach links zur nächsten, nach rechts zur vorherigen Seite wischen; an den äußeren Seiten gibt es keinen Umlauf. Vier kleine Markierungen am oberen Rand zeigen die aktuelle Seite. Tippen auf ein Statussymbol der Hauptseite öffnet die Geräteseite. Dropdowns und Helligkeitsregler verarbeiten ihre Berührungen selbst, ohne dabei versehentlich die Seite zu wechseln.

  • Raumluft: CO₂ in ppm, VOC-/NOx-Index und ein kleiner CO₂-Verlauf. Nicht verfügbare Kanäle erscheinen als --; SEN54 erzeugt keine künstlichen CO₂-Werte.
  • Verlauf: Auswahl zwischen CO₂, PM2.5, Temperatur, Feuchte, VOC und NOx. Gezeigt werden 180 Zehn-Sekunden-Mittelwerte über die letzten 30 Minuten. Die angezeigte Wertespanne entspricht der automatisch angepassten Diagrammachse. Fehlende Zeitabschnitte bleiben Lücken. Der feste RAM-Ringpuffer wird bei Neustart geleert; SD-Karte, WLAN und InfluxDB sind für den lokalen Verlauf nicht erforderlich.
  • Gerätestatus: WLAN/IP, Alter der letzten bestätigten Influx-Übertragung (HTTP 204) und Sensoraktualität. Ein WLAN-Erfolg gilt nicht als erfolgreiche Datenübertragung.
  • Helligkeit: 20–100 %, Standard 100 %. Automatisches Abdunkeln: aus oder nach 30/60/120 Sekunden, Standard 60 Sekunden. Abgedunkelt wird auf 15 %. Die erste Berührung weckt nur das Display und wird bis zum Loslassen verbraucht.
  • Display-Einstellungen werden erst nach Änderung gespeichert: Helligkeit beim Loslassen, Zeitwahl beim Auswählen. Eigener NVS-Namespace ui_display, keine WLAN-/Influx-Einstellungen. Beim ersten Start werden nur die Defaults gelesen.
  • Vor dem ersten Sensorpaket erscheint ein Starthinweis. Nach mehr als fünf Sekunden ohne erfolgreiches Paket werden die aktuellen Anzeigen als veraltet markiert und die Zahlen durch -- ersetzt; der vorhandene Verlauf bleibt sichtbar.

EEZ-Projekt und Firmware zusammen bearbeiten

eez/nanopsx.eez-project enthält Layout, Beschriftungen, Namen und Grundkonfiguration der Widgets. PlatformIO ruft vor jedem Build tools/export_display.py auf und hält screens.c/screens.h automatisch synchron. Kein manueller EEZ-Studio-Export nötig. Der projektspezifische Exporter unterstützt die hier verwendeten statischen Screen-, Panel-, Label-, Image-, Chart-, Slider- und Dropdown-Widgets und deren verwendete Stile. Nicht unterstützte Widgettypen/Stile brechen den Build ab, statt unbemerkt wegzufallen; bei Erweiterungen zuerst den Exporter ergänzen. EEZ Flow bleibt aus.

Navigation, dynamische Texte, Chart-Daten, Touch-Aufwecken und Einstellungen liegen außerhalb der generierten Dateien in ui_navigation.c, ui_dashboard.c und ui_model.c. Diese werden nach ui_init() unter dem LVGL-Lock initialisiert. Der Sensorproducer übergibt skalierte Zahlen an ui_model_publish() und ruft keine LVGL-Funktionen auf. Snapshot und begrenzter Ringpuffer sind auf dem ESP mit einem Spinlock geschützt. Die Diagramme werden im GUI-Task aktualisiert.

Prüfungen aus dem Repository-Hauptverzeichnis:

python3 firmware/tools/export_display.py --check
python3 firmware/test/ui/run_tests.py
bash firmware/test/sensors/run.sh

Die UI-Tests verwenden echte LVGL-Quellen und exportierte Displayobjekte bei 48 KiB LVGL-Speicher. Sie prüfen vierseitige Navigation, Tippen, kurze/vertikale Gesten, äußere Grenzen, Kindobjekte, Dropdown-Isolation, Helligkeitsregler, Aufweckberührung, Abdunkeln, fehlende/veraltete Werte und Verlaufsmittelwerte, Lücken und Verdrängung alter Daten. Voraussetzung sind ein C-Compiler und die bereits aufgelöste LVGL-Komponente unter firmware/managed_components. Ein optionaler Verzeichnispfad hinter dem UI-Testbefehl speichert vier gerenderte PPM-Vorschauen mit simulierten Messwerten. Physische Darstellung und Fingerbedienung müssen zusätzlich am Gerät geprüft werden.