Criar um dispositivo virtual 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 usando recursos do SDK do Matter.

Para saber mais sobre o Matter, acesse o Centro para Desenvolvedores 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 comissionar 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).
  • Uma máquina Linux executando o sistema de janelamento X11.
  • Docker.
  • Git
  • Noções básicas de Linux.
    • Observe que o shell presumido para todos os comandos neste codelab é o BASH.

2. Configurar o ambiente

Verifique seu hardware

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.

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

Configurar o ambiente de desenvolvimento

  1. Instalar o Docker Engine (não usar o Docker Desktop).
  2. Clone o SDK do Matter e confira a confirmação a seguir.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Execute um contêiner de build usando as imagens públicas de CI do SDK e o dispositivo virtual recém-criado nesse contêiner. Localize a imagem que será usada correspondente à nossa versão do SDK, desta forma:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Se você estiver usando a mesma confirmação, a seguinte mensagem vai aparecer: ghcr.io/project-chip/chip-build:66Primeiro, encaminhe portas xhost para usarmos aplicativos de interface depois:
    xhost local:1000
    Em seguida, inicie o contêiner com os recursos apropriados encaminhados do host (nossos recursos de finalização de compra do SDK, rede e display/comunicação).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

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

  • O 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 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 para o 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.
  • O -it executa o Docker com um terminal interativo (tty) em vez de um processo em segundo plano.
  • --mount monta o SDK que conferimos anteriormente no contêiner.
  • --workdir define o diretório de trabalho na inicialização para o diretório montado do SDK.

Opcionalmente, execute uma instância do segundo terminal da sessão:

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

Interromper e iniciar o contêiner do Docker do Matter

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

Por esse motivo, 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 de terminal:

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

Você pode 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

Inicializar o SDK

Inicialize o SDK do Matter. Essa operação levará alguns minutos para ser concluída.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

O SDK do Matter foi inicializado. Para reinicializar o ambiente rapidamente no futuro, execute:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Compartilhar arquivos entre o host e o contêiner

Anteriormente, acessamos os arquivos na sua máquina host pelo contêiner usando uma montagem de vinculação. Também é possível gravar arquivos no diretório montado a partir do contêiner para acesso do host.

Em geral, use montagens de vinculação executando 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 montado 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 de terminal no host do contêiner e defina o diretório de trabalho para o diretório ativado pelo contêiner.

Defina de modo recursivo 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. 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 dos novos arquivos criados pelo usuário host. Atualize as permissões dos novos arquivos criados no host conforme necessário.

Você pode adicionar o usuário host ao grupo do usuário do contêiner para herdar permissões nos arquivos criados pelo usuário do contêiner.

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

3. Console para desenvolvedores do Google Home

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

Qualquer dispositivo Matter que tenha sido aprovado pela certificação da Connectivity Standards Alliance (Alliance) Matter funciona no ecossistema do Google Home. Dispositivos em desenvolvimento que não foram certificados podem ser comissionados no ecossistema do Google Home sob determinadas condições. Consulte Restrições de pareamento para mais informações.

Criar um projeto de desenvolvedor

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

  1. Clique em Criar projeto.
  2. Insira um nome de projeto exclusivo e clique em Criar projeto. Caixa de diálogo "Criar novo projeto"
  3. Clique em + Adicionar integração para acessar a tela Recursos do Matter, onde é possível conferir 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 vai exibir a página Lista de verificação do Matter.
  5. Clique em Próxima: configuração.
  6. Na página Configuração, insira 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)", selecione Testar VID e escolha "0xFFF1" no menu suspenso "Testar VID". Em ID do produto (PID), insira 0x8000 e clique em Salvar e continuar e, em seguida, clique em Salvar na próxima página. Use esses valores exatos de VID/PID. As etapas posteriores do codelab dependem deles.
    Como configurar um projeto
  9. Sua 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 for necessário alterar o VID ou o PID posteriormente, 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.

4. Criar um dispositivo

Todos os exemplos em Matter podem ser encontrados na pasta examples no repositório do GitHub. Há vários exemplos disponíveis, mas nosso foco neste codelab é o Chef.

Chef é:

  • Um app de exemplo que fornece 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 o desenvolvimento de um dispositivo compatível com o Matter.

Navegue até a pasta de exemplo do Chef e crie seu primeiro build do Matter:

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

A Chef tem algumas opções que podem ser consultadas ao executar chef.py -h. Estas são as opções que estamos usando:

  • -d: define o tipo de dispositivo a ser usado. Neste caso, estamos criando um app de iluminação com controles de ligar/desligar e de 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, a ZAP cria automaticamente um código para ser incorporado no 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 de 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. Você pode executar ./chef.py -h para conferir todos os comandos disponíveis e as plataformas de destino compatíveis. O 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 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, vamos nos concentrar no app Google Home para comissionar o dispositivo no Google Home.

Parar o dispositivo

Se for preciso parar o dispositivo, saia do programa pressionando CTRL+C. Se o app não for fechado, talvez seja necessário usar também 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á necessário excluir esses arquivos executando o seguinte comando:

$ rm /tmp/chip*

5. Comissionar o dispositivo

Observação: esta etapa só será concluída se você já tiver configurado seu projeto no Google Home Developer Console.

Nest Hub

Um hub é necessário para comissionar o dispositivo no tecido Matter. Este é um dispositivo Google Nest, como o Nest Hub (2a geração), que oferece suporte ao Matter e serve 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 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 que você usou para fazer login no console do Google Home.
  • O 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 que você usa no app Google Home. A "casa" no Google Home Graph representa sua estrutura.

Receber um QR code

O processo de comissionamento precisa de informações de integração do Matter fornecidas por um QR code. Analise a saída do console do aplicativo Matter, que vai conter um link para o QR code relevante para o comissionamento.

Executar a operação de comissionamento

  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 outro dispositivo e selecione Dispositivo Matter na lista.
  7. Aponte a câmera para o QR code do dispositivo ou gerado pelo site.
  8. Continue o processo de pareamento conforme indicado no fluxo do app Google Home.

Depois de concluir essas etapas, o dispositivo virtual Matter 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 "Problema de conectividade" ou "Não foi possível entrar em contato com o Google" mensagens de erro

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

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

6. 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 dele usando diferentes métodos:

  • Usando o Google Assistente.
  • No app Google Home.

Google Assistente

Use o Google Assistente no seu smartphone ou hub para alternar o estado do dispositivo por comandos de voz, como dizer "Ok Google, ligar as 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 ver mais exemplos de comandos.

App Google Home

Toque nos marcadores Ativado e Desativado ao lado do ícone de lâmpada no app Google Home.

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

7. Parabéns!

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

Neste codelab, você aprendeu a:

  • Instalar um ambiente de desenvolvimento do Matter.
  • Crie e execute um dispositivo virtual do Matter.
  • Comissionamento e controle do seu dispositivo virtual pelo Google Home.

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