Creare un dispositivo virtuale Matter

1. Introduzione

Matter è un protocollo di connettività che offre entusiasmanti opportunità per lo sviluppo di smart device. In questo codelab, creerai il tuo primo dispositivo Matter utilizzando le risorse dell'SDK Matter.

Per saperne di più su Matter, visita il Developer Center di Google Home o il sito web della Connectivity Standards Alliance.

Obiettivi didattici

  • Come configurare un ambiente di build Matter
  • Come creare un dispositivo Matter virtuale in esecuzione sul tuo computer
  • Come mettere in servizio e controllare il dispositivo Matter virtuale con Google Home

Che cosa ti serve

  • Un hub, ovvero qualsiasi dispositivo Google Nest che supporta Matter, come Nest Hub (2a generazione).
  • Una macchina Linux che esegue il sistema windowing X11.
  • e Docker.
  • o Git.
  • Conoscenza di base di Linux.
    • Nota che la shell presunta per tutti i comandi in questo codelab è BASH.

2. Configura l'ambiente

Controlla l'hardware

I computer Windows e macOS non sono supportati da questa installazione Docker. Puoi installare e creare manualmente Matter su macOS.

Inoltre, queste istruzioni presuppongono che sulla tua macchina Linux sia in esecuzione il sistema di windowing X11. Se sul tuo computer Linux è in esecuzione Wayland, assicurati che sia installato anche X.Org.

Configura l'ambiente di sviluppo

  1. Installa Docker Engine (non utilizzare Docker Desktop).
  2. Clona l'SDK Matter e tieni presente il commit che utilizzeremo di seguito.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Esegui un container di build utilizzando le immagini CI pubbliche dell'SDK ed esegui il dispositivo virtuale appena creato dall'interno di questo container. Individua l'immagine da utilizzare corrispondente alla nostra versione dell'SDK, nel seguente modo:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Se utilizzi lo stesso commit, dovresti vedere ghcr.io/project-chip/chip-build:66Prima di tutto, inoltra le porte xhost in modo da poter utilizzare in seguito le applicazioni UI:
    xhost local:1000
    Successivamente, avvia il container con le risorse appropriate inoltrate dall'host (le nostre risorse di pagamento dell'SDK, networking e display/comunicazione).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Vediamo il comando docker e le opzioni che abbiamo passato al comando:

  • xhost local:1000 consente a X Window System di ricevere connessioni dall'host locale sulla porta 1000, consentendo l'utilizzo di un'interfaccia utente grafica.
  • docker run … image esegue l'immagine specificata, eseguendone il pull dal registro Docker, se necessario.
  • --ipc=host consente a Docker di condividere lo spazio dei nomi della comunicazione tra processi con la tua macchina host.
  • --net=host consente a Docker di usare lo stack di rete dell'host all'interno del container, necessario per passare il traffico mDNS dall'host al container e per condividere il display X11 dell'host.
  • -e DISPLAY esporta $DISPLAY nell'host, fornendo accesso all'interfaccia grafica di sistema. Questo è necessario per eseguire lo strumento ZAP durante la modifica dei cluster Matter.
  • -it esegue Docker con un terminale interattivo (tty), anziché come processo in background.
  • --mount monta l'SDK che abbiamo esaminato in precedenza nel container.
  • --workdir imposta la directory di lavoro all'avvio sulla directory dell'SDK montato.

Facoltativamente, puoi eseguire una seconda istanza di sessione del terminale:

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

arresta e avvia il container Docker Matter

Ogni volta che esegui un comando docker run, creerai un nuovo container con l'immagine specificata. Se esegui questa operazione, i dati precedenti salvati in un'istanza di container precedente andranno persi. A volte è ciò che vuoi che succeda, perché ti consente di iniziare con una nuova installazione. Tuttavia, a volte potrebbe essere preferibile salvare la configurazione di lavoro e dell'ambiente tra una sessione e l'altra.

Per questo motivo, dopo aver creato il contenitore, puoi arrestarlo per evitare di perdere il lavoro.

user@host> docker stop matter-container

Quando vuoi eseguirlo di nuovo, avvia il container e apri una finestra del terminale:

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

Puoi aprire altre sessioni del terminale per il tuo container con:

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

Oppure avvia una sessione root utilizzando:

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

Configurazione iniziale di Matter

Inizializzare l'SDK

Inizializza l'SDK Matter. Il completamento di questa operazione richiederà diversi minuti.

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

L'SDK Matter è ora inizializzato. Per reinizializzare rapidamente l'ambiente in futuro, esegui:

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

Condividi file tra l'host e il container

In precedenza, abbiamo eseguito l'accesso ai file sul computer host dall'interno del container tramite un binding. Puoi anche scrivere file nella directory montata dall'interno del container per accedere dall'host.

In generale, utilizza i vincoli di montaggio eseguendo il container con l'argomento aggiuntivo --mount source=$(pwd),target=/workspace,type=bind per montare la directory di lavoro corrente nel container in /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

Le autorizzazioni dell'utente container nella directory montata devono essere gestite nell'host.

Recupera l'ID gruppo dell'utente contenitore dal contenitore.

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

Apri un'altra sessione del terminale sull'host del container e imposta la directory di lavoro sulla directory montata dal container.

Imposta in modo ricorsivo il gruppo per i file della directory montata sul gruppo dell'utente del container.

user@host> sudo chgrp -R 1000 .

Concedi al gruppo le autorizzazioni desiderate nella directory. Questo esempio fornisce al gruppo dell'utente del container le autorizzazioni di lettura, scrittura ed esecuzione su tutti i file nella directory montata.

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

Tieni presente che questi comandi non influiscono sull'autorizzazione dei nuovi file creati dall'utente host. Ricordati di aggiornare le autorizzazioni dei nuovi file creati nell'host in base alle esigenze.

Puoi aggiungere l'utente host al gruppo dell'utente contenitore per ereditare le autorizzazioni sui file creati dall'utente del contenitore.

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

3. console per gli sviluppatori di Google Home

La Console per gli sviluppatori di Google Home è l'applicazione web in cui puoi gestire le integrazioni Matter con Google Home.

Tutti i dispositivi Matter che hanno superato la certificazione Connectivity Standards Alliance (Alliance) Matter funzionano nell'ecosistema Google Home. I dispositivi in fase di sviluppo che non sono stati certificati possono essere messi in servizio nell'ecosistema Google Home in determinate condizioni. Per ulteriori informazioni, consulta la sezione Limitazioni all'accoppiamento.

Crea un progetto sviluppatore

Inizia dalla console per gli sviluppatori di Google Home:

.

  1. Fai clic su Crea progetto.
  2. Inserisci un nome univoco per il progetto e fai clic su Crea progetto. Finestra di dialogo Crea nuovo progetto
  3. Fai clic su + Aggiungi integrazione per aprire la schermata delle risorse Matter, dove puoi consultare la documentazione per lo sviluppo di Matter e leggere informazioni su alcuni strumenti.
  4. Quando vuoi continuare, fai clic su Successivo: Sviluppo, che visualizza la pagina Elenco di controllo Matter.
  5. Fai clic su Successivo: configurazione
  6. Nella pagina Configurazione, inserisci il Nome del prodotto.
  7. Fai clic su Seleziona tipo di dispositivo e seleziona il tipo di dispositivo dal menu a discesa (in questo caso, Light).
  8. In ID fornitore (VID), seleziona Test VID e seleziona 0xFFF1 dal menu a discesa Test VID. In ID prodotto (PID), inserisci 0x8000 e fai clic su Salva & continua, poi fai clic su Salva nella pagina seguente. Utilizza questi valori VID/PID esatti, da cui dipendono i passaggi successivi del codelab.
    Configurazione di un progetto
  9. Ora vedrai l'integrazione in Integrazioni Matter.
  10. Riavvia l'hub per assicurarti che riceva la configurazione più recente del progetto di integrazione con Matter. Se in un secondo momento devi modificare il VID o il PID, dovrai anche riavviare dopo aver salvato il progetto affinché la modifica venga applicata. Per istruzioni dettagliate sul riavvio, consulta la sezione Riavviare i dispositivi Google Nest o Google Wifi.

4. Crea un dispositivo

Tutti gli esempi in Matter sono disponibili nella cartella examples del repository GitHub. Sono disponibili diversi esempi, ma in questo codelab ci concentreremo su Chef.

Chef è:

  • Un'app di esempio che fornisce un'interfaccia del terminale e include funzionalità, disponibile anche nell'app examples/shell.
  • Uno script che abbraccia il principio della sovra-configurazione per incapsulare molte delle attività comuni necessarie per lo sviluppo di un dispositivo compatibile con Matter.

Vai alla cartella di esempio Chef e crea la tua prima build Matter:

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

Chef ha alcune opzioni che possono essere visualizzate eseguendo chef.py -h. Le opzioni che stiamo utilizzando sono:

  • -d: definisce il tipo di dispositivo da utilizzare. In questo caso, stiamo creando un'app per l'illuminazione con controlli di attivazione e disattivazione e di livello.
  • -z: richiama lo strumento ZAP per generare i file di origine che implementano il tipo di dispositivo. In altre parole, a seconda dell'illuminazione che hai scelto, ZAP creerà automaticamente nella build un codice da incorporare per definire la luce (il modello dei dati) e il modo in cui interagisce con gli altri dispositivi (il modello di interazione).
  • -b: build.
  • -r: [facoltativo] abilita il server RPC sul dispositivo Matter virtuale in modo che altri componenti (come la GUI) possano comunicare con il dispositivo per impostare e recuperare gli attributi del modello dei dati.
  • -t linux: piattaforma di destinazione. Le piattaforme di supporto sono linux, nrfconnect e esp32. Puoi eseguire ./chef.py -h per visualizzare tutti i comandi disponibili e le piattaforme di destinazione supportate. linux viene utilizzato per i dispositivi Matter virtuali.

Esegui il dispositivo

Matter utilizza la porta TCP/UDP 5540, quindi se sul tuo computer è in esecuzione un firewall, arrestalo o consenti le connessioni TCP/UDP in entrata sulla porta 5540.

Esegui il dispositivo virtuale nel container con:

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

Lascia in esecuzione il dispositivo. Ora rivolgeremo la nostra attenzione all'app Google Home per effettuare la messa in servizio del tuo dispositivo in Google Home.

Arresta il dispositivo

Per arrestare il dispositivo, puoi uscire dal programma premendo Ctrl+C. Se l'app non si chiude, potresti dover utilizzare anche CTRL+\.

Le credenziali del dispositivo virtuale sono archiviate nella directory /tmp/, in file che iniziano con il prefisso chip.

Se vuoi ripetere l'intero processo di messa in servizio dall'inizio, devi eliminare i file eseguendo questo comando:

$ rm /tmp/chip*

5. Messa in servizio del dispositivo

Nota: questo passaggio andrà a buon fine solo se hai già configurato il tuo progetto nella console per gli sviluppatori di Google Home.

Nest Hub

È necessario un hub per mettere in servizio il dispositivo su Matter fabric. Si tratta di un dispositivo Google Nest, come Nest Hub (2a generazione), che supporta Matter e che fungerà sia da router di confine per i dispositivi compatibili con Thread sia da percorso di distribuzione locale per il routing degli intent della smart home.

Fai riferimento a questo elenco per vedere quali hub supportano Matter.

Prima di iniziare la procedura di messa in servizio, accertati che:

  • L'hub è accoppiato allo stesso Account Google che hai usato per accedere alla console Google Home.
  • L'hub si trova sulla stessa rete Wi-Fi del computer che utilizzi per eseguire il dispositivo Virtual Matter.
  • L'hub si trova nella stessa struttura che utilizzi nell'app Google Home. (La "casa" nel Google Home Graph rappresenta la tua struttura).

Ricevi un codice QR

La procedura di messa in servizio richiede le informazioni di onboarding di Matter fornite tramite un codice QR. Esamina l'output della console dell'applicazione Matter, che conterrà un link al codice QR relativo alla messa in servizio.

Eseguire l'operazione di commissione

  1. Apri l'app Google Home.
  2. Tocca il segno + nell'angolo in alto a sinistra.
  3. Tocca Configura dispositivo.
  4. Tocca Nuovo dispositivo.
  5. Seleziona la tua casa e tocca Avanti.
  6. L'app Google Home cerca il tuo dispositivo. Se appare il messaggio "Dispositivo Matter trovato...", tocca "Sì". Altrimenti, tocca Configura un altro dispositivo, quindi seleziona Dispositivo Matter dall'elenco dei dispositivi.
  7. Inquadra con la fotocamera il codice QR del tuo dispositivo o il codice QR generato dal sito web.
  8. Continua la procedura di accoppiamento come indicato nella procedura dell'app Google Home.

Una volta completati questi passaggi, il dispositivo virtuale Matter dovrebbe essere stato commissionato correttamente e dovrebbe apparire come nuova icona nell'app Google Home.

Lampadina accoppiata nell'app Google Home

Risoluzione dei problemi

La messa in servizio non va a buon fine con "Problema di connettività" o "Impossibile contattare Google" messaggi di errore

  • Assicurati di aver creato un progetto con la combinazione VID/PID corretta nella console Google Home e di non avere altri progetti che utilizzano la stessa combinazione VID/PID.

La messa in servizio non va a buon fine dopo "Scansione del dispositivo" per un lungo periodo

6. Controlla il dispositivo

Dopo aver messo in servizio il dispositivo compatibile con Matter e averlo visualizzato nell'app Google Home sotto forma di lampadina, puoi testare il controllo del dispositivo con diversi metodi:

  • Utilizzo dell'Assistente Google.
  • Con l'app Google Home.

Assistente Google

Usare l'Assistente Google sullo smartphone o sull'hub per attivare/disattivare lo stato del dispositivo dai comandi vocali, ad esempio dicendo "Hey Google, attiva le luci".

Per altri esempi di comandi, consulta la sezione Controllare i dispositivi per la smart home con i comandi vocali di Controllare i dispositivi per la smart home aggiunti all'app Google Home.

App Google Home

Puoi toccare le etichette On e Off accanto all'icona della lampadina mostrata nell'app Google Home.

Per ulteriori informazioni, consulta la sezione Controllare i dispositivi con l'app Google Home di Controllare i dispositivi per la smart home aggiunti all'app Google Home.

7. Complimenti!

Hai creato il tuo primo dispositivo Matter. Ottimo!

In questo codelab hai imparato a:

  • Installa un ambiente di sviluppo Matter.
  • Crea ed esegui un dispositivo virtuale Matter.
  • Commissione e controlla il dispositivo virtuale da Google Home.

Per saperne di più su Matter, consulta questi riferimenti: