Criar um dispositivo virtual do Matter

1. Introdução

O Matter é um protocolo de conectividade que oferece oportunidades incríveis para o desenvolvimento de dispositivos inteligentes. Neste codelab, você criará seu primeiro dispositivo Matter, usando SDKs e dependências fornecidos em uma imagem do Docker pré-configurada.

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

O que você vai aprender

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

O que é necessário

2. Configurar o ambiente

Usaremos 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 Matter.

Verifique seu hardware

No momento, computadores Windows e MacOS não são compatíveis com esta instalação do Docker. Você pode instalar e criar o Matter manualmente no MacOS ou Windows.

Além disso, essas instruções presumem que a máquina Linux esteja executando o sistema de janelas X11. Caso sua máquina Linux execute 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ê verá um resultado de diagnóstico seguido por uma mensagem informando 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 X Window System 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 fornecida, 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 ao contêiner e compartilhar a tela do host X11.
  • O -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.

Se quiser, execute uma segunda instância da sessão do terminal:

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

Interromper e iniciar o contêiner do Matter Docker

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 ele permite que você comece com uma nova instalação. No entanto, em algumas sessões, é preferível salvar a configuração do ambiente e do trabalho.

Por esse motivo, depois de criar seu contêiner, você pode interrompê-lo para evitar a perda do trabalho.

user@host> docker stop matter-container

Quando estiver 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

Você pode abrir mais sessões do terminal no 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 caso

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 de dentro do contêiner, use um suporte de vinculação. Você também pode gravar arquivos no diretório ativado a partir do contêiner para facilitar o acesso a partir do host.

Execute o contêiner com o argumento adicional --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.

Receba o código do grupo do usuário do contêiner 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 ativado pelo contêiner.

Defina recursivamente 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 ao grupo. Este exemplo dá ao grupo de usuários do contêiner 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 dos novos arquivos criados pelo usuário host. Lembre-se de atualizar as permissões dos novos arquivos criados no host conforme necessário.

Você pode adicionar seu usuário host ao grupo do usuário do contêiner para herdar as permissões nos 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 é o aplicativo da Web em que você gerencia as integrações do Matter com o Google Home.

Todos os dispositivos Matter que passaram na certificação Connectivity Standards Alliance (Alliance) Matter funcionam no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser encomendados 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 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 exclusivo para o projeto e clique em Criar novo projeto. Caixa de diálogo "Criar novo projeto"
  2. Clique em + Adicionar integração, que leva você à tela "Recursos do caso" para ver a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
  3. Quando estiver pronto para continuar, clique em Próxima: desenvolver, que exibe a página Lista de verificação de casos.
  4. Clique em Próxima: configuração.
  5. Na página Configuração, insira o Nome do produto.
  6. Clique em Selecionar tipo de dispositivo e escolha o tipo de dispositivo no menu suspenso (neste caso, Light).
  7. Em "ID do fornecedor" (VID, na sigla em inglês), selecione VID de teste e selecione 0xFFF1 no menu suspenso "VID de teste". No ID do produto (PID), digite 0x8000 e clique em Salvar e continuar. Em seguida, clique em Salvar na página a seguir.
    Como configurar um projeto
  8. Agora você verá um dispositivo Matter em "Integrações do Matter". Integrações de casos
  9. 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 reinicializar após salvar o projeto para que a alteração entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para ver instruções de reinicialização passo a passo.

4. Criar um dispositivo

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

Chef é:

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

Navegue até a pasta de exemplo do Chef e faça 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. As opções usadas são:

  • -d: define o tipo de dispositivo a ser usado. Neste caso, estamos criando um app de iluminação com controles de ativação/desativação 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 para ser incorporado à compilação, 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 Matter virtual 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 as plataformas de destino compatíveis. linux é usado para dispositivos Matter virtuais.

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 seu dispositivo em execução. Agora, voltaremos a atenção para o app Google Home para que possamos colocar seu dispositivo em prática no Google Home.

Parar o dispositivo

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

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 controlador de dispositivo virtual é um app independente que fornece 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 ambiente de desenvolvimento.

O controlador de dispositivo virtual

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

É possível interagir com o dispositivo virtual por meio da interface gráfica do usuário (GUI) do controlador de dispositivo virtual. As alterações na GUI afetam o modelo de dados subjacente. Atualmente, 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 Docker LTS 20.04 do Ubuntu.

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

Interface gráfica do usuário do dispositivo virtual

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

O aplicativo 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 exibir o código QR deste dispositivo:

Código QR

Você pode usar esse código QR para encomendar seu dispositivo.

6. Comissionamento do dispositivo

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

Nest Hub

É necessário ter um hub para colocar seu dispositivo no tecido da Matter. Este é 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 Thread e como um caminho de fulfillment local para rotear 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:

  • Seu hub está 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ê usa para executar o dispositivo virtual de caso.
  • Seu hub está na mesma estrutura que você está usando no app Google Home. A "casa" no gráfico do Google Home representa sua estrutura.

Receber um código QR

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

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 "Matter Device found..." for exibida, toque em "Sim". Caso contrário, toque em Configurar um dispositivo diferente 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 será encomendado 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"

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

O 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 por diferentes métodos:

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

Google Assistente

Use o Google Assistente no smartphone ou hub para alternar o estado do dispositivo dos comandos de voz, como "Ok Google, mude 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.

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 de dispositivo virtual

É possível interagir com a GUI do dispositivo virtual para alterar o estado do dispositivo. Independentemente de você controlar o dispositivo virtual com o controlador de dispositivo virtual, o app Google Home no seu smartphone ou com o hub, todas essas interfaces refletirão 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 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, veja estas referências: