Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Plugin Matter

Cos'è Matter Plugin

Matter Plugin è un'implementazione di riferimento creata utilizzando la Plugin di protocollo personalizzato funzionalità dell'SDK Managed Integrations Hub. Consente all'hub di controllare i dispositivi Matter sia localmente sulla stessa rete, seguendo le specifiche Matter, sia in remoto tramite integrazioni gestite.

Il plugin Matter è incluso nell'Hub SDK. Comunica con i dispositivi Matter, implementa le funzionalità di Matter Controller ed espone un percorso di controllo remoto tramite integrazioni gestite.

chip-tool è un controller di riferimento basato sulla riga di comando di connectedhomeip. Funziona come una struttura Commissioner/Controller on a Matter, che consente di commissionare dispositivi, read/write attributi e richiamare comandi ed è destinato allo sviluppo e ai test di interoperabilità. In questa guida, il plugin Matter utilizzerà il chip-tool per controllare il dispositivo Matter e dimostrerà anche la messa in servizio di Matter dall'app mobile.

L'ambito di questa distribuzione non include un'applicazione mobile di produzione, né copre attività di certificazione e produzione come i test e la certificazione di laboratorio CSA. Queste restano parte del processo di sviluppo del prodotto.

Come creare il plugin Matter

Il plugin Matter ha le seguenti dipendenze oltre all'Hub SDK:

Configura il repository con il seguente comando:

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

Quindi costruiscilo con il seguente comando:

cmake --build .

Dopo la creazione, aggiungi il percorso della libreria a LD_LIBRARY_PATH:

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

Quickstart: configura ed esegui il plugin Matter

Segui i passaggi seguenti per configurare il plugin Matter e la soluzione Matter corrispondente. Il flusso presuppone due macchine: un Hub (che esegue Hub SDK + Matter Plugin) e un Raspberry Pi che rappresenta la «Mobile App» per la messa in servizio e il controllo di base.

Gestione degli ID dei nodi

In Matter, ogni nodo di una struttura, inclusi dispositivi, controller e commissari, deve avere un ID di nodo univoco. Per evitare collisioni, è necessaria una politica di allocazione coerente. In questa guida, gli ID dei nodi vengono assegnati manualmente; in produzione, è necessario gestire correttamente gli ID dei nodi.

Per gli esempi di questo documento, il chip-tool dell'Hub (utilizzato dal plugin Matter) utilizza il Node ID 112233 predefinito e il chip-tool sull'app mobile Raspberry Pi utilizza Node ID. 123456 Ai dispositivi appena messi in servizio vengono assegnati ID di nodo non in conflitto sullo stesso tessuto (ad esempio, 101 nel quickstart).

Prerequisiti

Prima di iniziare, assicurati di disporre di quanto riportato di seguito:

Passaggio 1. Prepara il Raspberry Pi (che rappresenta l'app mobile)

La catena generata è memorizzata in: $HOME/iotmi/matter/chip_tool_config.alpha.ini

Copierai questo file nell'Hub in un secondo momento.

Passaggio 2. Prepara l'Hub (che esegue il plugin Matter)

Avremo anche bisogno dello sha256sum del chip-tool per un uso successivo. È possibile utilizzare il seguente comando per ottenere lo sha256sum:

sha256sum /path/to/chip-tool

I passaggi seguenti devono essere eseguiti su Raspberry Pi, ovvero su Commissioner.

Fase 3. Commissiona un dispositivo Matter (sul Raspberry Pi)

Utilizza chip-tool per mettere in servizio il dispositivo utilizzando il codice QR decodificato e le credenziali di fornitura. Wi-Fi In questo esempio, il dispositivo utilizzerà l'ID del nodo 101 e l'ID del nodo commissario è. 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/

Note:

chip-tool supporta diversi metodi di associazione, tra cui l'associazione del codice QR o del codice PIN con Thread o dispositivi. WiFi Per ulteriori informazioni sul comando di associazione chip-tool, consulta la documentazione ufficiale.

Passaggio 4. Concedi l'accesso a Hub sul dispositivo (aggiorna ACL)

Dopo la messa in servizio, consenti al chip-tool dell'Hub di controllare il dispositivo. In questo esempio, l'ID del nodo 123456 (Raspberry Pi) ha l'autorizzazione di amministratore (5) e l'ID del nodo 112233 (Hub) ha l'autorizzazione di gestione (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/

Fase 5. Crea un oggetto gestito per il dispositivo (User-Guided Configurazione)

La risposta di esempio include un ID del lavoro di configurazione guidato dall'utente:

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

Risposta di esempio:

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

Esempio di risposta (con l'ID dell'oggetto gestito 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"  
}

Fase 6. Controlla il dispositivo tramite integrazioni gestite

Usa il send-managed-thing-command comando per inviare un comando alla tua cosa gestita.

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"

Fase 7. Leggi lo stato del dispositivo

Invia il seguente comando per ottenere lo stato del dispositivo.

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

Esempio di risultato:

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

Fase 8. Rimuovi la cosa gestita dal tuo hub

Tipi di dispositivi Matter supportati

Aggiungere il supporto per cluster aggiuntivi

Per estendere il plugin Matter al supporto di tipi e funzionalità di dispositivi aggiuntivi, modifica matter_action_converter.cpp seguendo questo schema:

Modello di implementazione:

Usa i cluster esistenti come modelli:

Tutti i cluster supportati (Identify,,, OnOff, Thermostat LevelControl DoorLock,,) seguono questa struttura. ColorControl BooleanState Esamina le implementazioni esistenti in matter_action_converter.cpp per comprendere lo schema completo.

Integra diverse soluzioni Matter Controller

Questa sezione fornisce indicazioni su come integrare diverse soluzioni Matter Controller con il Matter Plugin. Descrive i possibili approcci e le considerazioni importanti, ma non fornisce un codice di implementazione dettagliato.

Esistono due modi principali per integrare le soluzioni Matter Controller. Il primo consiste nell'utilizzare il Matter Plugin con uno strumento di chip personalizzato. Il secondo consiste nell'utilizzare un Matter Controller a scelta e nell'integrazione con le integrazioni gestite tramite la libreria Custom Protocol.

Utilizzo del plug-in Matter con un file personalizzato Chip-Tool

In questo approccio, il plugin Matter viene esteso per funzionare con una versione personalizzata di Chip-Tool. Per raggiungere questo obiettivo, potrebbe essere necessario modificare il codice sorgente del plugin Matter e introdurre una logica aggiuntiva:

Per quanto riguarda i chip tool, sono consigliati anche i seguenti miglioramenti:

Utilizzo di un Matter Controller esistente con integrazioni gestite

Se il tuo Matter Controller non è basato su chip-tool (ad esempio, un' Python-based implementazione o una soluzione basata su chiamate di funzioni), l'approccio STDIO potrebbe non essere adatto. In questi casi, è possibile effettuare l'integrazione diretta con le integrazioni gestite utilizzando un plug-in Matter come Plugin di protocollo personalizzato riferimento. Tieni presente le seguenti considerazioni: