A partire dal 2026, tutti i test e l'integrazione di Matter richiederanno l'Interop Test dell'alleanza. Per ulteriori informazioni, consulta la pagina di transizione del laboratorio di test di interoperabilità di Alliance.

Crea un dispositivo 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. Per scoprire di più su Matter, visita il Centro per gli sviluppatori Google Home: Matter o il sito web di Connectivity Standards Alliance.

Obiettivi didattici

Come integrare un dispositivo fisico con Matter.
Come configurare e controllare il tuo dispositivo Matter con Google Home.

Che cosa ti serve

Un hub, ovvero qualsiasi dispositivo Google Nest che supporta Matter, ad esempio Nest Hub (2ª gen.).
Una scheda di valutazione Matter ESP32-DevkitC o ESP32 M5STACK di Espressif Systems.
Un PC con Linux.
Conoscenza di base di Linux.

2. Configura l'ambiente

Identificare il dispositivo seriale

Il primo passaggio per configurare l'ambiente di sviluppo è determinare a quale porta seriale è connesso il dispositivo. Queste informazioni ti consentiranno di programmare e interagire con la tua scheda di sviluppo.

Collega la scheda di sviluppo al computer utilizzando un cavo USB.
Cerca nel file system /dev per trovare il dispositivo della scheda di sviluppo. Puoi restringere la ricerca specificando il prefisso del dispositivo della scheda di sviluppo. ESP32 di Espressif utilizza /dev/ttyUSBx:
```
user@host $ ls /dev/ttyUSB*
/dev/ttyUSB0
```

Configurare l'hub

Configura l'hub utilizzando lo stesso Account Google che intendi utilizzare per questo codelab.

Configurazione dell'ambiente di sviluppo

Prerequisiti

Queste istruzioni sono state testate su Debian Linux e dovrebbero funzionare sulla maggior parte delle distribuzioni Linux basate su Debian, inclusa Ubuntu. Se utilizzi una distribuzione Linux diversa, la procedura di configurazione delle dipendenze potrebbe variare rispetto a quella descritta di seguito.

Installa le dipendenze

Esegui il seguente comando per installare i file binari del pacchetto Linux richiesti che potrebbero non essere ancora installati:

$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev screen

Configura l'SDK

Per continuare questo codelab, ti servirà l'SDK Espressif (Espressif IoT Development Framework o "ESP-IDF").

Crea una directory per contenere ESP-IDF:
```
$ mkdir ~/esp-idf_tools
```

Clona ESP-IDF da GitHub in questa directory:

$ cd ~/esp-idf_tools
$ git clone -b v4.4.3 --recursive https://github.com/espressif/esp-idf.git

Completa l'installazione della toolchain:
```
$ cd ./esp-idf
$ ./install.sh
$ cd ~/
```

Configura l'SDK Matter

Clona il repository open source di Matter:

$ git clone https://github.com/project-chip/connectedhomeip.git
$ cd ./connectedhomeip
$ git fetch origin v1.0-branch
$ git checkout FETCH_HEAD

Recupera i sottomoduli del repository:

$ ./scripts/checkout_submodules.py --shallow --platform esp32

Esegui il bootstrap dell'ambiente di sviluppo Matter:
```
$ source ./scripts/bootstrap.sh
```

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:

Fai clic su Crea progetto.
Inserisci un nome univoco per il progetto e fai clic su Crea progetto.
Importante: quando scegli un nome per il progetto, è buona norma renderlo significativo e distinto. Valuta la possibilità di includere il nome della tua azienda e il tipo di dispositivo o l'Azione che implementerà. Ad esempio, "encom-smartlight-switch" utilizza entrambi questi elementi.
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.
Quando è tutto pronto per continuare, fai clic su Avanti: sviluppa, che mostra la pagina Elenco di controllo della pratica.
Fai clic su Avanti: configurazione.
Nella pagina Configurazione, inserisci il Nome prodotto.
Fai clic su Seleziona tipo di dispositivo e seleziona il tipo di dispositivo dal menu a discesa (in questo caso, Light).
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.
Nota: i VID 0xFFF1, 0xFFF2, 0xFFF3 e 0xFFF4 sono riservati ai test. Prima di lanciare un prodotto, devi richiedere un VID alla Connected Standards Alliance. Inoltre, i PID da 0x8000 a 0x801F hanno DAC di test (certificati di attestazione del dispositivo) che possono essere utilizzati per gli esempi. A meno che tu non preveda di configurare un tuo DAC, utilizza un PID all'interno di questo intervallo.
Ora vedrai l'integrazione nella sezione Integrazioni di Matter.
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. Costruire il dispositivo

Tutti gli esempi in Matter si trovano nella cartella examples del repository GitHub. Sono disponibili diversi esempi, ma in questo codelab ci concentreremo sull'app per l'illuminazione.

Questo esempio è un semplice dispositivo che viene visualizzato in Google Home come luce on/off e risponde ai comandi On e Off. Il controllo di una luce elettrica reale non rientra nell'ambito di questo codelab.

Configurare la build

Configura l'SDK Matter e attiva l'ambiente di build di Matter:

$ cd ~/esp-idf_tools/esp-idf
$ source export.sh
$ cd ~/connectedhomeip
$ source ./scripts/activate.sh

Attiva Ccache, che accelera il processo di compilazione:
```
$ export IDF_CCACHE_ENABLE=1
```
Passa alla directory di compilazione lighting-app ESP32 e imposta l'architettura di destinazione:
```
$ cd ./examples/lighting-app/esp32
$ idf.py set-target esp32
```
1. Esegui l'utilità di configurazione:
```
$ idf.py menuconfig
```
2. Seleziona Demo -> Device Type e imposta Device Type su ESP32-DevKitC.
3. Premi il tasto Freccia sinistra per tornare al menu di primo livello.
4. Seleziona Component config --->.
5. Seleziona CHIP Device Layer --->.
6. Seleziona Device Identification Options --->.
7. Imposta Vendor ID sull'ID fornitore assegnato dall'alleanza o su un ID fornitore di test.
8. Imposta Product ID sul PID impostato nell'integrazione Matter in Google Home Developer Console.
9. Premi S per salvare.
10. Premi Invio per accettare il percorso predefinito in cui verrà salvata la configurazione.
11. Premi Invio per chiudere la finestra di dialogo di conferma del salvataggio.
12. Premi Q per uscire dall'utilità di configurazione.

Esegui la build

Richiama lo script di build:

idf.py build

La build deve essere completata senza errori.

Programma il dispositivo

Collega la scheda di sviluppo al computer utilizzando un cavo USB.
Elimina qualsiasi firmware precedente sul dispositivo (se al computer è collegata una sola scheda di sviluppo, puoi omettere l'opzione -p {device}: il dispositivo dovrebbe essere rilevato automaticamente):
```
idf.py -p {device} erase-flash
```
Copia la nuova applicazione sulla scheda di sviluppo con:
```
idf.py -p {device} flash
```

Per maggiori informazioni sulle opzioni di flashing, visita la pagina della documentazione di Espressif esptool.py.

5. Connettersi al dispositivo

Apri una finestra del terminale.
Prendi nota della directory in cui ti trovi, quindi connettiti al nuovo dispositivo Matter utilizzando GNU screen:
```
$ screen -L {device} 115200
```
Se vedi una console vuota, premi il pulsante RESET per avviare la procedura di avvio del dispositivo.
Importante: quando ti connetti al dispositivo con screen, la console si riempie rapidamente di output. Se devi scorrere indietro e visualizzare l'output precedente e l'emulatore di terminale non dispone di un buffer scorrevole, dovrai trovare un altro modo per visualizzarlo.

La soluzione alternativa consiste nel visualizzare il file screen0.log, un file di log che contiene l'output di GNU screen e si trova nella stessa directory in cui hai eseguito screen. Puoi farlo utilizzando un editor di testo o in un'altra finestra del terminale utilizzando pager, more o qualsiasi utilità di paginazione installata sul tuo sistema Linux.

6. 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.

Accoppiare il dispositivo

Segui le istruzioni di accoppiamento ESP32 per accoppiare il dispositivo.

Nota: se utilizzi M5STACK, tieni presente che lo schermo rimarrà vuoto dopo il flashing, quindi dovrai visualizzare il codice QR utilizzando l'URL visualizzato nella console. In alternativa, puoi inserire il codice di accoppiamento manuale.

Output della console di esempio che mostra l'URL del codice QR:

I (1926) chip[DL]: Done driving station state, nothing else to do...
I (1936) chip[SVR]: SetupQRCode: [MT:X.XXXXXXXXXXXXXXXXX]
I (1936) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1946) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3XX.KXXXXXXXXXXXXXXXX
I (1956) chip[SVR]: Manual pairing code: [XXXXXXXXXXX]]

Risoluzione dei problemi

Provisioning non riuscito

Assicurati di aver creato un progetto con la combinazione VID/PID corretta nella console Google Home.
Assicurati di aver inserito il VID e il PID corretti nella configurazione della build.
Assicurati di aver selezionato il Device Type corretto nella configurazione della build.

Per altri suggerimenti per la risoluzione dei problemi, consulta la pagina Risoluzione dei problemi di Matter.

7. Controllare il dispositivo

Una volta che il dispositivo compatibile con Matter è stato commissionato correttamente e viene visualizzato nell'app Google Home come lampadina, puoi provare a controllarlo utilizzando l'Assistente Google, l'app Google Home o il simulatore dell'Assistente Google nell'estensione Google Home per VS Code.

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 saperne di più, consulta l'articolo Controllare i dispositivi con l'app Google Home.

Simulatore dell'Assistente Google

Nell'estensione Google Home per VS Code, utilizzando il simulatore dell'Assistente Google, puoi inviare comandi vocali al tuo dispositivo utilizzando un'interfaccia simile a una chat.

8. Complimenti!

Hai creato e commissionato correttamente il tuo primo dispositivo Matter. Fantastico!

In questo codelab hai imparato a:

Installa un ambiente di sviluppo Matter dai requisiti a uno stato di funzionamento.
Crea ed esegui un dispositivo Matter.
Esegui il provisioning e controlla il dispositivo da Google Home.

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

La guida introduttiva a Matter di Google Home, in cui imparerai i concetti e i principi importanti del protocollo Matter.
Le specifiche Matter, la libreria di dispositivi Matter e la libreria di cluster di applicazioni Matter, pubblicate dalla Connected Standard Alliance.
Il repository GitHub di Matter.