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.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar um dispositivo Matter

1. Introdução

O Matter é um protocolo de conectividade que oferece oportunidades interessantes 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.

O que você vai aprender

Como integrar um dispositivo físico ao Matter.
Como configurar 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 na configuração do ambiente de desenvolvimento é determinar a porta serial a que o dispositivo está conectado. Essas informações permitem 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. Você pode restringir a pesquisa especificando o prefixo do dispositivo da placa de desenvolvimento. O ESP32 da Espressif usa /dev/ttyUSBx:
```
user@host $ ls /dev/ttyUSB*
/dev/ttyUSB0
```

Configurar seu hub

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

Configurar o ambiente de desenvolvimento

Pré-requisitos

Essas instruções foram testadas no Linux Debian 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 poderá variar do que segue.

Instalar dependências

Execute o comando a seguir para instalar binários de pacotes Linux necessários que talvez ainda não estejam 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 para esse diretório:

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

Conclua a instalação do conjunto 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. Google Home Developer Console

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 do Matter da Connectivity Standards Alliance (Alliance) funciona no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser comissionados 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 de projeto exclusivo e clique em Criar projeto.
Importante: ao criar um nome de 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 ele vai implementar. Por exemplo, "encom-smartlight-switch" usa esses dois elementos.
Clique em + Adicionar integração, que leva à tela Recursos do Matter, onde você pode conferir a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
Quando estiver tudo pronto para continuar, 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 de dispositivo 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 e, em seguida, clique em Salvar na página a seguir. Use esses valores exatos de VID/PID. 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. Além disso, os PIDs 0x8000 a 0x801F têm DACs de teste (certificados de atestação de dispositivo) que podem ser usados para exemplos. A menos que você planeje configurar seu próprio DAC, use um PID dentro desse intervalo.
Agora, sua integração vai aparecer em Integrações do Matter.
Reinicialize 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 o PID mais tarde, também será necessário reiniciar depois de salvar o projeto para que a mudança entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para conferir instruções detalhadas de reinicialização.

4. Criar o dispositivo

Todos os exemplos do Matter são colocados na pasta de exemplos no repositório do GitHub. Há vários exemplos disponíveis, mas nosso foco neste codelab é o lighting-app.

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

Configurar o build

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
```
Acesse 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 Developer 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.
Limpe qualquer firmware anterior no dispositivo. Se você tiver apenas uma placa de desenvolvimento conectada ao computador, poderá deixar a opção -p {device} desativada. O dispositivo será detectado automaticamente:
```
idf.py -p {device} erase-flash
```
Copie seu novo aplicativo para a placa de desenvolvimento com:
```
idf.py -p {device} flash
```

Mais informações sobre as opções de flash podem ser encontradas na página de documentação Espressif esptool.py.

5. Conectar ao dispositivo

Abra uma janela do terminal.
Anote o diretório em que você está e conecte-se ao novo dispositivo Matter usando o screen do GNU:
```
$ 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 conferir a saída anterior, e o emulador de terminal não tiver um buffer rolável, será necessário outra maneira de visualizá-lo.

A solução alternativa é visualizar o arquivo screen0.log, que é um arquivo de registro que contém a saída screen do GNU 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 sistema Linux.

6. Comissionar o dispositivo

Observação: essa etapa só será bem-sucedida se você já tiver configurado o projeto no Google Home Developer Console.

Nest Hub

Um hub é necessário para comissionar o dispositivo no Fabric do Matter. Esse é um dispositivo Google Nest, como o Nest Hub (2ª geração), que é compatível com o Matter e que vai servir 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 comissionamento, 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 que o 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 Google Home Graph 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 permanecer em branco após o flash. Portanto, será necessário visualizar o QR code usando o URL que aparece no console. Ou, você pode digitar 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

Falha no comissionamento

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

Para mais dicas de solução de problemas, consulte a página 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, você poderá tentar 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, ligue minhas luzes".

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

App Google Home

Você pode tocar nos rótulos Ativado e Desativado 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 o 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:

Instalar um ambiente de desenvolvimento do Matter, desde os requisitos até um estado de funcionamento.
Criar e executar um dispositivo Matter.
Comissionar e controlar o dispositivo no Google Home.

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

O Matter Primer do Google Home, em que você vai aprender os conceitos e princípios importantes do protocolo Matter.
A especificação do Matter, a biblioteca de dispositivos do Matter e a biblioteca de clusters de aplicativos do Matter, publicadas pela Connected Standard Alliance.
O repositório do Matter no GitHub.