Tworzenie wirtualnego urządzenia Sprawa

1. Wprowadzenie

Matter to protokół łączności, który zapewnia niesamowite możliwości w zakresie rozwoju inteligentnych urządzeń. W ramach tego ćwiczenia w programie zbudujesz pierwsze urządzenie Matter przy użyciu zasobów z pakietu Matter SDK.

Aby dowiedzieć się więcej o standardzie Matter, odwiedź Centrum dla programistów Google Home lub stronę Connectivity Standards Alliance.

Czego się nauczysz

  • Jak skonfigurować środowisko kompilacji Matter
  • Jak utworzyć wirtualne urządzenie Matter, które działa na komputerze
  • Jak uruchomić i sterować wirtualnym urządzeniem Matter za pomocą Google Home

Czego potrzebujesz

  • Hub, czyli dowolne urządzenie Google Nest obsługujące standard Matter, takie jak Nest Hub (2 generacji).
  • Komputer z systemem Linux z systemem okien X11.
  • Dockera.
  • Git.
  • Podstawowa znajomość systemu Linux.
    • Zakładamy, że powłoką wszystkich poleceń w tym ćwiczeniu z programowania jest BASH.

2. Konfigurowanie środowiska

Sprawdź sprzęt

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

W tych instrukcjach zakładamy też, że na komputerze z systemem Linux działa system okien X11. Jeśli na komputerze z systemem Linux działa Wayland, zainstaluj też X.Org.

Skonfiguruj środowisko programistyczne

  1. Zainstaluj Docker Engine (nie używaj Docker Desktop).
  2. Skopiuj pakiet Matter SDK i zanotuj używane w tym celu zatwierdzenie.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Uruchom kontener kompilacji przy użyciu publicznych obrazów CI pakietu SDK i uruchom nowo skompilowane urządzenie wirtualne w tym kontenerze. Znajdź obraz, który ma pasować do naszej wersji SDK:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Jeśli używasz tego samego zatwierdzenia, zobaczysz komunikat ghcr.io/project-chip/chip-build:66Najpierw przekieruj porty xhost, abyśmy mogli później użyć aplikacji interfejsu:
    xhost local:1000
    Następnie uruchom kontener z odpowiednimi zasobami przekazanymi z hosta (naszym pakietem SDK do płatności, siecią i zasobami dotyczącymi wyświetlania/komunikacji).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Przyjrzyjmy się poleceniu dockera i opcjom, które do niego przekazaliśmy:

  • xhost local:1000 umożliwia systemowi X Window otrzymywanie połączeń od 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 udostępnianie przestrzeni nazw komunikacji między procesami maszynie hosta.
  • --net=host umożliwia Dockerowi wykorzystanie stosu sieciowego hosta wewnątrz kontenera, co jest wymagane do przekazywania ruchu mDNS z hosta do kontenera i udostępniania ekranu hosta X11.
  • -e DISPLAY eksportuje plik $DISPLAY na hosta, aby umożliwić 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 jako procesem w tle.
  • --mount podłącza do kontenera pakiet SDK, który sprawdziliśmy wcześniej.
  • Podczas uruchamiania --workdir ustawia katalog roboczy na katalog podłączonych pakietów SDK.

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

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

Zatrzymywanie i uruchamianie kontenera Dockera Matter

Uruchamiając polecenie docker run, tworzysz nowy kontener z określonym obrazem. Gdy to zrobisz, stare dane zapisane w poprzedniej instancji kontenera zostaną utracone. Czasami właśnie tak się dzieje, ponieważ umożliwia to rozpoczęcie od nowa instalacji. Czasami jednak wolisz zapisywać konfigurację miejsca pracy i środowiska między sesjami.

Dlatego po utworzeniu kontenera możesz go zatrzymać, aby nie stracić wprowadzonych danych.

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, używając:

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 standardu Matter

Inicjowanie pakietu SDK

