Beta ioBroker-Matter Adapter

[apollon77]

Hallo Freunde moderner IoT-Geräte,

und willkommen beim Beta-Test des Matter Adapters!

Matter ist der Smart-Home-Standard der Zukunft. Es verspricht, in vielen Ökosystemen wie Apple, Google, Amazon und Samsung einheitlich zu funktionieren, ohne dass man für jedes System spezielle Lösungen benötigt.

Der heutige Beta-Start ist ein wichtiger Meilenstein in der etwa zweijährigen Entwicklungsphase – und er ist nicht das Ende, sondern erst der Anfang weiterer Entwicklungen rund um Matter. Bevor ich euch einen kurzen Überblick über die Funktionen des Adapters gebe, möchte ich mich bei Moritz (@foxriver76) und Denis (@bluefox) für ihre Unterstützung bei der Adapter- und App-Entwicklung bedanken. Ebenso danke ich allen Alpha-Testern, vor allem auch bei @Feuersturm. Ich denke, wir starten die Beta-Phase mit einem soliden Funktionsumfang und guter Qualität.

IPv6, Hubs und sonstige Vorbedingungen (Unbedingt lesen und befolgen!)

• Hubs: Je nach Ökosystem benötigt man unbedingt einen Hub um ioBroker Geräte über Matter zu nutzen, damit es funktioniert. Dies ist vor allem bei Google, Amazon und SmartThings der Fall. Apple benötigt ab iOS 18 (und theoretisch Tuya, aber besser Finger weg lassen) keinen Hub. Wer Thread-basierte Matter-Geräte nutzen möchte, benötigt ggf. Hubs, die auch Thread unterstützen. Das sind nicht alle Hubs!
• IPv6: Matter funktioniert nur, wenn im lokalen Netzwerk IPv6 aktiv ist und der ioBroker-Host eine IPv6-Adresse hat! Wer LXC-Container oder Docker nutzt, muss eventuell spezielle Einstellungen vornehmen! Eine externe IPv6 Adresse von Eurem Internetprovider ist nicht erfolrderlich. Weitere Informationen
• UDP-Kommunikation: Matter nutzt primär UDP für Discovery (MDNS) und die Kommunikation danach. Das bedeutet, dass zwischen allen beteiligten Systemen – sei es der ioBroker-Host, das Handy oder Matter-Hubs – "freie" UDP-Kommunikation notwendig ist. Dies bedeutet keine Firewalls oder Netzwerk-Segmentierung dürfen im Weg sein! Ein Netzwerk mit mehreren VLANs oder Segmenten muss MDNS und UDP routing unbedingt zulassen.
• Linux-Einstellungen: Wer den Adapter als Controller nutzen will und Thread-basierte Geräte nutzen möchte, muss möglicherweise weitere IPv6-Einstellungen an seinem Linux-ioBroker-System vornehmen, falls die Kommunikation mit den Geräten nicht funktioniert. Weitere Informationen.
• Docker: Wenn Docker verwendet wird, muss der “Host-Netzwerk”-Modus genutzt werden oder ein MacVlan-Setup für das Netzwerk erstellt werden, damit UDP-Broadcasts den Adapter erreichen.
• ** js-controller-Version:** Der Adapter sollte ab js.controller 5.0.19 funkitonieren. Aber natürlich gilt - je aktueller dedo besser.
• Admin-Version: Admin v7.4.x sollte genutzt werden. Bitte ggf. auf die Beta-Version aktualisieren.
• Visu-App und Cloud-Lizenz: Wenn die Controller-Funktionalität mit der Visu-App genutzt werden soll, sind iot v3.4.5, die ioBroker Visu-App in v1.3.2 und eine aktive ioBroker Pro Cloud-Lizenz für Fernzugriff und Assistenten erforderlich!

Für Fragen oder Diskussionen zu diesen Punkten nutzt bitte den Thread https://forum.iobroker.net/topic/79494/matter-beta-ipv6-hubs-und-sonstige-vorbedingungen.

Weitere wichtige Informationen zum Adapter

• Installation: Der Adapter kann nicht direkt aus GitHub installiert werden! Die Installation erfolgt über das Admin Beta Repository oder im Notfall über den Custom-Install-Icon und den “Von NPM”-Tab.
• Keine manuelle Konfiguration: Löscht niemals die Instanz, um den Adapter neu zu installieren oder ändert manuell die Objekte! Viele Konfigurationen des Adapters befinden sich in den Objekten, nicht an einer zentralen Stelle. Der Export-Button in der Instanz-Konfiguration bringt hier keinen echten Mehrwert. Am besten sichert ihr alle matter.X.* Objekte über Admin und stellt sie bei Bedarf wieder her. Falls diese gelöscht werden, bleiben nur die Backups oder es müssen ggf. alle Geräte neu verknüpft werden.
• *Instanzen: Es kann nur eine Instanz des Adapters pro ioBroker-Host installiert werden, da mehrere Instanzen bei MDNS bzw. den Matter-Ports zu Konflikten führen können.
• RAM-Verbrauch: Der Adapter kann, je nachdem, was damit gemacht wird (z.B. wie groß die Bridges sind oder wie viele Geräte im Controller verknüpft sind), durchaus 200-300 MB RAM benötigen oder auch kurzfristig bis zu 100 MB mehr beim Start. Stellt sicher, dass ausreichend RAM verfügbar ist!

Installation

Wir haben gestartet die Dokumentation unter https://github.com/ioBroker/ioBroker.matter/wiki zu erfassen und laden jeden gern ein hier mitzumachen und Informationen zu schreiben bzw zu ergänzen!

Der Adapter ist ab sofort im Beta-Repository unter dem Namen “Matter” verfügbar. Falls jemand das Stable-Repo nutzt, kann der Adapter auch ohne Umstellung des Repos über den Expertenmodus – Custom-Install-Tab “Von NPM” – installiert werden. Updates werden euch dann jedoch nicht angezeigt, aber folgt gern diesem Post, um Updates hier zu erhalten. Beachtet auch die Adapter-Versionen von Admin und iot, die ggf. ebenfalls aktualisiert werden müssen.

Wir starten die Beta mit Version 0.4.9, aber ich gehe davon aus, dass schnell weitere Versionen folgen werden.

Fehler, Probleme und wie berichten?

GitHub-Issues: https://github.com/ioBroker/ioBroker.matter/issues

Falls Fehlermeldungen im Log erscheinen, bitte in den Matter-Adapter-Einstellungen das erweiterte Logging aktivieren und die Adapter-Instanz auf Debug stellen. Dadurch wird der Adapter neu gestartet und es werden detaillierte Logs erstellt. Diese Logs sollten dann im GitHub-Issue angehängt werden, idealerweise mit dem Log-Teil um den Fehler herum (ca. 30-60 Sekunden davor und danach). Aber Achtung: Je nachdem was Ihr mit dem Adapter alles tut kann das Debug Log auch schnell recht groß werden!

Bei Problemen mit der Erkennung von Geräten im Controller oder bei Bridges/Devices bitte zuerst das Troubleshooting durchgehen und prüfen. Es wird empfohlen, die oben genannten Hinweise zu lesen. Wenn keine Logs zu sehen sind, die auf “eingehende oder ausgehende Nachrichten” hinweisen, dann stimmt oft etwas mit dem UDP-Routing oder der IPv6-Konfiguration nicht!

Für weitere Fragen bitte den dem Problem bzw Thema entsprechenden Diskussions-Thread nutzen.

Matter Adapter als Controller (Matter-Geräte in ioBroker einbinden)

Um Matter-fähige Geräte direkt in ioBroker einzubinden, deren Daten anzuzeigen und sie zu steuern, nutzt ihr ioBroker als sogenannten “Controller”. Der ioBroker-Host fungiert dann als Hub, der mit den Geräten über das Netzwerk kommuniziert. Die Geräte müssen einmalig mit ioBroker verknüpft werden.

Dies erfolgt auf verschiedene Arten:

• Wenn das Gerät breits im IP-Netzwerk ist (z.B. auch mit einem anderen Ökosystem verknüpft), kann es direkt über die Admin-Oberfläche des Adapters verknüpft werden. Im Controller-Tab können Geräte gesucht, QR-Codes gescannt oder Pairing-Codes eingegeben werden. Wichtig: Wenn das Gerät bereits mit einem anderen Ökosystem verknüpft ist, darf der originale QR-Code nicht verwendet werden. Das verknüpfte Ökosystem bietet normalerweise eine Option, einen neuen Pairing-Code zu generieren.
• Wenn das Gerät noch nicht verknüpft ist und Thread oder Wifi nutzt, kann es über die ioBroker Visu-App via BLE verknüpft werden. Während dieses Vorgangs wird das Gerät mit Apple oder Google verknüpft und danach erhält der Matter-Adapter über die ioBroker-Cloud und den iot-Adapter alle Informationen, um das Gerät auch in ioBroker zu pairen.
• Falls BLE vom ioBroker-Host nicht genutzt wird und sich das Gerät in der Nähe des Hosts befindet, kann es auch direkt über den ioBroker-Host gepaired werden. Hierfür müssen ggf. WLAN- oder Thread-Daten in den Adapter-Einstellungen hinterlegt werden. Es gibt bei diesem Weg noch bekannte Probleme und wenn möglkich nutzt bitte die Visu-App.

Nach erfolgreicher Verknüpfung wird das Gerät zusammen mit den angebotenen Funktionen angezeigt. Die Node-Kachel bietet alle allgemeinen Informationen und Funktionen, die “Gerätekacheln” enthalten spezifischere Informationen. Eine Node hat meist nur eine Funktionskachel, manchmal aber auch mehrere, je nach Hersteller. Über das “Info”-Symbol in der Kachel könnt ihr weitere Informationen abrufen und auch die States sehen, die zu ioBroker-Geräten gemappt wurden. Diese lassen sich teilweise auch steuern. Das gleiche findet ihr unter den Objekten in matter.X.controller.XXXXXXX.*.

Was die States und die Werte angeht gilt beim Controller:

• Zum Steuern des Gerätes die Werte mit ack=false setzen wenn der State beschreibbar ist.
• Der Adapter setzt die bestätigten Werte des Gerätes dann mit ack=true, wie es üblich ist.
• Bei einigen Daten gibt es ggf einen zweiten State mit "ACTUAL" im Namen (zB "SET" und "ACTUAL" beim Thermostat für die Temperatur oder "SET" und "ON_ACTUAL" bei einem Licht). Der ACTUAL stellt den aktuellen Wert vom dar und ist nicht beschreibbar. Der "SET" ist beschreibbar um einen neuen Wert zu setzen, wird aber ggf nicht vom System "bestätigt".

Bei Fragen und Diskussionen zur Controller Funktionalität nutzt bitte den Thread https://forum.iobroker.net/topic/79495/matter-beta-controller-matter-geräte-in-iobroker-einbinden.
Bei Fragen zu nicht unterstützten Gerätetypen oder Einstellungen nutzt bitte den Thread https://forum.iobroker.net/topic/79496/matter-adapter-nicht-unterstützte-geräte-einstellungen

Matter Adapter für Bridges und Devices (ioBroker States als Matter Bridge oder Gerät anbieten)

Die nächsten beiden Tabs im Adapter-UI ermöglichen es, ioBroker-Objekte und Geräte als Matter-Geräte in einer Bridge oder als Einzelgeräte anzubieten, um sie mit Apple, Google, Alexa, Samsung SmartThings oder anderen Systemen zu verknüpfen und lokal zu steuern.

Falls ihr Alexa einsetzen wollt, könnt ihr momentan nur eine Bridge nutzen, da Alexa nur auf einem Port nach Geräten sucht. In den Adapter-Einstellungen kann eine Bridge als “Standard-Bridge” festgelegt werden.

ioBroker Pro Cloud-Lizenz: Falls ihr keine ioBroker Pro Cloud-Lizenz für Fernzugriff oder Assistenten habt, könnt ihr nur eine begrenzte Anzahl von Geräten in einer Bridge oder als Einzelgeräte anlegen. Mit einer Lizenz seid ihr hier unbegrenzt und unterstützt auch das ioBroker-Projekt und unser weiteres Engagement im Bereich Matter.

Um Geräte hinzuzufügen, gibt es eine automatische Geräteerkennung, die mit dem Type-Detector funktioniert. Diese erfordert, dass die Geräte bestimmten Räumen zugewiesen sind, um die Filterung zu erleichtern. Alternativ kann auch ein Channel- oder Device-Objekt ausgewählt werden, um den Gerätetyp zu erkennen. Die “Einzel-State hinzufügen”-Option ist ausschliesslich für einfache Geräte mit nur genau einem State, wie Sensoren oder On/Off-Geräte, geeignet.

Falls die automatische Erkennung von Objektstrukturen nicht wie gewünscht funktioniert, verwendet den Devices-Adapter, um Aliase für die Geräte zu erstellen und nutzt diese Aliase im Adapter.

Wenn Ihr Bridges zusammenstellt empfehle ich erst einmal nur maximal 10-15 Geräte hinzuzufügen und dann die Bridge mit dem gewünschten Ökosystem zu verknüpfen. Weitere Geräte können danach beliebig zur Bridge hinzugefügt und gelöscht werden und die Änderung wird dann nach 15-60 Sekunden erkannt und aktualisiert. Diese initiale Limitierung macht Sinn weil es zB bei Alexa ggf Probleme gibt wenn zu grosse Bridges initial verknüpft werden. Danach mehr hinzuzufügen tut problemlos.
Im Wiki findet Ihr eine Liste der bisher unterstützten ioBroker-Gerätetypen.
Wer Bedarf an weiteren Typen hat bitte am besten ein GitHub Issue als Feature Request anlegen und Screenshots vom Admin mit Euren Objekt-Strukturen des Geräts hinzufügen.

Es sei noch erwähnt das es durchaus Unterschiede geben kann wie genau Geräte und Ihre Funktionen bei Apple, Google und Amazon angezeigt werden und nicht jeder kann alle Gerätetypen überhaupt oder vollständig unterstützen.
Weiterhin wird die Bridge bzw die Geräte beim verbinden als "nicht zertifiziert" angezeigt und Ihr müsste ggf bestätigen das Ihr so ein Gerät pairen wollt. Dies geht - ausser wir investieren 30.000EUR und mehr - nicht so einfach zu ändern für uns als Open Source Projekt. Leider ist aus diesem grund auch ein Pairing der Bridges und Devices mit dem Aqara Hub M3 und Yandex Hubs nach aktuellem Kenntnisstand nicht möglich, was sich vielleicht irgendwann mal noch ändert, aber diese verbieten aktuell nicht zertifizierte Geräte. Falls das Pairing mit Google (vor allem unter Nutzung der iOs Google Home App) nicht funktioniert, so müssen in Eurem Google Developer Account ggf Freischaltungen vorgenommen werden. Informationen dazu im Troubleshooting Guide.

Bei Fragen und Diskussionen zur Bridge und Device Funktionalität nutzt bitte den Thread https://forum.iobroker.net/topic/79497/matter-beta-devices-und-bridges

Wenn Euch ioBroker Gerätetypen fehlen, die der Adapter noch nicht kann bitte https://forum.iobroker.net/topic/79496/matter-adapter-nicht-unterstützte-geräte-einstellungen nutzen.

Zusammenfassung der Diskussions- und Fragen-Threads

Bei allgemeinen Fragen oder Diskussionen nutzt bitte den Thread https://forum.iobroker.net/topic/79498/matter-beta-allgemeine-fragen-und-diskussionen

Ansonsten zusammengefasst hier noch die bereits oben genannten Threads:

• Allgemeine Fragen und Diskussionen
• IPv6, Hubs und sonstige Vorbedingungen
• Matter-Controller: Matter Geräte in ioBroker einbinden
• Nicht unterstützte Matter-Geräte
• Matter Devices und Bridges

So und jetzt viel Spass mit dem Adapter und dem Weg in die neue Smart Home Welt

Ingo

[apollon77]

0.4.10:

• Fixed Thermostat limit initialization and Mode error
• Fixed Matter Event handling when mapped to an ioBroker state (e.g.GenericSwitch)
• Fixed Device type detection by really preferring the preferred type

[apollon77]

0.4.11 released

• Fixed caching issues in device type detection
• Added Debug info icon for Devices and Bridges