Hinweis: Neue Vorschauprogramme für Entwickler werden bald eingeführt. Bewirb dich hier und probiere als einer der Ersten neue Tools aus und gib uns Feedback.

Virtuelles Gerät erstellen

1. Einführung

Matter ist ein Verbindungsprotokoll, das aufregende Möglichkeiten für die Entwicklung von Smart-Home-Geräten bietet. In diesem Codelab erstellen Sie mithilfe von SDKs und Abhängigkeiten Ihr erstes Matter-Gerät in einem vorkonfigurierten Docker-Image.

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 dem Computer ausgeführt wird
  • Virtuelle Matter-Geräte mit Google Home in Betrieb nehmen und steuern

Voraussetzungen

  • Ein Hub, der jedes Google Nest-Gerät ist, das Matter unterstützt, z. B. Nest Hub (2. Generation). Sie können einen Hub im Google Store oder bei Ihrem bevorzugten Händler kaufen.
  • Ein Linux-Computer, auf dem das X11-Windowing-System ausgeführt wird.
  • Docker
  • Grundkenntnisse in Linux

2. Umgebung einrichten

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

Hardware prüfen

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

Bei dieser Anleitung wird außerdem davon ausgegangen, dass auf Ihrem Linux-Computer das Windowing-System X11 ausgeführt wird. Wenn Wayland auf Ihrem Linux-Computer ausgeführt wird, prüfen Sie, ob X.Org installiert ist.

Docker einrichten

  1. Installieren Sie Docker Engine (verwenden Sie nicht Docker Desktop).
  2. Rufen Sie das Docker-Image aus Docker Hub ab. Führen Sie in einem Terminalfenster den folgenden Befehl 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 ausgeführten Docker-Container:
    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 sollte eine Diagnoseausgabe angezeigt werden, gefolgt von einer Meldung, dass Ihre Containerkonfiguration korrekt ist, und schließlich die Container-Shell-Eingabeaufforderung:

Environment looks good, you are ready to go!
$

Sehen wir uns den Docker-Befehl und die an ihn übergebenen Optionen an:

  • xhost local:1000 ermöglicht dem X-Fenstersystem, Verbindungen vom lokalen Host auf Port 1000 zu empfangen. So kann eine grafische Benutzeroberfläche verwendet werden.
  • docker run … image führt das angegebene Image aus und ruft es bei Bedarf aus der Docker-Registry ab.
  • --ipc=host ermöglicht Docker, den Namespace für die Interprozesskommunikation mit Ihrem Hostcomputer zu teilen.
  • 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 auf den Host und bietet Zugriff auf die grafische Benutzeroberfläche Ihres Systems. Dies ist erforderlich, um das ZAP-Tool beim Bearbeiten von Matter-Clustern auszuführen.
  • -it führt Docker mit einem interaktiven Terminal (tty) anstelle eines Hintergrundprozesses 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

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 möchten Sie das aber tun, weil Sie mit einer Neuinstallation beginnen können. Manchmal ist es jedoch besser, die Konfiguration Ihrer Arbeits- und Umgebung zwischen den Sitzungen zu speichern.

Aus diesem Grund können Sie nach dem Erstellen des Containers den Container beenden, damit Ihre Arbeit nicht verloren geht.

user@host> docker stop matter-container

Wenn Sie wieder zur Ausführung bereit sind, 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 Ihren Container mit folgenden Terminalsitzungen öffnen:

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

Oder starten Sie eine Stammsitzung mit:

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

Ersteinrichtung

Wenn sich Ihr 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 dem Hostcomputer aus dem Container können Sie eine Bindungsbereitstellung verwenden. Sie können auch Dateien aus dem Container in das bereitgestellte Verzeichnis schreiben, um einfach vom Host aus 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 im 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 Verzeichnis fest, das vom Container bereitgestellt wird.

Legen Sie die Gruppe für Dateien im bereitgestellten Verzeichnis rekursiv auf die Gruppe des Containernutzers fest.

user@host> sudo chgrp -R 1000 .

Gewähren Sie der Gruppe die gewünschten Berechtigungen im Verzeichnis. In diesem Beispiel erhält die Gruppe des Containernutzers Berechtigungen zum Lesen, Schreiben und Ausführen für alle Dateien im bereitgestellten Verzeichnis.

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

Beachten Sie, dass diese Befehle keinen Einfluss auf die Berechtigung neuer Dateien haben, die vom Hostnutzer erstellt wurden. Denken Sie daran, die Berechtigungen neuer Dateien, die auf dem Host erstellt werden, nach Bedarf zu aktualisieren.

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

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 Sie Ihre Matter-Integrationen in Google Home verwalten.

Alle Matter-Geräte, die die CSA Matter-Zertifizierung bestanden haben, funktionieren im Google Home-System. In Entwicklung befindliche Geräte, die nicht zertifiziert sind, können unter bestimmten Bedingungen im Google Home-System in Betrieb genommen werden. Weitere Informationen finden Sie unter Einschränkungen beim Koppeln.

Entwicklerprojekt erstellen

Öffnen Sie zuerst die Google Home Developer Console:

  1. Klicken Sie auf der Seite Projekte verwalten auf Projekt erstellen.
    Google Home-Entwicklercenter
  2. Klicken Sie auf der Seite Jetzt starten auf Projekt erstellen.

  1. Geben Sie einen eindeutigen Projektnamen ein und klicken Sie dann auf Neues Projekt erstellen. Dialogfeld „Neues Projekt erstellen“
  2. Klicken Sie auf + Integration hinzufügen, um den Bildschirm „Matter-Ressourcen“ aufzurufen. Hier finden Sie die Matter-Entwicklungsdokumentation und Informationen zu einigen Tools.
  3. Wenn Sie fortfahren möchten, klicken Sie auf Weiter: Entwickeln, um die Seite Matter-Checkliste aufzurufen.
  4. Klicken Sie auf Weiter: Einrichtung.
  5. Geben Sie auf der Seite Einrichtung Ihren Produktnamen ein.
  6. Klicken Sie auf Gerätetyp auswählen und wählen Sie dann im Drop-down-Menü den Gerätetyp aus (in diesem Fall Light).
  7. Wählen Sie unter „Anbieter-ID (VID)“ die Option Test VID und dann „0xFFF1“ aus dem Drop-down-Menü „Test VID“ aus. Geben Sie im Feld „Produkt-ID (PID)“ den Wert „0x8000“ ein und klicken Sie auf Speichern und fortfahren. Klicken Sie dann auf der nächsten Seite auf Speichern.
    Projekt einrichten
  8. Jetzt siehst du unter Matter-Integrationen ein Matter-Gerät. Matter-Integrationen
  9. Starte deinen Hub neu, damit er die aktuelle Matter-Integrationsprojektkonfiguration erhält. Wenn Sie die VID oder PID später ändern müssen, müssen Sie das Projekt auch neu starten, damit die Änderung wirksam wird.

4. Gerät erstellen

Alle Beispiele in Matter finden Sie im Ordner examples im GitHub-Repository. Es gibt verschiedene Beispiele, aber bei diesem Codelab liegt der Schwerpunkt auf Chef.

Chef ist beides:

  • Eine Beispiel-App mit einer Terminalschnittstelle, die auch Funktionen in der examples/shell-App umschließt.
  • Ein Skript, das das Prinzip der Konvention-über-Konfiguration verwendet, um mehrere gängige Aufgaben einzuschließen, die für die Entwicklung eines Matter-fähigen Geräts erforderlich sind.

Gehen Sie zum Chef-Beispielordner und erstellen Sie Ihren ersten Matter-Build:

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

Chef hat mehrere Optionen, die mit chef.py -h ausgeführt werden können. Folgende Optionen werden verwendet:

  • -d: Definiert den zu verwendenden Gerätetyp. In diesem Fall erstellen wir eine Beleuchtungs-App mit Ein/Aus- und Level-Steuerung.
  • -z: ruft das ZAP-Tool auf, um die Quelldateien zu generieren, die den Gerätetyp implementieren. Basierend auf Ihrer Auswahl der Beleuchtung erstellt ZAP automatisch Code, der in den Build integriert wird, der das Licht (das Datenmodell) und seine Interaktion mit anderen Geräten (dem Interaktionsmodell) definiert.
  • -b: Builds.
  • -r: [optional] aktiviert den RPC-Server auf dem virtuellen Matter-Gerät, sodass andere Komponenten (z. B. das 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 aufzurufen. linux wird für virtuelle Matter-Geräte verwendet.

Gerät ausführen

Matter verwendet den TCP/UDP-Port 5540. Wenn Sie also eine Firewall auf Ihrem Computer verwenden, deaktivieren Sie diesen oder lassen Sie eingehende TCP/UDP-Verbindungen über Port 5540 zu.

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

$ ./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]

Lass dein Gerät laufen. Als Nächstes wenden wir uns der Google Home App zu, damit wir dein Gerät für Google Home in Betrieb nehmen können.

Gerät beenden

Du kannst das Programm mit Strg + C beenden. Wenn die App nicht beendet wird, müssen Sie möglicherweise auch Strg + \ verwenden.

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 Provisionsprozess von Anfang an wiederholen möchten, müssen Sie diese Dateien mit dem folgenden Befehl löschen:

$ rm /tmp/chip*

5. Der virtuelle Gerätecontroller

Der Virtual Device Controller ist eine eigenständige App mit einer grafischen Benutzeroberfläche, über die Sie den Status Ihrer virtuellen Matter-Geräte steuern und anzeigen können. Es verwendet einen RPC-Client, um mit den Matter-Geräten zu kommunizieren, die mit Ihrer Entwicklungsumgebung verbunden sind.

Der virtuelle Gerätecontroller

Der virtuelle Gerätecontroller bietet eine visuelle Darstellung deines virtuellen Geräts.

Sie können über die grafische Benutzeroberfläche (Virtual Device Controller, GUI) mit dem virtuellen Gerät interagieren. Änderungen am GUI wirken sich auf das zugrunde liegende Datenmodell aus. Der Virtual Device Controller unterstützt derzeit den Gerätetyp „Dimmable Light“.

Virtuellen Gerätecontroller installieren

Der virtuelle Gerätecontroller ist auf dem Ubuntu LTS 20.04-Docker-Container vorinstalliert.

Controller für virtuelle Geräte ausführen

Erstellen Sie die zweite Instanz der Terminalsitzung:

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

Starten Sie den virtuellen Gerätecontroller, indem Sie den Netzwerkanschluss 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 NetzwerkSocket-Option mit dem Localhost-Port 33000 verwendet. Sobald der Controller eine Verbindung zum virtuellen Gerät herstellen kann, wird ein Bildschirm mit deinem Gerätestatus angezeigt:

Grafik der Benutzeroberfläche des virtuellen Geräts

Die App sendet Anfragen an den RPC-Server des Geräts, wenn Sie Änderungen in der Virtual Controller App vornehmen, und ruft 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. Klicken Sie neben dem Gerätebild auf das Symbol für den QR-Code, um den QR-Code für dieses Gerät aufzurufen:

QR-Code

Mit diesem QR-Code können Sie Ihr Gerät in Betrieb 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

Zur Inbetriebnahme Ihres Geräts auf dem Matter-Stoff ist ein Hub erforderlich. Dies ist ein Google Nest-Gerät wie Nest Hub (2. Generation), das Matter unterstützt und sowohl als Border-Router für Thread-fähige Geräte als auch als lokaler Auftragsausführungspfad für die Weiterleitung von Smart-Home-Intents dient.

In dieser Liste sehen Sie, welche Hubs Matter unterstützen.

Bevor Sie mit der Inbetriebnahme beginnen, prüfen Sie Folgendes:

  • Ihr Hub ist mit demselben Google-Konto gekoppelt, mit dem Sie sich in der Google Home Console angemeldet haben.
  • Dein Hub ist mit demselben WLAN wie der Computer verbunden, auf dem du dein Virtual-Matter-Gerät verwendest.
  • Ihr Hub befindet sich in derselben Struktur, die Sie in Ihrer Google Home App verwenden. Das „Haus“ im Google Home Graph steht für Ihre Struktur.

QR-Code anfordern

Für die Inbetriebnahme müssen Onboarding-Informationen von Matter über einen QR-Code benötigt werden. Sie können den QR-Code für Ihr virtuelles Gerät über den virtuellen Gerätecontroller abrufen.

Provisionsvorgang ausführen

  1. Öffnen Sie die Google Home App.
  2. Tippen Sie oben links auf +.
  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 deinem Gerät. Wenn die Meldung „Matter-Gerät gefunden...“ erscheint, tippen Sie auf „Ja“. Tippen Sie andernfalls auf Anderes Gerät einrichten und wählen Sie dann Matter-Gerät aus der Liste der Geräte aus.
  7. Richten Sie die Kamera auf den QR-Code Ihres Geräts oder auf den von der Website generierten QR-Code.
  8. Fahren Sie mit dem in der Google Home App angegebenen Vorgang fort.

Anschließend sollte das virtuelle Matter-Gerät als neues Symbol in der Google Home App angezeigt werden.

Gekoppelte Lampe in der Google Home App

Fehlerbehebung

Die Inbetriebnahme schlägt mit den Fehlermeldungen „Verbindungsproblem“ oder „Es konnte keine Verbindung zu Google hergestellt werden“ fehl.

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

Die Inbetriebnahme schlägt nach der Überprüfung Ihres Geräts über einen längeren Zeitraum fehl

7. Gerät steuern

Sobald Ihr Matter-fähiges Gerät erfolgreich 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
  • Das GUI des virtuellen Geräts verwenden.

Google Assistant

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

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

Google Home App

Sie können neben dem in der Google Home App angezeigten Glühbirnensymbol auf 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.

Benutzeroberfläche für virtuelle Geräte

Sie können die virtuelle Geräte-GUI verwenden, um den Status des Geräts zu ändern. Unabhängig davon, ob du das virtuelle Gerät mit dem virtuellen Gerätecontroller, der Google Home App auf deinem Smartphone oder mit deinem Hub steuerst, spiegeln alle diese Schnittstellen 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:

  • Installieren Sie eine Matter-Entwicklungsumgebung mithilfe eines vorkonfigurierten Docker-Images.
  • Virtuelles Matter-Gerät erstellen und ausführen
  • Virtuelle Geräte über Google Home verwalten und steuern.

Weitere Informationen zu Matter finden Sie in diesen Referenzen: