Troubleshooting - ioBroker/ioBroker.matter GitHub Wiki

Einleitung

Auf dieser Seite werden Hilfestellungen zu Problemen mit dem Matter Adapter / Matter Ökosystem gesammelt. Zusätzliche Hinweise sind auch auf der Troubleshooting Seite von matter.js dokumentiert. Der ioBroker Matter Adapter basiert auf der "matter.js" Bibliothek.

Wie melde ich ein Problem / Bug?

Bitte überprüfe zuerst die Informationen auf der Seite Einleitung und wichtige Hinweise sowie die auf dieser Seite beschriebenen Hilfestellungen
Prüfe, ob die neueste verfügbare Version installiert ist - oder wenn nicht, ob das Changelog der neueren Versionen als die installierte das aktuelle Problem löst und aktualisiere den Adapter.
Überprüfe, ob ein offenes GitHub issues zu deinem Problem existiert. Wenn das Problem schon gemeldet wurde, reagiere im ersten Beitrag mit einen "Daumen hoch". Dies hilft, die Probleme zu priorisieren. „Me Too"- Kommentare ohne zusätzliche Informationen sind nicht erforderlich.
Erstellen ein GitHub issue beim Adapter, wenn das Problem noch nicht existiert.
Setze bei der Adapter Intanz das Loglevel auf "Debug" und aktiviere in den Einstellungen der Matter Instanz auf dem ersten Tab "Allgemein" die Option "Erweitertes Debug-Logging für das Matter-Protokoll aktivieren (nur sichtbar mit der Protokollebene „Debug“)". Hänge das Log (Logfile-Speicherort üblicherweise /opt/iobroker/logs/...) als Textdateianhang an das github issue. Stelle bitte nicht nur die eigentliche Fehlermeldeung zur Verfügung, sondern stelle auch einige Minuten des Protokolls vor und nach dem Fehler bereit, um mehr Kontext zu erhalten. Beschreibe im issue so ausführlich wie möglich, was gemacht wurde als der Fehler entstanden ist und wie sich der Fehler genau äußert. Je detaillierte das Problem beschrieben ist, desto besser kann es analysiert werden.

Verbindungs- und Kommunikationsprobleme

IPv6 Konfiguration des ioBroker Host Systems

Proxmox LXC Container mit Ubuntu & Debian

Um IPv6 für den ioBroker Matter Adapter verwenden zu können, muss im LXC Container in Proxmox die Option "SLAAC" aktiviert werden.

Kurze Erklärung zum Thema SLAAC: https://www.elektronik-kompendium.de/sites/net/1902141.htm

grafik

Erfolgreich getestet mit Ubuntu 24.04, Debian 12 + Fritzbox 7530 mit DHCP + Defaulteinstellungen für "IPv6 Einstellungen"

IPV6 Kommunikation für Nutzung von Thread Geräten:

Eine weitere englischsprachige Anleitung ist hier: https://github.com/project-chip/matter.js/blob/main/docs/TROUBLESHOOTING.md#ipv6-linux-system-details

Die folgenden Einstellungen für den ioBroker Host können helfen, wenn es Probleme in der Kommunikation zu Thread Geräten über einen Matter Hub (z.B. von Google oder Apple) gibt.

Als erstes herausfinden, welches die aktive Netzwerkschnittstelle ist. Konsole: ip a

grafik

Im Beispiel ist jetzt die aktive Netwerkschnittstelle: wlxc83a35b56a45

Terminal: sudo nano /etc/sysctl.conf

