Quelltext der Seite Matter-Schaltdose über Home Assistant in FHEM integrieren

Diese Anleitung beschreibt, wie eine SONOFF-Matter-Schaltdose über eine Home-Assistant-VM (HAOS) kommissioniert und anschließend per MQTT-Bridge in FHEM eingebunden wird – inklusive Schalten und Auslesen von Energiemesswerten.


=== Ausgangslage / Voraussetzungen ===

* Home Assistant OS (HAOS) als VM auf Proxmox, installiert über die Proxmox VE Helper-Scripts
* Ein per PCI(e)-Passthrough oder USB-Passthrough durchgereichter Bluetooth-Stick an der HA-VM (wird für das Matter-Commissioning per BLE benötigt)
* Eine SONOFF-Matter-Schaltdose (Matter-over-WiFi)
* FHEM mit eigenem <code>MQTT2_SERVER</code> als MQTT-Broker (kein separater Mosquitto-Broker nötig)



=== Home Assistant Ersteinrichtung ===

Beim ersten Aufruf der HA-Weboberfläche erscheint der Onboarding-Dialog "Willkommen!".

* '''Kein Cloud-Konto notwendig.''' Über "Mein Smarthome erstellen" wird nur Folgendes abgefragt:
*# Name des Smart Homes
*# Standort (für Sonnenauf-/untergang, Wetter etc.)
*# Lokaler Admin-Account (Benutzername/Passwort) – rein lokal, keine Cloud-Registrierung
* "Home Assistant Cloud" (Nabu Casa) ist optional und für dieses Vorhaben nicht erforderlich.



=== Matter Server als App installieren ===

Seit Home Assistant 2026.2 wurde der Menüpunkt '''"Add-ons"''' in '''"Apps"''' umbenannt (funktional identisch – weiterhin vom Supervisor verwaltete Docker-Container).

* Einstellungen → '''Apps''' → nach "'''Matter Server'''" suchen, installieren, starten



=== Matter-Gerät kommissionieren – ohne Smartphone-App ===

Der offiziell dokumentierte Weg über "Gerät hinzufügen" in der Matter-Integration verlangt die Home-Assistant-Companion-App auf dem Smartphone. Da bereits ein Bluetooth-Stick an die HA-VM durchgereicht wurde, kann das Commissioning stattdessen server-seitig direkt über die Weboberfläche des Matter-Servers erfolgen.


==== Bluetooth-Adapter-ID ermitteln ====

* Einstellungen → Geräte & Dienste → Bluetooth (bzw. Hardware-/USB-Übersicht)
* Der durchgereichte Stick erscheint dort als <code>hci0</code> (ggf. <code>hci1</code>, falls ein weiterer Adapter vorhanden ist) – Nummer notieren


==== Matter Server auf den Adapter konfigurieren ====

* Einstellungen → Apps → '''Matter Server''' öffnen
* Reiter '''Konfiguration'''
* "Erweiterte/unbenutzte Optionen anzeigen" aktivieren
* Feld '''Bluetooth Adapter ID''' mit der ermittelten Nummer befüllen
* Speichern → App neu starten


==== Kommissionieren über die Matter-Server-Weboberfläche ====

* Auf der App-Seite '''Matter Server''' → Button "'''Benutzeroberfläche öffnen'''" klicken
* '''Commission Node''' wählen
* '''Commission new Wi-Fi device''' auswählen
* WLAN-SSID und -Passwort eingeben (Ziel WLAN-Netz in das die Dose integriert werden soll)
* Onboarding-/Setup-Code der Dose eingeben (auf Gerät/Verpackung aufgedruckt bzw. QR-Code-Inhalt)
* '''Commission''' klicken – die Verbindung läuft per BLE über den durchgereichten Stick; nach Übergabe der WLAN-Daten verbindet sich die Dose eigenständig per WLAN

'''Hinweis:''' Dies ist ein von der Community dokumentierter, nicht offiziell beworbener Weg. Funktioniert zuverlässig, ist aber weniger komfortabel als der App-Flow (z.B. keine ausführlichen Fehlermeldungen).



=== Gerät in Home Assistant übernehmen ===

* Nach erfolgreichem Commissioning erscheint das Gerät automatisch unter Einstellungen → Geräte & Dienste als neues Matter-Gerät
* Gerät benennen (im Beispiel: <code>Matter_Sonoff1</code>) und ggf. einem Bereich zuweisen
* Resultierende Entity im Beispiel: <code>switch.matter_over_wifi_smart_switch</code> (zusätzlich Sensor-Entities für Spannung, Leistung, Strom, Energie sowie ein Select für das Wiedereinschaltverhalten)



=== MQTT-Integration in Home Assistant einrichten ===

* Einstellungen → Geräte & Dienste → '''Integration hinzufügen''' → "MQTT" suchen
* Aus der Auswahlliste den Eintrag '''"MQTT"''' wählen (nicht "MQTT Statestream", "MQTT Eventstream" etc. – diese sind nur über <code>configuration.yaml</code> konfigurierbar und daher in der Liste nicht anklickbar)
* Broker-Adresse: IP/Hostname des FHEM-Servers mit dem <code>MQTT2_SERVER</code>-Device
* Port: Standard <code>1883</code> bzw. der in FHEM konfigurierte Port
* Ggf. Benutzername/Passwort, falls der <code>MQTT2_SERVER</code> abgesichert ist
* '''Protokollversion:''' MQTT 3.1.1 (FHEMs <code>MQTT2_SERVER</code> ist eine Eigenimplementierung, die nicht den vollen MQTT-5.0-Funktionsumfang unterstützt)



=== MQTT Statestream einrichten (Status: HA → FHEM) ===

In der <code>configuration.yaml</code> (Bearbeitung z. B. über die App "File editor" oder "Studio Code Server") folgenden Block auf oberster Ebene ergänzen:

<pre>
mqtt_statestream:
  base_topic: homeassistant/statestream
  publish_attributes: false
  publish_timestamps: false
</pre>

'''Wichtig:''' Einrückung mit Leerzeichen (2 pro Ebene), keine Tabs.


==== Konfiguration prüfen ====

* Einstellungen → System → Neu starten → Button/Link "Konfiguration überprüfen" nutzen
* Meldung "Konfiguration ist gültig" abwarten, bevor neu gestartet wird


==== Neu starten ====

* Einstellungen → System → Neu starten → "Home Assistant neu starten"

Ab jetzt published HA bei jeder Zustandsänderung automatisch Topics nach dem Schema:
<pre>
homeassistant/statestream/<domain>/<entity_id>/state
</pre>



=== FHEM: Autocreate-Devices nach erster Verbindung ===

Nach dem Verbindungsaufbau legt FHEMs Autocreate typischerweise zwei generische <code>MQTT2_DEVICE</code>-Einträge an:

* Ein '''Bridge-Device''', das den Verbindungsstatus (online/offline) des HA-MQTT-Clients sowie dessen Abonnements abbildet
* Ein '''Sammel-Device''', in dem sämtliche ankommenden Statestream-Topics der gesamten HA-Installation landen (wächst mit jeder Entity, unübersichtlich)

Empfohlen: beide Devices zur besseren Übersicht umbenennen, z. B.:

<pre>
rename &lt;autoname1&gt; HomeAssistant_Bridge
rename &lt;autoname2&gt; HomeAssistant_Statestream_ALL
</pre>



=== Eigenes FHEM-Device für die Steckdose anlegen ===

Für die Steckdose (Beispielname in HA: <code>Matter_Sonoff1</code>, Entity <code>switch.matter_over_wifi_smart_switch</code>) ein eigenes, zweckgebundenes Device anlegen:

<pre>
define Matter_Sonoff1 MQTT2_DEVICE
attr Matter_Sonoff1 IODev MQTT_Broker
attr Matter_Sonoff1 room HomeAssistant
attr Matter_Sonoff1 readingList homeassistant/statestream/switch/matter_over_wifi_smart_switch/state:.* state
homeassistant/statestream/sensor/matter_over_wifi_smart_switch_spannung/state:.* voltage
homeassistant/statestream/sensor/matter_over_wifi_smart_switch_leistung/state:.* power
homeassistant/statestream/sensor/matter_over_wifi_smart_switch_wirkstrom/state:.* current
homeassistant/statestream/sensor/matter_over_wifi_smart_switch_eingespeiste_energie/state:.* energy
homeassistant/statestream/select/matter_over_wifi_smart_switch_wiedereinschaltverhalten/state:.* restartBehavior
</pre>

Damit stehen in FHEM als Readings zur Verfügung: <code>state</code> (on/off), <code>voltage</code>, <code>power</code>, <code>current</code>, <code>energy</code>, <code>restartBehavior</code>.



=== Schaltbefehle FHEM → Home Assistant (Automation) ===

Statestream ist nur lesend (HA → FHEM). Zum Schalten aus FHEM heraus wird in Home Assistant eine Automation angelegt, die auf ein Kommando-Topic hört:

* Einstellungen → Automationen & Szenen → "'''+ Automation erstellen'''" → "Neue Automation erstellen" (leere Automation)
* Im visuellen Editor oben rechts auf die drei Punkte '''⋮''' klicken → "'''In YAML bearbeiten'''"
* Folgenden Block einfügen (im Beispiel final funktionierende Version):

<pre>
alias: MQTT -> Matter Sonoff1 Steckdose schalten
description: ""
triggers:
  - topic: cmnd/Matter_Sonoff1/set
    trigger: mqtt
actions:
  - target:
      entity_id: switch.matter_over_wifi_smart_switch
    action: |
      {{ 'switch.turn_on' if trigger.payload == 'ON' else 'switch.turn_off' }}
</pre>

* Speichern (Diskette-Symbol oben rechts)



=== setList in FHEM ergänzen ===

Am FHEM-Device <code>Matter_Sonoff1</code> das Attribut <code>setList</code> ergänzen, damit <code>set Matter_Sonoff1 on/off</code> die passenden MQTT-Kommandos publiziert:

<pre>
attr Matter_Sonoff1 setList on:noArg cmnd/Matter_Sonoff1/set ON
off:noArg cmnd/Matter_Sonoff1/set OFF
</pre>



=== Aufräumen ===

Sobald das dedizierte Device <code>Matter_Sonoff1</code> nachweislich funktioniert, kann das Sammel-Device gelöscht werden:

<pre>
delete HomeAssistant_Statestream_ALL
</pre>

Das Bridge-Device (Verbindungsstatus) kann bestehen bleiben, es liefert bei Bedarf den Online-Status der HA-MQTT-Verbindung.



=== Test ===

* In FHEM: <code>set Matter_Sonoff1 on</code> bzw. <code>off</code> ausführen → Dose schaltet
* Manuelles Schalten der Dose direkt in Home Assistant → Reading <code>state</code> in FHEM aktualisiert sich über den Statestream

'''Ergebnis:''' Die Matter-Schaltdose lässt sich bidirektional zwischen Home Assistant und FHEM steuern und überwachen (Schaltzustand sowie Energiemesswerte).




=== Architekturübersicht ===

<pre>
SONOFF-Matter-Dose
   │ (WLAN, nach Commissioning)
   ▼
Home Assistant (Matter-Integration / Matter Server)
   │ (MQTT Statestream – Status)         │ (Automation – Befehle)
   ▼                                     ▲
FHEM MQTT2_SERVER (Broker)  ◄────────────┘
   │
   ▼
FHEM MQTT2_DEVICE "Matter_Sonoff1"
</pre>