Virtuelles 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 in Betrieb nehmen und steuern

Voraussetzungen

  • Ein Hub, also ein Google Nest-Gerät, das Matter unterstützt, z. B. der Nest Hub (2. Generation).
  • Ein Linux-Computer mit dem X11-Fenstersystem.
  • Docker
  • Git
  • Grundkenntnisse in Linux.
    • Die angenommene Shell für alle Befehle in diesem Codelab 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. Beachten Sie 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. Suchen Sie das Bild, das zu Ihrer SDK-Version passt:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Wenn Sie denselben Commit verwenden, sollten Sie Folgendes sehen: ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Starten Sie als Nächstes den Container mit den entsprechenden Ressourcen, die vom Host weitergeleitet werden (unser 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 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.
  • Mit --ipc=host kann Docker den Namespace für die Interprozesskommunikation mit Ihrem Hostcomputer teilen.
  • --net=host ermöglicht es 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 an den 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 und nicht als Hintergrundprozess.
  • Mit --mount wird das SDK, das wir zuvor ausgecheckt haben, in den Container eingebunden.
  • Mit --workdir wird das Arbeitsverzeichnis beim Start auf das bereitgestellte SDK-Verzeichnis festgelegt.

Optional können Sie eine zweite Terminal-Sitzung starten:

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 verloren, die in einer vorherigen Containerinstanz gespeichert waren. Manchmal ist das auch erwünscht, da Sie so mit einer Neuinstallation beginnen können. Es gibt jedoch Zeiten, in denen Sie Ihre Arbeit und die Umgebungskonfiguration zwischen den Sitzungen speichern möchten.

Aus diesem Grund sollten 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, die Anwendung auszuführen, 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 mit folgendem Befehl ö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

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

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

Das Matter SDK wurde initialisiert. Um die Umgebung in Zukunft schnell neu zu initialisieren, führen Sie Folgendes aus:

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

Dateien zwischen Host und Container freigeben

Bisher haben wir über eine Bind-Mount-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-Mounts, 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 Container-Nutzers für das bereitgestellte Verzeichnis müssen auf dem Host verwaltet werden.

Rufen Sie die Gruppen-ID des Container-Nutzers 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.

Die Gruppe für Dateien im bereitgestellten Verzeichnis wird rekursiv auf die Gruppe des Container-Nutzers festgelegt.

user@host> sudo chgrp -R 1000 .

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

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

Beachten Sie, dass diese Befehle sich nicht auf die Berechtigungen neuer Dateien auswirken, die vom Hostnutzer erstellt werden. Denken Sie daran, die Berechtigungen für neue Dateien, die im Host erstellt wurden, nach Bedarf zu aktualisieren.

Sie können Ihren 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 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, die sich in der Entwicklung befinden und nicht zertifiziert wurden, können unter bestimmten Bedingungen im Google Home-Ökosystem in Betrieb genommen werden. Weitere Informationen finden Sie unter Einschränkungen beim Koppeln.

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 auf Projekt erstellen. Dialogfeld „Neues Projekt erstellen“
  3. Klicke auf + Verknüpfung hinzufügen. Dadurch gelangst du zum Bildschirm Matter-Ressourcen, auf dem du die Matter-Entwicklerdokumentation und Informationen zu einigen Tools findest.
  4. Wenn Sie bereit sind, klicken Sie auf Weiter: Entwickeln. Die Seite Matter-Checkliste wird angezeigt.
  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 „Vendor 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)“ 0x8000 ein und klicken Sie auf Speichern und fortfahren. Klicken Sie dann auf der nächsten Seite auf Speichern. Verwenden Sie genau diese VID/PID-Werte, da spätere Codelab-Schritte davon abhängen.
    Projekt einrichten
  9. Ihre Integration wird jetzt unter Matter-Integrationen angezeigt.
  10. Starte deinen Hub neu, damit er die aktuelle Projektkonfiguration für die Matter-Integration erhält. Wenn Sie die VID oder PID später ändern müssen, müssen Sie das Gerät nach dem Speichern des Projekts neu starten, damit die Änderung wirksam wird. Eine detaillierte Anleitung zum Neustart findest du unter Google Nest- oder Google Wifi-Geräte neu starten.

4. Gerät entwickeln

Alle Beispiele in Matter finden Sie 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 Terminaloberfläche bietet und Funktionen umfasst, die auch in der examples/shell App verfügbar sind.
  • Ein Skript, das das Prinzip „Konvention vor Konfiguration“ nutzt, um mehrere der gängigen Aufgaben zu kapseln, die für die Entwicklung eines Matter-kompatiblen Geräts erforderlich sind.

Wechseln 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. Die Optionen, die wir hier verwenden, sind:

  • -d: Definiert den zu verwendenden Gerätetyp. In diesem Fall erstellen wir eine Beleuchtungs-App mit Ein/Aus- und Helligkeitssteuerungen.
  • -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 wird und das Licht (das Datenmodell) und die Interaktion mit anderen Geräten (das Interaktionsmodell) definiert.
  • -b: builds.
  • -r: [optional] Aktiviert den RPC-Server auf dem virtuellen Matter-Gerät, damit andere Komponenten (z. B. die Benutzeroberfläche) mit dem Gerät kommunizieren können, um Data Model-Attribute festzulegen und abzurufen.
  • -t linux: Zielplattform. Die unterstützten Plattformen sind linux, nrfconnect und esp32. Mit ./chef.py -h können Sie alle verfügbaren Befehle und unterstützten Zielplattformen aufrufen. linux wird für virtuelle Matter-Geräte verwendet.

Gerät ausführen

Matter verwendet den TCP/UDP-Port 5540. Wenn auf deinem Computer eine Firewall ausgeführt wird, musst du sie entweder deaktivieren oder eingehende TCP/UDP-Verbindungen über Port 5540 zulassen.

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 das Gerät eingeschaltet. Jetzt wenden wir uns der Google Home App zu, damit wir dein Gerät in Google Home einrichten können.

Gerät stoppen

Wenn Sie das Gerät stoppen möchten, 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 gespeichert, die mit dem Präfix chip beginnen.

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

$ 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

Du benötigst einen Hub, um dein Gerät in der Matter-Fabric in Betrieb zu nehmen. Das ist ein Google Nest-Gerät, z. B. der 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.

Hier findest du eine Liste der Hubs, die Matter unterstützen.

Prüfen Sie vor Beginn der Inbetriebnahme, ob Folgendes zutrifft:

  • Dein Hub ist mit demselben Google-Konto verknüpft, mit dem du dich in der Google Home Console angemeldet hast.
  • Dein Hub ist mit demselben WLAN wie der Computer verbunden, auf dem du dein virtuelles Matter-Gerät ausführst.
  • Dein Hub befindet sich in derselben Struktur, die du in der Google Home App verwendest. Das „Haus“ im Google Home Graph steht für deine Struktur.

QR‑Code abrufen

Für die Inbetriebnahme ist ein QR-Code mit Matter-Onboarding-Informationen erforderlich. Sehen Sie sich die Konsolenausgabe der Matter-Anwendung an. Sie enthält einen Link für den QR-Code, der für die Inbetriebnahme relevant ist.

Inbetriebnahme durchfü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ähle dein Zuhause aus und tippe auf Weiter.
  6. Die Google Home App sucht nach deinem Gerät. Wenn die Meldung „Matter-Gerät gefunden…“ angezeigt wird, tippe auf „Ja“. Tippe andernfalls auf Anderes Gerät einrichten und wähle 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 von der Website generierten QR-Code.
  8. Setze den Kopplungsvorgang wie im Ablauf der Google Home App beschrieben fort.

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

Gekoppelte Glühbirne in der Google Home App

Fehlerbehebung

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

  • Achte darauf, dass du in der Google Home Console ein Projekt mit der richtigen VID-/PID-Kombination erstellt hast und keine anderen Projekte dieselbe VID-/PID-Kombination verwenden.

Die Einrichtung schlägt fehl, nachdem das Gerät längere Zeit gescannt wurde

6. Gerät steuern

Sobald dein Matter-kompatibles Gerät erfolgreich in Betrieb genommen wurde und in der Google Home App als Glühbirne angezeigt wird, kannst du die Steuerung des Geräts auf verschiedene Arten testen:

  • Google Assistant verwenden
  • Über die Google Home App

Google Assistant

Sie können Google Assistant auf Ihrem Smartphone oder Hub verwenden, um den Gerätestatus per Sprachbefehl zu ändern, z. B. indem Sie „Hey Google, schalte meine Beleuchtung um“ sagen.

Weitere Beispiele für Befehle findest du 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

Tippe in der Google Home App neben dem Glühbirnensymbol auf die Labels Ein und Aus.

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:

  • Installieren Sie eine Matter-Entwicklungsumgebung.
  • 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 in diesen Referenzen: