기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Matter 플러그인

Matter 플러그인이란?

Matter 플러그인은 Managed integrations Hub SDK의 사용자 지정 프로토콜 플러그인 기능을 사용하여 구축된 참조 구현입니다. 이를 통해 허브는 Matter 사양에 따라 동일한 네트워크에서 로컬로, 그리고 관리형 통합을 통해 원격으로 Matter 디바이스를 제어할 수 있습니다.

Matter 플러그인은 Hub SDK에 포함되어 있습니다. Matter 디바이스와 통신하고, Matter Controller 기능을 구현하고, 관리형 통합을 통해 원격 제어 경로를 노출합니다.

chip-tool은 connectedhomeip의 명령줄 기반 참조 컨트롤러입니다. Matter 패브릭에서 커미셔너/컨트롤러 역할을 하므로 디바이스를 커미셔닝하고, 속성을 읽고, 쓰고, 명령을 호출할 수 있으며, 개발 및 상호 운용성 테스트를 위한 것입니다. 이 가이드에서 Matter 플러그인은 칩 도구를 사용하여 Matter 디바이스를 제어하고 모바일 앱에서 Matter 커미셔닝을 시연합니다.

이 배포의 범위에는 프로덕션 모바일 애플리케이션이 포함되지 않으며 CSA 랩 테스트 및 인증과 같은 인증 및 프로덕션 활동을 다루지 않습니다. 이는 제품 개발 프로세스의 일부로 유지됩니다.

Matter 플러그인을 빌드하는 방법

Matter 플러그인에는 Hub SDK 외에도 다음과 같은 종속성이 있습니다.

다음 명령을 사용하여 리포지토리를 구성합니다.

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

그런 다음 다음 명령을 사용하여 빌드합니다.

cmake --build .

빌드 후 라이브러리 경로를 LD_LIBRARY_PATH에 추가합니다.

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

빠른 시작: Matter 플러그인 설정 및 실행

아래 단계에 따라 Matter 플러그인과 해당 Matter 솔루션을 설정합니다. 이 흐름은 두 시스템, 즉 Hub( Hub SDK + Matter 플러그인 실행)와 커미셔닝 및 기본 제어를 위한 "모바일 앱"을 나타내는 Raspberry Pi를 가정합니다.

노드 ID 관리

특히 디바이스, 컨트롤러, 커미셔너 등 패브릭의 모든 노드에는 고유한 노드 ID가 있어야 합니다. 충돌을 방지하려면 일관된 할당 정책이 필요합니다. 이 가이드에서는 노드 IDs 수동으로 할당되므로 프로덕션 환경에서 노드 IDs 올바르게 관리해야 합니다.

이 문서의 예제에서 Hub의 칩 도구( Matter 플러그인에서 사용)는 기본 노드 ID를 사용하고 Mobile App Raspberry Pi의 112233칩 도구는 노드 ID를 사용합니다123456. 새로 커미셔닝된 디바이스에는 동일한 패브릭에 충돌하지 않는 노드 IDs가 할당됩니다(예: 빠른 시작 시 101).

사전 조건

시작하기 전에 다음이 있는지 확인하십시오.

1단계. Raspberry Pi 준비(모바일 앱을 나타냄)

생성된 체인은 다음 위치에 저장됩니다. $HOME/iotmi/matter/chip_tool_config.alpha.ini

나중에이 파일을 Hub에 복사합니다.

2단계. 허브 준비( Matter 플러그인 실행)

나중에 사용할 수 있도록 칩 도구의 sha256sum도 필요합니다. 다음 명령을 사용하여 sha256sum을 가져올 수 있습니다.

sha256sum /path/to/chip-tool

아래 단계는 Raspberry Pi, 즉 커미셔너에서 실행해야 합니다.

3단계. Matter 디바이스 커미셔닝(Raspberry Pi)

칩 도구를 사용하여 디코딩된 QR 코드를 사용하여 디바이스를 커미셔닝하고 Wi-Fi 자격 증명을 프로비저닝합니다. 이 예제에서 디바이스는 노드 ID 101을 사용하고 커미셔너 노드 ID는 입니다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/

참고:

chip-tool은 Thread 또는 WiFi 디바이스와의 QR 코드 또는 PIN 코드 페어링을 비롯한 다양한 페어링 방법을 지원합니다. 칩 도구 페어링 명령에 대한 자세한 내용은 공식 설명서를 참조하세요.

4단계. 디바이스에 대한 Grant Hub 액세스 권한(ACL 업데이트)

커미셔닝 후 Hub의 칩 도구가 디바이스를 제어할 수 있도록 합니다. 이 예제에서 노드 ID123456(Raspberry Pi)에는 관리자 권한(5)이 있고 노드 ID112233(Hub)에는 관리 권한(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/

5단계. 디바이스에 대한 관리형 사물 생성(사용자 가이드 설정)

샘플 응답에는 사용자 안내 설정 작업 ID가 포함됩니다.

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

샘플 응답:

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

샘플 응답(디바이스의 관리형 사물 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"  
}

6단계. 관리형 통합을 통해 디바이스 제어

send-managed-thing-command 명령을 사용하여 관리형 사물에 명령을 보냅니다.

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"

7단계. 디바이스 상태 읽기

다음 명령을 전송하여 디바이스 상태를 가져옵니다.

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

샘플 결과:

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

8단계. 허브에서 관리형 사물 제거

지원되는 Matter 디바이스 유형

추가 클러스터에 대한 지원 추가

Matter 플러그인을 확장하여 추가 디바이스 유형 및 기능을 지원하려면 다음 패턴에 따라 matter_action_converter.cpp를 수정합니다.

구현 패턴:

기존 클러스터를 템플릿으로 사용:

지원되는 모든 클러스터(Identify, OnOff, LevelControl, DoorLock, 온도 조절기, ColorControl, BooleanState)는이 구조를 따릅니다. matter_action_converter.cpp의 기존 구현을 검토하여 전체 패턴을 이해합니다.

다양한 Matter Controller 솔루션 통합

이 섹션에서는 다양한 Matter Controller 솔루션을 Matter 플러그인과 통합하는 방법에 대한 지침을 제공합니다. 가능한 접근 방식과 중요한 고려 사항을 간략하게 설명하지만 자세한 구현 코드는 제공하지 않습니다.

Matter Controller 솔루션을 통합하는 두 가지 주요 방법이 있습니다. 첫 번째는 Matter 플러그인을 사용자 지정된 칩 도구와 함께 사용하는 것입니다. 두 번째는 원하는 Matter Controller를 사용하고 사용자 지정 프로토콜 라이브러리를 통해 관리형 통합과 통합하는 것입니다.

사용자 지정 칩 도구와 함께 Matter 플러그인 사용

이 접근 방식에서는 Matter 플러그인이 Chip-Tool의 사용자 지정 버전으로 작동하도록 확장됩니다. 이를 위해 Matter 플러그인 소스 코드를 수정하고 추가 로직을 도입해야 할 수 있습니다.

칩 도구 측에서는 다음과 같은 개선 사항도 권장됩니다.

관리형 통합과 함께 기존 Matter Controller 사용

Matter Controller가 칩 도구(예: Python 기반 구현 또는 함수 호출 기반 솔루션)를 기반으로 하지 않는 경우 STDIO 접근 방식이 적합하지 않을 수 있습니다. 이러한 경우 Matter 플러그인을 참조로 사용사용자 지정 프로토콜 플러그인하면서를 사용하여 관리형 통합과 직접 통합할 수 있습니다. 다음 사항을 고려하세요.