Criar um dispositivo virtual Matter

1. Introdução

O Matter é um protocolo de conectividade que traz oportunidades incríveis 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 o Centro para Desenvolvedores do Google Home ou o site da Connectivity Standards Alliance.

Neste curso, você vai aprender a:

  • Como configurar um ambiente de build do Matter
  • Como criar um dispositivo virtual Matter para ser executado no computador
  • Como comissionar e controlar o dispositivo virtual Matter com o Google Home

O que é necessário

2. Configurar o ambiente

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

Verifique seu hardware

Computadores Windows e macOS não são compatíveis com esta instalação do Docker. Você pode instalar e criar manualmente o Matter no macOS.

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

Configurar o Docker

  1. Instale o Docker Engine (não use o Docker Desktop).
  2. Extrair 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 encontrar uma saída de diagnóstico, seguida por uma mensagem confirmando que a configuração dele está correta e, por fim, o prompt do shell do contêiner:

Environment looks good, you are ready to go!
$

Vamos entender o comando docker e as opções que passamos para ele:

  • xhost local:1000 permite que o X Window System receba conexões do host local na porta 1000, possibilitando o uso de uma interface gráfica do usuário.
  • docker run … image executa a imagem especificada, 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), em vez de como um processo em segundo plano.

Outra opção é executar uma segunda instância de sessão do terminal:

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

Interrompa e inicie o contêiner do Docker do Matter

Sempre que você executar um comando docker run, 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 começar com uma instalação nova. No entanto, pode ser preferível salvar sua configuração de trabalho e ambiente entre uma sessão e outra.

Por isso, depois de criar o contêiner, é possível interrompê-lo 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 do terminal:

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

É possível abrir sessões de terminal adicionais para seu 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 pelo contêiner, use uma montagem de vinculação. Também é possível gravar arquivos no diretório montado de dentro do contêiner para facilitar o acesso do host.

Execute o contêiner com o argumento extra --mount source=$(pwd),target=/workspace,type=bind para ativar o 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.

Conseguir o ID do grupo do usuário do contêiner no 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 de maneira recursiva o grupo de arquivos no diretório ativado para o grupo do usuário do contêiner.

user@host> sudo chgrp -R 1000 .

Conceda as permissões desejadas no diretório para o grupo. Neste exemplo, o grupo do usuário do contêiner tem permissões de leitura, gravação e execução em todos os arquivos no diretório ativado.

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

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

É possível adicionar o usuário de host ao grupo do usuário 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 para desenvolvedores do Google Home

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

Qualquer dispositivo Matter que tenha sido aprovado na certificação Matter da Connectivity Standards Alliance (Alliance) funciona no ecossistema Google Home. 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 Play Console do Google Home:

  1. Clique em Criar projeto.
  2. Insira um nome exclusivo para o projeto e clique em Criar projeto. Caixa de diálogo "Criar novo projeto"
  3. Clique em + Add integration para acessar a tela Matter resources (recursos do Matter), onde você pode ver a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
  4. Quando estiver tudo pronto para continuar, clique em Próximo: desenvolver, que exibe a página Lista de verificação do Matter.
  5. Clique em Próxima configuração.
  6. Na página Configuração, digite o nome do produto.
  7. Clique em Selecionar tipo de dispositivo e selecione o tipo de dispositivo no menu suspenso (neste caso, Light).
  8. Em "ID do fornecedor" (VID, na sigla em inglês), selecione Testar VID e escolha 0xFFF1 no menu suspenso. Em "ID do produto" (PID, na sigla em inglês), insira "0x8000", clique em Salvar e continuar. Em seguida, clique em Salvar na página seguinte. Use esses valores exatos de VID/PID. As etapas posteriores do codelab dependem deles.
    Como configurar um projeto
  9. A integração vai aparecer em Integrações do Matter.
  10. Reinicie o hub para garantir que ele receba a configuração mais recente do projeto de integração do Matter. Se você precisar alterar o VID ou o PID mais tarde, também será necessário reiniciar depois de salvar o projeto para que a alteração entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para ver instruções detalhadas de reinicialização.

4. Criar um dispositivo

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

Chef é:

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

Navegue até a pasta de exemplo do Chef e crie a primeira versã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. As opções que estamos usando são as seguintes:

  • -d: define o tipo de dispositivo a ser usado. Neste caso, estamos criando um app de iluminação com controles de ligar/desligar e nível.
  • -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 cria automaticamente o código a ser incorporado ao build que define a luz (o modelo de dados) e como ele 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 do 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ê tiver 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 focar no app Google Home para colocar seu dispositivo no Google Home.

Pare o dispositivo

Se precisar interromper o dispositivo, pressione CTRL+C para sair do programa. Se o app não for encerrado, também é possível 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, você terá que 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 mostrar os estados dos dispositivos virtuais Matter. Ele usa um cliente RPC para se comunicar com os dispositivos Matter conectados ao seu ambiente de desenvolvimento.

O controlador de dispositivo virtual

O Virtual Device Controller 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). Suas alterações na GUI afetam o modelo de dados subjacente. Consulte Dispositivos compatíveis para conferir a lista completa dos tipos de dispositivos virtuais Matter compatíveis.

Instalar o controlador de dispositivo virtual

Ele vem pré-instalado no contêiner do Ubuntu LTS 20.04 Docker.

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 do 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 localhost. Assim que o controlador conseguir se conectar ao dispositivo virtual, ele exibirá uma tela mostrando o estado do seu dispositivo:

Interface gráfica do usuário do dispositivo virtual

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

O app de controle do dispositivo virtual também pode ser usado para recuperar o código QR como parte do fluxo de comissionamento do dispositivo. Clique no ícone do código QR ao lado da imagem do dispositivo para exibir o código QR deste dispositivo. Use este código QR para comissionar seu dispositivo.

6. Comissionamento do dispositivo

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

Nest Hub

É necessário ter um hub para comissionar o dispositivo no tecido do Matter. Este é um dispositivo Google Nest, como o Nest Hub (2a geração), compatível com o Matter e que vai funcionar como roteador de borda para dispositivos com Thread e como um caminho de fulfillment local para roteamento de intents de 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:

  • A central está pareada com a mesma Conta do Google que você usou para fazer login no Google Home Console.
  • O hub está na mesma rede Wi-Fi do computador que você está usando para executar o Dispositivo Virtual Matter.
  • O hub está na mesma estrutura que você usa no app Google Home. A "casa" no Google Home Graph representa sua estrutura.

Receber um código QR

O processo de comissionamento precisa das informações de integração do Matter fornecidas por um código QR. Você pode obter o código QR do seu dispositivo virtual no Virtual Device Controller.

Realize 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..." aparecer, toque em "Sim". Caso contrário, toque em Configurar um dispositivo diferente e selecione Dispositivo Matter na lista de dispositivos.
  7. Aponte a câmera para o código QR do dispositivo ou para o código gerado pelo site.
  8. Continue o processo de pareamento conforme indicado no fluxo do app Google Home.

Após concluir essas etapas, o dispositivo virtual Matter vai ser comissionado e 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"

O comissionamento falha após "Verificar seu dispositivo" por um longo período

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á testar o controle usando diferentes métodos:

  • Usando o Google Assistente.
  • No app Google Home.
  • Como usar a GUI do dispositivo virtual.

Google Assistente

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

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

App Google Home

Toque nos marcadores Ativar e Desativar ao lado do ícone de lâmpada exibido no app Google Home.

Consulte a seção Controlar dispositivos com o app Google Home de Controlar dispositivos de casa inteligente adicionados ao app Google Home para mais informações.

GUI do dispositivo virtual

Você pode interagir com a GUI do dispositivo virtual para mudar o estado dele. Independentemente de você usar o controlador do dispositivo virtual, o app Google Home no smartphone ou a central, todas essas interfaces vão refletir 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 do Matter.
  • Comissione e controle seu dispositivo virtual pelo Google Home.

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