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

O que é o Matter Plugin

O Matter Plugin é uma implementação de referência criada usando o Plugin de protocolo personalizado 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.

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. 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:

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ão112233, 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:

Etapa 1. Prepare o Raspberry Pi (representando o aplicativo móvel)

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)

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

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:

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, 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)

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  
}

Resposta de exemplo:

{  
    "Items": [  
        {  
            "DeviceTypes": [],  
            "DiscoveredAt": "2025-08-05T06:46:35.407000+08:00",  
            "AuthenticationMaterial": "<AUTH_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' <<EOF  
[  
  {  
    "endpointId": "1",  
    "capabilities": [  
      {  
        "id": "matter.OnOff@1.4",  
        "name": "On/Off",  
        "version": "1",  
        "actions": [  
          {  
            "name": "Toggle",  
            "parameters": {}  
          }  
        ]  
      }  
    ]  
  }  
]  
EOF  
)  
aws iot-managed-integrations send-managed-thing-command \  
    --managed-thing-id "DEVICE_MANAGED_THING_ID" \  
    --endpoints "$json"

Etapa 7. Leia o estado do dispositivo

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

Tipos de dispositivos Matter compatíveis

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:

Use clusters existentes como modelos:

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:

No lado da ferramenta de corte, os seguintes aprimoramentos também são recomendados:

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 umPlugin de protocolo personalizado, enquanto usa o Matter Plugin como referência. As seguintes considerações se aplicam: