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 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
  • Virtuelle Matter-Geräte für deinen Computer erstellen
  • Virtuelle Matter-Geräte mit Google Home in Betrieb nehmen und steuern

Voraussetzungen

  • Ein Hub, also ein Google Nest-Gerät, das Matter unterstützt, z. B. Nest Hub (2. Generation).
  • Ein Linux-Computer, auf dem das X11-Windowing-System ausgeführt wird.
  • Docker erstellen.
  • Git
  • Grundkenntnisse in Linux
    • In diesem Codelab wird für alle Befehle BASH als Shell vorausgesetzt.

2. Umgebung einrichten

Hardware prüfen

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

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

Entwicklungsumgebung einrichten

  1. Installieren Sie Docker Engine (nicht Docker Desktop).
  2. Klonen Sie das Matter-SDK und 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 SDKs und das neu erstellte virtuelle Gerät in diesem Container aus. Suchen Sie das Bild, das mit unserer SDK-Version übereinstimmen soll:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Wenn Sie denselben Commit verwenden, wird die Meldung ghcr.io/project-chip/chip-build:66Zuerst xhost-Ports weiterleiten, damit wir später Benutzeroberflächenanwendungen verwenden können:
    xhost local:1000
    Als Nächstes starten Sie den Container mit entsprechenden Ressourcen, die vom Host weitergeleitet wurden (unsere SDK-Checkout-, Netzwerk- und Display-/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 an ihn übergeben haben:

  • xhost local:1000 ermöglicht dem X Window System, Verbindungen vom lokalen Host an Port 1000 zu empfangen, sodass eine grafische Benutzeroberfläche verwendet werden kann.
  • docker run … image führt das angegebene Image aus und ruft es gegebenenfalls aus der Docker-Registry ab.
  • --ipc=host ermöglicht Docker, den Namespace für die Interprozesskommunikation für Ihren Hostcomputer freizugeben.
  • --net=host ermöglicht Docker, den Netzwerkstack des Hosts im Container zu verwenden. Dies ist erforderlich, um mDNS-Traffic vom Host an den Container zu übergeben und die X11-Anzeige des Hosts freizugeben.
  • -e DISPLAY exportiert $DISPLAY an den Host und ermöglicht so Zugriff auf die Grafikoberfläche deines 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.
  • --mount stellt das zuvor geprüfte SDK im Container bereit.
  • --workdir legt beim Start als Arbeitsverzeichnis das bereitgestellte 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

Wenn Sie einen docker run-Befehl ausführen, erstellen Sie einen neuen Container mit dem angegebenen Image. Dabei gehen Ihre alten Daten, die in einer vorherigen Containerinstanz gespeichert wurden, verloren. Manchmal ist das so, was Sie möchten, denn Sie können dann mit einer neuen Installation beginnen. Manchmal empfiehlt es sich jedoch, Ihre Arbeits- und Umgebungskonfiguration zwischen Sitzungen zu speichern.

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

user@host> docker stop matter-container

Wenn die Ausführung wieder möglich ist, starten Sie den Container und öffnen Sie ein Terminalfenster:

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

Mit den folgenden Methoden können Sie zusätzliche Terminalsitzungen für Ihren Container öffnen:

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

SDK initialisieren

Initialisiere das Matter-SDK. Dieser Vorgang kann einige Minuten dauern.

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

Dein Matter-SDK ist jetzt initialisiert. Führen Sie folgenden Befehl aus, um die Umgebung schnell neu zu initialisieren:

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

Dateien zwischen Host und Container freigeben

Zuvor haben wir mithilfe einer Bind-Moppe aus dem Container 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 Binde-Bereitstellungen, indem Sie Ihren Container mit dem zusätzlichen Argument --mount source=$(pwd),target=/workspace,type=bind ausführen, um Ihr aktuelles 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 das Arbeitsverzeichnis auf das vom Container bereitgestellte Verzeichnis fest.

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

user@host> sudo chgrp -R 1000 .

Erteilen Sie der Gruppe im Verzeichnis die gewünschten Berechtigungen. 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 für neue Dateien haben, die vom Hostnutzer erstellt werden. Denken Sie daran, die Berechtigungen neuer Dateien, die auf dem Host erstellt wurden, nach Bedarf zu aktualisieren.

Sie können den Hostnutzer zur 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 Sie Ihre Matter-Integrationen in Google Home verwalten.

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

Entwicklerprojekt erstellen

Rufe 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 können Sie sich die Matter-Entwicklungsdokumentation und Informationen zu einigen Tools ansehen.
  4. Wenn Sie fortfahren möchten, klicken Sie auf Weiter: Entwickeln, um die Seite Checkliste für Sachverhalte aufzurufen.
  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 im Drop-down-Menü den Gerätetyp aus (in diesem Fall Light).
  8. Wähle unter „Vendor ID (VID)“ die Option Test VID aus und wähle dann im Drop-down-Menü „Test-VID“ die Option „0xFFF1“ aus. Geben Sie unter Produkt-ID (PID) 0x8000 ein und klicken Sie auf Speichern und weiter und klicken Sie dann auf der nächsten Seite auf Speichern. Verwenden Sie genau diese VID/PID-Werte. Die späteren Codelab-Schritte hängen davon ab.
    Projekt einrichten
  9. Nun wird deine Integration unter Matter-Integrationen angezeigt.
  10. Starten Sie Ihren Hub neu, damit er die neueste Konfiguration des Matter-Integrationsprojekts erhält. Wenn du die VID oder PID später ändern musst, musst du nach dem Speichern des Projekts neu starten, damit die Änderung wirksam wird. Eine detaillierte Anleitung finden Sie unter Google Nest- oder Google Wifi-Geräte neu starten.

4. Gerät bauen

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

Chef ist beides:

  • Eine Beispiel-App mit einer Terminal-Schnittstelle, die auch Funktionen der examples/shell-App umfasst.
  • Ein Skript, das das Prinzip der Konfiguration statt auf Konvention umsetzt, um einige der gängigen Aufgaben zu erfassen, die für die Entwicklung eines Matter-kompatiblen 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 bietet einige Optionen, die durch Ausführen von chef.py -h angezeigt 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 Lautstärkesteuerung.
  • -z: ruft das ZAP-Tool auf, um die Quelldateien zu generieren, die den Gerätetyp implementieren. Das heißt, ZAP erstellt auf Grundlage Ihrer Auswahl automatisch Code, der in den Build eingebunden wird. Dieser definiert das Licht (das Datenmodell) und wie es mit anderen Geräten interagiert (das Interaktionsmodell).
  • -b: Builds.
  • -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 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 anzuzeigen. linux wird für virtuelle Matter-Geräte verwendet.

Gerät ausführen

Matter verwendet den TCP/UDP-Port 5540. Wenn auf Ihrem Computer also eine Firewall ausgeführt wird, schalten 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]

Lass dein Gerät laufen. Als Nächstes richten wir uns auf die Google Home App, damit wir Ihr Gerät für Google Home in Betrieb nehmen können.

Gerät anhalten

Wenn du das Gerät anhalten musst, kannst du das Programm mit Strg+C beenden. Wenn die App nicht beendet wird, müssen Sie möglicherweise auch Strg+\ verwenden.

Die Anmeldedaten für dein 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. Gerät in Betrieb nehmen

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

Nest Hub

Für die Inbetriebnahme des Geräts auf dem Matter-Fabric 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 Ausführungspfad für das Routing von Smart-Home-Intents dient.

dieser Liste kannst du entnehmen, welche Hubs Matter unterstützen.

Überprüfen Sie vor Beginn der Inbetriebnahme Folgendes:

  • Dein Hub ist mit demselben Google-Konto gekoppelt, mit dem du dich in der Google Home Console angemeldet hast.
  • Dein Hub befindet sich im selben WLAN wie der Computer, auf dem du dein Virtual Matter-Gerät ausführen möchtest.
  • Dein Hub befindet sich in derselben Struktur, die du in der Google Home App verwendest. Das „Haus“ in Google Home Graph steht für Ihr Gebäude.

QR-Code anfordern

Für die Inbetriebnahme müssen die Onboarding-Informationen von Matter ü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 Inbetriebnahme relevant ist.

Provisionsvorgang ausführen

  1. Öffnen Sie die Google Home App.
  2. Tippen Sie oben links 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“. Tippe ansonsten auf Anderes Gerät einrichten und wähle dann Matter-Gerät aus der Geräteliste 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 der Kopplung wie in der Google Home App angegeben fort.

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

Gekoppelte Lampe in der Google Home App

Fehlerbehebung

Inbetriebnahme schlägt mit „Verbindungsproblem“ fehl oder „Keine Kontaktaufnahme mit Google“ Fehlermeldungen

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

Die Inbetriebnahme schlägt nach dem „Scannen des Geräts“ fehl über einen längeren Zeitraum

6. Gerät steuern

Sobald Ihr Matter-kompatibles 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 Arten testen:

  • Google Assistant wird verwendet.
  • Über die Google Home App

Google Assistant

Sie können Google Assistant auf Ihrem Smartphone oder Hub verwenden, um den Gerätestatus über Sprachbefehle umzuschalten, z. B. „Hey Google, schalte meine Lampen ein“.

Weitere Beispiele für Befehle finden Sie im Abschnitt Smart-Home-Geräte mit Sprachbefehlen steuern von 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 die Labels An oder Aus tippen.

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

7. Glückwunsch!

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

In diesem Codelab haben Sie gelernt, wie Sie:

  • Matter-Entwicklungsumgebung installieren
  • Ein virtuelles Matter-Gerät erstellen und ausführen
  • Virtuelles Gerät über Google Home in Betrieb nehmen und steuern

Weitere Informationen zu Matter finden Sie hier: