docs: add README with layout guide, icons, examples, and Victron tips

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 03:42:50 +02:00 · 2026-04-07 03:42:50 +02:00 · b1f3d0b523
commit b1f3d0b523
parent e760853781
1 changed files with 288 additions and 0 deletions
--- a/display/README.md
+++ b/display/README.md
@ -0,0 +1,288 @@
+# EPaper Display System — Anleitung
+
+## Webinterface
+
+Zugang: `http://<SERVER-IP>:4000`
+Login: `admin` / `admin`
+
+---
+
+## Schritt-für-Schritt: Von MQTT-Daten zum Display
+
+### 1. MQTT-Broker anlegen
+
+**MQTT Broker** in der Sidebar > "Broker hinzufuegen"
+
+| Feld | Beispiel |
+|------|----------|
+| Name | Victron Cerbo |
+| Host | 192.168.85.161 |
+| Port | 1883 |
+| Username/Passwort | leer lassen wenn nicht noetig |
+| TLS | aus |
+
+Nach dem Speichern verbindet sich die Middleware automatisch.
+
+### 2. Topics entdecken
+
+**Topics** in der Sidebar > Broker auswaehlen > "Discovery starten"
+
+- **Prefix leer lassen** fuer alle Topics (`#` Wildcard)
+- **Prefix setzen** (z.B. `N/b827eb12e445/grid/`) fuer gezieltes Suchen
+- Die Liste aktualisiert sich automatisch waehrend der 30s Discovery
+- Topics werden mit ihrem letzten Wert angezeigt
+
+### 3. Topics auswaehlen (= Datenpunkte erstellen)
+
+In der Topic-Liste:
+
+1. **Checkbox anklicken** bei den gewuenschten Topics — erstellt automatisch einen Datenpunkt
+2. **JSON-Pfad setzen** wenn der Payload JSON ist:
+   - Payload `{"value": 23.5}` → JSON-Pfad: `$.value`
+   - Payload `{"sensor": {"temp": 21.3}}` → JSON-Pfad: `$.sensor.temp`
+   - Payload `42.5` (kein JSON) → JSON-Pfad leer lassen
+
+### 4. Datenpunkte konfigurieren
+
+**Datenpunkte** in der Sidebar — hier siehst du alle erstellten Punkte.
+
+Inline bearbeitbar:
+- **Label**: Anzeigename (z.B. "Netzspannung L1" statt Topic-Pfad)
+- **Einheit**: z.B. `V`, `W`, `kWh`, `°C`, `%`
+
+### 5. Layout erstellen
+
+**Layouts** in der Sidebar > "Neues Layout"
+
+| Feld | Beschreibung |
+|------|-------------|
+| Name | z.B. "PV Monitor" |
+| Typ | `free` (freie Positionierung) oder `grid` (Raster) |
+
+Dann **Elemente hinzufuegen** — jedes Element ist ein Baustein auf dem Display.
+
+### 6. Display erstellen und Layout zuweisen
+
+**Displays** in der Sidebar > "Display hinzufuegen"
+
+| Feld | Beschreibung |
+|------|-------------|
+| Name | z.B. "Werkstatt Display" |
+| Layout | Layout aus Schritt 5 auswaehlen |
+| Refresh | Update-Intervall in Sekunden (z.B. 300 = 5 Min) |
+
+---
+
+## Layout-Elemente
+
+### Element-Typen
+
+| Typ | Beschreibung | Felder |
+|-----|-------------|--------|
+| `value` | Datenwert mit Label, Wert, Einheit, optional Icon + Karte | Datenpunkt, Icon, Style |
+| `label` | Statischer Text (Titel, Ueberschriften) | Text |
+| `line` | Horizontale/vertikale Trennlinie | Width, Height |
+| `rect` | Rechteck (Rahmen) | Width, Height |
+
+### Positionierung
+
+Das Display hat **800 x 480 Pixel**. Jedes Element wird ueber X/Y-Koordinaten positioniert:
+
+```
+(0,0) ────────────────────────────────── (800,0)
+│                                              │
+│   (20,20) Titel                              │
+│                                              │
+│   (20,80)──────────(410,80)──────────        │
+│   │ Wert 1        ││ Wert 2        │         │
+│   │ (halbe Breite)││ (halbe Breite)│         │
+│   └───────────────┘└───────────────┘         │
+│                                              │
+│   (20,180)───────────────────────────        │
+│   │ Wert 3 (volle Breite)          │         │
+│   └─────────────────────────────────┘        │
+│                                              │
+(0,480) ──────────────────────────────── (800,480)
+```
+
+### Styles
+
+| Style | Beschreibung |
+|-------|-------------|
+| `plain` | Nur Text, kein Rahmen |
+| `card` | Karte mit abgerundetem Rahmen, Icon oben links, Wert gross unten rechts |
+
+### Verfuegbare Icons
+
+Fuer `value`-Elemente mit `card`-Style. Werden als 24x24 Pixel Bitmaps auf dem ESP32 gerendert.
+
+| Icon-Name | Verwendung |
+|-----------|-----------|
+| `thermometer` | Temperatur |
+| `droplet` | Luftfeuchtigkeit, Regen |
+| `wind` | Windgeschwindigkeit, Lueftung |
+| `pressure` | Luftdruck, Druck |
+| `sun` | Sonneneinstrahlung, PV-Leistung |
+| `bolt` | Strom, Leistung, Energie |
+| `gauge` | Zaehlerstand, Fuellstand |
+| `wifi` | Netzwerk, Verbindungsstatus |
+| `battery` | Akkustand, Batterielevel |
+| `check` | Status OK, aktiv |
+| `warning` | Warnung, Fehler |
+| `clock` | Zeitstempel, Betriebsstunden |
+
+### Schriftgroessen
+
+| font_size | Verwendung |
+|-----------|-----------|
+| 12 | Footer, Zeitstempel |
+| 16 | Klein (Beschriftungen) |
+| 24 | Standard (Default) |
+| 28 | Ueberschriften |
+| 32 | Grosse Werte |
+| 40 | Sehr grosse Werte |
+
+---
+
+## Beispiel-Layouts
+
+### Beispiel 1: PV-Monitor (5 Werte, gemischt)
+
+```
+Layout: "PV Monitor", Typ: free
+
+Elemente:
+┌─────────────────────────────────────────────────────┐
+│ Element 1: label                                     │
+│   Text: "PV Anlage", x:400, y:15, font_size:28      │
+│   font_weight:bold, text_align:center                │
+├─────────────────────────────────────────────────────┤
+│ Element 2: line                                      │
+│   x:10, y:50, width:780, height:2                    │
+├─────────────────────┬───────────────────────────────┤
+│ Element 3: value    │ Element 4: value               │
+│   x:20, y:70        │   x:410, y:70                  │
+│   width:370, h:90   │   width:370, h:90              │
+│   Datenpunkt: PV W  │   Datenpunkt: Grid W           │
+│   Icon: sun         │   Icon: bolt                   │
+│   Style: card       │   Style: card                  │
+├─────────────────────┴───────────────────────────────┤
+│ Element 5: value    │ Element 6: value               │
+│   x:20, y:175       │   x:410, y:175                 │
+│   width:370, h:90   │   width:370, h:90              │
+│   Datenpunkt: Batt% │   Datenpunkt: Verbrauch        │
+│   Icon: battery     │   Icon: gauge                  │
+│   Style: card       │   Style: card                  │
+├─────────────────────┴───────────────────────────────┤
+│ Element 7: value (volle Breite)                      │
+│   x:20, y:280, width:760, height:90                  │
+│   Datenpunkt: Ertrag heute                           │
+│   Icon: sun, Style: card                             │
+├─────────────────────────────────────────────────────┤
+│ Element 8: label                                     │
+│   Text: (wird automatisch mit Zeitstempel gefuellt)  │
+│   x:400, y:465, font_size:12, text_align:center      │
+└─────────────────────────────────────────────────────┘
+```
+
+### Beispiel 2: Raumklima (3 Werte, schlicht)
+
+```
+Layout: "Raumklima", Typ: free
+
+Element 1: label
+  Text: "Buero", x:400, y:20, font_size:28, bold, center
+
+Element 2: value
+  x:20, y:80, width:760, height:100
+  Datenpunkt: Temperatur, Icon: thermometer, Style: card
+
+Element 3: value
+  x:20, y:200, width:760, height:100
+  Datenpunkt: Luftfeuchte, Icon: droplet, Style: card
+
+Element 4: value
+  x:20, y:320, width:760, height:100
+  Datenpunkt: CO2, Icon: wind, Style: card
+```
+
+### Beispiel 3: Grid-Layout (6 Kacheln)
+
+```
+Layout: "Uebersicht", Typ: grid, grid_cols:3, grid_rows:2
+
+Element 1: value, grid_col:0, grid_row:0
+  Datenpunkt: Temp, Icon: thermometer, Style: card
+
+Element 2: value, grid_col:1, grid_row:0
+  Datenpunkt: Feuchte, Icon: droplet, Style: card
+
+Element 3: value, grid_col:2, grid_row:0
+  Datenpunkt: CO2, Icon: wind, Style: card
+
+Element 4: value, grid_col:0, grid_row:1
+  Datenpunkt: PV, Icon: sun, Style: card
+
+Element 5: value, grid_col:1, grid_row:1
+  Datenpunkt: Batterie, Icon: battery, Style: card
+
+Element 6: value, grid_col:2, grid_row:1
+  Datenpunkt: Netz, Icon: bolt, Style: card
+```
+
+---
+
+## Victron/Venus OS Tipps
+
+Typische Topics und empfohlene Konfiguration:
+
+| Topic | JSON-Pfad | Label | Einheit | Icon |
+|-------|-----------|-------|---------|------|
+| `N/.../grid/40/Ac/L1/Voltage` | `$.value` | Netzspannung L1 | V | bolt |
+| `N/.../grid/40/Ac/L1/Power` | `$.value` | Netzleistung L1 | W | bolt |
+| `N/.../pvinverter/36/Ac/Power` | `$.value` | PV Leistung | W | sun |
+| `N/.../pvinverter/36/Ac/Energy/Forward` | `$.value` | PV Ertrag | kWh | sun |
+| `N/.../battery/512/Soc` | `$.value` | Batterie SOC | % | battery |
+| `N/.../battery/512/Dc/0/Voltage` | `$.value` | Batterie Spannung | V | battery |
+| `N/.../battery/512/Dc/0/Power` | `$.value` | Batterie Leistung | W | battery |
+| `N/.../system/0/Ac/Consumption/L1/Power` | `$.value` | Verbrauch L1 | W | gauge |
+
+Alle Venus OS Topics verwenden das Format `{"value": <zahl>}`, also immer `$.value` als JSON-Pfad.
+
+---
+
+## Datenpunkt-Transformationen
+
+Im Feld "Transform" (JSON-Format) auf der Datenpunkte-Seite:
+
+```json
+{"round": 1}              // auf 1 Nachkommastelle runden
+{"round": 0}              // ganzzahlig runden
+{"scale": 0.001, "round": 2}  // Watt → kW mit 2 Stellen
+{"map": {"1": "AN", "0": "AUS"}}  // Zahlwerte auf Text mappen
+```
+
+---
+
+## ESP32 einrichten
+
+1. **Firmware flashen**: `cd esp32 && pio run -t upload`
+2. Mit WiFi **"EPaper-Setup"** verbinden (kein Passwort)
+3. Browser oeffnet automatisch Konfigurationsseite
+4. Eingeben:
+   - WiFi SSID + Passwort
+   - API URL: `http://<SERVER-IP>:4000`
+   - Display ID: die ID aus dem Webinterface (z.B. `1`)
+   - Token: leer lassen (oder API-Token vom Display)
+5. ESP32 startet neu und zeigt die Daten an
+
+---
+
+## API-Endpunkt fuer ESP32
+
+```
+GET http://<SERVER-IP>:4000/api/display/<ID>
+GET http://<SERVER-IP>:4000/api/display/<ID>?token=<TOKEN>
+```
+
+Liefert JSON mit Display-Info, Layout-Typ und allen Elementen inkl. aktuellem Wert.