Tworzenie wirtualnego urządzenia Sprawa

1. Wprowadzenie

Matter to protokół łączności, który zapewnia ekscytujące możliwości rozwoju urządzeń inteligentnych. W ramach tego ćwiczenia z programowania utworzysz pierwsze urządzenie ze standardem Matter, używając pakietów SDK i zależności dostępnych we wstępnie skonfigurowanym obrazie Dockera.

Aby dowiedzieć się więcej o standardzie Matter, odwiedź Google Home Developer Center lub stronę Connectivity Standards Alliance.

Czego się nauczysz

  • Jak skonfigurować środowisko kompilacji Matter
  • Jak utworzyć wirtualne urządzenie ze standardem Matter, które będzie działać na Twoim komputerze
  • Jak uruchomić wirtualne urządzenie Matter i sterować nim w Google Home

Czego potrzebujesz

2. Konfigurowanie środowiska

Będziemy używać wcześniej skonfigurowanego kontenera Dockera na hoście z systemem Linux. Ten kontener zawiera wszystkie zależności niezbędne do skompilowania i uruchomienia urządzenia wirtualnego ze standardem Matter.

Sprawdź sprzęt

Ta instalacja Dockera nie obsługuje komputerów z systemami Windows i macOS. Możesz ręcznie zainstalować i skompilować Matter w systemie macOS.

W tych instrukcjach zakładamy też, że na Twoim komputerze z Linuksem jest zainstalowany system okien X11. Jeśli na komputerze z systemem Linux działa Wayland, upewnij się, że zainstalowano też X.Org.

Konfigurowanie Dockera

  1. Zainstaluj Docker Engine (nie używaj Dockera Desktop).
  2. Pobierz obraz Dockera z Docker Hub. W oknie terminala uruchom polecenie:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    Ukończenie tej operacji może potrwać kilka minut.
  3. Uruchom kontener Dockera:
    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

Po uruchomieniu kontenera powinny pojawić się dane diagnostyczne, a następnie komunikat potwierdzający, że konfiguracja kontenera jest prawidłowa, a na koniec komunikat powłoki kontenera:

Environment looks good, you are ready to go!
$

Przeanalizujmy polecenie dockera i przekazane do niego opcje:

  • xhost local:1000 umożliwia systemowi X Window System odbieranie połączeń z hosta lokalnego na porcie 1000, co pozwala na korzystanie z graficznego interfejsu użytkownika.
  • docker run … image uruchamia dany obraz, w razie potrzeby pobiera go z rejestru Dockera.
  • --ipc=host umożliwia Dockerowi współdzielenie przestrzeni nazw komunikacji międzyprocesowej z hostem.
  • --net=host umożliwia Dockerowi korzystanie ze stosu sieciowego hosta wewnątrz kontenera, co jest wymagane do przekazywania ruchu mDNS z hosta do kontenera i udostępniania wyświetlacza X11 hosta.
  • -e DISPLAY eksportuje $DISPLAY do hosta, dając dostęp do interfejsu graficznego systemu. Jest to wymagane do uruchomienia narzędzia ZAP podczas edytowania klastrów Matter.
  • -it uruchamia Dockera z interaktywnym terminalem (tty), a nie procesem w tle.

Opcjonalnie możesz uruchomić drugą instancję sesji terminala:

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

Zatrzymaj i uruchom kontener Dockera Matter

Za każdym razem, gdy uruchamiasz polecenie docker run, tworzysz nowy kontener z określonym obrazem. Gdy to zrobisz, stare dane, które zostały zapisane w poprzedniej instancji kontenera, zostaną utracone. Czasami właśnie tego oczekujesz, ponieważ umożliwia to rozpoczęcie nowej instalacji. Czasami jednak warto zapisać konfigurację pracy i środowiska między sesjami.

Z tego powodu po utworzeniu kontenera możesz go zatrzymać, aby nie utracić wyników swojej pracy.

user@host> docker stop matter-container

Gdy wszystko będzie gotowe do ponownego uruchomienia, uruchom kontener i otwórz okno terminala:

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

Możesz otworzyć dodatkowe sesje terminala w kontenerze za pomocą:

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

Lub rozpocznij sesję główną za pomocą:

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

Wstępna konfiguracja Matter

Gdy otworzy się terminal, będzie on już znajdować się w repozytorium sklonowanym Matter pod adresem ~/connectedhomeip. Nie musisz wykonywać żadnych dodatkowych czynności konfiguracyjnych standardu Matter.

Udostępnianie plików między hostem a kontenerem

Aby uzyskać dostęp z poziomu kontenera do plików na komputerze hosta, możesz użyć punktu montowania. W podłączonym katalogu możesz też zapisywać pliki z kontenera, by mieć do nich łatwy dostęp z hosta.

Uruchom kontener z dodatkowym argumentem --mount source=$(pwd),target=/workspace,type=bind, aby podłączyć bieżący katalog roboczy do kontenera pod adresem /workspace.

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

Uprawnieniami użytkownika kontenera do podłączonego katalogu muszą być zarządzane na hoście.

Uzyskaj identyfikator grupy użytkownika kontenera z kontenera.

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

Otwórz kolejną sesję terminala na hoście kontenera i ustaw katalog roboczy na katalog podłączony przez kontener.

Rekurencyjnie ustawiaj grupę dla plików w podłączonym katalogu do grupy użytkownika kontenera.

user@host> sudo chgrp -R 1000 .

Przyznaj grupie odpowiednie uprawnienia do katalogu. W tym przykładzie przyznano grupie użytkownika kontenera uprawnienia do odczytu, zapisu i wykonywania wszystkich plików w podłączonym katalogu.

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

Pamiętaj, że te polecenia nie mają wpływu na uprawnienia nowych plików tworzonych przez użytkownika hosta. Pamiętaj, aby w razie potrzeby zaktualizować uprawnienia nowych plików tworzonych na hoście.

Możesz dodać użytkownika hosta do grupy użytkownika kontenera, aby dziedziczyć uprawnienia do plików utworzonych przez użytkownika kontenera.

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

3. Konsola programisty Google Home

Konsola programisty Google Home to aplikacja internetowa, w której możesz zarządzać integracjami Matter z Google Home.

Każde urządzenie Matter, które przeszło certyfikat Connectivity Standards Alliance (Alliance) Matter, działa w ekosystemie Google Home. Urządzenia, które nie zostały certyfikowane, można od razu uruchomić w ekosystemie Google Home pod pewnymi warunkami. Więcej informacji znajdziesz w sekcji Ograniczenia dotyczące parowania.

Tworzenie projektu programisty

Najpierw otwórz konsolę programisty Google Home:

  1. Kliknij Create project (Utwórz projekt).
  2. Wpisz unikalną nazwę projektu i kliknij Utwórz projekt. Okno tworzenia nowego projektu
  3. Kliknij + Dodaj integrację. Otworzy się ekran Zasoby sprawy, na którym możesz przejrzeć dokumentację dotyczącą tworzenia standardu Matter i poznać niektóre narzędzia.
  4. Aby kontynuować, kliknij Next: Develop (Dalej: program), co spowoduje wyświetlenie strony Lista kontrolna spraw.
  5. Kliknij Dalej: konfiguracja.
  6. Na stronie Konfiguracja wpisz nazwę usługi.
  7. Kliknij Wybierz typ urządzenia i wybierz typ urządzenia z menu (w tym przypadku Light).
  8. W polu Identyfikator dostawcy (VID) wybierz Testuj identyfikator VID i z menu Testuj identyfikator VID wybierz 0xFFF1. W polu Identyfikator produktu (PID) wpisz 0x8000 i kliknij Zapisz i kontynuuj, a następnie kliknij Zapisz na następnej stronie. Zastosuj dokładnie te wartości VID/PID. Od nich będą zależeć kolejne kroki ćwiczeń z programowania.
    Konfiguruję projekt
  9. W sekcji Integracje zobaczysz swoją integrację.
  10. Zrestartuj centrum, aby mieć pewność, że otrzymuje najnowszą konfigurację projektu integracji Matter. Jeśli musisz później zmienić identyfikator VID lub PID, po zapisaniu projektu musisz też ponownie uruchomić projekt, aby zmiana została zastosowana. Szczegółowe instrukcje znajdziesz w artykule Ponowne uruchamianie urządzeń Google Nest lub Google Wifi.

4. Utwórz urządzenie

Wszystkie przykłady ze standardu Matter znajdziesz w folderze examples w repozytorium GitHub. Dostępnych jest kilka przykładów, ale w tym ćwiczeniu z programowania skupiamy się na kuchni.

Szef kuchni to jednocześnie:

  • Przykładowa aplikacja z interfejsem terminala, która udostępnia funkcje pakowania, które znajdują się też w aplikacji examples/shell.
  • Skrypt, który uwzględnia zasadę nadużywania konwencji, aby uwzględnić kilka typowych zadań niezbędnych do opracowania urządzenia obsługującego standard Matter.

Przejdź do przykładowego folderu Chef i utwórz swoją pierwszą kompilację Matter:

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

Chef ma kilka opcji, które można wyświetlić, uruchamiając polecenie chef.py -h. Używane przez nas opcje to:

  • -d: określa typ urządzenia, które ma zostać użyte. W tym przypadku tworzymy aplikację oświetleniową z elementami sterującymi włączaniem i wyłączaniem oraz poziomem głośności.
  • -z: wywołuje narzędzie ZAP, aby wygenerować pliki źródłowe, które implementują dany typ urządzenia. To oznacza, że na podstawie wybranego przez Ciebie oświetlenia ZAP automatycznie utworzy kod do wbudowania do kompilacji, który określa światło (model danych) i sposób jego interakcji z innymi urządzeniami (model interakcji).
  • -b: kompilacje.
  • -r: [opcjonalnie] włącza serwer RPC na urządzeniu wirtualnym Matter, aby inne komponenty (takie jak GUI) mogły komunikować się z urządzeniem w celu ustawiania i pobierania atrybutów modelu danych.
  • -t linux: platforma docelowa. Platformy pomocy to linux, nrfconnect i esp32. Aby zobaczyć wszystkie dostępne polecenia i obsługiwane platformy docelowe, możesz uruchomić polecenie ./chef.py -h. Funkcja linux jest używana na urządzeniach wirtualnych Matter.

Uruchom urządzenie

Sprawa używa portu TCP/UDP 5540, więc jeśli na komputerze działa zapora sieciowa, wyłącz ją lub zezwól na przychodzące połączenia TCP/UDP na porcie 5540.

Uruchom urządzenie wirtualne w kontenerze za pomocą:

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

Nie wyłączaj urządzenia. Teraz skupimy się na aplikacji Google Home, która pozwoli uruchomić Twoje urządzenie w Google Home.

Zatrzymaj urządzenie

Jeśli chcesz zatrzymać urządzenie, możesz zakończyć program, naciskając CTRL+C. Jeśli aplikacja nie zostanie zamknięta, być może trzeba będzie nacisnąć kombinację klawiszy CTRL+\.

Dane uwierzytelniające urządzenia wirtualnego są przechowywane w katalogu /tmp/, w plikach zaczynających się od chip.

Jeśli chcesz powtórzyć cały proces realizacji zamówienia od początku, musisz usunąć te pliki, uruchamiając to polecenie:

$ rm /tmp/chip*

5. Kontroler urządzenia wirtualnego

Kontroler urządzenia wirtualnego to samodzielna aplikacja z graficznym interfejsem użytkownika, która umożliwia sterowanie i wyświetlanie stanu urządzeń wirtualnych Matter. Do komunikacji z urządzeniami Matter połączonymi z Twoim środowiskiem programistycznym wykorzystuje klienta RPC.

Kontroler urządzenia wirtualnego

Kontroler urządzenia wirtualnego to wizualna reprezentacja urządzenia wirtualnego.

Z urządzeniem wirtualnym możesz korzystać za pomocą graficznego interfejsu użytkownika (GUI) kontrolera urządzenia wirtualnego. Zmiany w GUI mają wpływ na model danych. Pełną listę obsługiwanych typów urządzeń wirtualnych Matter znajdziesz w sekcji Obsługiwane urządzenia.

Instalowanie kontrolera urządzenia wirtualnego

Kontroler urządzenia wirtualnego jest fabrycznie zainstalowany w kontenerze Dockera Ubuntu LTS 20.04.

Uruchamianie kontrolera urządzenia wirtualnego

Utwórz drugą instancję sesji terminala:

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

Uruchom kontroler urządzenia wirtualnego, podając gniazdo sieciowe, które będzie używane do komunikacji z urządzeniem wirtualnym:

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

Jeśli uruchomisz kontroler bez podania żadnych argumentów, domyślnie zostanie użyty port sieciowy 33000. Gdy kontroler połączy się z urządzeniem wirtualnym, pojawi się ekran ze stanem urządzenia:

Graficzny interfejs użytkownika urządzenia wirtualnego

Aplikacja wysyła żądania do serwera RPC urządzenia, gdy wprowadzasz zmiany w aplikacji Virtual Controller, oraz raz na sekundę sonduje serwer RPC, aby pobrać stan.

W ramach procesu uruchamiania urządzenia można też używać aplikacji Virtual Device Controller (Kontroler urządzenia wirtualnego). Kliknij ikonę kodu QR obok obrazu urządzenia, aby wyświetlić kod QR tego urządzenia. Użyj tego kodu QR, aby wydać urządzenie.

6. Przekaż urządzenie

Uwaga: ten krok zadziała tylko wtedy, gdy masz już skonfigurowany projekt w konsoli programisty Google Home.

Nest Hub

Do złożenia urządzenia na tkaninę Matter wymagane jest centrum. To urządzenie Google Nest, takie jak Nest Hub (2 generacji), które obsługuje standard Matter i będzie pełnić zarówno funkcję routera granicznego dla urządzeń obsługujących Thread, jak i lokalną ścieżkę realizacji zamówień do inteligentnego domu.

Sprawdź tę listę, aby sprawdzić, które centra obsługują standard Matter.

Przed rozpoczęciem procesu uruchamiania upewnij się, że:

  • Twoje centrum jest sparowane z tym samym kontem Google, którego używasz do logowania się w konsoli Google Home.
  • Hub jest w tej samej sieci Wi-Fi co komputer, którego używasz do uruchamiania urządzenia Virtual Matter.
  • Twoje centrum ma tę samą strukturę, której używasz w aplikacji Google Home. „Dom” w Google Home Graph reprezentuje Twoją strukturę.

Uzyskaj kod QR

Proces wdrażania wymaga podania za pomocą kodu QR informacji wprowadzających do Matter. Kod QR urządzenia wirtualnego znajdziesz na kontrolerze urządzenia wirtualnego.

Wykonywanie operacji prowizji

  1. Otwórz aplikację Google Home.
  2. W lewym górnym rogu dotknij +.
  3. Kliknij Skonfiguruj urządzenie.
  4. Kliknij Nowe urządzenie.
  5. Wybierz swój dom i kliknij Dalej.
  6. Aplikacja Google Home skanuje urządzenie. Jeśli pojawi się komunikat „Znaleziono urządzenie sprawy...”, kliknij „Tak”. W innym przypadku kliknij Skonfiguruj inne urządzenie i wybierz Sprawne urządzenie z listy urządzeń.
  7. Skieruj aparat na kod QR urządzenia lub kod QR wygenerowany przez stronę internetową.
  8. Kontynuuj parowanie zgodnie z instrukcjami w aplikacji Google Home.

Po wykonaniu tych czynności urządzenie wirtualne Matter powinno zostać udostępnione i powinno pojawić się jako nowa ikona w aplikacji Google Home.

Sparowana żarówka w aplikacji Google Home

Rozwiązywanie problemów

Komisja kończy się niepowodzeniem i wyświetlany jest komunikat o błędzie „Problem z połączeniem” lub „Nie można skontaktować się z Google”

Prowizja kończy się niepowodzeniem po dłuższym czasie „Przeskanuj urządzenie”

7. Steruj urządzeniem

Gdy urządzenie obsługujące standard Matter pojawi się w aplikacji Google Home jako żarówka, możesz przetestować sterowanie urządzeniem na różne sposoby:

  • Przy użyciu Asystenta Google.
  • W aplikacji Google Home.
  • Korzystanie z GUI urządzenia wirtualnego

Asystent Google

Za pomocą Asystenta Google na telefonie lub centrum możesz przełączać stan urządzenia na podstawie poleceń głosowych, np. „OK Google, przełącz światła”.

Więcej przykładów poleceń znajdziesz w sekcji Sterowanie inteligentnymi urządzeniami domowymi za pomocą poleceń głosowych w artykule Sterowanie inteligentnymi urządzeniami domowymi dodanymi do aplikacji Google Home.

Aplikacja Google Home

Możesz kliknąć etykiety Wł. i Wył. obok ikony żarówki w aplikacji Google Home.

Więcej informacji znajdziesz w sekcji Sterowanie urządzeniami za pomocą aplikacji Google Home w artykule Sterowanie inteligentnymi urządzeniami domowymi dodanymi do aplikacji Google Home.

GUI urządzenia wirtualnego

Możesz korzystać z GUI urządzenia wirtualnego, aby zmienić stan urządzenia. Niezależnie od tego, czy sterujesz urządzeniem wirtualnym za pomocą kontrolera urządzenia wirtualnego, aplikacji Google Home na telefonie czy koncentratora, wszystkie te interfejsy będą odzwierciedlać bieżący stan urządzenia wirtualnego.

8. Gratulacje!

Udało Ci się utworzyć pierwsze urządzenie Matter. Świetnie!

Dzięki temu ćwiczeniu z programowania wiesz już, jak:

  • Instalowanie środowiska programistycznego Matter z użyciem gotowego obrazu Dockera.
  • Skompilować i uruchomić urządzenie wirtualne Matter.
  • Prowizja i sterowanie urządzeniem wirtualnym z poziomu Google Home.

Aby dowiedzieć się więcej o standardzie Matter, zapoznaj się z tymi materiałami: