Files
memory/systems/homeassistant.md
T
2026-11-16 22:00:25 +00:00

318 lines
48 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.
---
title: "Home Assistant"
category: systems
tags: [homeassistant, smart-home, mqtt, automation]
created: "2026-09-27"
modified: "2026-11-01"
---
# Home Assistant
> Smart Home Zentrale auf Proxmox. Steuerung, Automatisierung und Benachrichtigungen.
## Infrastruktur
- **Host:** `10.0.30.10` (HAOS VM **106** auf proxmox3, 4 Cores / 16 GB, bios ovmf)
- **CPU-Typ:** `x86-64-v2-AES` (seit 12.11.2026, vorher `kvm64`; Config-Backup
`/root/vm106-config.bak-20261112-161151` auf proxmox3). Kaltstart nötig, damit der
Typ greift. Grund: moderne Python-Wheels (numpy 2.5, pandas 3.1, pyarrow 26,
manylinux_2_28+) verlangen SSSE3/SSE4.1/SSE4.2/POPCNT. Alle 8 Cluster-Nodes können
das, `host` wäre nicht migrationssicher.
- **SSH:** Port 22222, Key `~/.ssh/id_ed25519_proxmox`, user `root`
- **URL:** `https://homeassistant.familie-schoen.com`
- **Container:** `homeassistant` (Docker); Add-ons werden nach Core-Start gestartet
(`startup: application`) — nach einem VM-Neustart braucht es ~5 min bis AppDaemon,
EMHASS, evcc und Earnie wieder laufen.
## MQTT
- **Broker:** Mosquitto Add-on v7.1.1 auf localhost:1883
- **HA MQTT User:** ehemals `opendtu` (BROKEN — ACL blockiert), gefixt
- **ACL:** `/etc/mosquitto/acl` definiert `user homeassistant` + `user addons`
- **Auth Plugin:** `go-auth.so` (files,http backends)
## Automations
- **File:** `/config/automations.yaml` (35 Automations)
- **Schreibmethode:** SSH → `docker exec homeassistant chmod 666`, danach restore 644
- **Reload:** REST API mit JWT (HS256, signed from `/config/.storage/auth`)
### Frigate AI Notification v3 (ID 1714065780832)
- **Trigger:** MQTT `frigate/reviews` (severity=alert, Kameras Einfahrt/Terrasse) — NICHT `frigate/events` (Raw=Spam)
- **Gate:** llmvision.image_analyzer (noris gemma-4-31b-it) VOR Push, binär KRITISCH/NORMAL
- **Suppress:** sub_labels Sarah/Dominik; 300s Kamera-Cooldown; Review-ID-Dedup
- **Push:** GENAU EIN kombinierter (Titel+Verdict+Objekte+Bild) nur bei KRITISCH ∨ KI-Fail ∨ Person (24/7, v3.1)
- Siehe [[systems/frigate]] + Solution Doc `bug-fixes/2026-10-10-frigate-notification-spam-review-alerts.md`
### Büro EG: Licht nach Präsenz (ID `buero_eg_licht_praesenz_nachlauf`, seit 02.11.2026, Stand 14.11.)
- **Trigger:** `binary_sensor.esp32_c3_buero_eg_presence` → `on` schaltet `switch.licht_buro` an — **nur wenn dunkel**; `off` für **2 min** schaltet aus (Nachlauf; Nutzer-Historie: 15 → 5 → 2 min am 14.11.)
- **Helligkeits-Gate:** `sensor.wetterstation_illuminance` (Wetterstation Beleuchtungsstärke, outdoor) **< 7000 lx** = Licht erlaubt. Schwellen-Historie (jeweils Nutzer-Vorgabe „ab der aktuellen Helligkeit"): 500 → 1.500 lx (14.11., 1.300 lx) → **7.000 lx (16.11., 6.400 lx)**. Outdoor-Lux ist nur ein **Proxy** für die Büro-Helligkeit (Nordseite/trüb ≠ Outdoor-Wert). Sensor `unavailable`/`unknown` → Licht wird eingeschaltet (Fail-safe Richtung Licht). Zusätzlicher Trigger `numeric_state below 7000 for 3 min` → bei Dämmerung einschalten, wenn Präsenz schon an ist (sonst käme nie eine neue Präsenzflanke)
- **Bewusst KEIN Ausschalten bei Helligkeit** (Heuristik-Veto: würde manuelles Einschalten überfahren); „Sonne raus → Licht aus" wäre ein separater Trigger mit Bestätigungszeit
- **Sweep:** `time_pattern /2` (Nutzer-Wert) — nur Restart-Recovery: Licht an + Präsenz ≥2 min aus → aus. Kein Re-Assert auf `on` — manuelles Ausschalten bei Anwesenheit bleibt respektiert
- **Sensor-Verhalten:** ESP32-C3 (10.0.50.147, Büro EG) meldet Präsenz in 20–60-s-Bursts mit Lücken von 15 s bis 6 min (Log 16.11. 08:00–09:00) → mit 2-min-Nachlauf fällt das Licht in längeren Lücken aus. Lux-Tagesgang 16.11.: 06:00 35 lx → 07:15 ~6.400 → 08:15–08:45 13.000–20.000 → 09:15 ~5.900 lx. **Offene Verbesserungen:** (a) Indoor-Lux (BH1750 am Büro-ESP32) statt Outdoor-Proxy, (b) LD2410-Hold/Absence-Timeout im ESPHome prüfen, (c) Nachlauf ggf. zurück auf 5 min
- **E2E verifiziert 14.11. (nach Umbau):** hell 8.537 lx + Präsenzflanke → Licht bleibt aus; fake 300 lx + Präsenzflanke → Licht an; echter 5-min-Nachlauf (Presence off 09:01:26 → Licht aus 09:06:28, Trace `choose/2`), Sweep-Läufe davor korrekt untätig. **Schwellen-A/B (14.11., gleiche Helligkeit ~1.280–1.300 lx):** Flanke 15:23:13 mit 500 lx → bleibt aus (`choose/3/conditions/0`), Flanke 15:24:13 mit 1500 lx → Licht an (`choose/0/sequence/0`). **16.11. gleiches Muster bei ~6.000 lx:** Flanke 09:11:26 mit 1500 lx → bleibt aus, Flanke 09:15:49 mit 7000 lx → Licht an 09:15:50 (`choose/0/sequence/0`). **2-min-Nachlauf (nach Umstellung):** Presence off 15:28:14,56 → Trigger 15:30:14,56 (exakt 2:00) → Licht aus 15:30:16,10, Trace `choose/2`
- **Pitfall:** Nutzer hatte die Automation zwischenzeitlich selbst editiert (5 min, Sweep /2) — blindes `POST` überschreibt das. Alte Config war aus dem Automation-Trace (`ws trace/get`) rekonstruierbar; seither gilt: vor Overwrite `GET` + Diff
- Entity-ID nach Anlegen via WS-Entity-Registry umbenannt (Alias-Slugify verschluckt Umlaute: „Büro"→`buro`, „Präsenz"→`prasenz`)
## Beschattungsautomatik Wohnzimmer (15.11.2026)
**Fassaden (Owner-Angabe):** Wohnzimmertüre (`ABB240561F51/ch0000`) + Wohnzimmerfenster 1 (`ch0001`) = **143° Südost**; Wohnzimmerfenster 2 (`ch0002`) = **233° Südwest** (90° versetzt). Alle drei sind free@home-Jalousien (Pos + Lamellen, Features 143).
**Entscheidung (Fassung 16.11.2026, Owner: „kein temperaturbasiertes Beschatten, kurze Helligkeits-Peaks ignorieren"):**
- **Helligkeit geglättet:** `sensor.helligkeit_geglaettet` (trigger-basiertes Template, **Median der letzten 7 Messwerte** — ein einzelner Peak kann den Wert nicht bewegen; ~3,5 min bei 30-s-Report). Roh bleibt `sensor.wetterstation_illuminance`.
- **Beschattet, wenn** `elev >= beschattung_sonnenhoehe_min (5°)` **und** `Einfallswinkel <= beschattung_einfall_max (25°)` **und** `Median-Lux >= beschattung_lux_min (8.000)`. Kein Temperatur-Gate, kein kt-Gate mehr (kt nur noch Diagnose-Attribut).
- **Ausfahren:** Sensor `off` **10 min**, nur bei Sonnenhöhe > 0 (der Sensor ist das einzige Abbild der Wahrheit — keine separaten Ausfahr-Schwellen).
- Attribute: `einfallswinkel`, `helligkeit_gefiltert`/`helligkeit_roh`, `klarheit_kt`, `sonnenhoehe`.
- Fassaden: Suedost 143° (Tür + Fenster 1) / Suedwest 233° (Fenster 2).
**Aktorik (automations.yaml, 4 Stück):** `beschattung_wz_so_sonne_einfahren` / `_sonne_raus`, `beschattung_wz_sw_sonne_einfahren` / `_sonne_raus`
- Einfahren: Sensor `on` **4 min** (`for`) → `cover.set_cover_position` (Öffnungsgrad, Default **20** — Owner-Korrektur 15.11.: „ein bisschen weiter runter") → warten bis Position ±6 → `cover.set_cover_tilt_position` (Lamellen, Default 25) → 20 s später Verifikation, bei Abweichung >8 % `persistent_notification`
- Ausfahren (Stand 15.11. 12:00 UTC): **eigener Template-Trigger 5 min** — `elev > 0` und (`elev < 8` **oder** `inc > 88°` **oder** `kt < input_number.beschattung_klarbeit_aus` 0.45) → 100/100, **nur wenn die Rollläden noch auf der Beschattungsposition stehen** (Manuell-Schutz, kein Überschreiben von Handeingriffen). Kein Re-Assert während aktiver Beschattung. Die Ausfahr-Schwelle liegt **0,07 kt unter** der Einfahr-Schwelle (Hysterese-Band) — nicht gleich setzen, sonst flattert es bei jeder Wolke. Nachts (`elev <= 0`) kein Öffnen (Privatsphäre) — das macht die Abend-Szene.
- Kein Zeit-Gate: nur Sonnenstand + Helligkeit.
**Tuning:** Dashboard „Haus" → View **Rollos** → Karte „Beschattung Wohnzimmer" (1 `input_boolean` + 10 `input_number` + Raumtemperatur).
**Pitfalls (live erlebt):**
- `homeassistant.reload_core_config` legt **neue** YAML-Helper NICHT an — dafür `input_number.reload` / `input_boolean.reload` (danach sind sie sofort da).
- HA-Templates: **kein** `radians()`/`degrees()`; `sin/cos/acos` rechnen im Bogenmaß, `pi`/`e` sind vorhanden → `R = pi/180` selbst multiplizieren. `sin(30,'deg')` ignoriert die Einheit (Ergebnis = sin(30 rad)).
- free@home-Cover invertieren intern (`100 - position` / `100 - tilt`): HA-Position 0 = zu, 100 = offen; HA-Tilt 100 = Lamellen offen.
- Entity-IDs aus Namen mit Umlauten/Klammern werden unbrauchbar → Sensornamen bewusst „Suedost"/„Suedwest".
## Notify Services
| Service | Status |
|---------|--------|
| `notify.mobile_app_iphone_dominik` | ✅ aktiv (DER Service für iPhone-Pushes) |
| `notify.mobile_app_sarahs_iphone_app` | verfügbar |
| `notify.mobile_app_ipad_2` / `notify.mobile_app_sm_x205` | verfügbar |
⚠️ **SERVICE ≠ ENTITY (Falle, 12.10.2026 live erlebt):** mobile_app registriert zusätzlich notify-ENTITIES mit anderem Namen (z.B. Entity `notify.iphone_dominik`). Diese Entities existieren in `get_states`, sind aber KEINE Service-Targets. Als action-Target in Automations ist IMMER `notify.mobile_app_*` zu verwenden; Verifikation ausschließlich via `get_services` (nicht `get_states`!). Verwechslung führte am 12.10. zu einem fehlgeleiteten 14-fachen-Rename, der via Backup sofort revertiert wurde.
## Entitäten
- Kameras: `camera.einfahrt_2`, `camera.terrasse_2` (Suffix `_2` wegen verwaister Integration)
- Motion: `binary_sensor.einfahrt_motion_2`, `binary_sensor.terrasse_motion_2`
- Input Text: `input_text.frigate_last_event_id` (dedup storage, max 255 chars)
## Snapshots
- Gespeichert: `/config/www/snapshots/{camera}_latest.jpg`
- URL: `/local/snapshots/` (HTTP 200, keine Auth)
## JWT Auth
1. `jwt_key` aus `/config/.storage/auth` lesen
2. Client `Hermes_202606` (token id `1444b2c6757b4d66a6f8f8e5899b4e6a`)
3. HS256 signieren, Bearer Header
4. `?return_response=true` für Service-Call Responses
## Integrations
- Frigate (MQTT)
- LLM Vision (noris AI `gemma-4-31b-it`)
- Tibber (Strom)
- Marstek Speicher (VENUS-E, IP 10.0.50.113)
- NUT (APC Back-UPS ES 700G via ms-a2-1, `10.0.20.92:3493`, User monuser; Sensors `sensor.apc_*`; Entry `5e1d2138235140eb9b476e9d6779c228`; deployed via `iac-homelab/epic-9-ups-nut`)
- Various sensors (Xiaomi BLE, etc.)
## Zigbee / Zigbee2MQTT (Stand 10.11.2026)
- **Stack:** Z2M Add-on `45df7312_zigbee2mqtt` **2.14.3-1**, zigbee-herdsman 11.2.0, **ZHC 26.125.0**; Addon-Zugriff nur über HA-Ingress-WS (Details: Skill-Ref `smart-home-automation/references/zigbee2mqtt-remote-diagnosis.md`)
- **Coordinator:** SONOFF Dongle-M, EmberZNet 7.4.5 [GA], EZSP 13, **TCP** `tcp://10.0.50.145:6638`
- **Netz:** Kanal **25**, PAN 33072; 8 Geräte (5× Schlafzimmer-Lampen, Esszimmertür, Garagentor-Neigungssensor, Wetterstation)
- **permit_join:** nur via `switch.zigbee2mqtt_bridge_permit_join` (254-s-Fenster, Refresher-Loop beim echten Pairing); `mqtt.publish` auf `zigbee2mqtt/bridge/request/permit_join` wird von der Broker-ACL **still verworfen**
- HA-MQTT-Entry-Titel `192.168.100.27` ist kosmetisch/veraltet — Discovery läuft normal
### Shelly/Ecowitt WS90 (gekoppelt 10.11.2026, Zigbee-Variante)
- **IEEE `0xc02cedfffe774579`**, `EndDevice`, interview complete, FW `251015/v1.1.6@62`, Manufacturer Shelly, Model-ID `WS90`
- **22 Entities** `sensor.wetterstation_*` / `binary_sensor.wetterstation_rain_status` / `button.wetterstation_identify` (Auto-Discovery, keine Handarbeit)
- Alle 12 Reportings + 7 Bindings von ZHC selbst provisioniert (inkl. `precipitation`); **keine** manuellen Reporting-Fixes nötig
- **Einheiten real:** pressure **hPa** (nicht kPa wie Z2M-Doku), Wind **km/h** (nicht m/s), precipitation mm `total_increasing`
- Live-Nachweis: humidity 51→42 % / Wind + Richtung / Gust innerhalb 95 s
- Battery **73 %** (0 %-Anfangsproblem nach Sonnenlicht aufgelöst); `capacitor_voltage` lädt mit Sonne; `voltage` unknown
- **Kein** `weather.`-Entity von Z2M — Wetterzustand nur als `sensor.wetterstation_weather_condition` (z. B. „cloudy")
### DWD-Integration hg1337/homeassistant-dwd (installiert 15.11.2026)
- **HACS** (`hg1337/homeassistant-dwd` v2026.10.0, Category `integration`), Core-Restart nötig zum Laden; Setup via Config-Flow: Station **P339 „Freystadt-Oberndorf"** (14 km, Messdaten+Forecast), `current_weather: hybrid`, `forecast: true` → `weather.freystadt_oberndorf`
- **`weather.get_forecasts` hourly: 244 Einträge MIT `precipitation_probability`** (met.no kann das nicht!) + precipitation, cloud_coverage, dew_point, pressure, wind_gust_speed
- DWD-Config-Flow-Falle: **max. EIN aktiver Flow pro Integration** — halbfertige Flows blockieren mit Abort `already_in_progress`; erst den hängenden Flow zu Ende führen (flow_id behalten!), nicht neue starten
- `sensor.regenwahrscheinlichkeit_6h_dwd` (trigger-basiertes Template, /30 min, DWD hourly, **max** `precipitation_probability` der nächsten 6 h) — 2. Block-Item in configuration.yaml `template:`-Liste
## Wetter-Dashboard (gebaut 15.11.2026)
- **View „Wetter"** im Default-Dashboard (Tabs: Home/Jalousien/Licht/**Wetter**) — via `lovelace/config/save` gebaut, View-Path `wetter`
- **HACS-Karten (installiert 15.11.):** `clock-weather-card` (pkissling), `lovelace-hourly-weather` (decompil3d), `weather-radar-card` (jpettitt, DWD-Quelle), `lovelace-windrose-card` (aukedejong), `MeteoalarmCard` (MrBartusek) — alle via HACS-WS (`hacs/repositories/add` + `hacs/repository/download`, Category `plugin`), Ressourcen verifiziert (HTTP 200)
- **Aufbau:** Meteoalarm-Card (DWD-Warnstufe) → Grid 2-spaltig: Clock-Weather (Forecast met.no + Ist-Temperatur vom WS90 via `additional_sensors`), Hourly-Weather (12 h), DWD-Regenradar (2 h), Windrose (WS90 Wind), ApexCharts Luftdruck (absolut, 48 h) + ApexCharts Regen 7 Tage (`precipitation` mit `group_by: delta/1h`) → Entitäten-Liste „Regen & Bewässerungs-Gates" (Warnstufen, regen_heute/monat/7_tage/regenprognose_6h, beide Gates)
- **Konventionen:** Mushroom/native Cards erlaubt, Bubble Card verboten (Skill `home-assistant-dashboard-conventions`); die 5 Custom-Cards sind Wetter-spezifische Ausnahmen nach Nutzer-Freigabe
- **Offen:** „go DWD" — hg1337/homeassistant-dwd via HACS installieren, `regenwahrscheinlichkeit_6h` (DWD `precipitation_probability` hourly) als zweites Gate-Kriterium; DWD-Vorhersage könnte auch `clock-weather-card`/`hourly-weather` füttern
## WS90-Regen-Automationen (gebaut 15.11.2026)
- **A — Regen-Sperre:** `binary_sensor.bewaesserung_regen_sperre` (Template-Config-Flow) = `rain_status` on ∨ `sensor.regen_heute` ≥ 3 mm ∨ `sensor.regenprognose_6h` ≥ 0,5 mm (met.no-Mengensumme) ∨ `sensor.regenwahrscheinlichkeit_6h_dwd` ≥ 60 % (DWD-Wahrscheinlichkeit). Fail-open (unbekannte Werte = 0 = nicht sperren). **Zwei unabhängige Vorhersage-Quellen** — das Gate sperrt, wenn eine von beiden Regen meldet.
- **B — Statistik:** `sensor.regen_heute`/`sensor.regen_monat` (utility_meter daily/monthly auf `sensor.wetterstation_precipitation`), `sensor.regen_7_tage` (statistics `change`, 168 h), `sensor.regenprognose_6h` (trigger-basiertes Template in configuration.yaml, /30 min + Start, `weather.get_forecasts` hourly, **Summe** `precipitation` der nächsten 6 h — met.no hourly hat **keine** `precipitation_probability`, Wahrscheinlichkeits-Gate daher unmöglich).
- **C — Frost/Sturm:** `binary_sensor.bewaesserung_frost_sturm_sperre` = Temp < 3 °C ∨ Böen > 40 km/h ∨ Sensoren unavailable (**fail-closed, bewusst: tote Station = keine Bewässerung**).
- **D — DWD-Push:** `automation.dwd_warnung_freystadt_push_ab_stufe_3` (automations.yaml, id `dwd_warnung_freystadt_push_20261115`): `numeric_state` above 2 auf `sensor.stadt_freystadt_aktuelle_warnstufe` → Push `notify.mobile_app_iphone_dominik` mit `warning_1_headline`/`warning_1_description` (+ Hinweis bei warning_count > 1).
- **E2E:** Gates mit echtem Wetter (−1,3 °C, rain_status on → beide `on`); DWD-Push via State-Override 1→3 mit TEST-Attributen (`last_triggered` 06:56:48Z), danach State+Attribute restoriert; `check_config` grün (nur bekannter Dimmer-Schlafzimmerlicht-Fehler).
- **Files:** configuration.yaml (Template-Block als Item in bestehendem `template:`-Block eingefügt), automations.yaml (Append); Backups `*.hermesbak-20261115` im selben Ordner. Rollback: Backup zurückkopieren + `template.reload` + `automation/reload`.
- **Verwaltung:** Gates/Statistik-Entities via Config-Flow-Options (GUI) änderbar; `regenprognose_6h` via configuration.yaml; verwaiste Entität `sensor.regenwahrscheinlichkeit_6h` (erste Version, Wahrscheinlichkeits-Ansatz) ist per Registry `disabled_by: user` versteckt — endgültiges Löschen nur via UI (WS-Delete-Command fehlt in 2026.10).
- **Pumpe noch offen:** `switch.bewaesserungspumpe` trägt die Gates noch nicht als Bedingung — Klärung „wie wird die Pumpe heute geschaltet?" steht aus. Gate-Bedingungs-Snippet: Skill `irrigation-rain-gates`.
## Xenia Kaffeemaschine (Stand 11.10.2026)
- ESP32 FW 3.9, IP 10.0.50.128 (VLAN 50, SSID IoT), REST `/api/v2/overview` (enthält MA_CUR_PWR in A!), `/api/v2/machine/data|status|control`
- **WARNUNG: MA_CUR_PWR ist AMPERE** — Power (W) = MA_CUR_PWR × Spannung L1 (`sensor.sn_3007105790_metering_voltage_l1` ≈ 234 V)
- Sensoren: `sensor.xenia_machine_data` (REST, scan_interval 1s, attr-basiert robust), `sensor.xenia_current_power_2` (GUI-Template, W), `sensor.xenia_total_energy_2` (Integration daraus), `sensor.xenia_status`, `switch.xenia_power` (Alexa-Pfad, rest_command control), Wrapper `sensor.xenia_active_power` (Disagg)
- **Fix 11.10.:** `xenia_current_power_2` war seit ~Aug tot (Entity-Rename `xenia_current_power`→`current_power_consumption` brach GUI-Template-String) → neu: `state_attr('sensor.xenia_machine_data','MA_CUR_PWR')|float(0) × voltage_l1|float(0)`; Metadaten (W/power/measurement) via Options-Flow komplett erhalten. Lesson: GUI-Template-Strings überleben Entity-Renames NICHT; REST-Sensoren feuern nur bei Wertänderung (idle = wenige History-Punkte ≠ offline); ESP32-Ping-Jitter (bis 550 ms) ist Power-Save, HTTP ist schnell (12–50 ms)
- **OFFEN (manuell, Setter defekt):** Web-UI http://10.0.50.128: `MA_MAX_AMPERE` 0→10, `MA_SET_TIMER_ECO_MA` 0→5 restaurieren (Fehlschrieb 05.10.)
- 4 Leichen im HA-Config-Dir: xenia_fix/modern/patch/remove_di.py (Alt-Sessions, ignorieren)
## EMHASS Batteriesteuerung
- **Endpoint:** `http://10.0.30.10:5000` (v0.18.4)
- **Architektur:** EMHASS = Sole Optimizer. Virtuelle Batterie **12,32 kWh** (SMA SBS 7,2 kWh nutzbar + Marstek 5,12 kWh). Bis 03.11.2026 stand hier fälschlich 16 kWh (11k + 5k) — gemessen aus 10 Tagen Lade-/Entladehistorie, siehe unten.
- **Config API:** `POST /set-config` überschreibt GESAMTE Konfig (kein Partial-Update!). Immer alle Felder senden. Siehe Solution Doc `integrations/2026-10-02-emhass-set-config-overwrite-pitfall.md`.
- **Aktuelle Config (2026-11-03):**
- Capacity **12320 Wh**, Charge/Discharge 6700 W, Efficiency 0.9 (Backup: `/config/config.json.bak-20261103` im Add-on-Container)
- ⚠️ `config.json` liegt im Add-on unter `/config/config.json`, NICHT über die Add-on-Options (dort nur Solcast-Keys). Änderung = Datei editieren + `docker restart app_5b918bf2_emhass`.
- Target SoC 0.15 (15%), Min SoC 0.1, Max SoC 1.0
- `set_battery_dynamic: True`, `set_use_battery: True`
- SoC sensor: `sensor.total_soc`, Power sensor: `sensor.batteries_power_out_total`
- **Kaskaden-Automation** (`1774430238377`, ON): EMHASS target → BYD (803 Auto default, 802 bei `target<=0 && pv<100`) + Marstek (Rest via `sensor.marstek_target_power`)
- **Template Sensoren:** `sensor.smart_battery_target` (EMHASS), `sensor.marstek_target_power` (Plan A: smart_target − actual_BYD_discharge). `sensor.sma_target_power` ENTFERNT (Double-Counting Bug).
- **Cutover (2026-10-09):** v2 (`emhass_optimizer_v2.py --publish --allow-grid-charge`) ist EINZIGER Produzent; Cron `a32005d62226` (runner `emhass-optimizer-v2-runner.sh`). v1 + Shadow-Collector `d046e808f543` + Watchdog `19aef2351273` pausiert = Rollback-Hebel. Race-Guard 30/20 s. Details: [[reference/emhass-cascade-automation-architecture]]
- **Cutover 2 (2026-11-02 16:19): Produzent lebt jetzt IN Home Assistant.** AppDaemon-Add-on `a0d7b954_appdaemon` (v0.19.3, `boot: auto`), App `emhass_optimizer` unter `/mnt/data/supervisor/app_configs/a0d7b954_appdaemon/apps/` (Quelle: `~/scripts/emhass_app/`: `emhass_core.py` = per AST verbatim aus v2 extrahierte Mathematik, `emhass_cycle.py` = Input-Phase, `emhass_app.py` = Trigger/POST/Verify/Ledger). Trigger `:04/:19/:34/:49`, Ledger `/share/emhass/ledger.jsonl`, Fehler → `persistent_notification`. **Kein Long-Lived-Token mehr im Produktionspfad** (AppDaemon bekommt HA-URL+Token automatisch vom Supervisor); EMHASS-Add-on bleibt unangetastet (nur `/action/dayahead-optim` + `/action/publish-data`). Hermes-Cron `a32005d62226` **pausiert = Rollback** (`cronjob_manage resume`, Token-Symlink existiert weiter). Parity-Nachweis: 19/19 Unit-Tests Kern↔v2 + Payload-Gate `PARITY OK` (v2 `--dump-payload` vs. Shadow, 48 Slots, 0 Warnungen). E2E 16:04 (Cutover) und 16:19 (erster Einzelproduzent, CSV synchron 16:19:00). SolDoc `architecture/2026-11-02-emhass-producer-appdaemon-cutover.md`
- **Publish-Pfadbruch 11.10. (GEFIXT ~20:30 UTC):** Nach HA-Core-Restart (Recorder-Incident) DEADLOCK: `p_batt_forecast`/`soc_batt_forecast`/`plan_*` sind set_state-Entities (überleben Restart NICHT), v2 liest sie hart → jeder Tick FATAL → nichts publizierte je wieder. Zweiter RC: `rest_command`-URLs `localhost:5000` — HA läuft im HOST-Netz, Addon in HassIO-Bridge; nach Restart connection-reset (10.0.30.10:5000 ging stets). Fix: beide URLs → `http://10.0.30.10:5000` (Backup `configuration.yaml.bak-20261011-restcmd`) + `rest_command/reload`. Heal-Pattern: `POST :5000/action/publish-data` direkt ans Addon. Verifikation: v2-Tick 20:32 komplett, plan_* 48 Slots, Kaskade folgt. ⚠️ Legacy-Automation „Trigger EMHASS" (*\/15): dayahead-call 400 (Payload ohne pv/load-Arrays) — funktional durch v2-Cron abgedeckt, disable/fix offen. Solution Doc `integrations/2026-10-11-emhass-publish-path-break-after-restart.md`
- **Token-Pfad (seit 02.11.2026):** HA-Token kanonisch `~/.hermes/secrets/ha_token.txt` (0600, aus 1P `op://Hermes/ewviwqhnpcpd2tg2gh5jbv76xm/password`), `/tmp/ha_token.txt` nur Symlink; `~/.hermes/scripts/ha-token-ensure.sh` heilt fehlenden Symlink/Token bei jedem v2-Lauf. Grund: /tmp wurde beim Boot 30.10. geleert → v2-Cron starb 3 Tage still (`FATAL: token file missing`), während `automation.trigger_emhass` per `/action/publish-data` weiter die **letzte Zeile** des alten Plans postete (frische Zeitstempel, eingefrorene Werte).
- **Cron-Schedule (seit 02.11.2026):** `a32005d62226` nicht mehr `every 15m` (Anker driftet in den Race-Guard → dauerhaft `REFUSED rc=2`), sondern `4,19,34,49 * * * *` Europe/Berlin.
- **Watchdog:** `3a99e3837250` `check_emhass_plan_freshness.sh`, stündlich :12, silent-on-healthy, Alarm wenn die **Result-CSV-Mtime** >40 min alt ist oder der Plan-Horizont <10 h (Telegram). ⚠️ **Keine Sensor-Zeitstempel als Liveness nutzen:** `automation.trigger_emhass` ruft alle 15 min `rest_command.emhass_publish_data` und frischt `p_batt_forecast`/`soc_batt_forecast` bei eingefrorenem Plan auf (dieselbe Maske wie beim 3-Tage-Ausfall); der Display-Publisher tut dasselbe für `plan_*`. Nur `opt_res_latest.csv` schreibt ein echter `dayahead-optim`. Test-Overrides `EMHASS_MAX_AGE_MIN` / `EMHASS_CSV_PATH`. Der alte Kaskaden-Watchdog `a2a1b429bc2e` ist seit 25.09.2026 pausiert (und enthält ein SSH-Klartextpasswort in `cron/jobs.json`).
- **`automation.trigger_emhass` (1774260225020) ist seit 03.11.2026 06:40 OFF** (`initial_state: false`, Backup `automations.yaml.bak-20261103-0620`). Sie rief nur alle 15 min `rest_command.emhass_publish_data` und hat damit einen eingefrorenen Plan mit frischen Zeitstempeln übermalt — die zentrale Maske beider EMHASS-Ausfälle. Der Produzent publiziert selbst; die Automation ist nicht mehr nötig.
- **Incident 03.11. 01:04–05:49 (5 h still):** Idempotenz-Bug in der App — `_slot_key` war `%Y%m%d_{minute//15}` → nur 4 Marker/Tag, danach `already ran … skip` für jeden weiteren Tick (Optimierung lief nur 4×/Tag um 00:xx). Fix: Key `%Y%m%d_%H%M`; App-Arg `run_on_start` als Ops-Hebel für Sofort-Zyklus nach Deploy. Warum unbemerkt: Watchdog maß `p_batt_forecast`, das die Publish-Automation alle 15 min auffrischte → jetzt CSV-Mtime. Verifiziert: Zwangszyklus 05:49:45 + planmäßiger Tick 06:04 nach dem Fix.
- **Display-Publisher (seit 02.11.):** Cron `4bc13a052329` (`:05/:20/:35/:50`, `no_agent`) → `emhass-extra-publisher-runner.sh` → `emhass_extra_publisher.py`. Spiegelt die EMHASS-CSV (per SSH, read-only) in `sensor.plan_pv_forecast` / `plan_netz_forecast` / `plan_last_forecast` fürs Akku-Dashboard. Optimiert **nie**; braucht den HA-Token nur zum Schreiben dieser drei Anzeige-Sensoren.
- **Historie:** Phase-2 Shadow (08.10., Dual-Solve, Deferrables als Phantom-Last entfernt, CSV 17 Spalten); Arbitrage-Flip produktiv (08.10. 22:20, `set_nocharge_from_grid` false).
- **Backup:** `.bak.20261001_175804` für configuration.yaml + automations.yaml
- **NFS-Backups (Fix 2026-10-07):** Supervisor-Mounts `Backup_NFS` (usage=backup) + `Medien_NFS` (usage=media) → **10.0.20.100:/pool01_n2_redundant/HomeAssistant** (vorher tote 10.0.30.100, verloren beim NAS-Crash-Reboot 03.10.). Volle automatische Backups ~03:27 UTC nightly. Monitoring: Hermes-Cron `2006a91fba21` (Alert bei Backup-Alter >30h). Lösungsdoku: `docs/solutions/bug-fixes/2026-10-07-ha-audit-nfs-mount-failure-after-nas-crash.md`
## PV-Anlage & Forecasts (Stand 11.10.2026)
**Arrays/WR:**
| Array | WR | Strings | kWp/Real | Forecast-Lage |
|---|---|---|---|---|
| Dach Teil 1 | SMA SB SN 3006252807 (10.0.50.201) | 2 (A+B, je String Ausrichtung unklar, SO/SW-Mix) | ~5,7 kWp; 6,7 kWh/11.10. | nur via FS-Site "Dach Südwest" (225°/23°/5760 W) — Zuordnung zu WR unbelegt |
| Dach Teil 2 | SMA SB SN 3006252817 (10.0.50.203) | 2 (dto.) | ~4,0 kWp; 6,7 kWh/11.10. | FS-Site "Dach Südost" (145°/24°/4000 W) — Zuordnung unbelegt |
| Speicher | SMA SBS SN 3007105790 (10.0.50.202, BYD) | keine PV-Strings | — | n/a |
| Zelt | Hoymiles HM-1500 (OpenDTU 10.0.40.55) | 2 Module zeltartig SW/NE aneinandergelehnt | 1,5 kWp; 2,1 kWh | ✅ FS-Sites "Zelt Südwest"+"Zelt Nordost" (65°/225°+65°/45°, je 750 W) seit 11.10. |
| Schuppen 1 | Hoymiles HMS (Limit 2250 W) | SW, ~5° flach | 2,2 kWp; 2,9 kWh | FS-Site ✓ (225°/5°/2200) |
| Schuppen 2 | Hoymiles HMS (Limit 2250 W) | SW, ~5° flach | 2,64 kWp; 3,5 kWh | FS-Site ✓ (225°/5°/2640) |
Aggregation: `sensor.pv_production` = min_max über 5 Sensoren (2×SMA grid_power + 3×Hoymiles) ✓ korrekt.
⚠️ `sensor.pv_daily_energy_total` = SUMME der 3 SMA daily_yields OHNE Hoymiles (−11%) und inkl. SBS-Batteriedurchsatz — nicht als PV-Tagesertrag verwenden!
**Forecast-Systeme (3 parallel):**
1. **Solcast** (Custom, Entry `01KKTKEN0VAWQTQCS4WWCQJWPT`) = PV-Input für EMHASS-v2-Optimizer (pooled aus `*_prognose_heute/morgen/tag_3` detailedHourly). Sites: "Schön Rohr" (043e-b831-88bf-b087, 16 kW, Azimut -132,6°/Tilt 19°, Freystadt = gemittelte Gesamtanlage) AKTIV; "Ogdak Netherlands" (59c8-caae-52f5-1686, Solcast-DEMO-Site Apeldoorn/NL) seit 11.10. **excludiert** (war ~9,6/23,4 kWh Phantom-PV!). API-Quota 30/Tag (Site-getrieben), hard_limit 100.
2. **forecast.solar** (Core, 4 Subentries): Dach SW/SO, Schuppen 1/2 — Dashboard-only, kein Optimizer-Input. Nutzer-Beschluss 11.10.: **komplett neu bauen** (war unbedacht eingerichtet). Achtung: API liefert lokale Timestamps; HA-Sensoren zeigten +2h-versetzte Werte (physikalisch unmögliche "Resttag"-Energie nach Sonnenuntergang) — beim Rebuild prüfen.
3. **EMHASS-Addon intern** (open-meteo + pvlib, generisches Fronius/CSUN-Modell) — irrelevant, v2-Optimizer published eigene Pläne.
**Bekannte Issues (11.10.):**
- ✅ TZ-Bug `emhass_optimizer_v2.py::build_pv_series` **GEFIXT 18:29** (`tzinfo=BERLIN` statt utc, Backup `.bak-20261011-tzfix`): Live-Tick 18:28 zeigte erstmals korrekte Abendkurve (36 W/18:30, 0 W nach Sunset statt ~1750 W Phantom).
- ✅ Reload-Race-Gefahr **GEHÄRTET 18:47**: `collect_solcast_pools()` mit 3×10s-Retry (Solcast-Options-Reload setzt Sensoren ~16s `unavailable`; 18:43-Tick crashte laut doctrine-konform).
- ✅ forecast.solar: **Zelt-Sites ergänzt** — "Zelt Südwest" (65°/225°/750 W) + "Zelt Nordost" (65°/45°/750 W), Area Photovoltaik. Dach/Schuppen-Entries validiert (SW/SE-Split ~62/38 ↔ 5,76/4,0 kWp passt zu Messdaten). HA-Parser ist KORREKT (Bibliothek fordert `time=utc` an; früherer +2h-Verdacht war Eigen-Parse-Artefakt).
- ✅ Solcast: `auto_dampen=True` + `get_actuals=True` + Kalibrierquelle `sensor.pv_production` (Validator-Kopplung "dampen_without_actuals" beachtet). Dämpfung lernt ab jetzt.
- ✅ `sensor.pv_daily_energy_total` repariert: Hoymiles REIN, SBS-Batteriedurchsatz RAUS (19,44→22,03 kWh, real ~22,4).
- 🟡 Solcast-Single-Site "Schön Rohr" = Mittelung (1 Azimut/Tilt für 6 Arrays) — Struktur grob, aber jetzt kalibrierend gedämpft; Feintuning über auto_dampen-Daten (Tage) beobachten.
- ✅ **Sauna-Shelly misst NETTO** (HM-1500 speist auf dem Sauna-Stromkreis rück): Shelly = Kreislast − Zelt-PV (validiert 11.10.: Steigung −0.983, r=−0.9985; Integrale 2,07 vs. 2,13 kWh). Template `Sauna Active Power` GEFIXT 19:39: `max(0, ΣPhasen + hm_1500_power)` mit float(0)-Guards — liefert jederzeit die wahre Sauna-Last, "Rest"-Helfer korrekt.
- Solution Doc: `docs/solutions/integrations/2026-10-11-solcast-sample-site-contamination-and-tz-shift.md`
## Garagentor (free@home ch0003) — Flanken-Toggle-Semantik
- **Kanal:** `switch.garagentor` = free@home Schaltaktor `ABB20C351F51/ch0003`, treppenlicht-parametriert (Kanal nach Aktivierung AN bis Timer-Ablauf). `cover.garagentor` = Template-Cover darüber (open/close = je EINE Kanalaktivierung).
- **Motor toggelt auf JEDE Kanalflanke.** Einzelimpuls = sauber Umschalten (belegt: 17:51 Puls → schloss in ~90s). **Zwei schnelle Flanken = Start-Stopp** (belegt: 17:07 mein OFF→ON-Doppelpuls, 17:48 Nutzer-Doppelklick — jeweils blieb das Tor offen!). Doppelklick-Gewohnheit wirkt der Schließfahrt aktiv entgegen.
- **BUG (seit 05.10.):** `switch.garagentor` = `unknown`, 0 Logbook-Events — Statusrückmeldung SysAP→HA für ch0003 tot. SysAP-REST-Zugang ist bekannt (Local-API-User `Installer`, s. Abschnitt „free@home Local-API" unten), SSH-Addon gestoppt.
- **Automations (2026-10-10, REST-config):** `warn_offen_beim_verlassen` (Person weg >2min + Garagentor/Esszimmertür offen → time-sensitive Push mit CLOSE_GARAGE-Button) + `garagentor_push_close` **v8 Single-Edge** (Guards: offen+90s stabil+45s Anti-Doppeltipp; EIN switch.turn_on, KEIN turn_off-Präludium; 45s-Verifikation per Neigungssensor; Retry erst nach 480s; ehrliche Fehler-Push). Tag `warn_offen_beim_verlassen` aktualisiert Notifications.
- Nur 2 physische Öffnungssensoren im Haus: Garagentor (Neigungssensor+Cover) + Esszimmertür (`binary_sensor.esszimertur_contact`, Aqara). free@home-Panels sind Taster, KEINE Fensterkontakte.
- Solution Doc: `docs/solutions/integrations/2026-10-10-freeathome-garage-impulse-toggle-semantics.md`
## free@home SysAP XMPP-Wedge & Remote-Reboot (Stand 12.10.2026)
- **Chronik:** 05.10. IqTimeout-Massenausfall (22 Entities, Fix: 120s-getAll-Timeout+300s-Keepalive, ephemeral in Container). **11.10. 19:56 erneuter Totalausfall** — diesmal trotz Patch: XMPP-RPC-Dispatcher lebte (echoTest/HW 0,1s), aber `getAll` hing serverseitig (>280s, REST liefert dieselben Daten instantan). HA-Restart wirkungslos (Fehler kam direkt nach frischem HA-Start 19:53).
- **HEBEL: `RemoteInterface.reboot(0)` via XMPP** — derselbe RPC, den die SysAP-Web-UI nutzt (Qt-WASM, kein REST-Endpoint). Funktioniert AUCH im Wedge (ACK 7,6s, ~4min Downtime, Konfig unversehrt). Param: RestartEraseCode 0=simpleRestart, 1=factoryReset(!), 2=resetUsingFlags, 3=factoryResetWithoutIA — **nur 0**. Danach `homeassistant/reload_config_entry`.
- **Recovery ist push-gestaffelt (Normverhalten, kein Defekt):** Steuerplane (Switch/Light/Cover-Pos) sofort aus getAll-Seed; Sense-Plane (Panel-Temp odp0010, Climate, BinSens, Locks) erst beim ersten Bus-Push (Min–Std). Identisch nach 05.10.-Vorfall (Recorder-History belegt).
- **Garagentor-switch BUG bleibt:** ch0003-Status weiterhin `unknown` (Status-Datapoint seit 05.10. tot, auch nach SysAP-Reboot 12.10.). Befehlspfad funktioniert. → dauerhafte Lösung nur via Local-API-Migration.
- **Kollateral 12.10.:** Automation „Dimmer Schlafzimmerlicht" (1697532906675) von HA deaktiviert (Trigger-Entity bei setup_error aus Registry geräumt). Analyse: leere Action-Hülle ohne Wirkung — echte Logik in „Helligkeit Schlafzimmerlicht"/`script.adjust_lights_schlafzimmer` (intakt). Empfehlung: löschen.
- **Migrations-Kandidat:** kingsleyadam/local-abbfreeathome-hass (REST+WS statt XMPP; SysAP-Kompatibilität verifiziert: REST 200, WS-Frame-Empfang ok, restApiStatus enabled). Impact: 152 Entities, 29 Refs automations.yaml, 241 Refs Lovelace. **WebSocket live getestet 12.10.: verbindet + pusht.**
- **Watchdog AKTIV (12.10.):** Cron-Job `43612c6d52b6` (jede 15 min, script-only, still bei Gesundheit, Telegram-Alert bei Intervention): `setup_error` ≥30 min → automatischer `reboot(0)` via persistentem Rescue-Kit `/config/fah_rescue/rescue.py` (HA-Container, überlebt Recreation) → SysAP-HTTP-Wait ≤8 min → `reload_config_entry` → Verifikation. Schutz: 6h-Reboot-Cooldown, Lock, Blind-Alert 1×/Tag, Throttle-Hinweis 1×/Tag. Lokal: `~/.hermes/scripts/fah_watchdog.py` (`--selftest` prüft Kette read-only).
- **Watchdog-Reparatur 06.11.2026 (war blind + interventionsunfähig):** Meldung „BLIND (RuntimeError)" kam, weil `get_token()` bei **jedem** Tick `op read` gegen 1Password machte — Service-Account war rate-limitet („Too many requests"; Reads ~1.000/h + Tageslimit). Zweiter, schwererer Defekt: `guest_exec()` hardcodete `root@10.0.20.93` (ms-a2-2), VM 106 lief aber auf **proxmox3** → `Configuration file nodes/ms-a2-2/qemu-server/106.conf does not exist`, der Rettungs-Reboot hätte nie gefeuert. Fix: Token cache-first aus `~/.hermes/secrets/ha_token.txt` (1P nur on-miss/401, Fallback auf Cache bei 1P-Ausfall) + `resolve_pve_host()` via `pvesh get /cluster/resources --type vm`. Verifiziert: `--selftest` → „Kette intakt" (ECHOTEST_OK, GETALL_OK 40,8 s), Entry `freeathome` = loaded. 1P-Limit hielt >8 min an (kein lokaler Verursacher-Prozess) — betrifft alle `op`-Skripte. Solution Doc: `docs/solutions/bug-fixes/2026-11-06-fah-watchdog-blind-1p-ratelimit-node.md`.
- Solution Doc: `docs/solutions/integrations/2026-10-12-freeathome-sysap-xmpp-rpc-wedge-reboot-fix.md`
## HA-Freeze via Memory-Leak + Verbindungs-Fix (Stand 08.11.2026)
- **Freeze (2× am 08.11.):** HAOS-VM 106 (12 GB) erstarrte — Kernel lebte (ICMP ok), Userspace tot (:8123 refused, SSH-Banner-Timeout, Guest-Agent down) → nur `qm reset` hilft. Kernel-Beweis des toten Boots: 391× „Under memory pressure" ab 14:51 (10,3 h nach Boot). **RCA: freeathome v1.0.12-Reconnect-Pathologie** (wait_for_connection/aiohttp ohne Timeout, blockierende SSL-Init im Event-Loop, reconnect=True → Client-Akkumulation) als Reaktion auf die SysAP-XMPP-Session-Instabilität. SysAP selbst gesund (REST 200, WS 101, 5222 connectet). Solution Doc: `docs/solutions/bug-fixes/2026-11-08-ha-freeze-freeathome-xmpp-leak.md`.
- **Fix 1:** Integration **v1.0.13** (PR #317 „monitor no longer stops updates") via `update/install` + Core-Restart. **E2E bewiesen:** REST-Write `ABB24F351F51.ch0001.idp0000=1` → `switch.techniklicht` in **1,5 s** in HA aktualisiert (XMPP-Event-Stream intakt).
- **Fix 2:** VM-RAM **12→16 GB** (`qm set 106 --memory 16000`; balloon=0 → Stop/Start nötig; Node-Headroom vorher geprüft).
- **Fix 3 — Watchdog gehärtet:** Stufe 0: `ha_http_up()`+`vm_agent_alive()` beide tot = Freeze → nach 2 Ticks (~30 min) **autom. `qm reset 106`** (6 h Cooldown, Boot-Verifikation 10 min). Stufe 0b: **Memory-Probe je Tick** → `~/.hermes/scripts/ha_mem_log.jsonl`; Alerts ab HA-Container 9,5 GiB / avail<1,5 GiB / Steigung ≥250 MiB/h (2-h-Fenster). Selbsttest + Tick grün.
- **Pitfalls:** HAOS-Host-Shell = busybox-artig: `/dev/tcp` gibt FALSE NEGATIVE, `nc`/`python3` fehlen → TCP-Tests via `docker exec homeassistant python3` (socket.create_connection). `curl -m telnet://` Exit 28 beweist nichts. HA-Log-Dateien: `.log.1` war von **2025** (Jahreszahl beim Grep prüfen!), aktuelles Log nur im Journal (`docker logs`). journald volatile → Kernel-Beweise des Vorboots nach Reboot weg. Custom-Integration-Logger WARNING-gefiltert → fehlende INFO-Zeilen sind kein Beweis. Cron-Fehler „worker exited before ownership acknowledgement" = Hermes-Dispatch, nicht Skript (failure_streak beobachten).
## free@home Local-API & Wanddisplay-Widgets (Stand 03.11.2026)
- **Zugang:** REST `https://10.0.50.40/fhapi/v1/api/rest`, HTTP Basic, User `Installer`; Passwort im HA-Config-Entry `freeathome` (`01K6JFZYN6J1FWDSTEHD5H4BHK`) — nur über das Dateisystem lesbar. VM 106 läuft auf **proxmox3 (10.0.20.30)**, nicht auf .93.
- **API v1:** configuration, devicelist, device, datapoint, pairings, sysap, notification, virtualdevice, ws. Swagger `https://10.0.50.40/swagger/`, Spec `/fhapi/v1/openapi.yaml`. **Kein Panel-/Widget-Endpoint.**
- **Display:** `ABB6BC5495EA` „free@homeTouch 7\"" (deviceId 1038), Raum Essbereich (EG) — **nur ein Display im SysAP** (die drei HA-HomeKit-Einträge sind Bridge-Accessories, keine Panels).
- **Widgets = Panel-Kanäle `ch0000`–`ch000f` + `/pairings`:** 9 belegt, 7 frei; leere Slots auto-benannt `" 1,<row>,<col>"` (4×4-Raster, Kanalindex zeilenweise). Kanäle `ch0010`–`ch001c` = Türsprech-Funktionen.
- **Live-Status** nur über Ziel-Aktor-`odp` lesen — Panel-Kanäle sind eigene, nicht gespiegelte Datapoints.
- Solution Doc: `docs/solutions/integrations/2026-11-03-freeathome-panel-widgets.md` · Skill-Ref: `smart-home-automation/references/freeathome-local-api.md`
## BLE-Proxies / Trilateration (Stand 01.11.2026)
**Bermuda** (Entry `01M1CF5AT5FAKMBHTMVCX0DRBS`) = Trilateration. HA hat KEINEN lokalen BT-Adapter (VM, `manager.adapters = {}`), alles läuft über Remote-Scanner.
| Proxy | Typ | Area | connectable |
|---|---|---|---|
| shellypro3em-08f9e0e98b9c ("Stromverbrauch Heizung") | Shelly | Heizraum | ❌ |
| shellypro3em-08f9e0e952e0 ("Strommessung Sauna") | Shelly | **Garage (EG)** — Gerät sitzt in der Garage, nur die Sauna steht auf dem Garagendach (Dachterrasse OG) | ❌ |
| shellyplus1-d0ef76d91930 ("Bewässerungskreis vorne") | Shelly | Garten | ❌ |
| 6× shellyplus1 (Beete/Hochbeete/hinten/mitte/Pumpe/Licht Terrasse Gartenhaus) | Shelly | Garten | ❌ |
| shellyplus1-a0a3b3c396e4 ("LED Streifen Windfang") | Shelly | Windfang | ❌ |
| shellypro4pm-841fe89726d0 | Shelly | Garten (gesetzt 01.11.) | ❌ |
| ble-proxy (10.0.50.206) | ESPHome **2026.10.2** | Wäscheraum | ✅ |
| esp32c3-supermini-buero-eg (10.0.50.147) | ESPHome | Büro EG | ✅ |
| esp32c3-supermini (90:DA:72:88:EB:42) | ESPHome | System | OFFLINE |
→ 13/13 aktive Proxies (`sensor.bermuda_global_active_proxy_count`), alle Mode **auto**; jede Shelly liefert 5–21 distinkte Geräte/Minute (Diagnostics `data.devices[*].stamps`, 45-s-Fenster).
**Area-Zuordnung der Scanner (Falle 01.11.):** Bermuda nimmt die Area NICHT vom Shelly-Gerät, sondern vom **Bluetooth-Geräte-Record** (`"<Name> (<MAC>)"`, angelegt von der bluetooth-Integration). Beide Records müssen dieselbe Area haben, sonst gewinnt der BT-Record. Beispiel Sauna: Shelly-Gerät + 3 Phasen-Kinder auf `garage` gesetzt → Bermuda zeigte weiter „Dachterrasse (OG)", bis auch der BT-Record `Strommessung Sauna (08:F9:E0:E9:52:E2)` auf `garage` stand. Danach: `area_name=Garage`, `floor_name=EG`. Area `garage` hatte floor=None → auf `eg` gesetzt.
**Shelly als BLE-Scanner freischalten (der einzige Weg, 01.11. verifiziert):** nicht per RPC (`BLE.SetConfig enable=true` reicht NICHT, `BLE.GetStatus` bleibt `{}`), sondern HA-Options-Flow der Shelly-Integration:
1. `POST /api/config/config_entries/options/flow` `{"handler": <shelly entry_id>}` → Formular mit **einem** Feld `ble_scanner_mode`: `disabled | auto | active | passive`, **Default `auto`**
2. `POST /api/config/config_entries/options/flow/<flow_id>` `{"ble_scanner_mode":"auto"}` → `create_entry` (löst Reload des Shelly-Entry aus)
3. Verify: Shelly-Scanner erscheint im BT-Manager (`scanning=true`, `last_detection` frisch) — Device-seitig bleibt `BLE.GetStatus` leer, das ist normal.
4. Beweis (A/B, 01.11.): `disabled` → Scanner weg (13→12), `auto` → wieder da (12→13). Die Option ist die Steuerung; der Wert selbst ist im REST-/WS-Entry-Listing NICHT sichtbar (`options={}`) — nicht als Statusquelle nutzen, sondern die Scanner-Liste prüfen.
**Wichtig:**
- Shelly-Scanner sind **passiv** (`connectable=False`) → GATT-Geräte (LD2410-Presence, Schlösser, aktive Sensoren) brauchen ESPHome-Proxies.
- 13 Scanner > 3 Slots → HA `bluetooth.auto_scheduler` teilt Scan-Fenster (15 s) im Round-Robin zu; nicht auf `always` stellen (2,4-GHz-Kollision).
- Bermuda cached Scanner-Areas beim Setup → nach Area-Änderung Config-Entry reloaden (REST `POST /api/config/config_entries/entry/<id>/reload`; WS `config_entries/reload` existiert NICHT). Repair-Issue `scanner_without_area` verschwindet danach.
- Neue Distanz-Sensoren (`sensor.*_ble_distance_to_<scanner>`) entstehen erst beim Bermuda-Reload; Werte `None` = Scanner hört das Gerät aktuell nicht.
- Distanzen sind unkalibriert (Default `ref_power=-55`, attenuation 3). **Korrektur 01.11.: `ref_power` ist PRO GETRACKTEM GERÄT** (iPhone/Tag/Schlüssel), NICHT pro Scanner — Bermuda-Entity `number.<device>_ble_calibration_ref_power_at_1m_0_for_default`, `0` = Default. Pro Scanner gibt es nur `attenuation` (Pfadverlust-Exponent, `options.attenuation=3`). Kalibrierung = Gerät auf 1 m neben einen Scanner legen, `sensor.<device>_ble_nearest_rssi` (Default deaktiviert → `config/entity_registry/update disabled_by=null` + Bermuda-Reload) samplen, Median als `ref_power` setzen. Werkzeug: `~/workspace/bermuda_calib.py {status,sample,apply,geometry}`.
- **Geometrie ist der eigentliche Engpass, nicht die Kalibrierung** (Messung 01.11., 30-s-Fenster): 18 von 27 BLE-Geräten werden von ≥3 Scannern gleichzeitig gesehen (Top: 11) — aber **nur im/am Garten**, weil 9 der 13 Scanner dort hängen. Indoor (iPhone Dominik) sieht genau **2** Scanner (`BLE Proxy`, `Büro EG`), beide ESPHome → Area-Ausgabe fürs iPhone unbrauchbar (`Wäscheraum` bei 8,3 m). Vor weiterer Kalibrierung: mehr ESPHome-Proxies indoor (Wohnen/Schlafen/Essen).
- `sensor.<device>_ble_nearest_rssi` / `_nearest_scanner` sind per Default **disabled**; nach dem Aktivieren braucht es einen Bermuda-Entry-Reload, sonst 404 im State-Machine.
- Config-Entry-**Titel** umbenennen geht per WS `config_entries/update {"entry_id":..,"title":..}` (existiert, im UI nicht dokumentiert); `config_entries/reload` existiert dagegen nicht (nur REST).
- **`$HA_TOKEN` in der Host-Env ist veraltet (401)** — funktionierender Token liegt in `/tmp/ha_token`. Skripte müssen die Datei bevorzugen, sonst 401 auf jedem API-Call.
- Shelly-Devices haben Kind-Geräte (Pro3EM `Phase A/B/C`, Pro4PM `Output 0..3`); Area-Zuweisung nur am Eltern-Gerät reicht nicht — Kinder können vereinzelt ohne Area bleiben (Fix 01.11.: `Output 0`/„Brunnenstein" → Garten via `config/device_registry/update`).
## BLE-Proxy Wäscheraum: OS-Update + WLAN-Starvation-Fix (15.11.2026)
- **Ist → Soll:** ESPHome **2026.8.2** (Build 09.09.) → **2026.10.2** per OTA (Upload 7,2 s, Commit 0,72 s). Gerät: `ble-proxy`, MAC C8:C9:A3:C8:65:2C, Board `esp32dev` (klassischer ESP32, 4 MB).
- **Symptom:** sporadische 1–3-s-Aussetzer auf der API (36 Requests/6 min → 2× 1,0 s und 2,9 s), Ping-RTT bis 317 ms, ein TCP-RST auf 6053 bei lebendem ICMP, Handshake-Abbrüche nach mehreren Connect-Zyklen → „hängt sich auf".
- **RCA:** `esp32_ble_tracker` lief mit **interval 1100 ms / window 1100 ms** (Vollduty). ESPHome 2026.10 warnt selbst: *„BLE scan window of 1100ms with wifi on the same radio starves wifi… keep the window at or below 600ms"*. BLE-Scan und WLAN teilen sich den Funk → WLAN wird periodisch ausgehungert.
- **Fix:** `interval: 320ms / window: 300ms` + `debug`-Sensoren. **Beweis nach Flash:** 18/18 API-Requests in 3 min, **0 slow / 0 fail, worst 0,15 s**; Ping 10/10, max 35 ms; Heap free 114,9 KB, Fragmentation 25 %.
- **Neue Entities** (Namen mit Area-Präfix `wascheraum_ble_proxy_*`): `uptime`, `wifi_signal` (−52 dBm), `heap_free`, `heap_max_block`, `heap_fragmentation`, `reset_reason`, `esphome_version`, `button.restart`.
- **Warum vorher kein Update möglich war:** HA legte keine `update`-Entity an (Config ohne `project:`-Metadaten), und im ESPHome Device Builder auf HA lag **keine YAML** — `/config/esphome` wurde erst am 30.10. frisch initialisiert, im Juli-Vollbackup existiert kein `esphome/`-Ordner. Geflasht worden war das Gerät am 09.09. vom **MacBook** (dort lag das OTA-Passwort).
- **Quelle der Wahrheit jetzt:** `/config/esphome/ble-proxy.yaml` + `/config/esphome/secrets.yaml` (Key `ble_proxy_api_key`, `iot_wifi_password`, `ota_password`). OTA-Passwort (aus dem Mac-secrets) bleibt in der neuen Firmware gesetzt und liegt jetzt in 1Password: Item **`ESPHome OTA ble-proxy`** (Vault Hermes). Der IoT-WLAN-PSK liegt in 1P-Item **`WLAN IoT`**.
- **Pitfalls:** (1) `esphome upload --password` ist der **MQTT**-Parameter — OTA-Passwort kommt ausschließlich aus `ota: password:` im YAML. (2) Falsches OTA-Passwort bricht vor jedem Schreibzugriff ab (risikolos). (3) `qm guest exec` killt den Prozessbaum, wenn der Agent-Timeout greift — Compile nur mit `--timeout 1500` fahren. (4) IoT-WLAN-PSK steht **nicht** in 1Password und ist in der Omada-Cloud-UI nicht lesbar; per API `GET /{omadacId}/api/v2/sites/{siteId}/setting/wlans/{gid}/ssids` → `pskSetting.securityKey` (Csrf-Token aus einem echten SPA-Request nötig).
## Related
- [[systems/frigate]] — NVR Integration
- [[systems/noris-ai]] — LLM Vision Provider
- [[reference/ip-map]] — IP Assignments
- [[reference/emhass-cascade-automation-architecture]] — Kaskaden-Architektur Details
## Security-Status
- **CVE-2026-98432: geschlossen** (2026-11-02) — HAOS VM106 läuft `6.18.58-haos` (Fix ab 6.18.56/57). Kernel-Check via `qm guest exec 106 -- uname -r` (QGA aktiv, VM liegt auf proxmox3).
## free@home Zombie-Session (09.11.2026 — 2. IqTimeout-Rezidiv, gefixt)
- **Failure-Mode:** Nach Event-Loop-Blockaden (Galera-SST-Sturm/Ceph-slow-ops 08.11. 19:01–19:21) blieb die XMPP-Session zombie: slixmpp „connected" (keine Connection-lost-Warnungen mehr, kein setup_error), aber set_datapoint → IqTimeout, keine PubSub-Events (Kanari stale). SysAP gesund. Watchdog blind dagegen (HA up, Memory ok).
- **Fix:** `docker restart homeassistant` (qm guest exec auf VM106) → Integration lädt, **E2E: turn_on via HA-API → State-Change in 3,0 s**.
- **E2E-Verifikation IMMER über HA-Service-Call** (testet den XMPP-Write-Pfad), nicht REST-datapoint-PUT (404t auf dieser Firmware — auch /configuration zeigt keine Datapoints, weder alt noch neu).
- **Offen:** Watchdog-Stufe 0c Kanari-Staleness (Vorschlag an Owner).
## free@home setup_error 12./13.11.2026 — SysAP-Reboot wirkungslos, Core-Restart = Fix
- **Verlauf:** 12.11. 16:18 UTC Entry `setup_error` (28/29 Entities `unavailable`), Log `IqTimeout` auf `RemoteInterface.getAll`. Watchdog feuerte 13.11. 05:11 den SysAP-Reboot (`REBOOT_ACKED`, SysAP-HTTP nach ~3 min wieder da), `reload_config_entry` blieb `setup_error`; HA-Retry um 06:13 weiter `IqTimeout`, danach Retry-Backoff erschöpft (letzte Logzeile 06:17 — **Stille ≠ gesund**).
- **Diskriminator:** SysAP-REST `/configuration` = 200 in 3 s (62 Geräte), `/sysap` 200, TCP 5222 offen ⇒ kein Server-Wedge, sondern **clientseitiger slixmpp-Desync**.
- **Fix:** `docker restart homeassistant` (qm guest exec @ proxmox3) 07:10 → `not_loaded` → `setup_in_progress` 07:14:18 → `loaded` 07:14:48. Alle 28 ABB-Entities available (nur `button.garagentor` = `unknown`, bekannter ch0003-Status-Bug), Temperatursensoren pushen wieder (07:15:41).
- **E2E:** `light.schaltaktor_4_fach_16a_reg_abb208351f51_ankleidelicht` turn_on → `on` (07:15:03), turn_off → `off` (07:15:05), beide HTTP 200.
- **Watchdog Stufe 2 (13.11. ergänzt):** Wird nach `reboot(0)` + reload der Entry nicht `loaded` UND liefert SysAP-REST `/configuration` 200 → automatischer `docker restart homeassistant` (State `last_core_restart`, 6-h-Cooldown, 1 Throttle-Meldung/Tag, Boot-Wait 6 min). Ohne REST-200 gibt es **keinen** Core-Restart (dann ist der SysAP das Problem) — nur Alert. Verifiziert: `--selftest` grün, Tick bei gesundem Entry still + State-Reset.
- **Pitfall:** `rescue.py probe` meldet `GETALL_TIMEOUT_OR_FAIL 45.0s` auch bei gesunder Integration (zweite Installer-Session parallel zu HA + 45-s-Hardtimeout) → nicht als Health-Oracle nutzen; Entscheidung über Entry-State + REST.