Tworzenie wirtualnego urządzenia Sprawa

1. Wprowadzenie

Matter to protokół połączeń, który zapewnia wiele możliwości rozwoju urządzeń. W tym ćwiczeniu z programowania utworzysz pierwsze urządzenie Matter z użyciem pakietów SDK i zależności, które znajdziesz na wstępnie skonfigurowanym obrazie Dockera.

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

Czego się nauczysz

  • Jak skonfigurować środowisko kompilacji Matter
  • Jak utworzyć urządzenie Matter działające na komputerze
  • Prowizje i sterowanie urządzeniem Matter w ramach Google Home

Czego potrzebujesz

2. Konfigurowanie środowiska

Będziemy używać wcześniej skonfigurowanego kontenera Dockera na hoście systemu Linux. Ten kontener zawiera wszystkie zależności wymagane do tworzenia i uruchamiania urządzenia wirtualnego Matter.

Sprawdź sprzęt

Komputery z systemem Windows i macOS nie są obecnie obsługiwane przez tę instalację Dockera. W systemie MacOS lub Windows możesz ręcznie zainstalować i utworzyć kompilację Matter.

W tych instrukcjach przyjęto założenie, że na komputerze z systemem Linux jest zainstalowany system X11. Jeśli Twój komputer z systemem Linux uruchamia Wayland, upewnij się, że zainstalowano także pakiet 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
    Wykonanie 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 wyświetlić się dane diagnostyczne z potwierdzeniem, że konfiguracja kontenera jest prawidłowa, a na koniec pojawi się pytanie powłoki:

Environment looks good, you are ready to go!
$

Omówienie polecenia Dockera i przekazanych do niego opcji:

  • xhost local:1000 pozwala systemowi okien X na odbieranie połączeń z hosta lokalnego na porcie 1000, dzięki czemu można korzystać z interfejsu graficznego.
  • docker run … image uruchomi dany obraz, pobierając go z rejestru Dockera w razie potrzeby.
  • --ipc=host umożliwia Dockerowi współdzielenie przestrzeni nazw międzyprocesowej komunikacji z komputerem hosta.
  • --net=host umożliwia Dockerowi korzystanie ze stosu sieciowego hosta w kontenerze, co jest wymagane do przekazywania ruchu mDNS z hosta do kontenera oraz udostępniania wyświetlacza X11 hosta.
  • -e DISPLAY eksportuje plik $DISPLAY do hosta, umożliwiając dostęp do interfejsu graficznego systemu. Jest to wymagane do uruchamiania narzędzia ZAP podczas edytowania klastrów Matter.
  • -it uruchamia Dockera z interaktywnym terminalem (tty), a nie w tle.

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

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

Zatrzymywanie i uruchamianie kontenera Dockera Matter

Każde uruchomienie polecenia docker run powoduje utworzenie nowego kontenera z określonym obrazem. Jeśli to zrobisz, utracisz stare dane, które zostały zapisane w poprzedniej instancji kontenera. Czasami takie działanie jest pożądane, ponieważ pozwala rozpocząć od nowa. Jednak czasami zdarza się, że wolisz zapisać konfigurację miejsca pracy i środowiska między sesjami.

Z tego powodu po utworzeniu kontenera możesz go zatrzymać, aby nie utracić wprowadzonych zmian.

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:

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

Możesz też rozpocząć sesję główną za pomocą:

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

Wstępna konfiguracja sprawy

Gdy terminal się otworzy, znajdziesz go w sklonowanym repozytorium Matter na ~/connectedhomeip. Nie musisz nic więcej konfigurować w sprawie Matter.

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

Aby uzyskać dostęp do plików na komputerze hosta z poziomu kontenera, możesz użyć podłączenia. Możesz też zapisywać pliki w podłączonym katalogu z poziomu kontenera, aby mieć do niego ł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 w podłączonym katalogu należy zarządzać na hoście.

Pobierz identyfikator grupy użytkownika kontenera z kontenera.

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

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

Ustaw ponownie grupę dla plików w podłączonym katalogu na grupę użytkownika kontenera.

user@host> sudo chgrp -R 1000 .

Przyznaj grupie wybrane uprawnienia w katalogu. W tym przykładzie grupa użytkowników kontenera ma uprawnienia do odczytu, zapisu i wykonywania wszystkich plików w podłączonym katalogu.

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

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

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

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

3. Konsola programisty Google Home

Google Home Developer Console to aplikacja internetowa, w której możesz zarządzać integracjami ze standardem Matter z Google Home.

Każde urządzenie Matter, które uzyskało certyfikat Connectivity Standards Alliance (Sojusz) działa w ekosystemie Google Home. Urządzenia w trakcie tworzenia, które nie mają certyfikatu, mogą być poddawane działaniu w ekosystemie Google Home pod pewnymi warunkami – więcej informacji znajdziesz w sekcji Ograniczenia parowania.

Tworzenie projektu programisty

Najpierw otwórz konsolę programisty Google Home:

  1. Na stronie Zarządzanie projektami kliknij Utwórz projekt.
    Centrum programistów Google Home
  2. Na stronie Rozpocznij kliknij Utwórz projekt.

  1. Wpisz niepowtarzalną nazwę projektu, a potem kliknij Utwórz nowy projekt. Okno tworzenia nowego projektu
  2. Kliknij + Dodaj integrację, aby otworzyć ekran „Zasoby Matter”, na którym możesz wyświetlić dokumentację dotyczącą standardu Matter i dowiedzieć się więcej o niektórych narzędziach.
  3. Gdy wszystko będzie gotowe, kliknij Dalej: Programowanie, co spowoduje wyświetlenie strony Lista kontrolna spraw.
  4. Kliknij Dalej – Konfiguracja.
  5. Na stronie Konfiguracja wpisz nazwę produktu.
  6. Kliknij Wybierz typ urządzenia i z menu wybierz typ urządzenia (w tym przypadku Light).
  7. W identyfikatorze dostawcy (VID) wybierz Test VID i z menu rozwijanego Test VID wybierz 0xFFF1. W polu Identyfikator produktu (PID) wpisz 0x8000, a potem kliknij Zapisz i kontynuuj, a następnie kliknij Zapisz na kolejnej stronie.
    Konfigurowanie projektu
  8. Teraz w sekcji Matter na liście będzie widoczne jedno urządzenie Matter. Integracje Matter
  9. Uruchom ponownie centrum, aby upewnić się, że otrzymuje ono najnowszą konfigurację projektu Matter. Aby później wprowadzić zmiany w identyfikatorach VID lub PID, musisz też ponownie uruchomić projekt. Szczegółowe instrukcje ponownego uruchamiania znajdziesz w artykule Ponowne uruchamianie urządzeń Google Nest lub Google Wifi.

4. Tworzenie urządzenia

Wszystkie przykłady w standardzie Matter znajdują się w folderze examples w repozytorium GitHub. Dostępnych jest kilka przykładów, ale przede wszystkim koncentrujemy się na kuchni.

Szef kuchni to:

  • Przykładowa aplikacja z terminalem i funkcjami pakowania dostępna również w aplikacji examples/shell.
  • Skrypt, który wciela się w zasadę konwencjonalnego konfigurowania konfiguracji w celu uwzględnienia kilku typowych zadań niezbędnych do opracowania urządzenia z standardem Matter.

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

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

Kucharz ma kilka opcji, które można wyświetlić, uruchamiając polecenie chef.py -h. Opcje, których używamy, to:

  • -d: określa typ urządzenia, którego chcesz użyć. W tym przypadku tworzymy aplikację oświetlenia z opcjami włączania i wyłączania oraz poziomą.
  • -z: wywołuje narzędzie ZAP, aby wygenerować pliki źródłowe implementujące typ urządzenia. Oznacza to, że na podstawie wybranego oświetlenia ZAP automatycznie utworzy kod, który zostanie włączony do kompilacji, która określa światło (model danych) i jak oddziałuje na inne urządzenia (model interakcji).
  • -b: kompilacje.
  • -r: [opcjonalnie] włącza serwer RPC na urządzeniu wirtualnym w standardzie Matter, aby inne komponenty (np. 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. linux jest używany na wirtualnych urządzeniach Matter.

Uruchom urządzenie

Matter używa portu TCP/UDP 5540, więc jeśli na komputerze masz włączoną zaporę sieciową, 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 zwróćmy uwagę na aplikację Google Home, abyśmy mogli przekazać Twoje urządzenie do Google Home.

Zatrzymaj urządzenie

Możesz wyjść z programu, naciskając klawisze CTRL+C. Jeśli aplikacja nie zamyka się, użyj klawiszy CTRL+\.

Dane logowania do urządzenia wirtualnego są przechowywane w katalogu /tmp/ w plikach rozpoczynających się od prefiksu chip.

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

$ rm /tmp/chip*

5. Kontroler urządzenia wirtualnego

Kontroler wirtualny to samodzielna aplikacja, która zapewnia graficzny interfejs użytkownika do kontrolowania i wyświetlania stanów urządzeń wirtualnych Matter. Wykorzystuje klienta RPC do komunikacji z urządzeniami Matter połączonymi z Twoim środowiskiem programistycznym.

Kontroler urządzenia wirtualnego

Kontroler wirtualny reprezentuje urządzenie wirtualne.

Możesz korzystać z urządzenia wirtualnego za pomocą graficznego interfejsu kontrolera urządzeń wirtualnych. Zmiany w GUI mają wpływ na model bazowy. Obecnie kontroler urządzeń wirtualnych obsługuje typ przyciemnianego światła.

Zainstaluj kontroler urządzenia wirtualnego

Kontroler wirtualny jest wstępnie zainstalowany w kontenerze Dockera Ubuntu LTS 20.04.

Uruchom kontroler 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 podawania argumentów, zostanie on domyślnie ustawiony na gniazdo sieciowe przy użyciu portu localhost 33000. Gdy kontroler połączy się z urządzeniem wirtualnym, pojawi się ekran ze stanem urządzenia:

Interfejs graficzny urządzenia wirtualnego

Aplikacja wysyła żądania do serwera RPC urządzenia, gdy wprowadzasz zmiany w aplikacji wirtualnego kontrolera, i co sekundę zbiera informacje z serwera RPC, aby uzyskać stan.

Aplikacja Virtual Device Controller może też służyć do pobierania kodu QR w ramach procedury zlecania urządzenia. Kliknij ikonę kodu QR obok obrazu urządzenia, aby wyświetlić ten kod:

Kod QR

Aby zlecić to urządzenie, możesz użyć tego kodu QR.

6. Uruchamianie urządzenia

Uwaga: ten krok zakończy się powodzeniem, jeśli Twój projekt został już skonfigurowany w Google Home Developer Console.

Nest Hub

Do utworzenia urządzenia w standardzie Matter wymagane jest centrum. To urządzenie Google Nest, takie jak Nest Hub (2 generacji), które obsługuje platformę Matter i będzie działać jako router graniczny urządzeń z wątkami oraz jako lokalna ścieżka realizacji w celu kierowania intencji inteligentnego domu.

Na tej liście sprawdzisz, które centra obsługują standard Matter.

Przed rozpoczęciem procedury prowizji upewnij się, że:

  • Centrum jest sparowane z tym samym kontem Google, którego używasz do logowania się w Google Home Console.
  • Centrum jest w tej samej sieci Wi-Fi co komputer, którego używasz do uruchamiania maszyny wirtualnej.
  • Koncentrator jest w tej samej strukturze, której używasz w aplikacji Google Home. „Autoreklama” na Grafie Google Home reprezentuje Twoją strukturę.

Uzyskaj kod QR

W ramach prowizji musisz podać informacje wprowadzające w standardzie Matter z użyciem kodu QR. Kod urządzenia wirtualnego (VAN) możesz uzyskać za pomocą kontrolera urządzenia wirtualnego.

Zrealizuj prowizję

  1. Otwórz aplikację Google Home.
  2. W lewym górnym rogu kliknij +.
  3. Kliknij Skonfiguruj urządzenie.
  4. Kliknij Nowe urządzenie.
  5. Wybierz dom i kliknij Dalej.
  6. Aplikacja Google Home skanuje urządzenie. Jeśli pojawi się komunikat „Znaleziono urządzenie Matter...”, kliknij „Tak”. W przeciwnym razie kliknij Skonfiguruj inne urządzenie, a potem na liście urządzeń kliknij Urządzenie Matter.
  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ć uruchomione jako zamówienie i powinno pojawić się jako nowa ikona w aplikacji Google Home.

Żarówka sparowana w aplikacji Google Home

Rozwiązywanie problemów

Łączenie nie powiodło się z powodu komunikatów o błędzie „Problem z połączeniem” lub „Nie udało się skontaktować z Google”

Nie można pobrać prowizji po długim skanowaniu urządzenia

7. Sterowanie urządzeniem

Po uruchomieniu urządzenia z włączonym standardem Matter i pojawieniu się w aplikacji Google Home w postaci żarówki możesz przetestować sterowanie urządzeniem na różne sposoby:

  • Korzystanie z Asystenta Google.
  • W aplikacji Google Home.
  • Korzystanie z GUI urządzenia wirtualnego.

Asystent Google

Za pomocą Asystenta Google na telefonie lub hubie możesz przełączać stan urządzenia, używając poleceń głosowych, np. „OK Google, przełącz oświetlenie”.

Więcej przykładów 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

Obok ikon żarówki w aplikacji Google Home możesz kliknąć etykiety Wł. i Wył.

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

GUI (urządzenie wirtualne)

Aby zmienić stan urządzenia, możesz wchodzić w interakcję z GUI urządzenia wirtualnego. Niezależnie od tego, czy sterujesz urządzeniem wirtualnym przy użyciu kontrolera urządzenia wirtualnego, aplikacji Google Home na telefonie czy koncentratora, wszystkie te interfejsy odzwierciedlają obecny stan urządzenia wirtualnego.

8. Gratulacje!

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

Dzięki nim dowiesz się, jak:

  • Zainstaluj środowisko programistyczne Matter, używając gotowego obrazu Dockera.
  • Utwórz i uruchom urządzenie wirtualne Matter.
  • Uruchamiaj i kontroluj urządzenie wirtualne z Google Home.

Więcej informacji o sprawie Matter znajdziesz w tych artykułach: