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 MQTT2_SERVER 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:
1. Name des Smart Homes
2. Standort (für Sonnenauf-/untergang, Wetter etc.)
3. 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 hci0 (ggf. hci1, 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: Matter_Sonoff1) und ggf. einem Bereich zuweisen
Resultierende Entity im Beispiel: switch.matter_over_wifi_smart_switch (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 configuration.yaml konfigurierbar und daher in der Liste nicht anklickbar)
Broker-Adresse: IP/Hostname des FHEM-Servers mit dem MQTT2_SERVER-Device
Port: Standard 1883 bzw. der in FHEM konfigurierte Port
Ggf. Benutzername/Passwort, falls der MQTT2_SERVER abgesichert ist
Protokollversion: MQTT 3.1.1 (FHEMs MQTT2_SERVER ist eine Eigenimplementierung, die nicht den vollen MQTT-5.0-Funktionsumfang unterstützt)

MQTT Statestream einrichten (Status: HA → FHEM)

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

mqtt_statestream:
  base_topic: homeassistant/statestream
  publish_attributes: false
  publish_timestamps: false

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:

homeassistant/statestream/<domain>/<entity_id>/state

FHEM: Autocreate-Devices nach erster Verbindung

Nach dem Verbindungsaufbau legt FHEMs Autocreate typischerweise zwei generische MQTT2_DEVICE-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.:

rename <autoname1> HomeAssistant_Bridge
rename <autoname2> HomeAssistant_Statestream_ALL

Eigenes FHEM-Device für die Steckdose anlegen

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

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

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

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):

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' }}

Speichern (Diskette-Symbol oben rechts)

setList in FHEM ergänzen

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

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

Aufräumen

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

delete HomeAssistant_Statestream_ALL

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

Test

In FHEM: set Matter_Sonoff1 on bzw. off ausführen → Dose schaltet
Manuelles Schalten der Dose direkt in Home Assistant → Reading state 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

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"