Tworzenie wirtualnego urządzenia Matter

1. Wprowadzenie

Matter to protokół łączności, który otwiera nowe możliwości w zakresie tworzenia inteligentnych urządzeń. W tym ćwiczeniu utworzysz pierwsze urządzenie Matter, korzystając z zasobów pakietu Matter SDK.

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

Czego się nauczysz

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

Czego potrzebujesz

  • Centrala, czyli dowolne urządzenie Google Nest obsługujące standard Matter, np. Nest Hub (2. generacji).
  • Komputer z systemem Linux i systemem okien X11.
  • Docker.
  • Git.
  • Podstawowa wiedza o systemie Linux.
    • Pamiętaj, że w tym ćwiczeniu wszystkie polecenia są przeznaczone dla powłoki BASH.

2. Konfigurowanie środowiska

Sprawdź sprzęt

Ta instalacja Dockera nie jest obsługiwana na komputerach z systemem Windows i macOS. Możesz ręcznie zainstalować i skompilować Matter w systemie macOS.

Te instrukcje zakładają też, że na komputerze z systemem Linux działa system okien X11. Jeśli na komputerze z systemem Linux działa Wayland, upewnij się, że jest też zainstalowany X.Org.

Konfigurowanie środowiska programistycznego

  1. Zainstaluj Docker Engine (nie używaj Docker Desktop).
  2. Sklonuj pakiet Matter SDK. Zwróć uwagę na commit, którego używamy poniżej.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Uruchom kontener kompilacji, korzystając z publicznych obrazów CI pakietu SDK, i wykonaj nowo utworzone urządzenie wirtualne w tym kontenerze. Znajdź obraz, którego chcesz użyć, pasujący do naszej wersji pakietu SDK:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Jeśli używasz tego samego commita, powinien pojawić się komunikat ghcr.io/project-chip/chip-build:66.Najpierw przekieruj porty xhost, abyśmy mogli później używać aplikacji z interfejsem użytkownika:
    xhost local:1000
    Następnie uruchom kontener z odpowiednimi zasobami przekierowanymi z hosta (nasz checkout pakietu SDK, zasoby sieciowe oraz zasoby wyświetlania i 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

Omówmy polecenie Dockera i przekazane do niego opcje:

  • xhost local:1000 umożliwia systemowi X Window 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 pobierając go z rejestru Dockera.
  • --ipc=host umożliwia Dockerowi udostępnianie przestrzeni nazw komunikacji między procesami (IPC) na hoście.
  • --net=host umożliwia Dockerowi korzystanie ze stosu sieciowego hosta w kontenerze, co jest wymagane, aby mógł przekazywać ruch mDNS z hosta do kontenera i udostępniać wyświetlacz X11 hosta.
  • -e DISPLAY eksportuje $DISPLAY do hosta, zapewniając dostęp do graficznego interfejsu systemu. Jest to wymagane do uruchomienia narzędzia ZAP podczas edytowania klastrów Matter.
  • -it uruchamia Dockera z interaktywnym terminalem (tty), a nie jako proces w tle.
  • --mount montuje pakiet SDK, który wcześniej sprawdziliśmy, w kontenerze.
  • --workdir ustawia katalog roboczy przy uruchomieniu na zamontowany katalog pakietu SDK.

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

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

Zatrzymywanie i uruchamianie kontenera Dockera Matter

Za każdym razem, gdy uruchamiasz polecenie docker run, tworzysz nowy kontener z określonym obrazem. Spowoduje to utratę starych danych, które zostały zapisane w poprzedniej instancji kontenera. Czasami jest to pożądane, ponieważ pozwala zacząć od nowej instalacji. Są jednak sytuacje, w których wolisz zapisać pracę i konfigurację środowiska między sesjami.

Dlatego po utworzeniu kontenera możesz go zatrzymać, aby nie utracić pracy.

user@host> docker stop matter-container

Gdy zechcesz ponownie uruchomić kontener, uruchom go 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

Możesz też rozpocząć sesję roota za pomocą:

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

Początkowa konfiguracja Matter

Inicjowanie pakietu SDK

Zainicjuj pakiet Matter SDK. Ta operacja potrwa kilka minut.

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

Pakiet Matter SDK został zainicjowany. Aby w przyszłości szybko ponownie zainicjować środowisko, uruchom:

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

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

Wcześniej uzyskiwaliśmy dostęp do plików na komputerze hosta z poziomu kontenera za pomocą montowania powiązań. Możesz też zapisywać pliki w zamontowanym katalogu z poziomu kontenera, aby uzyskać do nich dostęp z hosta.

Ogólnie rzecz biorąc, używaj montowania powiązań, uruchamiając kontener z dodatkowym argumentem --mount source=$(pwd),target=/workspace,type=bind, aby zamontować bieżący katalog roboczy w kontenerze w lokalizacji /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

Uprawnienia użytkownika kontenera w zamontowanym katalogu muszą być zarządzane na hoście.

Uzyskaj identyfikator grupy użytkownika kontenera z poziomu 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 zamontowany przez kontener.

Rekurencyjnie ustaw grupę plików w zamontowanym katalogu na grupę użytkownika kontenera.

user@host> sudo chgrp -R 1000 .

Przyznaj grupie odpowiednie uprawnienia w katalogu. W tym przykładzie grupa użytkownika kontenera ma uprawnienia do odczytu, zapisu i wykonywania wszystkich plików w zamontowanym katalogu.

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

Pamiętaj, że te polecenia nie mają wpływu na uprawnienia nowych plików utworzonych przez użytkownika hosta. W razie potrzeby pamiętaj o aktualizowaniu uprawnień 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 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 zarządzasz integracjami Matter z Google Home.

Każde urządzenie Matter, które przeszło certyfikację Connectivity Standards Alliance (Alliance), działa w ekosystemie Google Home. Urządzenia w trakcie opracowywania, które nie zostały jeszcze certyfikowane, mogą być konfigurowane w ekosystemie Google Home pod pewnymi warunkami. Więcej informacji znajdziesz w sekcji Ograniczenia parowania.

Tworzenie projektu dewelopera

Zacznij od otwarcia Konsoli 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ę, aby przejść do ekranu Zasoby Matter, na którym możesz wyświetlić dokumentację dotyczącą tworzenia aplikacji Matter i przeczytać o niektórych narzędziach.
  4. Gdy zechcesz kontynuować, kliknij Dalej: tworzenie, aby wyświetlić stronę Lista kontrolna Matter.
  5. Kliknij Dalej: konfiguracja.
  6. Na stronie Konfiguracja wpisz Nazwę produktu.
  7. Kliknij Wybierz typ urządzenia i w menu wybierz typ urządzenia (w tym przypadku Light).
  8. W polu Vendor ID (VID) wybierz Test VID, a następnie w menu Test VID wybierz 0xFFF1. W polu Product ID (PID) wpisz 0x8000 i kliknij Zapisz i kontynuuj , a potem na następnej stronie kliknij Zapisz. Użyj dokładnie tych wartości VID/PID. Będą one potrzebne w dalszych krokach ćwiczenia.
    Konfigurowanie projektu
  9. Teraz zobaczysz swoją integrację w sekcji Integracje Matter.
  10. Uruchom ponownie centralę, aby mieć pewność, że otrzyma najnowszą konfigurację projektu integracji Matter. Jeśli później będziesz musiał zmienić identyfikator VID lub PID, po zapisaniu projektu musisz też ponownie uruchomić centralę, aby zmiany zostały zastosowane. 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 Matter znajdziesz w folderze examples w repozytorium GitHub. Dostępnych jest kilka przykładów, ale w tym ćwiczeniu skupimy się na Chef.

Chef to:

  • przykładowa aplikacja, która udostępnia interfejs terminala, zawierający funkcje dostępne też w aplikacji examples/shell;
  • skrypt, który opiera się na zasadzie konwencji zamiast konfiguracji, aby enkapsulować kilka typowych zadań niezbędnych do tworzenia urządzenia obsługującego standard Matter.

Otwórz folder z przykładem Chef i utwórz 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 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 funkcjami włączania i wyłączania oraz sterowania poziomem.
  • -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 i będzie definiować światło (model danych) oraz sposób jego interakcji z innymi urządzeniami (model interakcji).
  • -b: kompiluje.
  • -r: [opcjonalnie] włącza serwer RPC na wirtualnym urządzeniu 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. Obsługiwane platformy to linux, nrfconnect i esp32. Aby wyświetlić wszystkie dostępne polecenia i obsługiwane platformy docelowe, możesz uruchomić ./chef.py -h. linux jest używany w przypadku wirtualnych urządzeń Matter.

Uruchamianie urządzenia

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

Pozostaw urządzenie włączone. Teraz zajmiemy się aplikacją Google Home, aby skonfigurować urządzenie w Google Home.

Zatrzymywanie urządzenia

Jeśli chcesz zatrzymać urządzenie, możesz zamknąć program, naciskając CTRL+C. Jeśli aplikacja się nie zamknie, może być konieczne użycie 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 konfiguracji od początku, musisz usunąć te pliki, uruchamiając to polecenie:

$ rm /tmp/chip*

5. Konfigurowanie urządzenia

Uwaga: ten krok zakończy się powodzeniem tylko wtedy, gdy projekt został już skonfigurowany w Konsoli programisty Google Home.

Nest Hub

Aby skonfigurować urządzenie w sieci Matter, potrzebujesz centrali. Jest to urządzenie Google Nest, np. Nest Hub (2. generacji), które obsługuje standard Matter i będzie pełnić funkcję zarówno routera brzegowego dla urządzeń obsługujących Thread, jak i lokalnej ścieżki realizacji do kierowania intencji inteligentnego domu.

Na tej liście znajdziesz centrale obsługujące standard Matter.

Zanim rozpoczniesz proces konfiguracji, sprawdź, czy:

  • centrala jest sparowana z tym samym kontem Google, którego używasz do logowania się w Konsoli Google Home;
  • centrala jest połączona z tą samą siecią Wi-Fi co komputer, na którym uruchamiasz wirtualne urządzenie Matter;
  • centrala znajduje się w tej samej strukturze, której używasz w aplikacji Google Home. („Dom” w grafie Google Home reprezentuje Twoją strukturę).

Uzyskiwanie kodu QR

Proces konfiguracji wymaga informacji o wdrożeniu Matter onboarding information, które są dostępne w postaci kodu QR. Sprawdź dane wyjściowe konsoli aplikacji Matter, które będą zawierać link do kodu QR odpowiedniego do konfiguracji.

Wykonywanie operacji konfiguracji

  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 w poszukiwaniu urządzenia. 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ń wybierz Urządzenie Matter.
  7. Skieruj aparat na kod QR urządzenia lub kod QR wygenerowany przez witrynę.
  8. Kontynuuj proces parowania zgodnie z instrukcjami w aplikacji Google Home.

Po wykonaniu tych czynności wirtualne urządzenie Matter powinno zostać skonfigurowane i powinno być widoczne jako nowa ikona w aplikacji Google Home.

Sparowana żarówka w aplikacji Google Home

Rozwiązywanie problemów

Konfiguracja nie powiodła się i wyświetlają się komunikaty o błędach „Problem z połączeniem” lub „Nie można skontaktować się z Google”

Konfiguracja nie powiodła się po długim czasie skanowania urządzenia

6. Sterowanie urządzeniem

Gdy urządzenie obsługujące standard Matter zostanie skonfigurowane i będzie widoczne w aplikacji Google Home jako żarówka, możesz przetestować sterowanie urządzeniem za pomocą różnych metod:

  • Za pomocą Asystenta Google.
  • Za pomocą aplikacji Google Home.

Asystent Google

Użyj Asystenta Google na telefonie lub centrali, aby przełączać stan urządzenia za pomocą poleceń głosowych, np. „OK Google, włą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łącz i Wyłącz obok ikony żarówki wyświetlanej 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!

W tym ćwiczeniu dowiedziałeś się, jak:

  • zainstalować środowisko programistyczne Matter;
  • utworzyć i uruchomić urządzenie wirtualne Matter;
  • skonfiguruj urządzenie wirtualne i steruj nim za pomocą Google Home.

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