folgendes ändern bzw. hinzufügen (##### entspricht den Namen der aktiven Netzwerkschnittstelle, also bitte entsprechend ersetzen)

net.ipv6.conf.all.forwarding=0
net.ipv6.conf.########.forwarding=0
net.ipv6.conf.########.accept_ra=2
net.ipv6.conf.########.accept_ra_rt_info_max_plen=64

oder per Terminal:

sudo sysctl -w net.ipv6.conf.####.forwarding=0

sudo sysctl -w net.ipv6.conf.####.accept_ra=2

sudo sysctl -w net.ipv6.conf.####.accept_ra_rt_info_max_plen=64

Ist eurer System mit wpa_supplicant (bei WLAN) bzw. Networkmanager konfiguriert, müsst ihr folgendes in die

/etc/network/interfaces

eintragen: (bei Konfiguration über systemd->? / IWCtl (Wlan)->siehe unten)

Konsole: sudo nano /etc/network/interfaces
folgendes ändern bzw. hinzufügen (##### entspricht den Namen der aktiven Netzwerkschnittstelle, also bitte entsprechend ersetzen)
- iface ####### inet6 auto

Ist eurer System mit IWCtl konfiguriert, müsst ihr folgendes in die

/etc/iwd/main.conf

eintragen:

Konsole: sudo nano /etc/iwd/main.conf
folgendes ändern bzw. hinzufügen:
[Network]
EnableIPv6=true

Dann einen reboot durchführen.

Kontrolle der Einstellungen:

(##### entspricht den Namen der aktiven Netzwerkschnittstelle, also bitte entsprechend ersetzen)

sudo sysctl -n net.ipv6.conf.########.forwarding

Ergebniss muss: 0

sudo sysctl -n net.ipv6.conf.#######.accept_ra

Ergebniss muss: 2

sudo sysctl -n net.ipv6.conf.#######.accept_ra_rt_info_max_plen

Ergebniss muss: 64

Sollte nach einem Reboot der wert bei accept_ra nicht "2" sein, kann es helfen, dieses in die /etc/network/interfaces zu schreiben: sudo nano /etc/networking/interfaces

iface ###### inet6 auto accept_ra 2

Raspberry Pi-Benutzer müssen möglicherweise die folgenden Zeilen hinzufügen, um zu verhindern, dass dhcpcd den accept_ra Wert überschreibt:

sudo nano /etc/dhcpcd.conf

Dann mit dem Coursor ganz runter fahren, dann:

noipv6

noipv6rs

einfügen

Speichern und Beenden

Sonderfall Synology (Stand 05.03.2025, DSM 7.2.2, Container Manager 24.0.2)

Habt Ihr bspw. Docker mit MACVLAN auf einer Synology laufen, helfen die Änderungen in den Konfig-Dateien, wie weiter oben beschrieben, leider nicht. Der einzige aktuell bekannte Weg ist eine statische Route zum Thread Border Router (TBR) herzustellen. Diese kann man entweder im Netzwerkrouter (z.B. Fritzbox) oder auf der Synology selbst einrichten.

Nun benötigt man die lokale ipv6 (ULA) des "Thread Border Routers (TBR)" sowie die ipv6 des "Thread-Gerätes" hinter dem TBR. Daraus ergibt sich die statische Route, die aus einem "Ziel" und einem "Gateway-Eintrag" besteht.

Wie könnte so eine Route aussehen?

Ziel: entweder nur die eine ipv6 des Thread-Gerätes ODER besser gleich alle ips hinter dem TBR, indem man nur den "ersten Teil" angibt (man sagt auch Präfix + Global_ID + Subnet_ID)

Bsp.: fdb2:4e20:390c:0:ada2:9a4b:e17f:cad4 (ip des einen Thread-Gerätes) ODER besser fdb2:4e20:390c:: (das ist der erste Teil von "Präfix + Global_ID + Subnet_ID" mit der Länge 48)

Gateway: ipv6 des TBR im "normalen" Netzwerk

Bsp.: fd7c:f3f8:4c39::1c10:c180:dd7f:3787

Wie komme ich an die ipv6 des Thread-Gerätes?

Im Log des Matter-Adapters taucht die ipv6 des zu verbindenden Thread-Gerätes auch bei einem Verbindungsfehler auf > muss man sich dann leider so raussuchen

Wie komme ich an die ipv6 des TBR?

findet man in der Liste der Netzwerkgeräte im Netzwerk-Router

Unterschiedliches Verhalten in den Ökosystemen

In diesem Abschnitt wird gesammelt an welchen Stellen sich die verschiedenen Ökoysteme unterschiedlich verhalten

Generelle Informationen sind auch unter den folgenden Links zu finden:

Temperatur

Google: Der Temperaturwert wird in der App auf 0.5° gerundet angezeigt

Water leak Sensor

Google: Nicht unterstützt
Amazon: Nicht unterstützt

Rolläden / Blinds

Der ioBroker Matter Adapter wird für Rolläden 0% = Rolladen geschlossen/unten (kein Licht kommt durch) 100% = Rolladen offen/oben (Licht kommt vollständig durch)

Wenn eine andere Logik benötigt wird, dann erzeuge vom entsprechenden Datenpunkt ein Alias. Mit rechtsklick kann der Alias bearbeitet werden und dort kann die Konvertierungsfunktion dazu verwendet werden die Behanghöhe zu invertieren, z.B. anstatt "val" wird "100-val" verwendet.

Apple

Anzeige von neuen Matter Geräten unter iOS 18.4

Mit der Version iOS 18.4 werden neue Gerätetypen unsterstützt. Damit diese unter Apple auch angezeigt werden, müssen ALLE Apple Hubs im Netzwerk inkl. aller Apple Handys die iOS Version 18.4 installiert haben, damit die neuen Gerätetypen sichtbar werden. Sobald ein Apple Hub/Handy nicht iOS 18.4 hat wird das neue Unterstützte Device nicht angezeigt.

Troubleshooting für Devices and Bridges

Mit Alexa kann nur die Standard-Bridge auf einem Host verwendet werden. Mehrere Bridges zur Verwendung mit Alexa sind nur auf verschiedenen ioBroker Hosts möglich.
Nach einem Matter Adapter restart oder ioBroker Host reboot kann es bis zu 10 - 15 Minuten dauern bis sich alle Controller wieder neu verbunden haben
Wenn ein Ecosystem das Gerät als nicht verbunden anzeigt, insbesondere nach einem Neustart des Adapters, bedeutet dies in der Regel, dass der Controller sich noch nicht wieder mit dem Gerät verbunden hat. Dies kann einige Zeit dauern. Wenn die Verbindung nach ein paar Minuten nicht wiederhergestellt ist, überprüfe bitte die Verbindungsinformationen in der Benutzeroberfläche. Wenn ein Ökosystem überhaupt keine Verbindung herstellt, überprüfen bitte das ioBroker Log (ggf. Debug Loglevel aktivieren) und erstelle falls notwendig ein github issue.

Known Bugs

Hue Lampen: Wer Aliase nutzt die mit "Devices" (Geräte) angelegt wurden und diese dann als Matter Device/Bridge bereitstellt kann aktuell HUE Lampen nicht über die App des Matter Ökosystems ein oder ausschalten. Ursache ist, dass die "role" beim "ON" State der Hue-Lampe im Alias nicht gesetzt wird ( https://github.com/ioBroker/ioBroker.devices/issues/363) . Workaround bis zum fix: Entweder über den Alias-Manager für diesen State die "common.role" auf "switch.light" setzen oder direkt das Alias Objekt alias.0.xxx.HueLampe.ON bearbeiten und im Abschnitt "common" die Zeile "role" hinzufügen. "common": { "alias": { "id": "xxxx" }, ... "role": "switch.light", },

Troubleshooting für den Matter Controller

tbd