Criar um dispositivo virtual 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 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 do Matter que é executado no seu computador
  • Como configurar e controlar o dispositivo virtual do Matter 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 que executa o sistema de janelas X11.
  • Docker.
  • Git.
  • Conhecimento básico do Linux.
    • Observação: o shell presumido para todos os comandos neste codelab é o BASH.

2. Configurar o ambiente

Verificar o hardware

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

Além disso, estas instruções pressupõem 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 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 estamos usando abaixo.
    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 nesse contêiner. Localize a imagem a ser usada que corresponda à nossa versão do SDK, como esta:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Se você estiver usando o mesmo commit, verá ghcr.io/project-chip/chip-build:66Primeiro, encaminhe as portas xhost para que possamos usar aplicativos de interface:
    xhost local:1000
    Em seguida, inicie o contêiner com os recursos apropriados encaminhados do host (nosso checkout do SDK, rede e recursos de exibição/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 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 que ele transmita o tráfego mDNS do host para o contêiner e compartilhe 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.
  • --mount ativa o SDK que verificamos anteriormente no contêiner.
  • --workdir define o diretório de trabalho na inicialização para o diretório do SDK ativado.

Opcionalmente, você pode executar uma segunda instância de sessão de terminal:

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

Parar e iniciar o contêiner do Docker do Matter

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

Por esse motivo, depois de criar o 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 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 leva vários 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 máquina host de dentro do contêiner usando uma montagem de vinculação. Você também pode gravar arquivos no diretório ativado 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 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 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 ativado pelo contêiner.

Defina recursivamente o grupo para arquivos no diretório ativado 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 de usuários do contêiner permissões de leitura, gravação e execução em todos os arquivos do 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 de novos arquivos criados no host conforme necessário.

Você pode adicionar o usuário do host ao grupo de usuários 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. Google Home Developer Console

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 passado pela certificação do Connectivity Standards Alliance (Alliance) funciona no ecossistema do Google Home. Os dispositivos em desenvolvimento que não foram certificados podem ser configurados 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 de projeto exclusivo e clique em Criar projeto. Caixa de diálogo "Criar projeto"
  3. Clique em + Adicionar integração, que leva à tela Recursos do Matter, onde você pode conferir a documentação de desenvolvimento do Matter e ler sobre algumas ferramentas.
  4. Quando estiver tudo pronto para continuar, 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 de dispositivo 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 e, em seguida, clique em Salvar na página a seguir. Use esses valores exatos de VID/PID. As etapas posteriores do codelab dependem deles.
    Como configurar um projeto
  9. Agora, sua integração vai aparecer em Integrações do Matter.
  10. Reinicialize 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 o PID mais tarde, também será necessário reiniciar depois de salvar o projeto para que a mudança entre em vigor. Consulte Reiniciar dispositivos Google Nest ou Google Wifi para conferir instruções detalhadas de reinicialização.

4. Criar um dispositivo

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

O Chef é:

  • Um app de exemplo que fornece uma interface de terminal, com 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 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 nível e de ativação/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 a 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 do 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. Você pode executar ./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 recebidas 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 nos concentrar no app Google Home para configurar o dispositivo no Google Home.

Parar o dispositivo

Se você precisar parar o dispositivo, poderá sair do programa com CTRL+C. Se o app não sair, talvez seja necessário usar CTRL+\.

As credenciais do 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 configuração desde o início, será necessário excluir esses arquivos executando o seguinte comando:

$ rm /tmp/chip*

5. Configurar o dispositivo

Observação: essa etapa só será bem-sucedida se você já tiver configurado o projeto no Google Home Developer Console.

Nest Hub

Um hub é necessário para configurar o dispositivo no Fabric do Matter. Esse é um dispositivo Google Nest, como o Nest Hub (2ª geração), que é compatível com o Matter e que vai servir como um roteador de borda para dispositivos compatíveis com o Thread e como um caminho de atendimento local para o roteamento de intents de casa inteligente.

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

Antes de iniciar o processo de configuraçã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 que o 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 Google Home Graph representa sua estrutura.

Gerar um QR code

O processo de configuração 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 a configuração.

Realizar a operação de configuraçã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 QR code do dispositivo ou para 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 do Matter será configurado e vai aparecer como um novo ícone no app Google Home.

Lâmpada pareada no app Google Home

Solução de problemas

A configuração 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.

A configuração falha após "Procurando seu dispositivo" por um longo período

6. Controlar o dispositivo

Depois que o dispositivo compatível com o Matter for configurado 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.
  • 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, acenda 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 mais exemplos de comandos.

App Google Home

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

  • Instalar um ambiente de desenvolvimento do Matter.
  • Criar e executar um dispositivo virtual do Matter.
  • Configurar e controlar o dispositivo virtual no Google Home.

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