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 Konfiguration Docker MacVlan mit einer FritzBox

IPV6 muss im Docker Daemon eingeschaltet sein. Dies steht in der Datei /etc/docker/daemon.json.
Ich habe mit folgenden Befehlen eine Netzwerkschnittstelle mac0 erstellt.
ip link add mac0 link eno1 type macvlan mode bridge

ip addr add 192.168.0.240/28 dev mac0

ifconfig mac0 up

In der FritzBox deren IPV6 Adresse suchen: Internet/Online Monitor/Verbindungsdetails Dort die IPV6 Adresse (nicht Präfix) heraussuchen Bei mir wäre das 2a02:8108:0:7f::127

In der docker-compose mit dem Editor folgende Einstellungen: services:
iobroker:
restart: always
image: buanet/iobroker:latest-v11
container_name: iobroker
hostname: iobroker
volumes:
- /opt/iobroker/iobrokerdata:/opt/iobroker
networks:
myvlan:
ipv4_address: 192.168.0.241

networks:
myvlan:
driver: macvlan
driver_opts:
parent: mac0
enable_ipv6: true
ipam:
driver: default
config:
- subnet: 192.168.0.0/24
ip_range: 192.168.0.0/24
gateway: 192.168.0.1
- subnet: 2a02:8109:0:7f::/64
gateway: 2a02:8109:0:7f::127

Wichtig sind folgende Einträge in der Datei im Abschnitt „networks“:
enable_ipv6: true zum einschalten von IPV6 im MacVlan
Subnet: hier kommt die ersten vier Kombinationen rein die Ihr aus der Fritzbox ausgelesen habe.
Gateway: hier kommt die Adresse der FritzBox rein.

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. Terminal: ip a

grafik

Im Beispiel ist jetzt die aktive Netwerkschnittstelle: wlxc83a35b56a45

Für Debian 13 (Trixie) und darauf basierenden Systemen

Unter Debian 13 (Trixie) und generell bei aktuellen systemd-basierten Distributionen gibt es eine kleine Änderung im Umgang mit sysctl-Konfigurationen. Siehe hierzu https://www.debian.org/releases/trixie/release-notes/issues.de.html#etc-sysctl-conf-is-no-longer-honored

Vor Debian 13 wurde im nächsten Absatz beschrieben /etc/sysctl.conf verwendet, seit Debian 13 jedoch bevorzugt systemd (bzw. systemd-sysctl.service).

Die Anwendung der alten Methode kann dazu führen, dass wichtige Konfigurationseinträge nach einem Rechner-Neustart vergessen werden; insbesondere der Eintrag accept_ra_rt_info_max_plen=64 scheint dafür anfällig zu sein. Lege zur Lösung des Problems eine eigene Konfigurationsdatei in /etc/sysctl.d/ an, z.B. /etc/sysctl.d/99-sysctl.conf .

Terminal:

sudo nano /etc/sysctl.d/99-sysctl.conf

folgendes 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

Falls eure /etc/sysctl.conf bereits Einträge enthält, sollten diese auch in die neue Datei übertragen werden. Abspeichern nicht vergessen !

Danach sofort aktivieren: sudo sysctl --system

Für Debian 12 sowie frühere Versionen und darauf basierenden Systeme

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)

Terminal:

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:

Terminal:

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

  • Screenshot 2025-03-05 152650

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

Devices and Bridges

  • 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.

Ökosystem Alexa

  • Wenn ioBroker Matter Devices oder Bridges in Alexa offline sind oder dort doppelt angezeigt werden, liegt das oft an einer Mischung aus alten und neuen Echo-Modellen. Lösung: Alle Echos aktualisieren und wenn dies nicht hilft, die Anzahl der verbundenen Geräte reduzieren.

Thread Geräte

  • Thread Geräte am besten nur mit einem Ökosystem (Google, Apple, Alexa, ...) aktiv nutzen, da es passieren kann, dass dies negative Auswirkung auf die Batterielebensdauer der Threadgeräte haben kann und dass es beim dimmen von Lampen Probleme geben kann.

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", },