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

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 da eseguire sul computer
  • Come mettere in servizio 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 contenitore 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 supportati da questa installazione Docker. Puoi installare e creare manualmente Matter su macOS.

Inoltre, queste istruzioni presuppongono che sul computer Linux sia in esecuzione il sistema a finestre X11. Se sul tuo computer Linux è installato 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
    
    Il completamento dell'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 seguito da un messaggio che conferma che la configurazione del container è corretta e, infine, il prompt della shell del container:

Environment looks good, you are ready to go!
$

Comprendiamo il comando docker e le opzioni che gli abbiamo fornito:

  • xhost local:1000 consente a X Window System di ricevere connessioni dall'host locale sulla porta 1000, consentendo di utilizzare 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 passare il traffico mDNS dall'host al container e per condividere il display dell'host X11.
  • -e DISPLAY esporta $DISPLAY nell'host, dando accesso all'interfaccia grafica di sistema. Questa operazione è necessaria per eseguire lo strumento ZAP durante la modifica dei cluster Matter.
  • -it esegue Docker con un terminale interattivo (tty), anziché come processo in background.

Se vuoi, 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, devi creare 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 che avvenga, perché ti consente di iniziare con una nuova installazione. Tuttavia, in alcuni casi è preferibile salvare la configurazione di lavoro e dell'ambiente 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 è 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 altre sessioni di terminale nel 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

All'apertura, il terminale si troverà già nel repository clonato di Matter alle ore ~/connectedhomeip. Non sono necessari ulteriori passaggi di configurazione di Matter.

Condividere file tra l'host e il container

Per accedere ai file sulla macchina host dall'interno del container, puoi utilizzare un montaggio di associazione. Puoi anche scrivere file nella directory montata dall'interno del container per accedervi facilmente dall'host.

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

Recupera l'ID gruppo dell'utente 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 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, se necessario.

Puoi aggiungere l'utente host al gruppo dell'utente del contenitore per ereditare le autorizzazioni per i 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 con cui puoi gestire le integrazioni di Matter con Google Home.

Tutti i dispositivi Matter che hanno superato la certificazione Matter (Alliance) della Connectivity Standards Alliance funzionano 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 ulteriori informazioni, consulta la sezione Limitazioni relative all'accoppiamento.

Creare un progetto sviluppatore

Inizia accedendo 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. Si aprirà la schermata Risorse Matter, dove potrai visualizzare la documentazione di sviluppo di Matter e leggere informazioni su alcuni strumenti.
  4. Quando tutto è pronto per continuare, fai clic su Avanti: sviluppa per visualizzare 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 il 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, quindi 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 seguente. Utilizza questi valori VID/PID esatti, i cui passaggi successivi del codelab dipendono da questi.
    Configurazione di un progetto
  9. A questo punto, l'integrazione viene visualizzata 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 dovrai modificare il VID o il PID, dovrai riavviare anche dopo aver salvato il progetto affinché la modifica abbia effetto. 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 codelab è incentrato su Chef.

Chef è entrambi:

  • Un'app di esempio che fornisce un'interfaccia di terminale con funzionalità di wrapping disponibili anche nell'app examples/shell.
  • Uno script che abbraccia il principio della convenzione sulla configurazione per racchiudere 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 per l'illuminazione con controlli on/off e di 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 un codice da incorporare nella build che definisce 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 (ad esempio 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 contenitore 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 passeremo all'app Google Home in modo da poter effettuare la messa in servizio del tuo dispositivo su Google Home.

Arresta il dispositivo

Se devi arrestare il dispositivo, puoi uscire dal programma con 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 desideri ripetere l'intero processo di messa in servizio dall'inizio, devi eliminare questi file eseguendo il seguente comando:

$ rm /tmp/chip*

5. Il controller per dispositivi virtuali

Virtual Device Controller è un'app autonoma che fornisce una Graphic User Interface per controllare e visualizzare gli stati dei dispositivi Matter virtuali. Utilizza un client RPC per comunicare con i dispositivi Matter connessi all'ambiente di sviluppo.

Il controller per dispositivi virtuali

Il controller per dispositivi virtuali fornisce una rappresentazione visiva del tuo dispositivo virtuale.

Puoi interagire con il dispositivo virtuale tramite l'interfaccia utente grafica (GUI) del controller per dispositivi virtuali. Le modifiche apportate alla GUI influiscono sul modello dei dati sottostante. Consulta la sezione Dispositivi supportati per l'elenco completo dei tipi di dispositivi virtuali Matter supportati.

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 il socket di rete che verrà utilizzato 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à utilizzata 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 del dispositivo virtuale

L'app invia le richieste al server RPC del dispositivo quando apporti modifiche all'app del controller virtuale ed esegue il polling del server RPC una volta al secondo per recuperare lo stato.

L'app Controller per dispositivi virtuali può essere utilizzata anche per recuperare il codice QR nell'ambito del flusso di messa in servizio del dispositivo. Fai clic sull'icona del codice QR accanto all'immagine del dispositivo per visualizzare il codice QR. Utilizza questo codice QR per la messa in servizio del dispositivo.

6. Commissione il dispositivo

Nota: questo passaggio avrà esito positivo solo se hai già configurato il progetto nella Developer Console di Google Home.

Nest Hub

È necessario un hub per mettere in servizio il dispositivo sull'infrastruttura Matter. 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 compatibili con Thread, sia da percorso di distribuzione locale per il routing degli intent della smart home.

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

Prima di iniziare la procedura di messa in servizio, verifica quanto segue:

  • L'hub sia accoppiato con lo stesso Account Google utilizzato per accedere a Google Home Console.
  • L'hub si trovi sulla stessa rete Wi-Fi del computer che utilizzi per eseguire il tuo dispositivo Virtual Matter.
  • L'hub ha la stessa struttura che utilizzi nell'app Google Home (la "casa" in Google Home Graph rappresenta la tua struttura).

Richiedi un codice QR

Per completare la procedura di onboarding è necessario che le informazioni di onboarding di Matter siano fornite tramite un codice QR. Puoi ottenere il codice QR del tuo dispositivo virtuale dal controller del dispositivo virtuale.

Esegui 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 visualizzi 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 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 una nuova icona nell'app Google Home.

Lampadina accoppiata nell'app Google Home

Risoluzione dei problemi

La messa in servizio non riesce e viene visualizzato il messaggio di errore "Problema di connettività" o "Impossibile contattare Google"

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

La messa in servizio non riesce dopo l'"analisi del dispositivo" per un lungo periodo di tempo

7. Controlla il dispositivo

Dopo aver commissionato correttamente il dispositivo compatibile con Matter e visualizzato nell'app Google Home come lampadina, puoi testare il controllo del dispositivo in diversi modi:

  • Con l'Assistente Google.
  • Tramite l'app Google Home.
  • Utilizzo della GUI del dispositivo virtuale.

Assistente Google

Usa l'Assistente Google sul telefono o sull'hub per attivare/disattivare lo stato del dispositivo dai comandi vocali, ad esempio per 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 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 saperne di più, 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.

GUI dispositivo virtuale

Puoi interagire con la GUI del dispositivo virtuale per cambiare lo stato del dispositivo. Sia che tu controlli il dispositivo virtuale con il controller per dispositivi virtuali, 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 preconfigurata.
  • Crea ed esegui un dispositivo virtuale Matter.
  • Commissione e controlla il tuo dispositivo virtuale con Google Home.

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