Matter 프로토콜 코덱

C 구조체 스키마 사용 가이드

C 구조체 스키마 모드를 사용하면 익숙한 C/C++ 구문을 사용하여 데이터 구조를 정의할 수 있습니다. 파서는 구조체 정의에서 필드 이름, 타입, TLV 태그를 추출한 후 데이터 입력 및 TLV 인코딩을 위한 시각적 폼을 생성합니다.

지원되는 구문

// Supported syntax forms:
typedef struct { ... } StructName;
typedef struct Tag { ... } StructName;
struct StructName { ... };

지원되는 데이터 타입

태그 주석 방법

주석을 사용하여 각 필드의 TLV 컨텍스트 태그를 지정합니다. 태그가 지정되지 않으면 0부터 자동으로 할당됩니다.

uint8_t field1;     // tag 0
uint16_t field2;    // tag: 1
uint32_t field3;    /* tag 2 */
@tag(3) uint64_t field4;

배열 지원

고정 크기 배열(예: uint32_t data[4])과 가변 크기 배열(예: uint8_t data[])이 지원됩니다. 폼에서는 동적 배열 요소 관리를 위한 '항목 추가' 버튼이 제공됩니다.

uint32_t subjects[4];  // Fixed-size array (max 4 items)
uint8_t data[];        // Variable-size array

현재 제한 사항

• 전처리기 지시문(#define, #ifdef)은 지원되지 않습니다
• typedef 별칭(예: typedef uint8_t BYTE)은 지원되지 않습니다
• 열거형, 공용체, 비트 필드는 지원되지 않습니다
• 중첩된 구조체 편집은 한 레벨로 제한됩니다
• 익명 구조체는 지원되지 않습니다

Matter TLV 인코딩 형식

Matter는 구조화된 데이터 직렬화를 위해 컴팩트한 TLV(Tag-Length-Value) 바이너리 인코딩 방식을 사용합니다. 이 형식은 인터랙션 모델 메시지, 디바이스 인증 데이터, 커미셔닝 페이로드 등 프로토콜 스택 전반에 걸쳐 사용됩니다.

제어 바이트 구조

제어 바이트는 각 TLV 요소의 첫 번째 바이트입니다. 하위 5비트는 요소 타입을, 상위 3비트는 태그 형식을 지정합니다.

TLV 요소 타입

요소 타입 필드는 값 부분의 인코딩 방법을 결정합니다. 정수 타입은 1, 2, 4, 8바이트를 사용합니다. 불리언 값은 타입 필드에 직접 인코딩되어 값 바이트가 불필요합니다. 문자열과 바이트 배열은 길이 접두사 뒤에 데이터가 따릅니다.

온보딩 페이로드 형식

Matter 디바이스 커미셔닝 시, 설정 정보는 QR 코드에 포함되거나 숫자 수동 페어링 코드로 제공됩니다. QR 코드 페이로드는 "MT:" 접두사 뒤에 Base38 인코딩된 바이너리 문자열이 이어지며, 버전, 벤더 ID, 제품 ID, 커미셔닝 플로우, 검색 방법, 디스크리미네이터, 설정 패스코드가 포함됩니다.

Base38 인코딩

Matter QR 코드 페이로드는 Base38 문자 집합(0-9, A-Z, -.)을 사용하여 효율적인 영숫자 표현을 합니다. 3바이트마다 5개의 Base38 문자로 인코딩됩니다.

수동 페어링 코드

11자리 수동 페어링 코드는 QR 코드 스캔이 불가능할 때 대체 커미셔닝 수단을 제공합니다. 디스크리미네이터(짧은 형식), 설정 패스코드, Verhoeff 체크 디짓이 인코딩됩니다. 21자리 버전은 벤더 ID와 제품 ID를 추가로 포함합니다.

Verhoeff 체크 디짓

수동 페어링 코드는 Verhoeff 알고리즘을 사용하여 오류를 감지합니다. 이 알고리즘은 모든 단일 자릿수 오류와 대부분의 인접 전치 오류를 감지할 수 있습니다.

개발 활용 사례

• 디바이스 통신에서 캡처한 Matter TLV 페이로드 디버깅
• 인터랙션 모델 요청 및 응답 메시지 검사
• QR 코드에 포함된 커미셔닝 페이로드 검증
• 디바이스 인증 인증서의 TLV 구조 유효성 검사
• Matter 프로토콜 적합성 테스트용 테스트 페이로드 구축

사양 참조

Matter 사양은 Connectivity Standards Alliance(CSA)에서 관리합니다. TLV 인코딩 형식은 코어 사양 부록 A에 정의되어 있습니다. 온보딩 페이로드 인코딩은 섹션 5.1에서 다룹니다.

• Matter 코어 사양 - CSA에서 다운로드
• 오픈소스 저장소 - github.com/project-chip/connectedhomeip
• SDK 개발 문서 - project-chip.github.io/connectedhomeip-doc
• Matter 개발자 핸드북 - handbook.buildwithmatter.com