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 (em inglês).

O que você vai aprender

  • Como configurar um ambiente de build do Matter
  • Como criar um dispositivo virtual Matter que é executado no seu computador
  • Como provisionar 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 (2ª geração).
  • Uma máquina Linux executando o sistema de janelas X11.
  • Docker.
  • Git.
  • Conhecimento básico do Linux.
    • O shell presumido para todos os comandos neste codelab é o BASH.

2. Configurar o ambiente

Verificar o 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, estas instruções pressupõem que sua máquina Linux esteja executando o sistema de janelamento X11. Se a máquina Linux usa o Wayland, verifique se o X.Org também está instalado.

Configurar o ambiente de desenvolvimento

  1. Instale o Docker Engine (não use o Docker Desktop).
  2. Clone o SDK do Matter e anote o commit que vamos usar 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 execute o dispositivo virtual recém-criado de dentro desse contêiner. Localize a imagem para usar correspondendo à nossa versão do SDK, assim:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Se você estiver usando o mesmo commit, vai ver ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Em seguida, inicie o contêiner com os recursos adequados encaminhados do host (nosso SDK checkout, rede e recursos de exibição/comunicações).
    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 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.
  • O 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 que ele transmita o tráfego mDNS do host para o contêiner e compartilhe a tela X11 do host.
  • 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 um processo em segundo plano.
  • --mount monta o SDK que extraímos anteriormente no contêiner.
  • --workdir define o diretório de trabalho no lançamento para o diretório do SDK montado.

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

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

Interromper e iniciar o contêiner do Docker do Matter

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

Por isso, depois de criar o contêiner, você pode interrompê-lo para não perder 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 outras sessões de terminal no 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 vai levar alguns minutos para ser concluída.

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

Seu 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

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

Em geral, use montagens de vinculação executando o contêiner com o argumento adicional --mount source=$(pwd),target=/workspace,type=bind para montar 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.

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

$ 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 como o diretório montado pelo contêiner.

Defina recursivamente o grupo para arquivos no diretório montado como 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 concede ao grupo do usuário do contêiner permissões de leitura, gravação e execução em todos os arquivos do diretório montado.

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

Esses comandos não afetam a permissão de novos arquivos criados pelo usuário host. Não se esqueça 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 permissões em arquivos criados pelo usuário do contêiner.

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

3. Play Console do Google Home

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 da Connectivity Standards Alliance (Aliança) funciona no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser provisionados 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:

  1. Clique em Criar projeto.
  2. Insira um nome exclusivo para o projeto e clique em Criar projeto. Caixa de diálogo "Criar projeto"
  3. Clique em + Adicionar integração para acessar a tela Recursos do Matter, onde você pode consultar a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
  4. Quando estiver tudo pronto, clique em Próxima: desenvolver, que mostra 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 escolha o tipo no menu suspenso (neste caso, Light).
  8. 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. Depois, clique em Salvar na página seguinte. Use esses valores exatos de VID/PID, já que as etapas posteriores do codelab dependem deles.
    Como configurar um projeto
  9. Agora você vai encontrar sua integração 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 mudar o VID ou PID depois, também será necessário reiniciar o dispositivo após salvar o projeto para que a mudança entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para conferir as 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árias amostras disponíveis, mas o foco deste codelab é o Chef.

O Chef é:

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

Navegue até a pasta de exemplo do Chef e faça seu primeiro build 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 aqui são:

  • -d: define o tipo de dispositivo a ser usado. Neste caso, estamos criando um app de iluminação com controles de liga/desliga 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, o ZAP cria automaticamente um código que será incorporado ao build e 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 do modelo de dados.
  • -t linux: plataforma segmentada. As plataformas compatíveis são linux, nrfconnect e esp32. Execute ./chef.py -h para conferir todos os comandos disponíveis e as plataformas de destino compatíveis. linux é usado para dispositivos virtuais do Matter.

Executar o dispositivo

O Matter usa a porta TCP/UDP 5540. Portanto, se você tiver um firewall em execução no computador, desative-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 ligado. Agora vamos nos concentrar no app Google Home para provisionar seu dispositivo no Google Home.

Parar o dispositivo

Se precisar parar o dispositivo, saia do programa com CTRL+C. Se o app não sair, talvez seja necessário usar CTRL+\ também.

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

Se você quiser repetir todo o processo de comissionamento do início, exclua esses arquivos executando o seguinte comando:

$ rm /tmp/chip*

5. Configurar o dispositivo

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

Nest Hub

É necessário um hub para comissionar o dispositivo no Matter. É um dispositivo Google Nest, como o Nest Hub (2ª geração), que é compatível com o Matter e serve 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 inclusão, 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 do 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 Home Graph do Google representa sua estrutura.

Ver um QR code

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

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 vai procurar 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 o QR code 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 vai aparecer como um novo ícone no app Google Home.

Lâmpada pareada no app Google Home

Solução de problemas

O provisionamento 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.

A configuração falha após "Verificando seu 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, teste o controle do dispositivo de diferentes maneiras:

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

Google Assistente

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

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

App Google Home

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

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

7. Parabéns!

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

Neste codelab, você aprendeu a:

  • Instale um ambiente de desenvolvimento do Matter.
  • Crie e execute um dispositivo virtual do Matter.
  • Provisione e controle seu dispositivo virtual no Google Home.

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