Atenção! Os novos programas da prévia para desenvolvedores serão lançados em breve. Inscreva-se aqui e seja um dos primeiros a testar novas ferramentas e enviar feedback.

Criar um dispositivo virtual do 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, usando SDKs e dependências fornecidos em uma imagem pré-configurada do Docker.

Para saber mais sobre o Matter, acesse a Central do desenvolvedor do Google Home ou o site da Connectivity Standards Alliance.

O que você vai aprender

  • Como configurar um ambiente de build do Matter
  • Como criar um dispositivo Matter virtual que é executado no computador.
  • Como gerenciar e controlar o dispositivo Matter virtual com o Google Home

O que é necessário

  • Um hub, que é qualquer dispositivo Google Nest compatível com o Matter, como o Nest Hub (2a geração). Você pode comprar um hub na Google Store ou no seu varejista preferido.
  • Uma máquina Linux executando o sistema de janelamento X11.
  • Docker
  • Conhecimento básico do Linux.

2. Configurar o ambiente

Usaremos um contêiner do Docker já configurado em uma máquina host Linux. Esse contêiner inclui todas as dependências necessárias para criar e executar um dispositivo virtual Matter.

Verificar o hardware

Atualmente, esta versão do Docker não oferece suporte a computadores Windows e MacOS. Você pode instalar e criar o Matter manualmente no MacOS ou Windows.

Além disso, essas instruções presumem que sua máquina Linux esteja executando o sistema de janelas X11. Se a máquina Linux executar o Wayland, verifique se o X.Org também está instalado.

Configurar o Docker

  1. Instale o Docker Engine (não use o Docker Desktop).
  2. Extraia a imagem do Docker do Docker Hub. Em uma janela de terminal, execute:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    Esta operação pode levar alguns minutos para ser concluída.
  3. Inicie o contêiner do Docker em execução:
    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

Depois de iniciar o contêiner, você vai ver uma saída de diagnóstico seguida por uma mensagem confirmando que a configuração do contêiner está correta e, por fim, o prompt do shell do contêiner:

Environment looks good, you are ready to go!
$

Vamos entender o comando do Docker e as opções que transmitimos a ele:

  • xhost local:1000 permite que o sistema de janelas X receba conexões do host local na porta 1000, permitindo o uso de uma interface gráfica do usuário.
  • docker run … image executa a imagem determinada, extraindo-a do registro do Docker, se necessário.
  • --ipc=host permite que o Docker compartilhe o namespace de comunicação entre processos com a máquina host.
  • --net=host permite que o Docker use a pilha de rede do host dentro do contêiner, o que é necessário para transmitir o tráfego mDNS do host para o contêiner e compartilhar a tela X11 do host.
  • -e DISPLAY exporta $DISPLAY para o host, fornecendo acesso à interface gráfica do sistema. Isso é necessário para executar a ferramenta ZAP ao editar clusters do Matter.
  • -it executa o Docker com um terminal interativo (tty), e não como um processo em segundo plano.

Também é possível executar uma segunda instância da sessão do terminal:

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

Interrompa e inicie o contêiner do Docker Matter

Sempre que executar um comando docker run, você criará um novo contêiner com a imagem especificada. Ao fazer isso, seus dados antigos, que foram salvos em uma instância de contêiner anterior, serão perdidos. Às vezes, é isso que você quer que aconteça, porque permite que você comece com uma nova instalação. Mas, às vezes, você prefere salvar a configuração do ambiente e do trabalho entre as sessões.

Por isso, depois de criar o contêiner, é possível interromper o contêiner para evitar a perda do seu trabalho.

user@host> docker stop matter-container

Quando estiver tudo pronto para executar novamente, inicie o contêiner e abra uma janela de terminal:

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

É possível abrir mais sessões do terminal para o contêiner com:

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

Ou inicie uma sessão raiz usando:

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

Configuração inicial do Matter

Quando o terminal abrir, ele já estará no repositório clonado do Matter em ~/connectedhomeip. Nenhuma outra etapa de configuração do Matter é necessária.

Compartilhar arquivos entre o host e o contêiner

Para acessar arquivos na máquina host a partir do contêiner, use um suporte de vinculação. Também é possível gravar arquivos no diretório montado no contêiner para facilitar o acesso pelo host.

Execute o contêiner com o argumento adicional --mount source=$(pwd),target=/workspace,type=bind para montar seu diretório de trabalho atual no contêiner em /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

As permissões do usuário do contêiner no diretório ativado precisam ser gerenciadas no host.

Consiga o ID do grupo do usuário do contêiner de dentro do contêiner.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Abra outra sessão do terminal no host do contêiner e defina o diretório de trabalho como o diretório montado pelo contêiner.

Defina recursivamente o grupo de arquivos no diretório montado como o grupo do usuário do contêiner.

user@host> sudo chgrp -R 1000 .

Conceda as permissões que você quer no diretório ao grupo. Este exemplo concede ao grupo de usuários do contêiner permissões de leitura, gravação e execução em todos os arquivos no diretório montado.

user@host> sudo chmod -R g+rwx .

Esses comandos não afetam a permissão dos novos arquivos criados pelo usuário host. Lembre-se de atualizar as permissões dos novos arquivos criados no host conforme necessário.

É possível adicionar o usuário host ao grupo de usuários do contêiner para herdar as permissões dos arquivos criados por ele.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Console do desenvolvedor do Google Home

O Console do desenvolvedor do Google Home é um app da Web em que você gerencia as integrações do Matter com o Google Home.

Qualquer dispositivo Matter que tenha a certificação CSA Matter funciona no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser encomendados no ecossistema do Google Home em algumas condições. Consulte Restrições de pareamento para mais informações.

Criar um projeto de desenvolvedor

Para começar, acesse o Console do desenvolvedor do Google Home:

.

  1. Na página Gerenciar projetos, clique em Criar um projeto.
    Central do desenvolvedor do Google Home
  2. Na página Primeiros passos, clique em Criar projeto.

  1. Insira um nome de projeto exclusivo e clique em Criar novo projeto. Caixa de diálogo "Create new project"
  2. Clique em + Adicionar integração, que leva à tela "Recursos do Matter", onde você pode ver a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
  3. Quando estiver pronto para continuar, clique em Próxima: desenvolver. A página Lista de verificação de casos será exibida.
  4. Clique em Next: Setup.
  5. Na página Configuração, insira o Nome do produto.
  6. Clique em Select device type e escolha o tipo de dispositivo no menu suspenso (neste caso, Light).
  7. Em "ID do fornecedor" (VID, na sigla em inglês), selecione Testar VID e escolha 0xFFF1 no menu suspenso "Testar VID". Em "ID do produto" (PID, na sigla em inglês), digite "0x8000" e clique em Salvar e continuar. Depois, clique em Salvar na página seguinte.
    Como configurar um projeto
  8. Agora você verá um dispositivo Matter em "Integrações do Matter". Integrações do Matter
  9. Reinicie o hub para garantir que ele receba a configuração mais recente do projeto de integração do Matter. Se for preciso alterar 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.

4. Criar um dispositivo

Todos os exemplos no Matter estão na pasta examples do repositório do GitHub (link em inglês). Há várias amostras disponíveis, mas nosso foco deste codelab é o Chef (em inglês).

O Chef é:

  • Um app de exemplo que oferece uma interface de terminal, encapsulando recursos também encontrados no app examples/shell.
  • Um script que segue o princípio de convenção sobre configuração para encapsular várias das tarefas comuns necessárias para desenvolver um dispositivo compatível com Matter.

Navegue até a pasta de exemplo do Chef e crie sua primeira compilação do Matter:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

O Chef tem algumas opções que podem ser visualizadas executando chef.py -h. Estas são as opções usadas:

  • -d: define o tipo de dispositivo a ser usado. Nesse caso, estamos criando um app de iluminação com controles de ativação e desativação.
  • -z: invoca a ferramenta ZAP para gerar os arquivos de origem que implementam o tipo de dispositivo. Ou seja, com base na sua escolha de iluminação, o ZAP vai criar automaticamente um código para ser incorporado ao build que define a luz (o modelo de dados) e como ela interage com outros dispositivos (o modelo de interação).
  • -b: builds.
  • -r: [opcional] ativa o servidor RPC no dispositivo virtual Matter para que outros componentes (como a GUI) possam se comunicar com o dispositivo para definir e recuperar atributos de modelo de dados.
  • -t linux: plataforma de destino. As plataformas de suporte são linux, nrfconnect e esp32. Execute ./chef.py -h para ver todos os comandos disponíveis e plataformas de destino compatíveis. O linux é usado para dispositivos virtuais Matter.

Executar o dispositivo

O Matter usa a porta TCP/UDP 5540. Portanto, se você tem um firewall em execução no seu computador, desligue-o ou permita conexões TCP/UDP de entrada na porta 5540.

Execute o dispositivo virtual no contêiner com:

$ ./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]

Deixe o dispositivo em execução. Agora, vamos voltar nossa atenção ao app Google Home para colocar seu dispositivo no modo Google Home.

Parar o dispositivo

Você pode sair do programa com CTRL+C. Se o app não for encerrado, talvez você também precise usar CTRL+\.

As credenciais do dispositivo virtual são armazenadas no diretório /tmp/, em arquivos que começam com o prefixo chip.

Se quiser repetir todo o processo de comissionamento desde o início, será preciso excluir esses arquivos executando o seguinte comando:

$ rm /tmp/chip*

5. O controlador de dispositivo virtual

O Virtual Device Controller é um app independente que oferece uma interface gráfica do usuário para controlar e exibir os estados dos dispositivos Matter virtuais. Ele usa um cliente RPC para se comunicar com os dispositivos Matter conectados ao seu ambiente de desenvolvimento.

O controlador de dispositivo virtual

O controlador de dispositivo virtual fornece uma representação visual do seu dispositivo virtual.

É possível interagir com o dispositivo virtual pela interface gráfica do usuário (GUI, na sigla em inglês). As mudanças na GUI afetam o modelo de dados subjacente. No momento, o controlador de dispositivo virtual é compatível com o tipo de dispositivo Dimable Light.

Instalar o controlador de dispositivo virtual

O controlador de dispositivo virtual vem pré-instalado no contêiner do Docker do LTS do Ubuntu 20.04.

Executar o controlador de dispositivo virtual

Crie a segunda instância da sessão do terminal:

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

Inicie o controlador de dispositivo virtual fornecendo o soquete de rede que será usado para se comunicar com o dispositivo virtual:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Se você iniciar o controlador sem fornecer argumentos, o padrão será a opção de soquete de rede usando a porta 33000 do host local. Quando o controlador conseguir se conectar ao dispositivo virtual, ele vai mostrar uma tela mostrando o estado do dispositivo:

Interface gráfica do usuário do dispositivo virtual

O app envia solicitações para o servidor RPC do dispositivo à medida que você faz alterações no app Controlador virtual e pesquisa o servidor RPC uma vez por segundo para recuperar o estado.

O app Virtual Device Controller também pode ser usado para recuperar o código QR como parte do fluxo de comissionamento do dispositivo. Clique no ícone de código QR ao lado da imagem para mostrar o código QR deste dispositivo:

Código QR

Use este código QR para encomendar seu dispositivo.

6. Ativar o dispositivo

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

Nest Hub

Um hub é necessário para encomendar seu dispositivo no tecido Matter. Esse é um dispositivo Google Nest, como o Nest Hub (segunda geração), compatível com o Matter e que funciona como um roteador de borda para dispositivos compatíveis com linha de execução e como um caminho de fulfillment local para rotear intents da casa inteligente.

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

Antes de iniciar o processo de comissionamento, verifique se:

  • Seu hub é pareado com a mesma Conta do Google que você usou para fazer login no Console do Google Home.
  • Seu hub está na mesma rede Wi-Fi que o computador que você está usando para executar o Dispositivo Matter Virtual.
  • O hub está na mesma estrutura usada no app Google Home (a "casa" no gráfico do Google Home representa a estrutura).

Receber um código QR

O processo de comissionamento precisa das informações de integração do Matter fornecidas através de um código QR. O controlador QR pode ser usado para encontrar o código QR do seu dispositivo virtual.

Realizar a operação de comissão

  1. Abra o app Google Home.
  2. Toque em + no canto superior esquerdo.
  3. Toque em Configurar dispositivo.
  4. Toque em Novo dispositivo.
  5. Selecione sua casa e toque em Próxima.
  6. O app Google Home procura seu dispositivo. Se a mensagem "Dispositivo Matter encontrado..." for exibida, toque em "Sim". Caso contrário, toque em Configurar outro dispositivo e selecione Dispositivo Matter na lista.
  7. Aponte a câmera para o código QR do dispositivo ou para o gerado pelo site.
  8. Continue o processo de pareamento conforme indicado no fluxo do app Google Home.

Depois que você concluir essas etapas, o dispositivo virtual Matter vai ser encomendado e vai aparecer como um novo ícone no app Google Home.

Lâmpada pareada no app Google Home

Solução de problemas

O comissionamento falha com as mensagens de erro "Problema de conectividade" ou "Não foi possível entrar em contato com o Google"

  • Verifique se você criou um projeto com a combinação VID/PID correta no Console do Google Home e se não há outros projetos usando a mesma combinação VID/PID.

A ativação do comissionamento falha após um longo período após a "verificação do dispositivo"

7. Controlar o dispositivo

Depois que o dispositivo compatível com o Matter for encomendado e aparecer no app Google Home como uma lâmpada, você poderá testar o controle do dispositivo usando diferentes métodos:

  • Usando o Google Assistente.
  • No app Google Home.
  • Usando a GUI de dispositivo virtual.

Google Assistente

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

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

App Google Home

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

Veja mais informações na seção Controlar dispositivos com o app Google Home em Controlar dispositivos de casa inteligente adicionados ao app Google Home.

GUI do dispositivo virtual

É possível interagir com a GUI de dispositivo virtual para mudar o estado do dispositivo. Se você controla o dispositivo virtual com o controlador de dispositivo virtual, o app Google Home no smartphone ou o hub, todas essas interfaces refletem o estado atual do dispositivo virtual.

8. Parabéns!

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

Neste codelab, você aprendeu a:

  • Instalar um ambiente de desenvolvimento do Matter usando uma imagem do Docker pré-empacotada.
  • Crie e execute um dispositivo virtual Matter.
  • Ative e controle seu dispositivo virtual pelo Google Home.

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