Virtuelles Gerät erstellen

1. Einführung

Matter ist ein Konnektivitätsprotokoll, das spannende Möglichkeiten für die Entwicklung von Smart-Home-Geräten bietet. In diesem Codelab baust du dein erstes Matter-Gerät mithilfe von SDKs und Abhängigkeiten, die in einem vorkonfigurierten Docker-Image bereitgestellt werden.

Weitere Informationen zu Matter finden Sie im Google Home Developer Center oder auf der Website der Connectivity Standards Alliance.

Lerninhalte

  • Matter-Build-Umgebung einrichten
  • Virtuelles Matter-Gerät erstellen, das auf deinem Computer ausgeführt wird
  • Virtuelles Matter-Gerät mit Google Home in Betrieb nehmen und steuern

Voraussetzungen

2. Umgebung einrichten

Wir verwenden einen zuvor konfigurierten Docker-Container auf einem Linux-Hostcomputer. Dieser Container enthält alle Abhängigkeiten, die zum Erstellen und Ausführen eines virtuellen Matter-Geräts erforderlich sind.

Hardware überprüfen

Windows- und macOS-Computer werden von dieser Docker-Installation nicht unterstützt. Sie können Matter unter macOS manuell installieren und erstellen.

Bei dieser Anleitung wird außerdem davon ausgegangen, dass auf Ihrem Linux-Computer das X11-Windowing-System ausgeführt wird. Wenn auf Ihrem Linux-Computer Wayland ausgeführt wird, muss X.Org ebenfalls installiert sein.

Docker einrichten

  1. Installieren Sie Docker Engine (nicht Docker Desktop).
  2. Rufen Sie das Docker-Image aus Docker Hub ab. Führen Sie in einem Terminalfenster Folgendes aus:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    
    Dieser Vorgang kann einige Minuten dauern.
  3. Starten Sie den Docker-Container mit folgendem Befehl:
    user@host> xhost local:1000
    user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    

Nach dem Starten des Containers sollten Sie eine Diagnoseausgabe sehen, gefolgt von einer Meldung, die bestätigt, dass Ihre Containerkonfiguration korrekt ist, und schließlich der Container-Shell-Eingabeaufforderung:

Environment looks good, you are ready to go!
$

Sehen wir uns den Docker-Befehl und die Optionen an, die wir an ihn übergeben haben:

  • xhost local:1000 ermöglicht dem X Window System, Verbindungen vom lokalen Host über Port 1000 zu empfangen, was die Verwendung einer grafischen Benutzeroberfläche ermöglicht.
  • docker run … image führt das angegebene Image aus und ruft es gegebenenfalls aus der Docker-Registry ab.
  • Mit --ipc=host kann Docker den Namespace für die Interprozesskommunikation für Ihren Hostcomputer freigeben.
  • Mit --net=host kann Docker den Netzwerkstack des Hosts im Container verwenden. Dies ist erforderlich, damit mDNS-Traffic vom Host an den Container weitergeleitet und die X11-Anzeige des Hosts freigegeben werden kann.
  • -e DISPLAY exportiert $DISPLAY zum Host und gewährt Zugriff auf die Systemgrafikoberfläche. Dies ist erforderlich, um das ZAP-Tool beim Bearbeiten von Matter-Clustern auszuführen.
  • -it führt Docker mit einem interaktiven Terminal (tty) statt als Hintergrundprozess aus.

Optional können Sie eine zweite Terminalsitzungsinstanz ausführen:

user@host> docker exec -it matter-container /bin/bash
$

Matter-Docker-Container beenden und starten

Jedes Mal, wenn Sie einen docker run-Befehl ausführen, wird ein neuer Container mit dem angegebenen Image erstellt. Dabei gehen Ihre alten Daten, die in einer vorherigen Containerinstanz gespeichert wurden, verloren. Manchmal ist dies der Fall, da Sie so mit einer neuen Installation beginnen können. Es gibt jedoch Situationen, in denen Sie Ihre Arbeits- und Umgebungskonfiguration zwischen Sitzungen speichern möchten.

Daher können Sie den Container nach dem Erstellen stoppen, damit Ihre Arbeit nicht verloren geht.

user@host> docker stop matter-container

Wenn Sie den Container wieder ausführen möchten, starten Sie den Container und öffnen Sie ein Terminalfenster:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Sie können zusätzliche Terminalsitzungen für Ihren Container öffnen, indem Sie Folgendes verwenden:

user@host> docker exec -it matter-container /bin/bash

Oder starten Sie eine Root-Sitzung mit:

user@host> docker exec -u 0 -it matter-container /bin/bash

Ersteinrichtung von Matter

Wenn sich dein Terminal öffnet, befindet es sich bereits im geklonten Matter-Repository unter ~/connectedhomeip. Es sind keine weiteren Matter-Einrichtungsschritte erforderlich.

Dateien zwischen Host und Container freigeben

Für den Zugriff auf Dateien auf Ihrem Hostcomputer aus dem Container heraus können Sie eine Bind-Bereitstellung verwenden. Sie können Dateien auch aus dem Container in das bereitgestellte Verzeichnis schreiben, um vom Host aus leicht darauf zugreifen zu können.

Führen Sie den Container mit dem zusätzlichen Argument --mount source=$(pwd),target=/workspace,type=bind aus, um das aktuelle Arbeitsverzeichnis im Container unter /workspace bereitzustellen.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Die Berechtigungen des Containernutzers für das bereitgestellte Verzeichnis müssen auf dem Host verwaltet werden.

Rufen Sie die Gruppen-ID des Containernutzers aus dem Container ab.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Öffnen Sie eine weitere Terminalsitzung auf dem Containerhost und legen Sie als Arbeitsverzeichnis das vom Container bereitgestellte Verzeichnis fest.

Die Gruppe für Dateien im bereitgestellten Verzeichnis rekursiv auf die Gruppe des Containernutzers festlegen.

user@host> sudo chgrp -R 1000 .

Erteilen Sie der Gruppe die gewünschten Berechtigungen im Verzeichnis. In diesem Beispiel erhält die Gruppe des Containernutzers Lese-, Schreib- und Ausführungsberechtigungen für alle Dateien im bereitgestellten Verzeichnis.

user@host> sudo chmod -R g+rwx .

Beachten Sie, dass diese Befehle keine Auswirkungen auf die Berechtigung von neuen Dateien haben, die vom Hostnutzer erstellt werden. Denken Sie daran, die Berechtigungen für neue Dateien, die auf dem Host erstellt werden, nach Bedarf zu aktualisieren.

Sie können den Hostnutzer der Gruppe des Containernutzers hinzufügen, um Berechtigungen für Dateien zu übernehmen, die vom Containernutzer erstellt wurden.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Google Home-Entwicklerkonsole

Die Google Home Developer Console ist die Webanwendung, in der du deine Matter-Integrationen mit Google Home verwalten kannst.

Alle Matter-Geräte, die die Matter-Zertifizierung der Connectivity Standards Alliance (Alliance) bestanden haben, können in Google Home verwendet werden. Geräte in der Entwicklung, die nicht zertifiziert sind, können unter bestimmten Bedingungen für Google Home in Betrieb genommen werden. Weitere Informationen finden Sie unter Einschränkungen bei der Kopplung.

Entwicklerprojekt erstellen

Rufe als Erstes die Google Home Developer Console auf:

  1. Klicken Sie auf Projekt erstellen.
  2. Geben Sie einen eindeutigen Projektnamen ein und klicken Sie auf Projekt erstellen. Dialogfeld „Neues Projekt erstellen“
  3. Klicke auf + Integration hinzufügen. Dadurch gelangst du zum Bildschirm Matter-Ressourcen. Dort kannst du dir die Dokumentation zur Matter-Entwicklung ansehen und dich über einige Tools informieren.
  4. Wenn Sie fortfahren möchten, klicken Sie auf Weiter: Entwickeln. Die Seite Matter-Checkliste wird angezeigt.
  5. Klicken Sie auf Weiter: Einrichtung.
  6. Geben Sie auf der Seite Einrichtung Ihren Produktnamen ein.
  7. Klicken Sie auf Gerätetyp auswählen und wählen Sie den Gerätetyp aus dem Drop-down-Menü aus (in diesem Fall Light).
  8. Wählen Sie unter „Anbieter-ID (VID)“ die Option Test-VID und dann im Drop-down-Menü „Test-VID“ die Option „0xFFF1“ aus. Geben Sie unter „Produkt-ID (PID)“ den Wert „0x8000“ ein, klicken Sie auf Speichern und fortfahren und dann auf der nächsten Seite auf Speichern. Verwende genau diese VID-/PID-Werte. Spätere Codelab-Schritte sind davon abhängig.
    Projekt einrichten
  9. Die Integration wird jetzt unter Matter-Integrationen angezeigt.
  10. Starten Sie Ihren Hub neu, damit er die aktuelle Konfiguration des Matter-Integrationsprojekts erhält. Wenn du die VID oder PID später ändern musst, musst du auch nach dem Speichern des Projekts neu starten, damit die Änderung wirksam wird. Eine detaillierte Anleitung zum Neustart finden Sie unter Google Nest- oder Google Wifi-Geräte neu starten.

4. Gerät entwickeln

Alle Beispiele in Matter befinden sich im Ordner examples im GitHub-Repository. Es sind mehrere Beispiele verfügbar. In diesem Codelab konzentrieren wir uns jedoch auf Chef.

Chef ist beides:

  • Eine Beispiel-App, die eine Terminalschnittstelle mit Wrapping-Funktionen bereitstellt, die auch in der examples/shell-App verfügbar sind.
  • Ein Skript, das das Prinzip der Konventionsellen Konfiguration aufgreift, um mehrere der allgemeinen Aufgaben zu kapseln, die für die Entwicklung eines Matter-kompatiblen Geräts erforderlich sind.

Rufen Sie den Beispielordner „Chef“ auf und erstellen Sie Ihren ersten Matter-Build:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef bietet einige Optionen, die durch Ausführen von chef.py -h angezeigt werden können. Hier verwenden wir folgende Optionen:

  • -d: definiert den zu verwendenden Gerätetyp. In diesem Fall erstellen wir eine Beleuchtungs-App mit Ein-/Aus- und Lautstärkereglern.
  • -z: ruft das ZAP-Tool auf, um die Quelldateien zu generieren, die den Gerätetyp implementieren. Das heißt, ZAP erstellt basierend auf Ihrer Auswahl der Beleuchtung automatisch Code, der in den Build eingebunden wird. Dieser Code definiert das Licht (das Datenmodell) und wie es mit anderen Geräten (dem Interaktionsmodell) interagiert.
  • -b: Builds.
  • -r: [optional] aktiviert den RPC-Server auf dem virtuellen Matter-Gerät, sodass andere Komponenten (z. B. die GUI) mit dem Gerät kommunizieren können, um Datenmodellattribute festzulegen und abzurufen.
  • -t linux: Zielplattform. Die Supportplattformen sind linux, nrfconnect und esp32. Sie können ./chef.py -h ausführen, um alle verfügbaren Befehle und unterstützten Zielplattformen zu sehen. linux wird für virtuelle Matter-Geräte verwendet.

Gerät ausführen

Matter verwendet den TCP/UDP-Port 5540. Wenn auf Ihrem Computer eine Firewall ausgeführt wird, fahren Sie sie entweder herunter oder lassen Sie eingehende TCP/UDP-Verbindungen über Port 5540 zu.

Führen Sie das virtuelle Gerät im Container mit folgendem Befehl aus:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Lassen Sie Ihr Gerät laufen. Jetzt konzentrieren wir uns auf die Google Home App, damit wir dein Gerät bei Google Home in Betrieb nehmen können.

Halte das Gerät an.

Wenn Sie das Gerät beenden müssen, können Sie das Programm mit Strg + C beenden. Wenn die App nicht beendet wird, müssen Sie möglicherweise auch STRG+\ drücken.

Die Anmeldedaten für Ihr virtuelles Gerät werden im Verzeichnis /tmp/ in Dateien gespeichert, die mit dem Präfix chip beginnen.

Wenn Sie den gesamten Inbetriebnahmeprozess von Anfang an wiederholen möchten, müssen Sie diese Dateien löschen, indem Sie den folgenden Befehl ausführen:

$ rm /tmp/chip*

5. Die virtuelle Gerätesteuerung

Der Virtual Device Controller ist eine eigenständige App mit einer grafischen Benutzeroberfläche, über die du den Status deiner virtuellen Matter-Geräte steuern und anzeigen kannst. Die Kommunikation mit den Matter-Geräten, die mit deiner Entwicklungsumgebung verbunden sind, erfolgt über einen RPC-Client.

Die virtuelle Gerätesteuerung

Der Virtual Device Controller bietet eine visuelle Darstellung Ihres virtuellen Geräts.

Sie können über die grafische Benutzeroberfläche (GUI) des Virtual Device Controllers mit dem virtuellen Gerät interagieren. Ihre Änderungen in der GUI wirken sich auf das zugrunde liegende Datenmodell aus. Unter Unterstützte Geräte findest du eine vollständige Liste der unterstützten Matter Virtual-Gerätetypen.

Virtuellen Gerätecontroller installieren

Der Virtual Device Controller ist im Ubuntu LTS 20.04-Docker-Container vorinstalliert.

Virtuellen Gerätecontroller ausführen

Erstellen Sie die zweite Terminalsitzungsinstanz:

user@host> docker exec -it matter-container /bin/bash
$

Starten Sie den Virtual Device Controller, indem Sie den Netzwerk-Socket angeben, der für die Kommunikation mit dem virtuellen Gerät verwendet wird:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Wenn Sie den Controller starten, ohne Argumente anzugeben, wird standardmäßig die Netzwerk-Socket-Option mit dem Localhost-Port 33000 verwendet. Sobald der Controller eine Verbindung zum virtuellen Gerät herstellen kann, wird ein Bildschirm mit Ihrem Gerätestatus angezeigt:

Grafische Benutzeroberfläche für virtuelle Geräte

Die App sendet Anfragen an den RPC-Server des Geräts, wenn Sie Änderungen an der Virtual Controller App vornehmen, und fragt den RPC-Server einmal pro Sekunde ab, um den Status abzurufen.

Die App „Virtual Device Controller“ kann auch verwendet werden, um den QR-Code im Rahmen der Inbetriebnahme des Geräts abzurufen. Klicke auf das QR-Code-Symbol neben dem Gerätebild, um den QR-Code für dieses Gerät anzuzeigen. Verwende diesen QR-Code, um dein Gerät in Betrieb zu nehmen.

6. Gerät in Betrieb nehmen

Hinweis: Dieser Schritt ist nur erfolgreich, wenn Sie Ihr Projekt bereits in der Google Home Developer Console eingerichtet haben.

Nest Hub

Ein Hub ist erforderlich, um dein Gerät auf dem Matter-Fabric in Betrieb zu nehmen. Es handelt sich um ein Google Nest-Gerät wie Nest Hub (2. Generation), das Matter unterstützt und als Border-Router für Thread-kompatible Geräte sowie als lokaler Auftragsausführungspfad für das Routing von Smart-Home-Intents dient.

In dieser Liste siehst du, welche Hubs Matter unterstützen.

Prüfen Sie vor der Inbetriebnahme Folgendes:

  • Ihr Hub ist mit demselben Google-Konto gekoppelt, mit dem Sie sich in der Google Home Console angemeldet haben.
  • Der Hub ist mit demselben WLAN wie der Computer verbunden, auf dem du dein Virtual Matter-Gerät verwendest.
  • Dein Hub befindet sich in der Struktur, die du in der Google Home App verwendest. Das „Haus“ in Google Home Graph ist dein Gebäude.

QR-Code anfordern

Für die Inbetriebnahme müssen die Onboarding-Informationen von Matter über einen QR-Code bereitgestellt werden. Den QR-Code für Ihr virtuelles Gerät erhalten Sie vom Virtual Device Controller.

Inbetriebnahme durchführen

  1. Öffnen Sie die Google Home App.
  2. Tippen Sie links oben auf das +.
  3. Tippen Sie auf Gerät einrichten.
  4. Tippen Sie auf Neues Gerät.
  5. Wählen Sie Ihr Zuhause aus und tippen Sie auf Weiter.
  6. Die Google Home App sucht nach Ihrem Gerät. Wenn die Meldung „Matter-Gerät gefunden...“ angezeigt wird, tippen Sie auf „Ja“. Tippen Sie andernfalls auf Anderes Gerät einrichten und wählen Sie Matter-Gerät aus der Liste der Geräte aus.
  7. Richten Sie Ihre Kamera auf den QR-Code Ihres Geräts oder auf den von einer Website generierten QR-Code.
  8. Setzen Sie die Kopplung wie in der Google Home App beschrieben fort.

Nachdem Sie diese Schritte ausgeführt haben, sollte das virtuelle Matter-Gerät erfolgreich in Betrieb genommen werden und in der Google Home App als neues Symbol angezeigt werden.

Gekoppelte Lampe in der Google Home App

Fehlerbehebung

Fehler bei der Inbetriebnahme mit der Fehlermeldung „Verbindungsproblem“ oder „Google konnte nicht kontaktiert werden“

  • Prüfen Sie, ob Sie ein Projekt mit der richtigen Kombination aus VID und PID in der Google Home Console erstellt haben und keine anderen Projekte mit derselben Kombination aus VID und PID vorhanden sind.

Die Inbetriebnahme schlägt nach längerem „Scannen des Geräts“ fehl

7. Gerät steuern

Sobald Ihr Matter-kompatibles Gerät in Betrieb genommen wurde und in der Google Home App als Glühbirne angezeigt wird, können Sie die Steuerung des Geräts auf verschiedene Weise testen:

  • Google Assistant wird verwendet.
  • Über die Google Home App
  • Über die GUI des virtuellen Geräts

Google Assistant

Mit Google Assistant auf Ihrem Smartphone oder Hub können Sie den Gerätestatus per Sprachbefehl ändern, z. B. mit „Hey Google, schalte meine Lampen“.

Weitere Beispiele für Befehle finden Sie im Abschnitt Smart-Home-Geräte mit Sprachbefehlen steuern des Hilfeartikels Zur Google Home App hinzugefügte Smart-Home-Geräte steuern.

Google Home App

Sie können neben dem Glühbirnensymbol, das in der Google Home App angezeigt wird, auf die Labels An und Aus tippen.

Weitere Informationen finden Sie im Abschnitt Geräte mit der Google Home App steuern unter Smart-Home-Geräte steuern, die der Google Home App hinzugefügt wurden.

GUI des virtuellen Geräts

Sie können mit der grafischen Benutzeroberfläche des virtuellen Geräts interagieren, um den Status des Geräts zu ändern. Unabhängig davon, ob Sie das virtuelle Gerät mit dem virtuellen Gerätecontroller, der Google Home App auf Ihrem Smartphone oder mit Ihrem Hub steuern – alle diese Schnittstellen spiegeln den aktuellen Status des virtuellen Geräts wider.

8. Glückwunsch!

Du hast dein erstes Matter-Gerät erstellt. Prima!

In diesem Codelab haben Sie Folgendes gelernt:

  • Matter-Entwicklungsumgebung mit einem vorkonfigurierten Docker-Image installieren
  • Virtuelles Matter-Gerät erstellen und ausführen
  • Du kannst dein virtuelles Gerät über Google Home in Betrieb nehmen und steuern.

Weitere Informationen zu Matter finden Sie in den folgenden Referenzen: