Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Complemento Matter

¿Qué es Matter Plugin

El complemento Matter es una implementación de referencia creada con la Plugin de protocolo personalizado función del SDK de Managed Integrations Hub. Permite que su hub controle los dispositivos Matter tanto de forma local en la misma red, siguiendo las especificaciones de Matter, como de forma remota mediante integraciones gestionadas.

El complemento Matter está incluido en el SDK de Hub. Se comunica con los dispositivos Matter, implementa las funcionalidades de Matter Controller y expone una ruta de control remoto mediante integraciones gestionadas.

chip-tool es un controlador de referencia basado en la línea de comandos de connectedhomeip. Actúa como si fuera una estructura Matter, ya que permite poner Commissioner/Controller en marcha dispositivos, read/write atributos e invocar comandos, y está diseñado para pruebas de desarrollo e interoperabilidad. En esta guía, el complemento Matter utilizará una herramienta de chip para controlar el dispositivo Matter y también mostrará la puesta en marcha de Matter desde la aplicación móvil.

El alcance de esta distribución no incluye una aplicación móvil de producción, ni cubre las actividades de certificación y producción, como las pruebas de laboratorio y la certificación de la CSA. Estas siguen siendo parte del proceso de desarrollo de sus productos.

¿Cómo crear el complemento Matter

El complemento Matter tiene las siguientes dependencias además del SDK de Hub:

Configure el repositorio con el siguiente comando:

cd IotMI-DeviceSDK-MatterPlugin  
mkdir build  
cd build  
cmake ..

A continuación, compruébelo con el siguiente comando:

cmake --build .

Tras la compilación, añada la ruta de la biblioteca a LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/path/to/libraries:$LD_LIBRARY_PATH

Inicio rápido: configurar y ejecutar el complemento Matter

Siga los pasos que se indican a continuación para configurar el complemento Matter y la solución Matter correspondiente. El flujo se basa en dos máquinas: una Hub (que ejecuta el Hub SDK y el complemento Matter) y una Raspberry Pi, que representa la «aplicación móvil» para la puesta en marcha y el control básico.

Administración de identificadores de nodos

En Matter, cada nodo de una estructura (incluidos los dispositivos, los controladores y los comisionados) debe tener un ID de nodo único. Para evitar colisiones, se requiere una política de asignación coherente. En esta guía, los ID de nodo se asignan manualmente; en producción, debe gestionar los ID de nodo correctamente.

Para los ejemplos de este documento, la herramienta de chip del Hub (utilizada por el complemento Matter) usa el ID de nodo predeterminado112233, y la herramienta de chip de la aplicación móvil Raspberry Pi usa el ID de nodo. 123456 A los dispositivos recién puestos en servicio se les asignan identificadores de nodo no conflictivos en la misma estructura (por ejemplo, 101 en la guía de inicio rápido).

Requisitos previos

Antes de comenzar, asegúrese de que dispone de lo siguiente:

Paso 1. Prepara la Raspberry Pi (que representa la aplicación móvil)

La cadena generada se almacena en: $HOME/iotmi/matter/chip_tool_config.alpha.ini

Copiarás este archivo en el Hub más adelante.

Paso 2. Prepara el Hub (que ejecuta el complemento Matter)

También necesitaremos el sha256sum de la herramienta de chips para usarlo más adelante. Puedes usar el siguiente comando para obtener el sha256sum:

sha256sum /path/to/chip-tool

Los siguientes pasos deben ejecutarse en la Raspberry Pi, es decir, en el Commissioner.

Paso 3. Encargue un dispositivo Matter (en la Raspberry Pi)

Utilice una herramienta de chip para poner en marcha el dispositivo utilizando su código QR decodificado y sus credenciales de aprovisionamiento. Wi-Fi En este ejemplo, el dispositivo usará el ID de nodo 101 y el ID del nodo comisionado sí. 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/

Notas:

chip-tool admite diferentes métodos de emparejamiento, incluido el emparejamiento de códigos QR o PIN con Thread o dispositivos. WiFi Para obtener más información sobre el comando de emparejamiento chip-tool, consulte la documentación oficial.

Paso 4. Conceda acceso al Hub en el dispositivo (actualice la ACL)

Tras la puesta en servicio, deje que el chip-herramienta del Hub controle el dispositivo. En este ejemplo, el ID de nodo 123456 (Raspberry Pi) tiene permiso de administrador (5) y el ID de nodo 112233 (Hub) tiene permiso de administración (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/

Paso 5. Cree un elemento gestionado para el dispositivo (User-Guided Configuración)

El ejemplo de respuesta incluye un ID de trabajo de configuración guiado por el usuario:

{  
    "Id": "USER_GUIDED_SETUP_JOB_ID",  
    "StartedAt": 1753683326.056  
}

Respuesta de ejemplo:

{  
    "Items": [  
        {  
            "DeviceTypes": [],  
            "DiscoveredAt": "2025-08-05T06:46:35.407000+08:00",  
            "AuthenticationMaterial": "<AUTH_MATERIAL>"  
        }  
    ]  
}

Ejemplo de respuesta (con el ID de elemento gestionado del 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"  
}

Paso 6. Controle el dispositivo mediante integraciones gestionadas

Usa el send-managed-thing-command comando para enviar un comando a tu dispositivo gestionado.

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"

Paso 7. Lee el estado del dispositivo

Envíe el siguiente comando para obtener el estado del dispositivo.

aws iot-managed-integrations get-managed-thing-state \  
    --managed-thing-id "DEVICE_MANAGED_THING_ID"

Ejemplo de resultado:

{  
    "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"  
                        }  
                    ]  
                }  
            ]  
        }  
    ]  
}

Paso 8. Elimina lo gestionado de tu hub

Tipos de dispositivos Matter compatibles

Añadir soporte para clústeres adicionales

Para ampliar el complemento Matter para que admita tipos y capacidades de dispositivos adicionales, modifique el archivo matter_action_converter.cpp siguiendo este patrón:

Patrón de implementación:

Utilice los clústeres existentes como plantillas:

Todos los clústeres compatibles (Identify,, OnOff, LevelControl, Thermostat DoorLock, ColorControl, BooleanState) siguen esta estructura. Revise las implementaciones existentes en matter_action_converter.cpp para comprender el patrón completo.

Integre diferentes soluciones de Matter Controller

Esta sección proporciona orientación sobre cómo integrar diferentes soluciones de Matter Controller con el complemento Matter. Describe los posibles enfoques y las consideraciones importantes, pero no proporciona un código de implementación detallado.

Hay dos formas principales de integrar las soluciones Matter Controller. La primera es usar el complemento Matter con una herramienta de chip personalizada. La segunda consiste en utilizar un Matter Controller de su elección e integrarlo con las integraciones gestionadas a través de la biblioteca de protocolos personalizados.

Uso del complemento Matter con un complemento personalizado Chip-Tool

En este enfoque, el complemento Matter se amplía para que funcione con una versión personalizada del Chip-Tool. Para lograrlo, es posible que tengas que modificar el código fuente del complemento Matter e introducir una lógica adicional:

Por lo que respecta al uso de chips, también se recomiendan las siguientes mejoras:

Uso de un controlador de materias existente con integraciones gestionadas

Si su Matter Controller no está basado en una herramienta basada en chips (por ejemplo, una solución basada en una Python-based implementación o una llamada de función), es posible que el enfoque STDIO no sea adecuado. En esos casos, puedes integrarte directamente con las integraciones gestionadas utilizando un complemento Matter como Plugin de protocolo personalizado referencia. Tenga en cuenta las siguientes consideraciones: