Matter 协议编解码器
解码和编码 Matter TLV 数据，用于智能家居开发调试
粘贴从 Matter 设备或协议分析器中捕获的 TLV 数据
点击加载示例
解码结果
输入 TLV 数据并点击解码查看结果
字节查看器
使用带类型注解的 JSON 格式定义 TLV 元素
点击加载编码示例
使用 C/C++ 语法定义数据结构。使用 // tag N 注释指定 TLV 标签。
解析结果
填写字段值
编码结果
输入 JSON 并点击编码生成 TLV 数据
字节查看器
编码统计
输入 Matter QR 码字符串（MT:...）或手动配对码（11/21 位数字）
点击加载示例
配网信息解析结果
输入 QR 码字符串或手动配对码进行解析
基本信息
范围：1-99999998。无效值：0、11111111、22222222 等
配网流程
发现方式
输出格式
生成结果
填写参数后点击生成
TLV 元素类型
| 类型名称 | 类型码 | 值长度 |
|---|---|---|
| 有符号整数 | 0x00-0x03 | 1, 2, 4, 8 bytes |
| 无符号整数 | 0x04-0x07 | 1, 2, 4, 8 bytes |
| 布尔值 | 0x08-0x09 | 0 bytes |
| 单精度浮点 | 0x0A | 4 bytes |
| 双精度浮点 | 0x0B | 8 bytes |
| UTF-8 字符串 | 0x0C-0x0F | 1/2/4/8-byte length + data |
| 字节串 | 0x10-0x13 | 1/2/4/8-byte length + data |
| 空值 | 0x14 | 0 bytes |
| 结构体 | 0x15 | End-of-Container (0x18) |
| 数组 | 0x16 | End-of-Container (0x18) |
| 列表 | 0x17 | End-of-Container (0x18) |
| 容器结束 | 0x18 | 0 bytes |
Matter 协议技术参考
C 结构体 Schema 使用指南
C 结构体 Schema 模式允许您使用熟悉的 C/C++ 语法定义数据结构。解析器从结构体定义中提取字段名称、类型和 TLV 标签，然后生成可视化表单，方便数据输入和 TLV 编码。
支持的语法格式
// Supported syntax forms:
typedef struct { ... } StructName;
typedef struct Tag { ... } StructName;
struct StructName { ... };
支持的数据类型
| 类别 | C/C++ 类型 | TLV 类型 |
|---|---|---|
| 有符号整数 | int8_t, int16_t, int32_t, int64_t, char, short, int, long | int (1-8B) |
| 无符号整数 | uint8_t, uint16_t, uint32_t, uint64_t, unsigned char/short/int/long, size_t | uint (1-8B) |
| 布尔值 | bool, _Bool | bool |
| 浮点数 | float, double | float/double |
| 字符串 | char[], char[N], char* | UTF-8 string |
| 字节数组 | uint8_t[], uint8_t[N], uint8_t* | byte string |
Tag 标注方式
使用注释为每个字段指定 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 协议概述
Matter 是由连接标准联盟（CSA）制定的统一智能家居连接标准，前身为 Project CHIP（基于 IP 的互联家庭）。该标准使 Apple HomeKit、Google Home、Amazon Alexa 和 Samsung SmartThings 等不同平台的设备能够彼此互通。Matter 设备通过 Wi-Fi、Thread 和以太网进行通信，底层采用 IPv6 传输协议。Matter 1.0 于 2022 年 10 月正式发布，后续版本不断扩展了支持的设备类型范围。
Matter TLV 编码格式
Matter 使用紧凑的 TLV（Tag-Length-Value，标签-长度-值）二进制编码方案来序列化结构化数据。TLV 格式广泛应用于协议栈的各个层面，包括交互模型消息、设备认证数据和配网载荷。每个 TLV 元素由一个控制字节起始，该字节同时编码了元素类型和标签形式，后续依次是标签字节（如有）、长度字段（针对变长类型）以及值数据。
控制字节结构
控制字节是每个 TLV 元素的首字节。低 5 位指定元素类型，高 3 位标识标签形式。这种紧凑的编码方式使得小数值和短标签可以用单字节表示。
| 位域 | 说明 |
|---|---|
| Bits [4:0] | 元素类型（有符号整数/无符号整数、布尔值、浮点数、UTF-8 字符串、字节串、空值、结构体、数组、列表、容器结束标记） |
| Bits [7:5] | 标签形式：000 = 匿名，001 = 上下文标签（1字节），010-110 = Profile 标签，111 = 完全限定标签 |
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 算法进行错误检测。该算法能够检测所有单位数错误和大部分相邻换位错误，非常适合用于人工输入的纯数字代码。
开发应用场景
- 调试从 Matter 设备交互中捕获的 TLV 载荷数据
- 检查交互模型的请求和响应消息
- 验证嵌入 QR 码中的配网载荷信息
- 验证设备认证证书的 TLV 结构
- 为 Matter 协议一致性测试构建测试载荷
规范参考
Matter 规范由连接标准联盟（CSA）负责维护。TLV 编码格式定义在核心规范附录 A 中，配网载荷编码详见第 5.1 节。
- Matter 核心规范 - 从 CSA 下载
- 开源代码仓库 - github.com/project-chip/connectedhomeip
- SDK 开发文档 - project-chip.github.io/connectedhomeip-doc
- Matter 开发手册 - handbook.buildwithmatter.com