Creare un dispositivo virtuale Matter

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

1. Introduzione

Matter è un protocollo per la connettività che offre entusiasmanti opportunità per lo sviluppo di smart device. In questo codelab, creerai il tuo primo dispositivo Matter, utilizzando SDK e dipendenze disponibili in un'immagine Docker preconfigurata.

Per saperne di più su Matter, visita il Google Home Developer Center o il sito web 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 mettere in servizio e controllare il dispositivo Matter virtuale con Google Home

Che cosa ti serve

  • Un hub, ovvero qualsiasi dispositivo Google Nest che supporti Matter, ad esempio Nest Hub (2a generazione). Puoi acquistare un hub sul Google Store o presso il tuo rivenditore preferito.
  • Una macchina Linux che esegue il sistema di windowing X11.
  • Docker,
  • Conoscenza di base di Linux.

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 il sistema Linux Windows 11 utilizzi per il tuo sistema Linux. Se sulla tua macchina Linux viene eseguito 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 visualizzare un output diagnostico seguito da un messaggio che conferma la configurazione corretta del container e, infine, dal prompt della shell del container:

Environment looks good, you are ready to go!
$

Analizziamo il comando docker e le opzioni che abbiamo trasmesso:

  • xhost local:1000 consente a X Window System di ricevere connessioni dall'host locale sulla porta 1000, permettendo quindi di utilizzare 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 del terminale:

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

Avvia e arresta il container Matter Docker

Ogni volta che esegui un comando docker run, devi creare un nuovo container con l'immagine specificata. In questo caso, i dati precedenti, salvati su un'istanza di container precedente, andranno persi. A volte questo è ciò che vuoi che accada, perché ti permette di iniziare con una nuova installazione. Tuttavia, in alcune situazioni preferiresti salvare la configurazione dell'ambiente di lavoro e dell'ambiente tra le sessioni.

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

user@host> docker stop matter-container

Quando vuoi essere di nuovo eseguito, 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 tuo container con:

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

In alternativa, avvia una sessione root utilizzando:

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

Configurazione iniziale di Matter

Quando il terminale si aprirà, si troverà già nel repository Matter clonato in ~/connectedhomeip. Non sono necessari passaggi di configurazione aggiuntivi di Matter.

Condividi file tra l'host e il container

Per accedere ai file sulla macchina host dall'interno del container, puoi utilizzare un supporto di associazione. Puoi anche scrivere i file nella directory montata dall'interno del container per un facile accesso dall'host.

Esegui 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 sulla directory montata devono essere gestite nell'host.

Recupera 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 al gruppo le autorizzazioni desiderate nella directory. Questo esempio fornisce al gruppo dell'utente dei 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, se necessario.

Puoi aggiungere l'utente host al gruppo dell'utente del 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. Google Home Console

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

Qualsiasi dispositivo Matter che ha superato la certificazione CSA Matter funziona nell'ecosistema Google Home.

Creare un progetto sviluppatore

Per iniziare, vai alla Google Home Developer Console: inizia dalla Google Home Developer Console:

  1. Nella schermata "Gestisci progetti", fai clic su Crea un progetto.
    Centro sviluppatori Google Home
  2. Nella schermata iniziale, fai clic su Crea progetto.

  1. Inserisci un nome univoco per il progetto e fai clic su Create new project (Crea nuovo progetto). Finestra di dialogo Crea nuovo progetto
  2. Fai clic su + Aggiungi l'integrazione per Matter per passare alla schermata "Risorse Matter", in cui puoi visualizzare la documentazione di sviluppo e scoprire alcuni strumenti.
  3. Quando è tutto pronto, fai clic su Avanti: sviluppa, che mostra la schermata "Elenco di controllo della pratica".
  4. Fai clic su Successivo: configurazione
  5. Nella schermata "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 Prova VID e scegli 0xFFF1 dal menu a discesa Prova 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 l'hub per assicurarti che riceva la configurazione del progetto di integrazione Matter più recente. Se in seguito dovrai modificare il VID o il PID, dopo aver salvato il progetto, dovrai riavviare anche il progetto perché la modifica venga applicata.

4. Crea un dispositivo

Tutti gli esempi in Matter si trovano nella cartella examples nel repository GitHub. Ci sono diversi esempi disponibili, ma ci concentriamo su questo codelab su Chef.

Chef è entrambi:

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

Passa 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 il chef.py -h. Le opzioni che usiamo qui 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 base alla scelta dell'illuminazione, ZAP crea automaticamente il codice da incorporare nella build che definisce la luce (il modello dei dati) e la sua interazione con altri dispositivi (il modello dell'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 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 nel 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 il dispositivo in funzione. Ora dedicheremo l'attenzione all'app Google Home per poter commissionire il tuo dispositivo su Google Home.

Arresta il dispositivo

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

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

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

$ 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 tuoi dispositivi Matter virtuali. 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 tuo dispositivo virtuale.

Puoi interagire con il dispositivo virtuale mediante la Graphic User Interface (GUI) di Virtual Device Controller. Le modifiche alla GUI influiscono sul modello dei dati sottostante. Attualmente, il controller del dispositivo virtuale supporta il tipo di dispositivo Dimmerabile.

Installa il controller del dispositivo virtuale

Il controller del dispositivo virtuale è preinstallato sul container Docker Ubuntu LTS 20.04.

Esegui il controller del dispositivo virtuale

Crea la seconda istanza di sessione del 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, verrà utilizzata per impostazione predefinita l'opzione socket di rete utilizzando la porta localhost 33000. Quando il controller riesce a connettersi al dispositivo virtuale, viene visualizzata una schermata che mostra lo stato del dispositivo:

Interfaccia utente grafica di un dispositivo virtuale

L'app invia richieste al server RPC del dispositivo quando apporti modifiche all'app Virtual Controller e invia un polling al 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 utilizzare questo codice QR per mettere in servizio il dispositivo.

6. Metti in servizio il dispositivo

Nota: questo passaggio avrà esito positivo solo se hai già configurato il tuo progetto nella Google Play Console.

Nest Hub

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

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 alla Google Home Console.
  • L'hub è sulla stessa rete Wi-Fi del computer che utilizzi per eseguire il dispositivo Matter virtuale.
  • Il tuo hub si trova nella stessa struttura che usi 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 per Matter fornite tramite un codice QR. Puoi ottenere il codice QR per il dispositivo virtuale dal Virtual Device Controller.

Eseguire 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 alternativa, tocca Configura un altro dispositivo, quindi seleziona Matter device (Dispositivo Matter) dall'elenco.
  7. Inquadra il codice QR del dispositivo con 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 commissionato correttamente e dovrebbe apparire come nuova icona nell'app Google Home.

Lampadina accoppiata nell'app Google Home

Risoluzione dei problemi

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

Messa in servizio non riuscita dopo "Scansione del dispositivo" per un lungo periodo

7. Controlla il dispositivo

Dopo aver commissionato il dispositivo compatibile con Matter e visualizzato nell'app Google Home come lampadina, puoi testarne il controllo con diversi metodi:

  • Con l'Assistente Google.
  • Con l'app Google Home.
  • Tramite la GUI dei dispositivi virtuali.

Assistente Google

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

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 per altri esempi di comandi.

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 di 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 del dispositivo virtuale, l'app Google Home sul telefono o con l'hub, tutte queste interfacce rifletteranno 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.
  • Commissiona e controlla il tuo dispositivo virtuale da Google Home.

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