Creare 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 saperne di più su Matter, visita il Centro per gli sviluppatori Google Home o il sito web di Connectivity Standards Alliance.

Obiettivi didattici

  • Come configurare un ambiente di build Matter
  • Come creare un dispositivo Matter virtuale che viene eseguito sul computer
  • Come eseguire il provisioning 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ª gen.).
  • Un computer Linux che esegue il sistema di finestre X11.
  • Docker.
  • Git.
  • Conoscenza di base di Linux.
    • Tieni presente che la shell presunta per tutti i comandi di questo codelab è BASH.

2. Configura l'ambiente

Controllare l'hardware

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

Inoltre, queste istruzioni presuppongono che la tua macchina Linux esegua il sistema di finestre X11. Se la tua macchina Linux esegue 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 annota 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 in modo che corrisponda alla nostra versione dell'SDK in questo modo:
    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:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Successivamente, avvia il container con le risorse appropriate inoltrate dall'host (il nostro checkout 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

Analizziamo il comando Docker e le opzioni che gli abbiamo passato:

  • xhost local:1000 consente a X Window System 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 interprocesso con la macchina host.
  • --net=host consente a Docker di utilizzare lo stack di rete dell'host all'interno del container, il che è necessario per trasferire il traffico mDNS dall'host al container e per condividere il display X11 dell'host.
  • -e DISPLAY esporta $DISPLAY all'host, fornendo l'accesso all'interfaccia grafica del sistema. Questo passaggio è 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 contenitore.
  • --workdir imposta la directory di lavoro all'avvio sulla directory SDK montata.

Se vuoi, puoi eseguire una seconda istanza della sessione del terminale:

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

Arrestare e avviare il container Docker Matter

Ogni volta che esegui un comando docker run, crei un nuovo container con l'immagine specificata. In questo modo, i tuoi vecchi dati, salvati in un'istanza del contenitore precedente, andranno persi. A volte è proprio quello che vuoi, perché ti consente di iniziare con una nuova installazione. Tuttavia, a volte preferisci salvare il lavoro e la configurazione dell'ambiente tra le sessioni.

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

user@host> docker stop matter-container

Quando è tutto pronto per eseguire di nuovo il comando, 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 è ora inizializzato. Per reinizializzare rapidamente l'ambiente in futuro, esegui:

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

Condividere file tra l'host e il container

In precedenza, abbiamo eseguito l'accesso ai file sulla macchina host dall'interno del contenitore utilizzando un montaggio bind. Puoi anche scrivere file nella directory montata dall'interno del container per accedervi dall'host.

In generale, utilizza i montaggi bind eseguendo il container con l'argomento aggiuntivo --mount source=$(pwd),target=/workspace,type=bind per montare la directory di lavoro attuale 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 contenitore dall'interno del 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 nella directory montata sul gruppo dell'utente del container.

user@host> sudo chgrp -R 1000 .

Concedi al gruppo le autorizzazioni che preferisci nella directory. Questo esempio concede al gruppo dell'utente del contenitore 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 contenitore per ereditare le autorizzazioni sui file creati dall'utente contenitore.

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

3. Google Home Developer Console

La console per gli sviluppatori di Google Home è l'applicazione web in cui gestisci le integrazioni Matter con Google Home.

Qualsiasi dispositivo Matter che ha superato la certificazione Matter della Connectivity Standards Alliance (Alliance) funziona nell'ecosistema Google Home. I dispositivi in fase di sviluppo che non sono stati certificati possono essere commissionati nell'ecosistema Google Home a determinate condizioni. Per saperne di più, consulta la sezione Limitazioni dell'accoppiamento.

Creare un progetto sviluppatore

Per iniziare, vai alla 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, che ti reindirizza alla schermata Risorse Matter, dove puoi visualizzare la documentazione di sviluppo di Matter e leggere informazioni su alcuni strumenti.
  4. Quando è tutto pronto per continuare, fai clic su Avanti: sviluppa, che mostra la pagina Elenco di controllo della pratica.
  5. Fai clic su Avanti: configurazione.
  6. Nella pagina Configurazione, inserisci il Nome 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 e continua, quindi fai clic su Salva nella pagina successiva. Utilizza questi valori VID/PID esatti, poiché i passaggi successivi del codelab dipendono da questi.
    Configurare un progetto
  9. Ora vedrai l'integrazione nella sezione Integrazioni di Matter.
  10. Riavvia l'hub per assicurarti che riceva la configurazione del progetto di integrazione Matter più recente. Se in un secondo momento devi modificare il VID o il PID, dovrai anche riavviare il dispositivo dopo aver salvato il progetto affinché la modifica venga applicata. Consulta l'articolo Riavviare i dispositivi Google Nest o Google Wifi per istruzioni dettagliate sul riavvio.

4. Crea un dispositivo

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

Chef è entrambe le cose:

  • Un'app di esempio che fornisce un'interfaccia terminale, con funzionalità di wrapping presenti anche nell'app examples/shell.
  • Uno script che adotta il principio della convenzione rispetto alla configurazione per incapsulare diverse attività comuni necessarie per lo sviluppo di un dispositivo compatibile con Matter.

Vai alla cartella di esempio di Chef ed esegui la prima build di Matter:

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

Chef offre alcune opzioni che possono essere visualizzate eseguendo chef.py -h. Le opzioni che utilizziamo qui sono:

  • -d: definisce il tipo di dispositivo da utilizzare. In questo caso, stiamo creando un'app per l'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. ovvero, in base all'illuminazione scelta, ZAP creerà automaticamente il codice da incorporare nella build che definisce la luce (il modello di 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 virtuale Matter 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 funzione. Ora ci concentreremo sull'app Google Home per poter eseguire il provisioning del 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 per il dispositivo virtuale sono archiviate nella directory /tmp/, in 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. Configurare il dispositivo

Nota: questo passaggio andrà a buon fine solo se hai già configurato il progetto nella console Google Home Developer.

Nest Hub

Per eseguire il provisioning del dispositivo nell'infrastruttura Matter è necessario un hub. Si tratta di un dispositivo Google Nest, ad esempio Nest Hub (2ª gen.), che supporta Matter e che fungerà sia da router di confine per i dispositivi compatibili con Thread sia da percorso di completamento locale per il routing degli intent di smart home.

Consulta questo elenco per scoprire quali hub supportano Matter.

Prima di iniziare la procedura di configurazione, controlla che:

  • Il tuo hub è associato allo stesso Account Google che hai utilizzato per accedere alla console Google Home.
  • L'hub è connesso alla 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 Google Home rappresenta la tua struttura.

Ottenere un codice QR

La procedura di commissioning 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 pertinente al provisioning.

Esegui l'operazione di commissione

  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 cerca il tuo dispositivo. Se viene visualizzato il messaggio "Dispositivo Matter trovato…", 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 quello 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 stato commissionato correttamente e dovrebbe essere visualizzato come nuova icona nell'app Google Home.

Lampadina accoppiata nell'app Google Home

Risoluzione dei problemi

Il commissioning 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 nella console Google Home e di non avere altri progetti che utilizzano la stessa combinazione VID/PID.

Il provisioning non riesce dopo la fase "Scansione del dispositivo" per un lungo periodo

6. Controllare il dispositivo

Una volta che il dispositivo compatibile con Matter è stato commissionato correttamente e viene visualizzato nell'app Google Home come lampadina, puoi testare il controllo del dispositivo con diversi metodi:

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

Assistente Google

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

Per altri esempi di comandi, consulta la sezione Controllare i dispositivi per la smart home con i 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:

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

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