As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Plugin Matter **Topics** + [O que é o Matter Plugin](#what-is-matter-plugin) + [Como criar o Matter Plugin](#how-to-build-matter-plugin) + [Início rápido: configurar e executar o plug-in Matter](#quickstart-setup-run-matter-plugin) + [As etapas abaixo devem ser executadas no Raspberry Pi, ou seja, no Comissário.](#raspberry-pi-commissioner-steps) + [Tipos de dispositivos Matter compatíveis](#supported-matter-device-types) + [Adicionando suporte para clusters adicionais](#adding-support-for-additional-clusters) + [Integre diferentes soluções do Matter Controller](#integrate-different-matter-controller-solutions) ## O que é o Matter Plugin O Matter Plugin é uma implementação de referência criada usando o [Plugin de protocolo personalizado](custom-protocol-plugin.md) recurso do Managed Integrations Hub SDK. Ele permite que seu hub controle os dispositivos Matter localmente na mesma rede, seguindo a especificação Matter, e remotamente por meio de integrações gerenciadas. ![Diagrama de arquitetura mostrando a integração do Matter Plugin com integrações gerenciadas Hub SDK](https://docs.aws.amazon.com/pt_br/iot-mi/latest/devguide/images/iotmi-matter-plugin.png) O plug-in Matter está incluído no Hub SDK. Ele se comunica com dispositivos Matter, implementa as funcionalidades do Matter Controller e expõe um caminho de controle remoto por meio de integrações gerenciadas. [chip-tool é um controlador de referência baseado em linha de comando da connectedhomeip.](https://github.com/project-chip/connectedhomeip) Ele atua como uma estrutura Commissioner/Controller on a Matter, permitindo que você comissione dispositivos, read/write atributos e invoque comandos, e é destinado ao desenvolvimento e testes de interoperabilidade. Neste guia, o Matter Plugin usará a ferramenta de chip para controlar o dispositivo Matter e também demonstrará o comissionamento do Matter a partir do aplicativo móvel. O escopo dessa distribuição não inclui um aplicativo móvel de produção, nem abrange atividades de certificação e produção, como testes e certificação de laboratório da CSA. Eles continuam sendo parte do seu processo de desenvolvimento de produtos. ## Como criar o Matter Plugin O plug-in Matter tem as seguintes dependências, além do Hub SDK: + OpenSSL 3.0.x: O requisito da versão do OpenSSL não é estrito — na maioria dos casos, a versão padrão do sistema funciona bem. + [nng v1.4.0](https://github.com/nanomsg/nng) + [CJSON v1.7.18](https://github.com/DaveGamble/cJSON) + [SDK de dispositivos AWS IoT CPP](https://github.com/aws/aws-iot-device-sdk-cpp-v2) V2 v1.33.0 + [SDK DA AWS CPP 1.11.433](https://github.com/aws/aws-sdk-cpp) Configure o repositório com o seguinte comando: ``` cd IotMI-DeviceSDK-MatterPlugin mkdir build cd build cmake .. ``` Em seguida, crie-o com o seguinte comando: ``` cmake --build . ``` Depois de criar, adicione o caminho da biblioteca a LD\_LIBRARY\_PATH: ``` export LD_LIBRARY_PATH=/path/to/libraries:$LD_LIBRARY_PATH ``` ## Início rápido: configurar e executar o plug-in Matter Siga as etapas abaixo para configurar o Matter Plugin e a solução Matter correspondente. O fluxo pressupõe duas máquinas: um Hub (executando o Hub SDK \+ Matter Plugin) e um Raspberry Pi que representa o “aplicativo móvel” para comissionamento e controle básico. ### Gerenciamento de ID de nó Na Matter, cada nó em uma malha, incluindo dispositivos, controladores e comissários, deve ter um ID de nó exclusivo. Para evitar colisões, é necessária uma política de alocação consistente. Neste guia, as IDs do Node são atribuídas manualmente; na produção, você deve gerenciar as IDs do Node adequadamente. Para os exemplos neste documento, a ferramenta de chip do Hub (usada pelo Matter Plugin) usa o Node ID padrão`112233`, e a ferramenta de chip no aplicativo móvel Raspberry Pi usa o Node ID. `123456` Os dispositivos recém-comissionados recebem IDs de nós não conflitantes na mesma estrutura (por exemplo, 101 no início rápido). ### Pré-requisitos Antes de começar, verifique se você tem: + Seu Hub já está integrado às integrações gerenciadas e o SDK do Hub está implantado (via script ou systemd). Se ainda não estiver integrado, siga [Configuração de integração do hub](managedintegrations-sdk-v2-cookbook-hubsetup.md) para Integrações gerenciadas e execute o SDK do [Instale e valide as integrações gerenciadas Hub SDK](managedintegrations-sdk-v2-cookbook-deployment.md) hub. Depois de integrado, anote o ID do item gerenciado do seu hub. Isso será necessário posteriormente. + Você tem um Raspberry Pi (ou qualquer máquina) que pode executar tanto a ferramenta de chip quanto o AWS CLI. + Você tem um dispositivo Matter para teste. Pode ser um dispositivo de matéria real ou um dispositivo virtual de matéria (por exemplo, aplicativo [de iluminação)](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/linux) ### Etapa 1. Prepare o Raspberry Pi (representando o aplicativo móvel) + Instale o AWS CLI e crie e instale a ferramenta de chip + Crie a ferramenta de chip seguindo o guia [oficial de construção da ferramenta de chip](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#building-from-source). A versão que verificamos é v1.4.2.0. + Instale o AWS CLI seguindo as instruções [oficiais](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + Prepare o armazenamento persistente para a ferramenta de chip ``` mkdir -p $HOME/iotmi/matter/ ``` + Gere a cadeia de certificados do comissário (atribua o ID do nó `123456` a essa ferramenta de chip) ``` cd connectedhomeip/ cd out/chip-tool/ ./chip-tool pairing get-commissioner-root-certificate \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` A cadeia gerada é armazenada em: `$HOME/iotmi/matter/chip_tool_config.alpha.ini` Você copiará esse arquivo para o Hub posteriormente. ### Etapa 2. Prepare o Hub (que executa o Matter Plugin) + Crie ou instale a ferramenta de chip no Hub (o plug-in Matter a usa para realizar operações do Matter). Você pode consultar o guia de [construção do chip-tool](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#building-from-source). A versão que verificamos é v1.4.2.0. Também precisaremos do sha256sum da ferramenta de chip para uso posterior. Você pode usar o comando a seguir para obter o sha256sum: ``` sha256sum /path/to/chip-tool ``` + Prepare o armazenamento e copie o arquivo do comissário do Raspberry Pi ``` mkdir -p $HOME/iotmi/matter/ # From Raspberry Pi to Hub (example): # scp $HOME/iotmi/matter/chip_tool_config.alpha.ini user@HUB_HOST:$HOME/iotmi/matter/ ``` + Execute o Matter Plugin (forneça o caminho da ferramenta de chip, seu SHA256 e a pasta de armazenamento) ``` ./iotmi_matter_plugin \ --chip-tool-path /path/to/chip-tool \ --sha256sum SHA256SUM_OF_THE_CHIP_TOOL \ --storage-folder $HOME/iotmi/matter/ \ --node-id 112233 ``` ## As etapas abaixo devem ser executadas no Raspberry Pi, ou seja, no Comissário. ### Etapa 3. Comissione um dispositivo Matter (no Raspberry Pi) Use a ferramenta de chip para comissionar o dispositivo usando seu código QR decodificado e credenciais de provisionamento. Wi-Fi Neste exemplo, o dispositivo usará o ID do nó 101 e o ID do nó do comissário é`123456`. ``` ./chip-tool pairing code-wifi 101 \ YOUR_WIFI_SSID YOUR_WIFI_PW \ MT:MFAA0W8C00UFQV2VL00 \ --bypass-attestation-verifier 1 \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` **Observações:** + `101`é o ID do nó Matter do dispositivo (você pode escolher um valor diferente). + `MT:MFAA0W8C00UFQV2VL00`é o conteúdo QR decodificado para o dispositivo. Para obter o contexto decodificado de um código QR, você precisa escolher um aplicativo ou biblioteca de código QR para decodificá-lo. Você também pode usar um serviço da Web que ofereça suporte à decodificação do código QR. + `-bypass-attestation-verifier 1`é apenas para uso em testes. Para produção, atualize a loja do PAA e realize verificações de atestado. O chip-tool suporta diferentes métodos de emparelhamento, incluindo código QR ou código PIN com Thread ou dispositivos. WiFi Para obter mais informações sobre o [comando de emparelhamento chip-tool](https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md#pairing), consulte a documentação oficial. ### Etapa 4: Conceder acesso ao Hub no dispositivo (atualizar ACL) Após o comissionamento, permita que a ferramenta de chip do Hub controle o dispositivo. Neste exemplo, o ID do nó `123456` (Raspberry Pi) tem permissão de administrador (5) e o ID do nó `112233` (Hub) tem permissão de gerenciamento (4). ``` chip-tool accesscontrol write acl \ '[{"fabricIndex":1,"privilege":5,"authMode":2,"subjects":[123456], "targets": null},{"fabricIndex":1,"privilege":4,"authMode":2,"subjects":[112233], "targets": null}]' \ 101 0 \ --commissioner-nodeid 123456 --storage-directory $HOME/iotmi/matter/ ``` ### Etapa 5. Crie uma coisa gerenciada para o dispositivo (User-Guided Configuração) + Comece a descoberta (substitua pelo ID de coisa gerenciada do seu Hub): ``` aws iot-managed-integrations start-device-discovery \ --discovery-type CUSTOM \ --custom-protocol-detail '{"Name": "Matter", "NodeId":"101", "FabricId":"1"}' \ --controller-identifier ``` O exemplo de resposta inclui um ID de tarefa de configuração guiado pelo usuário: ``` { "Id": "USER_GUIDED_SETUP_JOB_ID", "StartedAt": 1753683326.056 } ``` + Consulte os dispositivos descobertos usando o ID do trabalho: ``` aws iot-managed-integrations \ list-discovered-devices --identifier ``` Resposta de exemplo: ``` { "Items": [ { "DeviceTypes": [], "DiscoveredAt": "2025-08-05T06:46:35.407000+08:00", "AuthenticationMaterial": "" } ] } ``` + Crie uma coisa gerenciada para o dispositivo usando AuthenticationMaterial: ``` aws iot-managed-integrations create-managed-thing \ --role DEVICE \ --authentication-material-type DISCOVERED_DEVICE \ --authentication-material "" ``` Exemplo de resposta (com o ID do item gerenciado do dispositivo): ``` { "Id": "DEVICE_MANAGED_THING_ID", "Arn": "arn:aws:iotmanagedintegrations:eu-west-1:228183742813:managed-thing/515cf5a707ec41aaabb9914a1dd2889f", "CreatedAt": "2025-08-06T15:00:08.718000+08:00" } ``` ### Etapa 6. Controle o dispositivo por meio de integrações gerenciadas Use o `send-managed-thing-command` comando para enviar um comando para sua coisa gerenciada. ``` json=$(jq -cr '.|@json' < Envie o comando a seguir para obter o estado do dispositivo. ``` aws iot-managed-integrations get-managed-thing-state \ --managed-thing-id "DEVICE_MANAGED_THING_ID" ``` Resultado da amostra: ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "matter.OnOff@1.4", "name": "On/Off", "version": "1.4", "properties": [ { "value": { "lastChangedAt": "2025-08-14T13:16:02.132Z", "propertyValue": false }, "name": "OnOff" } ] } ] } ] } ``` ### Etapa 8. Remova a coisa gerenciada do seu hub + Remova a coisa gerenciada do seu hub com o seguinte comando ``` aws iot-managed-integrations delete-managed-thing \ --identifier "DEVICE_MANAGED_THING_ID" ``` + Desemparelhe o dispositivo do tecido do Raspberry Pi (se desejar): ``` ./chip-tool pairing unpair 101 \ --commissioner-nodeid 123456 \ --storage-directory $HOME/iotmi/matter/ ``` ## Tipos de dispositivos Matter compatíveis | Tipo de dispositivo relevante | Capacidades suportadas | | --- | --- | | [OnOffLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffPlug-inUnit.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (0x0006), Controle de [nível](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [DimmableLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmableLight.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (0x0006), Controle de [nível](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [ColorTemperatureLight](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorTemperatureLight.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)[, [On/Off (0x0006), controle de nível (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)[, controle de cores (0x0300)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/ColorControl.xml) | | [OnOffPlug-InUint](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffPlug-inUnit.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (0x0006), Controle de [nível](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [DimmablePlug-InUnit](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmablePlug-InUnit.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (0x0006), Controle de [nível](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [OnOffLightSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/OnOffLightSwitch.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)0x0006) | | [DimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DimmerSwitch.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [On/Off (0x0006), Controle de [nível](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml) (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml) | | [ColorDimmerSwitch](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/ColorDimmerSwitch.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml)[, [On/Off (0x0006), controle de nível (0x0008)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/OnOff.xml)[, controle de cores (0x0300)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/LevelControl.xml)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/ColorControl.xml) | | [DoorLock](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/DoorLock.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [fechadura da porta (](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/DoorLock.xml)0x0101) | | [Termostato](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/Thermostat.xml) | [Identifique (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [termostato](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Thermostat.xml) (0x0201) | | [WaterLeakDetector](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/device_types/WaterLeakDetector.xml) | [Identificar (0x0003)](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/Identify.xml), [estado booleano](https://github.com/project-chip/connectedhomeip/blob/master/data_model/1.4/clusters/BooleanState.xml) (0x0045) | ## Adicionando suporte para clusters adicionais Para estender o plug-in Matter para oferecer suporte a tipos e recursos adicionais de dispositivos, modifique **o matter\_action\_converter.cpp** seguindo este padrão: **Padrão de implementação:** 1. Defina mapeamentos para enums e bitmaps 1. Adicione UpdateState lógica para atributos graváveis 1. Adicionar processamento de comandos para ações de cluster 1. Adicionar análise de atributos para relatórios de estado **Use clusters existentes como modelos:** 1. **OnOff cluster** - Referência mais simples que mostra todos os quatro componentes com enumerações básicas, atributos graváveis, comandos e relatórios de atributos 1. **DoorLock cluster** - Exemplo complexo que demonstra vários tipos de enumeração, campos de bitmap, parâmetros de estrutura, parâmetros de comando opcionais e ampla cobertura de atributos Todos os clusters compatíveis (Identify, OnOff, LevelControl, DoorLock, Thermostat, ColorControl, BooleanState) seguem essa estrutura. Analise as implementações existentes em matter\_action\_converter.cpp para entender o padrão completo. ## Integre diferentes soluções do Matter Controller Esta seção fornece orientação sobre como integrar diferentes soluções do Matter Controller com o Matter Plugin. Ele descreve as possíveis abordagens e considerações importantes, mas não fornece um código de implementação detalhado. Há duas maneiras principais de integrar as soluções do Matter Controller. O primeiro é usar o Matter Plugin com uma ferramenta de chip personalizada. A segunda é usar um Matter Controller de sua escolha e integração com integrações gerenciadas por meio da biblioteca Custom Protocol. ### Usando o plug-in Matter com um personalizado Chip-Tool Nessa abordagem, o Matter Plugin é estendido para funcionar com uma versão personalizada do Chip-Tool. Para conseguir isso, talvez seja necessário modificar o código-fonte do Matter Plugin e introduzir uma lógica adicional: + Ajuste a lógica de análise STDIO: se sua ferramenta de chip personalizada gerar registros com um padrão diferente, atualize a lógica de análise adequadamente. + Implemente armazenamento seguro: o Matter Plugin fornece um mecanismo de armazenamento baseado em arquivos para informações do dispositivo. Para uso em produção, substitua isso por uma implementação de armazenamento mais segura ou aplique criptografia aos dados. E também precisa de procedimentos de limpeza adequados quando o Matter Plugin é desinstalado. + Implemente assinatura binária e proteção de integridade: em implantações de produção, você deve aplicar a proteção de integridade tanto para a ferramenta de chip personalizada quanto para o plug-in Matter estendido. Isso inclui assinar os binários como parte do processo de lançamento do software, verificar assinaturas durante a inicialização e integrar recursos de segurança da plataforma, como inicialização segura ou ferramentas de integridade. OS-level + Introduza a limitação de task/event taxa: Para evitar sobrecarga, certifique-se de que o Matter Plugin inclua uma limitação adequada da taxa de tarefas e eventos. Nas implantações de produção, você também deve adicionar métricas básicas e monitoramento para detectar padrões de atualização anormais e limitar ou suspender temporariamente o dispositivo ou a assinatura afetados. Esse comportamento semelhante ao de um disjuntor não é fornecido pela implementação de referência e deve ser implementado pelo cliente. + Integre diretamente a lógica da função principal do chip-tool: Se você preferir não confiar no STDIO, você pode integrar a função principal do chip-tool ao plug-in Matter. A input/output lógica padrão pode então ser conectada às read/write funções da ChptoolProc classe. + Support a geração de código: implemente um mecanismo para lidar com as atualizações da versão da especificação Matter por meio da geração de código. + Implemente os recursos do Matter Administration, incluindo: + Atribuição de IDs de nós aos dispositivos Commissioner, Controller e Matter. + Gerenciando vários tecidos. No lado da ferramenta de corte, os seguintes aprimoramentos também são recomendados: + Use armazenamento seguro: o chip-tool armazena certificados, chaves privadas e estatísticas do Matter em diretórios locais. Substitua isso por uma implementação segura. + Ativar processamento paralelo: por padrão, Chip-Tool executa um comando por vez. Adicionar suporte à execução paralela pode melhorar a eficiência em determinados cenários. ### Usando um controlador de matéria existente com integrações gerenciadas Se o seu Matter Controller não for baseado em uma ferramenta de chip (por exemplo, uma Python-based implementação ou solução baseada em chamada de função), a abordagem STDIO pode não ser adequada. Nesses casos, você pode se integrar diretamente às integrações gerenciadas usando um[Plugin de protocolo personalizado](custom-protocol-plugin.md), enquanto usa o Matter Plugin como referência. As seguintes considerações se aplicam: + Mantenha as IDs de malha e de nós: garanta que os metadados do dispositivo, como adding/removing dispositivos e atributos de cache, sejam mantidos de forma consistente. + Gerenciar assinaturas: cada dispositivo deve manter até uma assinatura ativa, para que seu estado possa ser atualizado continuamente. + Propagar mudanças de estado: quando um dispositivo atualiza seu estado, verifique as alterações e propague eventos para integrações gerenciadas. + Implemente um tradutor do modelo de dados Matter: embora as integrações gerenciadas usem o modelo de dados Matter, sua representação está no formato JSON. É necessário um tradutor para mapear entre o formato do modelo de dados Matter e a representação JSON.