Crea un dispositivo virtuale Matter

1. Introduzione

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

Per scoprire di più su Matter, visita il Centro per gli sviluppatori di Google Home o il sito web di Connectivity Standards Alliance.

Obiettivi didattici

  • Come configurare un ambiente di build di Matter
  • Come creare un dispositivo Matter virtuale che viene eseguito sul computer
  • Come configurare e controllare il dispositivo Matter virtuale con Google Home

Che cosa ti serve

  • Un hub, ovvero qualsiasi dispositivo Google Nest che supporta Matter, ad esempio Nest Hub (2ª generazione).
  • Un computer Linux che esegue il sistema di finestre X11.
  • Docker.
  • Git.
  • Conoscenza di base di Linux.
    • Tieni presente che la shell presupposta 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 di Docker. Puoi installare e creare Matter manualmente su macOS.

Inoltre, queste istruzioni presuppongono che il computer Linux esegua il sistema di finestre X11. Se il computer Linux esegue Wayland, assicurati che X.Org sia installato anche.

Configura l'ambiente di sviluppo

  1. Installa Docker Engine (non utilizzare Docker Desktop).
  2. Clona l'SDK Matter e prendi nota del commit che stiamo utilizzando 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 che corrisponda alla nostra versione dell'SDK come segue:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Se utilizzi lo stesso commit, dovresti visualizzare ghcr.io/project-chip/chip-build:66Per prima cosa, inoltra le porte xhost in modo da poter utilizzare le applicazioni UI in un secondo momento:
    xhost local:1000
    Quindi, avvia il container con le risorse appropriate inoltrate dall'host (il checkout dell'SDK, le risorse di rete e di visualizzazione/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 gli abbiamo passato:

  • xhost local:1000 consente al sistema X Window di ricevere connessioni dall'host locale sulla porta 1000, consentendo così l'utilizzo di un'interfaccia utente grafica.
  • docker run … image esegue l'immagine specificata, estraendola dal registro Docker, se necessario.
  • --ipc=host consente a Docker di condividere lo spazio dei nomi di comunicazione tra processi con la macchina host.
  • --net=host consente a Docker di utilizzare lo stack di rete dell'host all'interno del container, necessario per trasmettere il traffico mDNS dall'host al container e per condividere la visualizzazione X11 dell'host.
  • -e DISPLAY esporta $DISPLAY all'host, fornendo l'accesso all'interfaccia grafica del sistema. È 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 estratto in precedenza nel container.
  • --workdir imposta la directory di lavoro all'avvio sulla directory dell'SDK montata.

Se vuoi, puoi eseguire una seconda istanza della 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, crei un nuovo container con l'immagine specificata. In questo modo, i vecchi dati salvati in un'istanza di container precedente andranno persi. A volte è quello che vuoi, perché ti consente di iniziare con una nuova installazione. Tuttavia, a volte preferisci salvare la configurazione del lavoro e dell'ambiente tra le sessioni.

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

user@host> docker stop matter-container

Quando è tutto pronto per l'esecuzione, 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 sessioni di terminale aggiuntive nel 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

Inizializza l'SDK

Inizializza l'SDK Matter. Il completamento dell'operazione richiede diversi minuti.

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

L'SDK Matter è stato inizializzato. Per inizializzare di nuovo l'ambiente rapidamente 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 sulla macchina host dall'interno del container utilizzando un montaggio di binding. Puoi anche scrivere file nella directory montata dall'interno del container per accedervi dall'host.

In generale, utilizza i montaggi di binding 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 del container nella directory montata devono essere gestite nell'host.

Ottieni l'ID gruppo dell'utente del container dall'interno del container.

$ 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 nella directory montata sul gruppo dell'utente del container.

user@host> sudo chgrp -R 1000 .

Concedi le autorizzazioni desiderate nella directory al gruppo. Questo esempio concede 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. Ricorda di aggiornare le autorizzazioni dei nuovi file creati nell'host in base alle esigenze.

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

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

3. Google Home Developer Console

La Google Home Developer Console è l'applicazione web in cui gestisci le integrazioni di Matter con Google Home.

Qualsiasi dispositivo Matter che ha superato la certificazione Matter di Connectivity Standards Alliance (Alliance) funziona nell'ecosistema Google Home. I dispositivi in fase di sviluppo che non sono stati certificati possono essere configurati nell'ecosistema Google Home in determinate condizioni. Per ulteriori informazioni, consulta la sezione Restrizioni di accoppiamento.

Crea un progetto per sviluppatori

Inizia accedendo a Google Home Developer Console:

  1. Fai clic su Crea progetto.
  2. Inserisci un nome di progetto univoco e fai clic su Crea progetto. Finestra di dialogo Crea nuovo progetto
  3. Fai clic su + Aggiungi integrazione per accedere alla schermata Risorse Matter , dove puoi visualizzare la documentazione di sviluppo di Matter e leggere alcuni strumenti.
  4. Quando è tutto pronto per continuare, fai clic su Avanti: sviluppa per visualizzare la pagina Elenco di controllo di Matter.
  5. Fai clic su Avanti: 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 VID di test e seleziona 0xFFF1 dal menu a discesa VID di test. In ID prodotto (PID), inserisci 0x8000 e fai clic su Salva e continua, quindi fai clic su Salva nella pagina successiva. Utilizza questi valori VID/PID esatti, perché i passaggi successivi del codelab dipendono da essi.
    Configurare un progetto
  9. Ora vedrai l'integrazione in Integrazioni Matter.
  10. Riavvia l'hub per assicurarti che riceva la configurazione del progetto di integrazione di Matter più recente. Se devi modificare il VID o il PID in un secondo momento, dovrai anche riavviare dopo aver salvato il progetto affinché la modifica diventi effettiva. Per istruzioni dettagliate sul riavvio, consulta l'articolo Riavviare i dispositivi Google Nest o Google Wifi.

4. Crea un dispositivo

Tutti gli esempi in Matter si trovano nella cartella examples nel 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, che include anche le funzionalità dell'app examples/shell.
  • Uno script che adotta il principio di convenzione rispetto alla configurazione per incapsulare diverse attività comuni necessarie per lo sviluppo di un dispositivo compatibile con Matter.

Vai alla cartella dell'esempio di Chef ed esegui la prima build di 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 qui sono:

  • -d: definisce il tipo di dispositivo da utilizzare. In questo caso, stiamo creando un'app di illuminazione con controlli di accensione/spegnimento e di livello.
  • -z: richiama lo strumento ZAP per generare i file di origine che implementano il tipo di dispositivo. In base alla tua scelta di illuminazione, ZAP creerà automaticamente il codice da incorporare nella build che definisce la luce (il modello di dati) e il modo in cui interagisce con 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 di dati.
  • -t linux: piattaforma di destinazione. Le piattaforme supportate 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 computer è in esecuzione un firewall, disattivalo 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 il dispositivo in esecuzione. Ora ci concentreremo sull'app Google Home per configurare il dispositivo in Google Home.

Arresta il dispositivo

Se devi arrestare il dispositivo, puoi uscire dal programma con CTRL+C. Se l'app non si chiude, potrebbe essere necessario utilizzare anche CTRL+\.

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

Se vuoi ripetere l'intera procedura di configurazione dall'inizio, devi eliminare questi file eseguendo il seguente comando:

$ rm /tmp/chip*

5. Configura il dispositivo

Nota: questo passaggio verrà completato solo se hai già configurato il progetto in Google Home Developer Console.

Nest Hub

È necessario un hub per configurare il dispositivo nell'infrastruttura Matter. Si tratta di un dispositivo Google Nest, ad esempio Nest Hub (2ª generazione), che supporta Matter e che fungerà sia da router di confine per i dispositivi compatibili con Thread sia da percorso di fulfillment locale per il routing degli intent Smart Home.

Consulta questo elenco per vedere quali hub supportano Matter.

Prima di iniziare la procedura di configurazione, controlla che:

  • L'hub sia accoppiato allo stesso Account Google che hai utilizzato per accedere a Google Home Console.
  • L'hub si trova sulla stessa rete Wi-Fi del computer che utilizzi per eseguire il dispositivo Matter virtuale.
  • L'hub si trova nella stessa struttura che utilizzi nell'app Google Home. La "casa" nel grafico di Google Home rappresenta la tua struttura.

Mostra codice QR

La procedura di configurazione richiede 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 pertinente alla configurazione.

Esegui l'operazione di configurazione

  1. Apri l'app Google Home.
  2. Tocca + 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 esegue la scansione del dispositivo. Se viene visualizzato il messaggio "È stato trovato un dispositivo Matter...", tocca "Sì". In caso contrario, tocca Configura un altro dispositivo, quindi seleziona Dispositivo Matter dall'elenco dei dispositivi.
  7. Inquadra con la fotocamera il codice QR del dispositivo o il codice QR generato dal sito web.
  8. Continua la procedura di accoppiamento come indicato nel flusso dell'app Google Home.

Una volta completati questi passaggi, il dispositivo virtuale Matter dovrebbe essere configurato correttamente e dovrebbe essere visualizzato come una nuova icona nell'app Google Home.

Lampadina accoppiata nell'app Google Home

Risoluzione dei problemi

La configurazione non riesce e vengono visualizzati i messaggi di errore "Problema di connettività" o "Impossibile contattare Google"

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

La configurazione non riesce dopo che "Scansione del dispositivo" è stata eseguita per un lungo periodo

6. Controlla il dispositivo

Una volta configurato correttamente il dispositivo compatibile con Matter e visualizzato nell'app Google Home come una lampadina, puoi testare il controllo del dispositivo con diversi metodi:

  • Utilizzando l'Assistente Google.
  • Utilizzando l'app Google Home.

Assistente Google

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

Per altri esempi di comandi, consulta la sezione Controllare i dispositivi per la smart home tramite comandi vocali dell'articolo 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 dell'articolo Controllare i dispositivi per la smart home aggiunti all'app Google Home.

7. Complimenti!

Hai creato correttamente il tuo primo dispositivo Matter. Fantastico!

In questo codelab hai imparato a:

  • Installare un ambiente di sviluppo Matter.
  • Creare ed eseguire un dispositivo virtuale Matter.
  • Configurare e controllare il dispositivo virtuale da Google Home.

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