Tworzenie wirtualnego urządzenia Sprawa

1. Wprowadzenie

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

Więcej informacji o standardzie Matter znajdziesz w Centrum dla deweloperów Google Home lub na stronie Connectivity Standards Alliance.

Czego się nauczysz

  • Jak skonfigurować środowisko kompilacji Matter
  • Jak utworzyć wirtualne urządzenie Matter działające na komputerze
  • Jak skonfigurować wirtualne urządzenie Matter i sterować nim za pomocą Google Home

Czego potrzebujesz

  • hub, czyli dowolne urządzenie Google Nest obsługujące Matter, np. Nest Hub (2 generacji);
  • Komputer z systemem Linux i systemem okien X11.
  • Dockera.
  • Git.
  • Podstawowa znajomość systemu Linux.
    • Pamiętaj, że w przypadku wszystkich poleceń w tym samouczku zakłada się, że używasz powłoki BASH.

2. Konfigurowanie środowiska

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 przyjęto też, że na komputerze z Linuksem działa system okien X11. Jeśli na komputerze z Linuksem 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 i zapisz 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 za pomocą publicznych obrazów CI pakietu SDK i wykonaj nowo utworzone urządzenie wirtualne w tym kontenerze. Znajdź obraz, który pasuje do Twojej wersji pakietu SDK, w ten sposób:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Jeśli używasz tego samego zatwierdzenia, powinna się wyświetlić ta informacja: ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Następnie uruchom kontener z odpowiednimi zasobami przekazanymi z hosta (nasz pakiet SDK do płatności, 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

Przyjrzyjmy się poleceniu Docker i przekazanym do niego opcjom:

  • 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 podany 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 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 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 proces w tle.
  • --mount montuje w kontenerze pakiet SDK, który wcześniej sprawdziliśmy.
  • --workdir ustawia katalog roboczy przy uruchamianiu 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 były zapisane w poprzedniej instancji kontenera. Czasami jest to pożądane, ponieważ umożliwia rozpoczęcie od nowej instalacji. Czasami jednak możesz chcieć zapisać pracę i konfigurację środowiska między sesjami.

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

user@host> docker stop matter-container

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

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

Dodatkowe sesje terminala w kontenerze możesz otworzyć za pomocą tego polecenia:

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

Możesz też rozpocząć sesję z uprawnieniami roota, używając tego polecenia:

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

Początkowa konfiguracja 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

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 uzyskiwaliśmy dostęp do plików na komputerze hosta z poziomu kontenera za pomocą montowania wiązanego. 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 podłączeń wiążących, uruchamiając kontener z dodatkowym argumentem --mount source=$(pwd),target=/workspace,type=bind, aby podłączyć bieżący katalog roboczy do kontenera 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.

Rekursywnie 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 otrzymuje 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 do nowych plików utworzonych przez użytkownika hosta. W razie potrzeby pamiętaj o zaktualizowaniu uprawnień nowych plików utworzonych w aplikacji hosta.

Możesz dodać użytkownika hosta do grupy użytkownika kontenera, aby odziedziczyć 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 certyfikację Matter organizacji Connectivity Standards Alliance (Alliance), działa w ekosystemie Google Home. Urządzenia w trakcie opracowywania, które nie zostały certyfikowane, mogą być włączane do ekosystemu Google Home pod pewnymi warunkami. Więcej informacji znajdziesz w sekcji Ograniczenia parowania.

Tworzenie projektu deweloperskiego

Zacznij od otwarcia konsoli programisty Google Home:

  1. Kliknij Utwórz projekt.
  2. Wpisz unikalną nazwę projektu, a następnie kliknij Utwórz projekt. Okno tworzenia nowego projektu
  3. Kliknij + Dodaj integrację, aby przejść do ekranu Zasoby dotyczące Matter, na którym możesz wyświetlić dokumentację dotyczącą tworzenia urządzeń Matter i przeczytać informacje o niektórych narzędziach.
  4. Gdy wszystko będzie gotowe, kliknij Dalej: opracowywanie, 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 z 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 Identyfikator produktu (PID) wpisz 0x8000 i kliknij Save & continue (Zapisz i kontynuuj), a potem na następnej stronie kliknij Save (Zapisz). Użyj tych dokładnych wartości VID/PID, ponieważ zależą od nich kolejne kroki w samouczku.
    Konfigurowanie projektu
  9. Teraz w sekcji Integracje Matter zobaczysz swoją integrację.
  10. Uruchom ponownie hub, aby mieć pewność, że otrzyma najnowszą konfigurację projektu integracji Matter. Jeśli później musisz zmienić identyfikator dostawcy lub identyfikator produktu, po zapisaniu projektu musisz też ponownie uruchomić urządzenie, aby zmiana została zastosowana. 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 znajdują się 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 i zawiera funkcje dostępne też w aplikacji examples/shell.
  • Skrypt, który wykorzystuje zasadę konwencji zamiast konfiguracji, aby obejmować kilka typowych zadań niezbędnych do programowania 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 polecenie chef.py -h. Używamy tutaj tych opcji:

  • -d: określa typ urządzenia, które ma być używane. W tym przypadku tworzymy aplikację do oświetlenia z ustawieniami włączania i wyłączania oraz poziomu.
  • -z: wywołuje narzędzie ZAP, aby wygenerować pliki źródłowe, które implementują 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: kompilacje.
  • -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. Możesz uruchomić ./chef.py -h, aby zobaczyć wszystkie dostępne polecenia i obsługiwane platformy docelowe. linux jest używany w przypadku wirtualnych urządzeń Matter.

Uruchamianie urządzenia

Matter korzysta z 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ą tego polecenia:

$ ./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 przejdziemy do aplikacji Google Home, aby dodać urządzenie do Google Home.

Zatrzymywanie urządzenia

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

$ rm /tmp/chip*

5. Uruchom urządzenie

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

Nest Hub

Aby włączyć urządzenie w sieci standardu Matter, musisz mieć centralę. Jest to urządzenie Google Nest, takie jak Nest Hub (2 generacji), które obsługuje standard Matter i będzie pełnić funkcję routera granicznego dla urządzeń obsługujących Thread oraz lokalną ścieżkę realizacji do kierowania intencji związanych z inteligentnym domem.

Na tej liście znajdziesz informacje o tym, które huby obsługują Matter.

Zanim rozpoczniesz proces uruchamiania, sprawdź, czy:

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

Uzyskiwanie kodu QR

Proces uruchamiania wymaga informacji o wprowadzaniu urządzenia do sieci Matter, które są podawane za pomocą kodu QR. Sprawdź dane wyjściowe konsoli aplikacji Matter, które będą zawierać 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 Twoje urządzenie. Gdy pojawi się komunikat „Znaleziono urządzenie Matter…”, kliknij „Tak”. W przeciwnym razie kliknij Skonfiguruj inne urządzenie, a następnie wybierz Urządzenie Matter z listy urządzeń.
  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 urządzenie wirtualne Matter powinno zostać pomyślnie skonfigurowane i powinno pojawić się jako nowa ikona w aplikacji Google Home.

Sparowana żarówka w aplikacji Google Home

Rozwiązywanie problemów

Nie udało się skonfigurować urządzenia. Pojawiają się komunikaty o błędach „Problem z połączeniem” lub „Nie udało się skontaktować z Google”

  • Sprawdź, czy w konsoli Google Home masz utworzony projekt z prawidłową kombinacją VID/PID i czy nie masz innych projektów, które używają tej samej kombinacji VID/PID.

Nie udało się skonfigurować urządzenia po długim czasie oczekiwania na komunikat „Skanowanie urządzenia”

6. Sterowanie urządzeniem

Gdy urządzenie obsługujące standard Matter zostanie pomyślnie skonfigurowane i będzie widoczne w aplikacji Google Home jako żarówka, możesz przetestować sterowanie nim na różne sposoby:

  • Korzystanie z Asystenta Google.
  • za pomocą aplikacji Google Home;

Asystent Google

Używaj Asystenta Google na telefonie lub hubie, 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 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!

Pierwsze urządzenie Matter zostało utworzone. Świetnie!

Z tego modułu dowiedzieliśmy się, jak:

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

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