Files
nanopsx_sen66/firmware/HARDWARE.md
T

300 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Sensor und Board auswählen
Die zentrale Konfiguration steht in
[`components/hardware_config/hardware_config.h`](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:
```c
#define NANOPSX_SENSOR NANOPSX_SENSOR_SEN66
#define NANOPSX_BOARD NANOPSX_BOARD_C6_DISPLAY_8MB
```
Für einen SEN66 an GPIO7/8 ohne Display:
```c
#define NANOPSX_SENSOR NANOPSX_SENSOR_SEN66
#define NANOPSX_BOARD NANOPSX_BOARD_C6_DEVKIT_8MB
```
Für den bisher getesteten SEN54 am nanoPSX-Display-Board:
```c
#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:
```bash
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`](components/sen5x/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
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:
```bash
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:
```bash
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.
## Effiziente InfluxDB-Übertragung
Der Sensor misst weiter mit 1 Hz. Der Influx-Worker bündelt bis zu zehn einzelne
Messpunkte in einer HTTP-Anfrage; spätestens zehn Sekunden nach Beginn eines
Pakets wird auch ein kleineres Restpaket versendet. Ein Paket ist zusätzlich auf
4096 Bytes begrenzt. Keine Mittelung oder Änderung der Influx-Feldnamen/Einheiten;
Display und lokaler Verlauf aktualisieren sich unabhängig vom Netzwerk weiter.
Im normalen 1-Hz-Betrieb entstehen etwa sechs Schreibanfragen pro Minute statt 60,
mit bis zu etwa zehn Sekunden zusätzlicher Sichtbarkeitsverzögerung auf dem Server.
Jeder Punkt erhält einen eigenen Zeitstempel mit `precision=ms`. Der Messzeitpunkt
wird beim Einreihen über den monotonen ESP-Timer erfasst. Ein einmaliger GET auf
`/health` liest den HTTP-`Date`-Header desselben Influx-Servers und richtet damit
nur die interne Messuhr aus; weder ein Internet-Zeitdienst noch eine Änderung der
Systemuhr ist nötig. HTTP Date besitzt Sekundenauflösung: Die absolute Zuordnung
ist entsprechend ungefähr sekundengenau; die Abstände der Sekundenmessungen
bleiben erhalten. Spätere Date-Header gleichen größere Uhrdrift vorsichtig aus.
Explizite Zeitstempel der API bleiben erhalten. Fehlt ein gültiges Date vollständig,
werden sichere Einzelpunkt-Anfragen mit Serverzeit verwendet, bis eine Zeitbasis
verfügbar ist. Mehrere ungestempelte Punkte derselben Serie werden nicht gebündelt.
HTTP-Client und Verbindung werden über mehrere Anfragen wiederverwendet. Ein
Konfigurationswechsel oder Verbindungsfehler verwirft den Handle; der nächste
Versuch baut ihn neu auf. Es werden keine Token oder Messwert-Payloads protokolliert.
Der Worker meldet HTTP-Status, Punkt-/Bytezahl, erste/letzte UTC-Zeit im Paket und
gezählte Verbindungsaufbauten. Die Gerätestatusanzeige zählt nur bestätigte HTTP 204
als erfolgreiche Übertragung; ihr Alter kann jetzt regulär etwa zehn Sekunden betragen.
Der RAM-Puffer enthält 32 vorserialisierte Punkte ohne einzelne Heap-Allokationen
für jeden Feldnamen/Wert. Ein Paket bleibt bei Transportfehlern, Rate-Limits oder
Serverproblemen mit unverändertem Inhalt und Zeitstempeln für einen erneuten
Versuch erhalten (exponentielle Pause von 2 s bis maximal 300 s). Fünf Fehler lösen
ein Neuladen der vorhandenen Konfiguration aus. HTTP 400/413/422 wird als abgelehntes
Paket protokolliert und verworfen; bereits teilweise geschriebene Daten werden dabei
nicht gelöscht. Ohne Zeitbasis werden fehlgeschlagene Einzelpunkte nicht automatisch
wiederholt, da deren Serverzeit sonst neue Punkte erzeugen könnte.
Bei längerem Ausfall ersetzt die volle Warteschlange die ältesten noch nicht
versendeten Punkte; die Verluste werden gezählt und protokolliert. Puffer und
laufendes Paket sind RAM-basiert und gehen bei Neustart verloren. Der Producer
wartet nicht auf HTTP. Beim Stoppen räumt der Worker seine Ressourcen selbst auf;
er wird nicht mitten in einer Anfrage gewaltsam beendet.
Nativer Test mit dem echten Worker und simuliertem FreeRTOS/HTTP unter Address- und
UndefinedBehavior-Sanitizer, vom Repository-Hauptverzeichnis:
```bash
python3 firmware/test/net_influx/run_tests.py
```
Prüft Serialisierung/escaping, fehlende Kanäle, UTC-/Kalenderkonvertierung,
Messzeitabstände, 10er-Pakete, Wiederholungen mit identischem Body, Warteschlangen-
Überlauf, fehlende Zeitbasis, Einzelpunktfehler, Zeitlimit bei Restpaketen,
Bytegrenzen, dauerhaft abgelehnte Pakete und Wiederverwendung/Freigabe des Clients.