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 SDK e dipendenze forniti in un'immagine Docker preconfigurata.

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

Obiettivi didattici

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

Che cosa ti serve

2. Configura l'ambiente

Utilizzeremo un container Docker configurato in precedenza su una macchina host Linux. Questo container include tutte le dipendenze necessarie per la creazione e l'esecuzione di un dispositivo virtuale Matter.

Controlla l'hardware

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

Inoltre, queste istruzioni presuppongono che la tua macchina Linux esegua il sistema di windowing X11. Se la tua macchina Linux esegue Wayland, assicurati che sia installato anche X.Org.

Configura Docker

  1. Installa Docker Engine (non utilizzare Docker Desktop).
  2. Esegui il pull dell'immagine Docker da Docker Hub. In una finestra del terminale, esegui:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    Questa operazione potrebbe richiedere alcuni minuti.
  3. Avvia il container Docker in esecuzione:
    user@host> xhost local:1000
user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Dopo aver avviato il container, dovresti vedere un output di diagnostica con un messaggio che conferma che la configurazione del container è corretta e, infine, il prompt della shell:

Environment looks good, you are ready to go!
$

Esaminiamo il comando docker e le opzioni che vi 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 fornita, estraendola dal registro Docker, se necessario.
  • --ipc=host consente a Docker di condividere lo spazio dei nomi delle comunicazioni 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 passare il traffico mDNS dall'host al container e per condividere la visualizzazione dell'host X11.
  • -e DISPLAY esporta $DISPLAY nell'host, fornendo l'accesso alla tua 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.

Facoltativamente, puoi eseguire una seconda istanza di sessione terminale:

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

Avvia e arresta il container Docker Matter

Ogni volta che esegui un comando docker run, creerai un nuovo container con l'immagine specificata. Se lo fai, i dati precedenti, salvati su un'istanza di container precedente, andranno persi. A volte questo è ciò che vuoi ottenere, perché ti permette di iniziare con una nuova installazione. Tuttavia, in alcuni casi preferisci salvare la configurazione dell'ambiente di lavoro tra una sessione e l'altra.

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

user@host> docker stop matter-container

Quando vuoi tornare a eseguirlo, 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 aggiuntive nel terminale 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

All'apertura del terminale, questo si troverà già nel repository clonato di Matter all'indirizzo ~/connectedhomeip. Non sono necessari passaggi di configurazione aggiuntivi di Matter.

Condividere file tra host e container

Per accedere ai file sulla macchina host dall'interno del container, puoi utilizzare un attacco di bind. Puoi anche scrivere file nella directory montata all'interno del container per un facile accesso da parte dell'host.

Esegui il container con l'argomento aggiuntivo --mount source=$(pwd),target=/workspace,type=bind per montare la directory di lavoro corrente nel container all'indirizzo /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 sulla directory montata devono essere gestite nell'host.

Ottieni l'ID gruppo dell'utente all'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 della 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 fornisce le autorizzazioni di lettura, scrittura ed esecuzione per il gruppo utente del container 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 di utenti del container per ereditare le autorizzazioni sui file creati dall'utente.

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 gestisci le integrazioni 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 commissionati nell'ecosistema Google Home in determinate condizioni. Per ulteriori informazioni, consulta Limitazioni sull'accoppiamento.

Crea un progetto sviluppatore

Per iniziare, vai alla console per gli sviluppatori di Google Home:

  1. Nella pagina Gestisci progetti, fai clic su Crea un progetto.
    Centro per sviluppatori Google Home
  2. Nella pagina Inizia, fai clic su Crea progetto.

  1. Inserisci un nome per il progetto univoco e fai clic su Crea nuovo progetto. Finestra di dialogo Crea nuovo progetto
  2. Fai clic su + Aggiungi integrazione per accedere alla schermata "Risorse Matter", che ti consente di consultare la documentazione sullo sviluppo della tecnologia e leggere alcuni strumenti.
  3. Quando vuoi continuare, fai clic su Avanti: Sviluppo per visualizzare la pagina Elenco di controllo Matter.
  4. Fai clic su Successivo: configurazione.
  5. Nella pagina Configurazione, inserisci il nome del prodotto.
  6. Fai clic su Seleziona il tipo di dispositivo e scegli il tipo di dispositivo dal menu a discesa (in questo caso, Light).
  7. In ID fornitore (VID), seleziona VID di test e scegli 0xFFF1 dal menu a discesa Test VID. In ID prodotto (PID), inserisci 0 x 8000 e fai clic su Salva e continua, poi fai clic su Salva nella pagina seguente.
    Configurazione di un progetto
  8. Ora vedrai un dispositivo Matter in integrazioni Matter. Integrazioni con Matter
  9. Riavvia il tuo hub per assicurarti che riceva la configurazione del progetto di integrazione Matter più recente. Se in seguito dovrai modificare il VID o il PID, dovrai riavviare il dispositivo dopo aver salvato il progetto affinché la modifica venga applicata. 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 il nostro focus su questo codelab è sugli Chef.

Chef è:

  • Un'app di esempio che fornisce un'interfaccia del terminale, offre funzionalità di wrapping disponibili anche nell'app examples/shell.
  • Uno script che abbraccia il principio della convenzione durante la 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

Lo chef ha 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 di illuminazione con controlli di accensione e spegnimento e livello.
  • -z: richiama lo strumento ZAP per generare i file di origine che implementano il tipo di dispositivo. In altre parole, in base alla tua scelta di illuminazione, ZAP creerà automaticamente codice da incorporare nella build che definisce la luce (il Modello dati) e come 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 di assistenza 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 hai un firewall in esecuzione sul computer, 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 il dispositivo in funzione. Ora trasformeremo la nostra attenzione sull'app Google Home in modo che possiamo mettere in servizio il tuo dispositivo su Google Home.

Interrompere il dispositivo

Puoi uscire dal programma premendo CTRL+C. Se l'app non viene chiusa, potresti dover utilizzare anche CTRL+\.

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

Se vuoi ripetere l'intero processo di commissione dall'inizio, dovrai eliminare i file eseguendo questo comando:

$ rm /tmp/chip*

5. Il controller del dispositivo virtuale

Il controller del dispositivo virtuale è un'app autonoma che offre una Graphic User Interface per controllare e visualizzare gli stati dei dispositivi virtuali Matter. Utilizza un client RPC per comunicare con i dispositivi Matter connessi al tuo ambiente di sviluppo.

Il controller del dispositivo virtuale

Il controller del dispositivo virtuale fornisce una rappresentazione visiva del dispositivo virtuale.

Puoi interagire con il dispositivo virtuale tramite la GUI (Graphic User Interface) del controller del dispositivo virtuale. Le modifiche apportate alla GUI interessano il modello dei dati sottostante. Attualmente, il controller del dispositivo virtuale supporta il tipo di dispositivo con luce dimmerabile.

Installare il controller del dispositivo virtuale

Il controller di dispositivi virtuali è preinstallato nel container Docker Ubuntu LTS 20.04.

Esegui il controller del dispositivo virtuale

Crea la seconda istanza della sessione terminale:

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

Avvia il controller del dispositivo virtuale fornendo la presa di rete che verrà utilizzata per comunicare con il dispositivo virtuale:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Se avvii il controller senza fornire argomenti, per impostazione predefinita verrà applicata l'opzione socket di rete tramite la porta localhost 33000. Quando il controller è in grado di connettersi al dispositivo virtuale, viene visualizzata una schermata che mostra lo stato del dispositivo:

Interfaccia utente grafica del dispositivo virtuale

L'app invia richieste al server RPC del dispositivo quando apporti modifiche all'app Virtual Controller e esegue il polling del server RPC una volta al secondo per recuperare lo stato.

L'app Virtual Device Controller può essere utilizzata anche per recuperare il codice QR nell'ambito della procedura di messa in servizio del dispositivo. Fai clic sull'icona del codice QR accanto all'immagine del dispositivo per visualizzare il codice QR per questo dispositivo:

Codice QR

Puoi usare questo codice QR per mettere in servizio il dispositivo.

6. Eseguire la messa in servizio del dispositivo

Nota: questo passaggio avrà esito positivo solo se hai già configurato il progetto nella console per gli sviluppatori di Google Home.

Nest Hub

Per mettere in servizio il dispositivo con il tessuto Matter è necessario un hub. Si tratta di un dispositivo Google Nest, ad esempio Nest Hub (2a generazione), che supporta Matter e che fungerà sia da router di confine per i dispositivi abilitati per Thread sia come percorso di evasione degli ordini locale per il routing degli intent della smart home.

Consulta questo elenco per vedere quali hub supportano Matter.

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

  • Il tuo hub è accoppiato con lo stesso Account Google che hai utilizzato per accedere su Google Home Console.
  • L'hub è collegato alla stessa rete Wi-Fi a cui è collegato il computer utilizzato per eseguire il dispositivo Matter virtuale.
  • Il tuo hub si trova nella stessa struttura che utilizzi nell'app Google Home. La "casa" nel grafico della home page di Google rappresenta la tua struttura.

Richiedi un codice QR

Il processo di commissione richiede le informazioni di onboarding di Matter tramite un codice QR. Puoi ottenere il codice QR per il tuo dispositivo virtuale dal controller del dispositivo virtuale.

Eseguire l'operazione con 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ì". Altrimenti, tocca Configura un altro dispositivo, quindi seleziona Dispositivo Matter dall'elenco dei dispositivi.
  7. Inquadra 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.

Dopo aver completato questi passaggi, il dispositivo virtuale Matter dovrebbe essere stato commissionato correttamente e dovrebbe essere visualizzato come nuova icona nell'app Google Home.

Lampadina accoppiata sull'app Google Home

Risoluzione dei problemi

Messa in servizio non riuscita con messaggio 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.

Messa in servizio non riuscita dopo un lungo periodo di tempo durante la scansione del dispositivo

7. Controlla il dispositivo

Dopo aver commissionato il tuo dispositivo Matter e visualizzato nell'app Google Home come lampadina, puoi testare il controllo del dispositivo usando diversi metodi:

  • Con l'Assistente Google.
  • Con l'app Google Home.
  • Utilizzare la GUI del dispositivo virtuale.

Assistente Google

Usa l'Assistente Google sul telefono o sull'hub per attivare o disattivare lo stato del dispositivo dai comandi vocali, ad esempio dire "Hey Google, attiva/disattiva le luci".

Per altri esempi di comandi, consulta la sezione Controllare i dispositivi per la smart home con i comandi vocali in 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 a forma di lampadina visualizzata nell'app Google Home.

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

GUI del dispositivo virtuale

Puoi interagire con la GUI del dispositivo virtuale per cambiare lo stato del dispositivo. Sia che controlli il dispositivo virtuale con il controller di dispositivi virtuali, l'app Google Home sul telefono o con l'hub, tutte queste interfacce riflettono lo stato attuale del dispositivo virtuale.

8. Complimenti.

Hai creato il tuo primo dispositivo Matter. Ottimo!

In questo codelab hai imparato a:

  • Installa un ambiente di sviluppo Matter utilizzando un'immagine Docker preconfezionata.
  • Crea ed esegui un dispositivo virtuale Matter.
  • Esegui le commissioni e controlla il tuo dispositivo virtuale da Google Home.

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