Virtuelles Matter-Gerät erstellen

1. Einführung

Matter ist ein Verbindungsprotokoll, das spannende Möglichkeiten für die Entwicklung von Smart-Home-Geräten bietet. In diesem Codelab erstellen Sie Ihr erstes Matter-Gerät mit Ressourcen aus dem Matter SDK.

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 Ihrem Computer ausgeführt wird
  • Virtuelles Matter-Gerät mit Google Home einrichten und steuern

Voraussetzungen

  • Ein Hub, z. B. ein Google Nest Hub (2. Generation), also ein beliebiges Google Nest-Gerät, das Matter unterstützt.
  • Ein Linux-Computer mit dem X11-Fenstersystem.
  • Docker
  • Git
  • Grundkenntnisse in Linux
    • Hinweis: Die in diesem Codelab verwendete Shell ist BASH.

2. Umgebung einrichten

Hardware prüfen

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

Außerdem wird in dieser Anleitung davon ausgegangen, dass auf Ihrem Linux-Computer das X11-Fenstersystem ausgeführt wird. Wenn auf Ihrem Linux-Computer Wayland ausgeführt wird, muss auch X.Org installiert sein.

Entwicklungsumgebung einrichten

  1. Installieren Sie Docker Engine (verwenden Sie nicht Docker Desktop).
  2. Klonen Sie das Matter SDK. Notieren Sie sich den Commit, den wir im Folgenden verwenden.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Führen Sie einen Build-Container mit den öffentlichen CI-Images des SDK aus und führen Sie das neu erstellte virtuelle Gerät in diesem Container aus. So finden Sie das Image, das unserer SDK-Version entspricht:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Wenn Sie denselben Commit verwenden, sollte ghcr.io/project-chip/chip-build:66 angezeigt werden.Leiten Sie zuerst die xhost-Ports weiter, damit wir später UI-Anwendungen verwenden können:
    xhost local:1000
    Starten Sie dann den Container mit den entsprechenden Ressourcen, die vom Host weitergeleitet werden (unser SDK-Checkout, Netzwerk- und Anzeige-/Kommunikationsressourcen).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

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

  • xhost local:1000 ermöglicht dem X Window System, Verbindungen vom lokalen Host auf Port 1000 zu empfangen, sodass eine grafische Benutzeroberfläche verwendet werden kann.
  • 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.
  • --net=host ermöglicht Docker, den Netzwerkstack des Hosts im Container zu 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 ermöglicht so den 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) aus, nicht als Hintergrundprozess.
  • --mount stellt das SDK, das wir zuvor ausgecheckt haben, im Container bereit.
  • --workdir legt das Arbeitsverzeichnis beim Start auf unser bereitgestelltes SDK-Verzeichnis fest.

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

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

Matter-Docker-Container beenden und starten

Bei jedem Ausführen eines docker run-Befehls wird ein neuer Container mit dem angegebenen Image erstellt. Dabei gehen Ihre alten Daten verloren, die in einer vorherigen Containerinstanz gespeichert wurden. Manchmal ist das gewünscht, da Sie so mit einer neuen Installation beginnen können. Es gibt aber auch Fälle, in denen Sie Ihre Arbeit und die Umgebungskonfiguration zwischen Sitzungen speichern möchten.

Aus diesem Grund können Sie den Container nach dem Erstellen beenden, um zu verhindern, dass Ihre Arbeit verloren geht.

user@host> docker stop matter-container

Wenn Sie wieder bereit sind, führen Sie den Container aus 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 mit folgendem Befehl öffnen:

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

Oder starten Sie eine Root-Sitzung mit folgendem Befehl:

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

Ersteinrichtung von Matter

SDK initialisieren

Initialisieren Sie das Matter SDK. Dieser Vorgang kann mehrere Minuten dauern.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

Ihr Matter SDK ist jetzt initialisiert. So initialisieren Sie die Umgebung in Zukunft schnell neu:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Dateien zwischen Host und Container freigeben

Zuvor haben wir über eine Bind-Bereitstellung aus dem Container heraus auf die Dateien auf Ihrem Hostcomputer zugegriffen. Sie können auch Dateien aus dem Container in das bereitgestellte Verzeichnis schreiben, um vom Host aus darauf zuzugreifen.

