Matter Plugin

What is Matter Plugin

Matter Plugin is a reference implementation built using the Custom protocol plugin feature of the Managed integrations Hub SDK. It enables your hub to control Matter devices both locally on the same network, following the Matter specification, and remotely through Managed integrations.

The Matter Plugin is included in the Hub SDK. It communicates with Matter devices, implements Matter Controller functionalities, and exposes a remote control path via Managed integrations.

chip-tool is a command-line based reference controller from connectedhomeip. It acts as a Commissioner/Controller on a Matter fabric, allowing you to commission devices, read/write attributes, and invoke commands and is intended for development and interoperability testing. In this guide, the Matter Plugin will use chip-tool to control the Matter device and also demonstrate Matter commissioning from the Mobile App.

The scope of this distribution does not include a production mobile application, nor does it cover certification and production activities such as CSA lab test and certification. These remain part of your product development process.

How to build Matter Plugin

The Matter Plugin has the following dependencies in addition to the Hub SDK:

Configure the repo with the following command:

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

Then build it with the following command:

cmake --build .

After building, add the library path to LD_LIBRARY_PATH:

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

Quickstart: Set Up and Run the Matter Plugin

Follow the steps below to set up the Matter Plugin and the corresponding Matter solution. The flow assumes two machines: a Hub (running the Hub SDK + Matter Plugin) and a Raspberry Pi that represents the "Mobile App" for commissioning and basic control.

Node ID Management

In Matter, every node on a fabric—including devices, controllers, and commissioners—must have a unique Node ID. To avoid collisions, a consistent allocation policy is required. In this guide, Node IDs are assigned manually; in production, you should manage Node IDs properly.

For the examples in this document, the Hub's chip-tool (used by the Matter Plugin) uses default Node ID 112233, and the chip-tool on the Mobile App Raspberry Pi uses Node ID 123456. Newly commissioned devices are assigned non-conflicting Node IDs on the same fabric (for instance, 101 in the quickstart).

Prerequisites

Before you begin, ensure that you have the following:

Step 1. Prepare the Raspberry Pi (representing the Mobile App)

The generated chain is stored at: $HOME/iotmi/matter/chip_tool_config.alpha.ini

You'll copy this file to the Hub later.

Step 2. Prepare the Hub (which runs the Matter Plugin)

We'll also need the the sha256sum of the chip-tool for later use. You can use the following command to get the sha256sum:

sha256sum /path/to/chip-tool

The steps below are to be run on the Raspberry Pi i.e. the Commissioner.

Step 3. Commission a Matter device (on the Raspberry Pi)

Use chip-tool to commission the device using its decoded QR code and provision Wi-Fi credentials. In this example, the device will use node ID 101 and the commissioner node ID is 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/

Notes:

chip-tool supports different pairing methods, including QR code or PIN code pairing with Thread or WiFi devices. For more information about the chip-tool pairing command, see the official documentation.

Step 4. Grant Hub access on the device (update ACL)

After commissioning, allow the Hub's chip-tool to control the device. In this example, node ID 123456 (Raspberry Pi) has Admin permission (5) and node ID 112233 (Hub) has Manage permission (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/

Step 5. Create a managed thing for the device (User-Guided Setup)

Sample response includes a user-guided setup job ID:

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

Sample response:

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

Sample response (with device's managed thing ID):

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

Step 6. Control the device via Managed integrations

Use the send-managed-thing-command command to send a command to your managed thing.

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"

Step 7. Read device state

Send the following command to get the device state.

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

Sample result:

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

Step 8. Remove the managed thing from your hub

Supported Matter device types

Adding Support for Additional Clusters

To extend the Matter Plugin to support additional device types and capabilities, modify matter_action_converter.cpp following this pattern:

Implementation pattern:

Use existing clusters as templates:

All supported clusters (Identify, OnOff, LevelControl, DoorLock, Thermostat, ColorControl, BooleanState) follow this structure. Review the existing implementations in matter_action_converter.cpp to understand the complete pattern.

Integrate different Matter Controller solutions

This section provides guidance on how to integrate different Matter Controller solutions with the Matter Plugin. It outlines the possible approaches and important considerations but does not provide detailed implementation code.

There are two main ways to integrate Matter Controller solutions. The first one is using the Matter Plugin with a customized chip-tool. The second one is to use a Matter Controller of your choice and integration with Managed integrations through Custom Protocol library.

Using the Matter Plugin with a Customized Chip-Tool

In this approach, the Matter Plugin is extended to work with a customized version of the Chip-Tool. To achieve this, you may need to modify the Matter Plugin source code and introduce additional logic:

On the chip-tool side, the following enhancements are also recommended:

Using an Existing Matter Controller with Managed integrations

If your Matter Controller is not based on chip-tool (for example, a Python-based implementation or function-call–based solution), the STDIO approach may not be suitable. In such cases, you can integrate directly with Managed integrations using a Custom protocol plugin, while using the Matter Plugin as a reference. The following considerations apply: