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）はサポートされていません
• 列挙型、共用体、ビットフィールドはサポートされていません
• ネストされた構造体の編集は1レベルに制限されています
• 匿名構造体はサポートされていません

Matter TLV エンコーディング形式

Matter は構造化データのシリアライズにコンパクトな TLV（Tag-Length-Value）バイナリエンコーディング方式を採用しています。TLV 形式はプロトコルスタック全体で広く使用され、Interaction Model メッセージ、デバイス認証データ、コミッショニングペイロードなどに用いられます。各 TLV 要素は、要素タイプとタグ形式を同時にエンコードする制御バイトから始まり、タグバイト、長さフィールド、値データが続きます。

制御バイトの構造

制御バイトは各 TLV 要素の先頭バイトです。下位5ビットが要素タイプを、上位3ビットがタグ形式を指定します。このコンパクトなエンコーディングにより、小さな値や短いタグを1バイトで表現できます。

TLV 要素タイプ

要素タイプフィールドは値部分のエンコード方法を決定します。整数型は1、2、4、8バイトを使用します。ブール値はタイプフィールドに直接エンコードされ値バイトは不要です。文字列やバイト配列は長さプレフィックスの後にデータが続きます。

オンボーディングペイロード形式

Matter デバイスのコミッショニング時、セットアップ情報はQRコードに埋め込まれるか数値の手動ペアリングコードとして提示されます。QRコードペイロードは「MT:」プレフィックスの後に Base38 エンコードされたバイナリ文字列が続き、バージョン、ベンダーID、プロダクトID、コミッショニングフロー、ディスカバリ方式、ディスクリミネーター、セットアップパスコードが含まれます。

Base38 エンコーディング

Matter QRコードペイロードは Base38 文字セット（0-9、A-Z、-.）を使用した効率的な英数字表現を採用しています。QRコードの英数字モードの制約内でデータ密度を最大化するために選択されたエンコーディングです。3バイトごとに5文字の Base38 文字にエンコードされます。

手動ペアリングコード

11桁の手動ペアリングコードはQRコードのスキャンが利用できない場合のフォールバック手段です。ディスクリミネーター（短縮形）、セットアップパスコード、Verhoeff チェックディジットがエンコードされています。21桁版はベンダーIDとプロダクトIDを追加で含みます。

Verhoeff チェックディジット

手動ペアリングコードは Verhoeff アルゴリズムを用いてエラー検出を行います。このアルゴリズムは全ての1桁エラーと大部分の隣接転置エラーを検出でき、人間が入力する数値コードに適しています。

開発ユースケース

• デバイス通信から取得した Matter TLV ペイロードのデバッグ
• Interaction Model リクエスト・レスポンスメッセージの検査
• 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