Zainicjuj pakiet SDK Matter. Wykonanie tej operacji może potrwać kilka minut.

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

Twój pakiet SDK Matter został zainicjowany. Aby w przyszłości szybko ponownie zainicjować środowisko, uruchom polecenie:

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

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

Wcześniej uzyskiwać dostęp do plików na hoście z poziomu kontenera przy użyciu uchwytu montowania powiązania. Możesz też zapisywać pliki w podłączonym katalogu z poziomu kontenera, aby mieć do nich dostęp z hosta.

Ogólnie rzecz biorąc, aby podłączyć bieżący katalog roboczy do kontenera w lokalizacji /workspace, musisz uruchomić kontener z dodatkowym argumentem --mount source=$(pwd),target=/workspace,type=bind.

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

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

Pobierz z kontenera identyfikator grupy użytkownika 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.

Rekursywnie ustawiaj grupę dla plików w podłączonych katalogu na grupę użytkownika kontenera.

user@host> sudo chgrp -R 1000 .

Przyznaj grupie odpowiednie uprawnienia w katalogu. Ten przykład nadaje grupie użytkownika kontenera uprawnienia do odczytu, zapisu i wykonywania we wszystkich plikach w podłączonym katalogu.

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

Pamiętaj, że te polecenia nie mają wpływu na uprawnienia do nowych plików utworzonych przez użytkownika korzystającego z hosta. Pamiętaj, aby w razie potrzeby zaktualizować uprawnienia do 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 tego użytkownika.

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ć integracją standardu Matter z Google Home.

W ekosystemie Google Home działa każde urządzenie Matter, które otrzymało certyfikat Connectivity Standards Alliance (Alliance) Matter. Urządzenia będące w trakcie opracowywania, które nie mają certyfikatu, można w określonych warunkach przekazywać w ekosystemie Google Home. Więcej informacji znajdziesz w sekcji Ograniczenia parowania.

Tworzenie projektu programisty

Najpierw otwórz konsolę programisty Google Home:

  1. Kliknij 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 dotyczące spraw, na którym możesz wyświetlić dokumentację programowania standardu Matter i poczytać o niektórych narzędziach.
  4. Aby przejść dalej, kliknij Dalej: Programowanie. Wyświetli się strona Lista kontrolna do 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 Test VID (Testuj identyfikator VID) i wybierz 0xFFF1 z menu Testuj identyfikator VID. W polu Identyfikator produktu (PID) wpisz 0x8000 i kliknij Zapisz i kontynuuj, a następnie na następnej stronie kliknij Zapisz. Użyj tych dokładnych wartości VID/PID. Zależą od nich późniejsze kroki ćwiczeń w Codelabs.
    Konfiguruję projekt
  9. Teraz zobaczysz swoją integrację w sekcji Integracje spraw.
  10. Zrestartuj centrum, aby mieć pewność, że otrzymało najnowszą konfigurację projektu integracji ze standardem Matter. Jeśli później będzie konieczna zmiana identyfikatora VID lub PID, trzeba będzie zrestartować projekt po zapisaniu projektu, aby zmiana zaczęła obowiązywać. Szczegółowe instrukcje znajdziesz w artykule Ponowne uruchamianie urządzeń Google Nest lub Google Wifi.

4. Zbuduj urządzenie

Wszystkie przykłady ze standardu Matter znajdują się w folderze examples w repozytorium GitHub. Dostępnych jest kilka przykładów, ale to ćwiczenia z programowania skupiamy się na pracy szefa kuchni.

Szef kuchni to:

  • Przykładowa aplikacja z interfejsem terminala z funkcjami pakowania, które można też znaleźć w aplikacji examples/shell.
  • skrypt uwzględniający zasadę stosowania konwencji i konfiguracji obejmującej 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

Kucharz ma kilka opcji, które można wyświetlić, uruchamiając chef.py -h. Używamy tych opcji:

  • -d: określa typ urządzenia, którego chcesz użyć. W tym przypadku tworzymy aplikację oświetleniową z elementami umożliwiającymi włączanie i wyłączanie oświetlenia oraz regulację poziomu.
  • -z: wywołuje narzędzie ZAP, aby wygenerować pliki źródłowe implementujące typ urządzenia. Oznacza to, że na podstawie wybranego przez Ciebie oświetlenia ZAP automatycznie utworzy kod do włączenia w kompilacji, która 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. W przypadku wirtualnych urządzeń Matter używana jest usługa linux.

Uruchamianie urządzenia

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, aby umożliwić nam skonfigurowanie Twojego urządzenia w Google Home.

Zatrzymaj urządzenie

Jeśli chcesz zatrzymać urządzenie, możesz zamknąć program, naciskając CTRL+C. Jeśli aplikacja nie zostanie zamknięta, trzeba również nacisnąć CTRL+\.

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

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

$ rm /tmp/chip*

5. Przekaż urządzenie

Uwaga: ten krok powiedzie się tylko wtedy, gdy Twój projekt jest już skonfigurowany w konsoli programisty Google Home.

Nest Hub

Aby uruchomić urządzenie na tkaninie Matter, musisz mieć centrum. Jest to urządzenie Google Nest, takie jak Nest Hub (2 generacji), które obsługuje standard Matter i służy zarówno jako router brzegowy w przypadku urządzeń obsługujących Thread, jak i lokalna ścieżka realizacji do kierowania intencji inteligentnego domu.

Na tej liście możesz sprawdzić, które centra obsługują standard Matter.

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

  • Centrum jest sparowane z tym samym kontem Google, którego używasz do logowania się w konsoli Google Home.
  • Centrum jest w tej samej sieci Wi-Fi co komputer, którego używasz do uruchomienia urządzenia wirtualnej sprawy.
  • Centrum jest w tej samej strukturze, której używasz w aplikacji Google Home. („Dom” na Grafie Google Home reprezentuje Twoją strukturę).

Uzyskaj kod QR

Proces uruchamiania wymaga danych rejestracyjnych Matter za pomocą kodu QR. Sprawdź dane wyjściowe w konsoli aplikacji Matter zawierające link do kodu QR odpowiedniego do uruchomienia.

Wykonaj operację prowizji

  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 wyszuka urządzenie. Jeśli pojawi się komunikat „Znaleziono urządzenie z Androidem...”, kliknij „Tak”. W przeciwnym razie kliknij Skonfiguruj inne urządzenie, a potem z listy urządzeń wybierz Urządzenie z problemem.
  7. Skieruj aparat na kod QR urządzenia lub kod QR wygenerowany przez stronę.
  8. Kontynuuj proces parowania zgodnie z instrukcjami w aplikacji Google Home.

Po wykonaniu tych czynności urządzenie wirtualne Matter powinno zostać oddane do użytku i powinno pojawić się jako nowa ikona w aplikacji Google Home.

Sparowana żarówka w aplikacji Google Home

Rozwiązywanie problemów

Prowizje kończą się niepowodzeniem i występuje „problem z połączeniem” lub „Nie można skontaktować się z Google” komunikaty o błędach

Przekazywanie dalej się nie udaje, gdy „Skanujesz urządzenie” na długi okres

6. Steruj urządzeniem

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

  • za pomocą Asystenta Google.
  • W aplikacji Google Home.

Asystent Google

Użyj Asystenta Google na telefonie lub koncentratorze, aby przełączać stan urządzenia za pomocą poleceń głosowych, takich jak „OK Google, przełącz światło”.

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

7. Gratulacje!

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

Dzięki temu ćwiczeniu w programie omówiliśmy, jak:

  • Zainstaluj środowisko programistyczne Matter.
  • Tworzenie i uruchamianie urządzenia wirtualnego ze standardem Matter.
  • Przekaż urządzenie wirtualne i steruj nim z poziomu Google Home.

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