Im Allgemeinen verwenden Sie Bind-Bereitstellungen, indem Sie den Container mit dem zusätzlichen Argument --mount source=$(pwd),target=/workspace,type=bind ausführen, um das aktuelle Arbeitsverzeichnis unter /workspace im Container 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 Container-Nutzers für das bereitgestellte Verzeichnis müssen auf dem Host verwaltet werden.

Rufen Sie die Gruppen-ID des Container-Nutzers im Container ab.

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

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

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

user@host> sudo chgrp -R 1000 .

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

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

Diese Befehle wirken sich nicht auf die Berechtigungen neuer Dateien aus, die vom Hostnutzer erstellt wurden. Denken Sie daran, die Berechtigungen für neue Dateien, die auf dem Host erstellt wurden, nach Bedarf zu aktualisieren.

Sie können Ihren Hostnutzer der Gruppe des Container-Nutzers hinzufügen, um Berechtigungen für Dateien zu übernehmen, die vom Container-Nutzer erstellt wurden.

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

3. Google Home Developer Console

Die Google Home Developer Console ist die Webanwendung, in der Sie Ihre Matter-Integrationen mit Google Home verwalten.

Alle Matter-Geräte, die die Matter-Zertifizierung der Connectivity Standards Alliance (Alliance) bestanden haben, funktionieren im Google Home-Ökosystem. Geräte in der Entwicklung, die noch nicht zertifiziert wurden, können unter bestimmten Bedingungen im Google Home-Ökosystem eingerichtet werden. Weitere Informationen finden Sie unter Einschränkungen bei der Kopplung.

Entwicklerprojekt erstellen

Rufen Sie zuerst die Google Home Developer Console auf:

  1. Klicken Sie auf Projekt erstellen.
  2. Geben Sie einen eindeutigen Projektnamen ein und klicken Sie dann auf Projekt erstellen. Dialogfeld „Neues Projekt erstellen“
  3. Klicken Sie auf + Integration hinzufügen, um zum Bildschirm Matter-Ressourcen zu gelangen. Dort finden Sie die Matter-Entwicklerdokumentation und Informationen zu einigen Tools.
  4. Wenn Sie bereit sind, klicken Sie auf Weiter: Entwickeln, um die Seite Matter-Checkliste aufzurufen.
  5. Klicken Sie auf Weiter: Einrichtung.
  6. Geben Sie auf der Seite Einrichtung den 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 aus und wählen Sie im Drop-down-Menü „Test-VID“ die Option „0xFFF1“ aus. Geben Sie unter „Produkt-ID (PID)“ den Wert „0x8000“ ein und klicken Sie auf Speichern und fortfahren und dann auf der folgenden Seite auf Speichern. Verwenden Sie genau diese VID/PID-Werte, da spätere Schritte im Codelab davon abhängen.
    Projekt einrichten
  9. Ihre Integration wird jetzt unter Matter-Integrationen angezeigt.
  10. Starten Sie den Hub neu, damit er die neueste Konfiguration des Matter-Integrationsprojekts erhält. Wenn Sie die VID oder PID später ändern müssen, müssen Sie den Hub auch neu starten, nachdem Sie das Projekt gespeichert haben, 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 erstellen

Alle Beispiele in Matter finden Sie im Ordner examples im GitHub-Repository. Es sind mehrere Beispiele verfügbar, aber in diesem Codelab konzentrieren wir uns auf Chef.

Chef ist beides:

  • Eine Beispiel-App mit einer Terminaloberfläche, die Funktionen enthält, die auch in der App examples/shell zu finden sind.
  • Ein Skript, das dem Prinzip „Konvention vor Konfiguration“ folgt, um mehrere der gängigen Aufgaben zu kapseln, die für die Entwicklung eines Matter-kompatiblen Geräts erforderlich sind.

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

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

Chef hat einige Optionen, die mit chef.py -h angezeigt werden können. Die hier verwendeten Optionen sind:

  • -d: definiert den zu verwendenden Gerätetyp. In diesem Fall erstellen wir eine Beleuchtungs-App mit Ein/Aus- und Helligkeitssteuerung.
  • -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 aufgenommen werden soll und das Licht (das Datenmodell) und die Interaktion mit anderen Geräten (das Interaktionsmodell) definiert.
  • -b: erstellt.
  • -r: [optional] aktiviert den RPC-Server auf dem virtuellen Matter-Gerät, damit andere Komponenten (z. B. die GUI) mit dem Gerät kommunizieren können, um Attribute des Datenmodells festzulegen und abzurufen.
  • -t linux: Zielplattform. Die unterstützten Plattformen 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, beenden Sie sie oder lassen Sie eingehende TCP/UDP-Verbindungen auf 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 wenden wir uns der Google Home App zu, damit wir Ihr Gerät in Google Home einrichten können.

Gerät beenden

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 + \ verwenden.

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

Wenn Sie den gesamten Einrichtungsprozess von Anfang an wiederholen möchten, müssen Sie diese Dateien mit dem folgenden Befehl löschen:

$ rm /tmp/chip*

5. Gerät einrichten

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 Ihr Gerät in der Matter-Fabric einzurichten. Dabei handelt es sich um ein Google Nest-Gerät, z. B. den Nest Hub (2. Generation), das Matter unterstützt und sowohl als Border-Router für Thread-fähige Geräte als auch als lokaler Fulfillment-Pfad für das Routing von Smart-Home-Intents dient.

In dieser Liste finden Sie die Hubs, die Matter unterstützen.

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

  • Ihr Hub ist mit demselben Google-Konto gekoppelt, mit dem Sie sich in der Google Home Console angemeldet haben.
  • Ihr Hub befindet sich im selben WLAN wie der Computer, auf dem Sie Ihr virtuelles Matter-Gerät ausführen.
  • Ihr Hub befindet sich in derselben Struktur, die Sie in der Google Home App verwenden. Das "Haus" im Google Home Graph stellt Ihre Struktur dar.

QR-Code abrufen

Für die Einrichtung sind Matter-Onboarding-Informationen erforderlich, die über einen QR-Code bereitgestellt werden. Sehen Sie sich die Konsolenausgabe der Matter-Anwendung an. Sie enthält einen Link zum QR-Code, der für die Einrichtung relevant ist.

Einrichtungsvorgang ausführen

  1. Öffnen Sie die Google Home App.
  2. Tippen Sie oben links auf das Pluszeichen.
  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 dann in der Liste der Geräte Matter-Gerät aus.
  7. Richten Sie die Kamera auf den QR-Code Ihres Geräts oder den auf der Website generierten QR-Code.
  8. Setzen Sie den Kopplungsvorgang wie im Google Home App-Ablauf angegeben fort.

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

Gekoppelte Glühbirne in der Google Home App

Fehlerbehebung

Einrichtung schlägt mit den Fehlermeldungen „Verbindungsproblem“ oder „Google konnte nicht kontaktiert werden“ fehl

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

Einrichtung schlägt fehl, nachdem das Gerät lange gescannt wurde

6. Gerät steuern

Sobald Ihr Matter-kompatibles Gerät eingerichtet ist und in der Google Home App als Glühbirne angezeigt wird, können Sie die Steuerung des Geräts mit verschiedenen Methoden testen:

  • Mit Google Assistant
  • Mit der Google Home App

Google Assistant

Verwenden Sie Google Assistant auf Ihrem Smartphone oder Hub, um den Gerätestatus mit Sprachbefehlen zu ändern, z. B. „Hey Google, schalte meine Lichter 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 auf die Labels Ein und Aus neben dem Glühbirnensymbol in der Google Home App 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.

7. Glückwunsch!

Sie haben Ihr erstes Matter-Gerät erstellt. Sehr gut!

In diesem Codelab haben Sie Folgendes gelernt:

  • Matter-Entwicklungsumgebung installieren
  • Virtuelles Matter-Gerät erstellen und ausführen
  • Virtuelles Gerät über Google Home einrichten und steuern

Weitere Informationen zu Matter finden Sie in diesen Referenzen: