A partir de 2026, toda integração e teste do Matter vai exigir o teste de interoperabilidade da Alliance. Para mais informações, consulte a página de transição do Test Lab de interoperabilidade da Alliance.

Criar um dispositivo Matter

1. Introdução

O Matter é um protocolo de conectividade que oferece oportunidades incríveis para o desenvolvimento de dispositivos inteligentes. Neste codelab, você vai criar seu primeiro dispositivo Matter. Para saber mais sobre o Matter, acesse o Centro para desenvolvedores do Google Home: Matter ou o site da Connectivity Standards Alliance (em inglês).

O que você vai aprender

Como integrar um dispositivo físico com o Matter.
Como comissionar e controlar seu dispositivo Matter com o Google Home.

O que é necessário

Um hub, que é qualquer dispositivo Google Nest compatível com o Matter, como o Nest Hub (2ª geração).
Uma placa de avaliação do Matter ESP32-DevkitC ou ESP32 M5STACK da Espressif Systems.
Um PC com Linux.
Conhecimento básico do Linux.

2. Configurar o ambiente

Identificar o dispositivo serial

A primeira etapa para configurar seu ambiente de desenvolvimento é determinar a porta serial a que seu dispositivo está conectado. Com essas informações, você poderá programar e interagir com a placa de desenvolvimento.

Conecte a placa de desenvolvimento ao computador usando um cabo USB.
Procure no sistema de arquivos /dev para encontrar o dispositivo da placa de desenvolvimento. Para restringir a pesquisa, especifique o prefixo do dispositivo da sua placa de desenvolvimento. O ESP32 da Espressif usa /dev/ttyUSBx:
```
user@host $ ls /dev/ttyUSB*
/dev/ttyUSB0
```

Configurar seu hub

Configure o hub com a mesma Conta do Google que você pretende usar neste codelab.

Configurar o ambiente de desenvolvimento

Pré-requisitos

Estas instruções foram testadas no Debian Linux e devem funcionar na maioria das distribuições Linux baseadas no Debian, incluindo o Ubuntu. Se você estiver trabalhando com uma distribuição Linux diferente, o procedimento de configuração de dependência pode variar do que segue.

Instalar dependências

Execute o comando a seguir para instalar os binários de pacotes do Linux necessários que ainda não foram instalados:

$ 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

configurar o SDK

Para continuar este codelab, você vai precisar do SDK da Espressif (o Espressif IoT Development Framework ou "ESP-IDF").

Crie um diretório para conter o ESP-IDF:
```
$ mkdir ~/esp-idf_tools
```

Clone o ESP-IDF do GitHub neste diretório:

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

Conclua a instalação da cadeia de ferramentas:
```
$ cd ./esp-idf
$ ./install.sh
$ cd ~/
```

Configurar o SDK do Matter

Clone o repositório de código aberto do Matter:

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

Busque os submódulos do repositório:

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

Inicialize o ambiente de desenvolvimento do Matter:
```
$ source ./scripts/bootstrap.sh
```

3. Play Console do Google Home

O Google Home Developer Console é o aplicativo da Web em que você gerencia suas integrações do Matter com o Google Home.

Qualquer dispositivo Matter que tenha passado pela certificação da Connectivity Standards Alliance (Aliança) funciona no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser provisionados no ecossistema do Google Home em determinadas condições. Consulte Restrições de pareamento para mais informações.

Criar um projeto de desenvolvedor

Comece acessando o Google Home Developer Console:

Clique em Criar projeto.
Insira um nome exclusivo para o projeto e clique em Criar projeto.
Importante: ao criar um nome para o projeto, é recomendável que ele seja significativo e distinto. Considere incluir o nome da sua empresa e o tipo de dispositivo ou ação que ela vai implementar. Por exemplo, "encom-smartlight-switch" usa os dois elementos.
Clique em + Adicionar integração para acessar a tela Recursos do Matter, onde você pode consultar a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
Quando estiver tudo pronto, clique em Próxima: desenvolver, que mostra a página Lista de verificação do Matter.
Clique em Próxima: Configuração.
Na página Configuração, insira o Nome do produto.
Clique em Selecionar tipo de dispositivo e escolha o tipo no menu suspenso (neste caso, Light).
Em ID do fornecedor (VID), selecione VID de teste e escolha 0xFFF1 no menu suspenso "VID de teste". Em ID do produto (PID), insira 0x8000 e clique em Salvar e continuar. Depois, clique em Salvar na página seguinte. Use esses valores exatos de VID/PID, já que as etapas posteriores do codelab dependem deles.
Observação: os VIDs 0xFFF1, 0xFFF2, 0xFFF3 e 0xFFF4 são reservados para testes. Antes de lançar um produto, você precisa solicitar um VID na Connected Standards Alliance (em inglês). Além disso, os PIDs 0x8000 a 0x801F têm DACs de teste (certificados de atestação de dispositivo) que podem ser usados como exemplos. A menos que você planeje configurar seu próprio DAC, use um PID dentro desse intervalo.
Agora você vai encontrar sua integração em Integrações do Matter.
Reinicie o hub para garantir que ele receba a configuração mais recente do projeto de integração do Matter. Se você precisar mudar o VID ou PID depois, também será necessário reiniciar o dispositivo após salvar o projeto para que a mudança entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para conferir as instruções detalhadas de reinicialização.

4. Criar o dispositivo

Todos os exemplos do Matter estão na pasta "examples" do repositório do GitHub. Há várias amostras disponíveis, mas o foco deste codelab é o lighting-app.

Este exemplo é um dispositivo simples que aparece no Google Home como uma luz on/off, respondendo aos comandos "Ligar" e "Desligar". Fazer com que ele controle uma luz elétrica real está fora do escopo deste codelab.

Configurar a versão

Configure o SDK do Matter e ative o ambiente de build do Matter:

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

Ative o Ccache, que acelera o processo de build:
```
$ export IDF_CCACHE_ENABLE=1
```
Mova para o diretório de build do ESP32 lighting-app e defina a arquitetura de destino:
```
$ cd ./examples/lighting-app/esp32
$ idf.py set-target esp32
```
1. Execute o utilitário de configuração:
```
$ idf.py menuconfig
```
2. Selecione Demo -> Device Type e defina Device Type como ESP32-DevKitC.
3. Pressione a tecla de seta para a esquerda para voltar ao menu de nível superior.
4. Selecione Component config --->.
5. Selecione CHIP Device Layer --->.
6. Selecione Device Identification Options --->.
7. Defina Vendor ID como o VID atribuído pela Alliance ou um VID de teste.
8. Defina Product ID como o PID definido na integração do Matter no Google Home Play Console.
9. Pressione S para salvar.
10. Pressione Return para aceitar o caminho padrão em que a configuração será salva.
11. Pressione Return para dispensar a caixa de diálogo de confirmação de salvamento.
12. Pressione Q para sair do utilitário de configuração.

Executar o build

Invoque o script de build:

idf.py build

O build precisa ser concluído sem erros.

Programar o dispositivo

Conecte a placa de desenvolvimento ao computador usando um cabo USB.
Remova qualquer firmware anterior do dispositivo. Se você tiver apenas uma placa de desenvolvimento conectada ao computador, deixe a opção -p {device} desativada. O dispositivo será detectado automaticamente.
```
idf.py -p {device} erase-flash
```
Copie o novo aplicativo para a placa de desenvolvimento com:
```
idf.py -p {device} flash
```

Para mais informações sobre as opções de gravação, consulte a página de documentação do Espressif esptool.py.

5. Conectar ao dispositivo

Abra uma janela do terminal.
Anote em qual diretório você está e conecte-se ao novo dispositivo Matter usando o GNU screen:
```
$ screen -L {device} 115200
```
Se você vir um console em branco, pressione o botão RESET para iniciar o processo de inicialização do dispositivo.
Importante: quando você se conecta ao dispositivo com screen, o console é preenchido rapidamente com a saída. Se você precisar rolar para trás e analisar uma saída anterior, e o emulador de terminal não tiver um buffer rolável, será necessário encontrar outra maneira de visualizar.

A solução alternativa é visualizar o arquivo screen0.log, que é um arquivo de registro que contém a saída do GNU screen e está localizado no mesmo diretório em que você executou screen. Você pode fazer isso usando um editor de texto ou em outra janela de terminal usando pager, more ou qualquer utilitário de paginação instalado no seu sistema Linux.

6. Configurar o dispositivo

Observação: essa etapa só vai funcionar se você já tiver configurado o projeto no Google Home Play Console.

Nest Hub

É necessário um hub para comissionar o dispositivo no Matter. É um dispositivo Google Nest, como o Nest Hub (2ª geração), que é compatível com o Matter e serve como um roteador de borda para dispositivos compatíveis com o Thread e como um caminho de atendimento local para rotear intents de casa inteligente.

Consulte esta lista para saber quais hubs são compatíveis com o Matter.

Antes de iniciar o processo de inclusão, verifique se:

O hub está pareado com a mesma Conta do Google usada para fazer login no Google Home Console.
O hub está na mesma rede Wi-Fi do computador usado para executar o dispositivo virtual do Matter.
O hub está na mesma estrutura que você está usando no app Google Home. A "casa" no Home Graph do Google representa sua estrutura.

Parear o dispositivo

Siga as instruções de pareamento do ESP32 para parear o dispositivo.

Observação: se você estiver usando um M5STACK, saiba que a tela dele vai ficar em branco depois de ser atualizada. Portanto, será necessário acessar o QR code usando o URL que aparece no console. Ou digite o código de pareamento manual.

Exemplo de saída do console mostrando o URL do QR code:

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]]

Solução de problemas

Falhas no provisionamento

Verifique se você criou um projeto com a combinação VID/PID correta no console do Google Home.
Verifique se você inseriu o VID e o PID corretos na configuração do build.
Selecione o Device Type correto na configuração do build.

Para mais dicas de solução de problemas, consulte a página de solução de problemas do Matter.

7. Controlar o dispositivo

Depois que o dispositivo compatível com o Matter for comissionado e aparecer no app Google Home como uma lâmpada, tente controlar o dispositivo usando o Google Assistente, o app Google Home ou o simulador do Google Assistente na extensão do Google Home para VS Code.

Google Assistente

Use o Google Assistente no smartphone ou hub para alternar o estado do dispositivo com comandos de voz, como "Ok Google, alterne as luzes".

Consulte a seção Controlar dispositivos de casa inteligente com comandos de voz em Controlar os dispositivos de casa inteligente adicionados ao app Google Home para mais exemplos de comandos.

App Google Home

Toque nos rótulos Ligado e Desligado ao lado do ícone de lâmpada mostrado no app Google Home.

Consulte Controlar dispositivos com o app Google Home para mais informações.

Simulador do Google Assistente

Na extensão do Google Home para VS Code, usando o Simulador do Google Assistente, você pode emitir comandos para seu dispositivo usando uma interface semelhante a um chat.

8. Parabéns!

Você criou e comissionou seu primeiro dispositivo Matter. Incrível!

Neste codelab, você aprendeu a:

Instale um ambiente de desenvolvimento do Matter, desde os requisitos até um estado de funcionamento.
Crie e execute um dispositivo Matter.
Provisione e controle seu dispositivo pelo Google Home.

Para saber mais sobre o Matter, consulte estas referências:

O Guia básico do Matter do Google Home, em que você aprende os conceitos e princípios importantes do protocolo Matter.
A especificação do Matter, a biblioteca de dispositivos Matter e a biblioteca de clusters de aplicativos Matter, publicadas pela Connected Standard Alliance (em inglês).
O repositório do GitHub do Matter.