Skip to content

Commit 72ab975

Browse files
thengeroffthengeroff
committed
feat: introduce template fan entity with sync logic and feedback-loop guards for ventosync-card integration
1 parent 5b7812d commit 72ab975

5 files changed

Lines changed: 531 additions & 2 deletions

File tree

‎documentation/VentoSync – Home Assistant Dashboard.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# VentoSync – Home Assistant Dashboard
2+
3+
## Übersicht
4+
5+
Dieses Dokument beschreibt das modulare Lovelace-Dashboard für **VentoSync**-Geräte in Home Assistant. Das Dashboard nutzt ein wiederverwendbares **Decluttering-Template**, das für beliebig viele VentoSync-Geräte instanziiert werden kann – pro Gerät sind nur 3 Zeilen YAML nötig.
6+
7+
![Dashboard Vorschau](docs/images/dashboard-preview.png)
8+
9+
---
10+
11+
## Inhaltsverzeichnis
12+
13+
- [Voraussetzungen](#voraussetzungen)
14+
- [Installation](#installation)
15+
- [Dashboard-Architektur](#dashboard-architektur)
16+
- [Template-Aufbau](#template-aufbau)
17+
- [1. Hero Section](#1-hero-section)
18+
- [2. Status Chips](#2-status-chips)
19+
- [3. Detail Cards](#3-detail-cards)
20+
- [4. Mini Graph](#4-mini-graph)
21+
- [5. Steuerung](#5-steuerung)
22+
- [6. Switches](#6-switches)
23+
- [Entity-Referenz](#entity-referenz)
24+
- [Geräte hinzufügen](#geräte-hinzufügen)
25+
- [Anpassungen](#anpassungen)
26+
- [Fehlerbehebung](#fehlerbehebung)
27+
28+
---
29+
30+
## Voraussetzungen
31+
32+
### HACS Custom Cards
33+
34+
Folgende Custom Cards müssen über [HACS](https://hacs.xyz/) (Frontend) installiert sein:
35+
36+
| Card | Repository | Zweck |
37+
|------|-----------|-------|
38+
| **Mushroom** | [piitaya/lovelace-mushroom](https://github.com/piitaya/lovelace-mushroom) | Template-, Chips-, Select-, Number-Cards |
39+
| **Mini Graph Card** | [kalkih/mini-graph-card](https://github.com/kalkih/mini-graph-card) | Verlaufsgraphen |
40+
| **Card Mod** | [thomasloven/lovelace-card-mod](https://github.com/thomasloven/lovelace-card-mod) | CSS-Anpassungen & Animationen |
41+
| **Stack In Card** | [custom-cards/stack-in-card](https://github.com/custom-cards/stack-in-card) | Nahtlose Kartenverschachtelung |
42+
| **Decluttering Card** | [jcwillox/lovelace-decluttering-card](https://github.com/jcwillox/lovelace-decluttering-card) | Wiederverwendbare Templates |
43+
44+
### Systemvoraussetzungen
45+
46+
- Home Assistant **2024.1** oder neuer
47+
- Mindestens ein konfiguriertes VentoSync-Gerät via ESPHome
48+
- Einheitliches Entity-Namensschema (automatisch durch ESPHome `name:`)
49+
50+
---
51+
52+
## Installation
53+
54+
### 1. HACS Cards installieren
55+
HACS → Frontend → + Explore & Download Repositories → Suche nach: mushroom, mini-graph-card, card-mod, stack-in-card, decluttering-card → Jeweils installieren
56+
57+
### 2. Browser-Cache leeren
58+
59+
Nach jeder HACS-Installation **zwingend** den Browser-Cache leeren:
60+
61+
- **Windows/Linux:** `Strg + Shift + R`
62+
- **macOS:** `Cmd + Shift + R`
63+
64+
### 3. Dashboard konfigurieren
65+
66+
1. Dashboard öffnen → Oben rechts `⋮` → **Raw-Konfigurationseditor**
67+
2. Das `decluttering_templates:`-Block **vor** `views:` einfügen
68+
3. In der gewünschten View die Geräte per `custom:decluttering-card` aufrufen
69+
4. Speichern
70+
71+
---
72+
73+
## Dashboard-Architektur
74+
75+
```text
76+
┌─────────────────────────────────────────────┐
77+
│ HERO SECTION │
78+
│ Animiertes Fan-Icon + Modus + Metrics │
79+
│ ┌───────────────────────────────────────┐ │
80+
│ │ Chips: Richtung │ Fenster │ Gehäuse │ │
81+
│ └───────────────────────────────────────┘ │
82+
├─────────────────────────────────────────────┤
83+
│ DETAIL CARDS (4 Spalten) │
84+
│ Drehzahl │ PWM Duty │ Gehäuse │ Fensterspr. │
85+
├─────────────────────────────────────────────┤
86+
│ MINI GRAPH │
87+
│ Drehzahl (RPM) + PWM (%) + Temp (°C) │
88+
├─────────────────────────────────────────────┤
89+
│ STEUERUNG │
90+
│ Betriebsmodus (Select) │
91+
│ Lüfter Stufe (Slider) │
92+
│ LED Helligkeit (Slider) │
93+
├─────────────────────────────────────────────┤
94+
│ SWITCHES (2 Spalten) │
95+
│ Fenstersperre │ Kindersicherung │
96+
└─────────────────────────────────────────────┘
97+
```
98+
99+
### Wiederverwendbarkeit
100+
101+
```yaml
102+
decluttering_templates:
103+
ventosync: # ← Template (einmal definiert)
104+
card: ... # ← Enthält [[device]] Platzhalter
105+
106+
# Anwendung im Dashboard:
107+
views:
108+
cards:
109+
- type: custom:decluttering-card
110+
template: ventosync
111+
variables:
112+
- device: ventosync_dg_buero # ← Instanz 1
113+
- type: custom:decluttering-card
114+
template: ventosync
115+
variables:
116+
- device: ventosync_eg_wozi # ← Instanz 2
117+
```
118+
119+
---
120+
121+
## Template-Aufbau
122+
123+
### 1. Hero Section
124+
125+
Das zentrale Element des Dashboards. Zeigt den aktuellen Betriebsmodus mit einem animierten Fan-Icon.
126+
127+
**Features:**
128+
129+
- **Richtungsbewusste Spin-Animation:** Das Icon dreht sich vorwärts (Zuluft) oder rückwärts (Abluft)
130+
- **RPM-skalierte Geschwindigkeit:** Die Animationsgeschwindigkeit passt sich der tatsächlichen Drehzahl an
131+
- `> 1500 RPM` → 0.8s (schnell)
132+
- `> 800 RPM` → 1.5s (mittel)
133+
- `≤ 800 RPM` → 3s (langsam)
134+
- `0 RPM` → keine Animation
135+
- **Dynamische Farbcodierung:**
136+
- 🔵 Blau = Zuluft (positive RPM)
137+
- 🟠 Orange = Abluft (negative RPM)
138+
- ⚫ Disabled = Stillstand
139+
140+
**Kompakte Sekundärzeile:**
141+
Zuluft (Rein) · 1680 RPM · 22% PWM · Stufe 5
142+
143+
144+
### 2. Status Chips
145+
146+
Drei farbcodierte Chips unterhalb des Hero-Icons:
147+
148+
| Chip | Entity-Suffix | Darstellung |
149+
|------|--------------|-------------|
150+
| **Richtung** | `_lufter_richtung` | ↓ Zuluft (blau) / ↑ Abluft (orange) / ⇅ Wärmetausch (teal) / ⏸ Pause (grau) |
151+
| **Fenstersperre** | `_fenstersperre_aktiv` | 🟢 Fenster zu / 🔴 Fenster offen |
152+
| **Gehäuse-Temp** | `_bmp390_temperatur` | Farbcodiert: teal (< 40°C) / orange (40–50°C) / rot (> 50°C) |
153+
154+
### 3. Detail Cards
155+
156+
Vier Mushroom Template Cards in einer horizontalen Reihe:
157+
158+
| Card | Entity-Suffix | Besonderheit |
159+
|------|--------------|-------------|
160+
| **Drehzahl** | `_lufter_drehzahl` | Zeigt `↓ 1680 RPM` (blau) oder `↑ 1680 RPM` (orange) je nach Richtung. Pulse-Animation wenn aktiv. |
161+
| **PWM Duty** | `_lufter_pwm` | Farbcodiert: amber (< 50%) / deep-orange (50–80%) / rot (> 80%) |
162+
| **Gehäuse** | `_bmp390_temperatur` | Farbcodiert: blau (< 40°C) / deep-orange (40–50°C) / rot (> 50°C) |
163+
| **Fenstersperre** | `_fenstersperre_aktiv` | Dynamisches Icon: 🪟 offen (rot) / 🪟 geschlossen (grün) |
164+
165+
### 4. Mini Graph
166+
167+
Verlaufsgraph mit drei numerischen Metriken:
168+
169+
| Metrik | Farbe | Y-Achse |
170+
|--------|-------|---------|
171+
| Drehzahl (RPM) | `#7c4dff` (lila) | Sekundär (rechts) |
172+
| PWM (%) | `#ff6d00` (orange) | Primär (links) |
173+
| Temp. Gehäuse (°C) | `#00b0ff` (blau) | Primär (links) |
174+
175+
**Konfiguration:**
176+
- `hours_to_show: 0.2` (ca. 12 Minuten – ideal für den ~70s Reversierzyklus)
177+
- `points_per_hour: 3600` (1 Punkt pro Sekunde)
178+
- `fill: fade` (halbtransparente Füllung unter den Linien)
179+
180+
### 5. Steuerung
181+
182+
Drei Controls in einer nahtlosen `stack-in-card`:
183+
184+
| Control | Typ | Entity-Suffix |
185+
|---------|-----|--------------|
186+
| **Betriebsmodus** | Mushroom Select (Dropdown) | `_luftermodus` |
187+
| **Lüfter Stufe** | Mushroom Number (Slider) | `_lufter_intensitat` |
188+
| **LED Helligkeit** | Mushroom Number (Slider) | `_maximale_led_helligkeit` |
189+
190+
### 6. Switches
191+
192+
Zwei Toggle-Cards nebeneinander mit visuellem Feedback:
193+
194+
| Switch | Entity-Suffix | Aktiv-Zustand |
195+
|--------|--------------|--------------|
196+
| **Fenstersperre ignorieren** | `_fenstersperre_ignorieren` | 🟠 Orange Border + "Wird ignoriert" |
197+
| **Kindersicherung** | `_kindersicherung` | 🔴 Rote Border + "Bedienfeld gesperrt" |
198+
199+
Beide Cards reagieren auf **Tap** zum Togglen und zeigen über eine farbige `border-left`-Linie den aktiven Override-Zustand an.
200+
201+
---
202+
203+
## Entity-Referenz
204+
205+
Alle Entities folgen dem Schema `{domain}.{device}_{suffix}`:
206+
207+
| Domain | Suffix | Typ | Beschreibung |
208+
|--------|--------|-----|-------------|
209+
| `select` | `_luftermodus` | Select | Betriebsmodus (Wärmerückgewinnung, Zuluft, Abluft, etc.) |
210+
| `number` | `_lufter_intensitat` | Number | Lüfterstufe (manuell) |
211+
| `number` | `_maximale_led_helligkeit` | Number | Maximale LED-Helligkeit am Bedienfeld |
212+
| `sensor` | `_lufter_drehzahl` | Sensor | Aktuelle Drehzahl in RPM (negativ = Abluft) |
213+
| `sensor` | `_lufter_pwm` | Sensor | Aktueller PWM Duty Cycle in % |
214+
| `sensor` | `_lufter_richtung` | Sensor | Aktuelle Richtung (z.B. "Zuluft (Rein)", "Abluft (Raus)") |
215+
| `sensor` | `_bmp390_temperatur` | Sensor | Gehäusetemperatur (BMP390) in °C |
216+
| `sensor` | `_fenstersperre_aktiv` | Sensor | Fenstersperre Status ("Ja" / "Nein") |
217+
| `switch` | `_fenstersperre_ignorieren` | Switch | Override: Fenstersperre ignorieren |
218+
| `switch` | `_kindersicherung` | Switch | Kindersicherung (Bedienfeld sperren) |
219+
220+
> **Hinweis:** Die Entity-IDs werden automatisch durch ESPHome generiert, basierend auf dem `name:`-Feld in der ESPHome-Konfiguration. Alle VentoSync-Geräte müssen das gleiche Suffix-Schema verwenden.
221+
222+
---
223+
224+
## Geräte hinzufügen
225+
226+
### Neues Gerät in 3 Zeilen
227+
228+
```yaml
229+
- type: custom:decluttering-card
230+
template: ventosync
231+
variables:
232+
- device: ventosync_STOCKWERK_RAUM
233+
```
234+
235+
### Beispiel: Komplettes Haus
236+
237+
```yaml
238+
views:
239+
- title: Lüftung
240+
icon: mdi:hvac
241+
path: lueftung
242+
cards:
243+
# Dachgeschoss
244+
- type: custom:decluttering-card
245+
template: ventosync
246+
variables:
247+
- device: ventosync_dg_buero
248+
```

‎manifest_example.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
{
66
"chipFamily": "ESP32-C6",
77
"ota": {
8-
"md5": "23404910e80270f6c84c6617bcec9e23",
8+
"md5": "081e620e1af2a733c1a70f47eb9b751b",
99
"path": "firmware.bin",
1010
"summary": "OTA update check frequency set to 15 minutes"
1111
}

‎packages/actuators/logic_automation.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ script:
7171
id(pre_vacation_intensity) = id(fan_intensity_level);
7272
7373
// Read configured vacation mode and intensity from HA config entities
74-
std::string vacation_mode = id(vacation_mode_select).state;
74+
std::string vacation_mode = id(vacation_mode_select).current_option();
7575
float vacation_intensity = id(vacation_intensity_number).state;
7676
7777
// Fallback to safe defaults if entities are not yet initialized

‎packages/base/ventosync_base.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ packages:
6969
maintenance: !include ../actuators/logic_maintenance.yaml
7070
safety: !include ../actuators/logic_safety.yaml
7171
integration: !include ../integration/homeassistant.yaml
72+
ha_fan: !include ../integration/ha_fan_entity.yaml
7273

7374
external_components:
7475
- source:

0 commit comments

Comments
 (0)