谷歌 Matter 智能家居开发完全指南：从入门到认证

2026/7/3 · Stack Frame

前言

2022年，CSA连接标准联盟（Connectivity Standards Alliance）正式发布了Matter 1.0协议标准，谷歌、苹果、亚马逊三大科技巨头同时宣布支持。作为智能家居领域期待已久的"大一统"标准，Matter协议旨在解决长期困扰行业的生态碎片化问题——让不同品牌的智能家居设备能够跨平台、跨生态系统互联互通。

本文整合了谷歌官方Matter开发文档、ESP-Matter开发框架实践、以及多位开发者的实战经验，为你呈现一份完整的Matter设备开发指南。

一、Matter 协议简介

1.1 什么是 Matter？

Matter 是一个应用层协议，基于 IPv6 网络协议栈构建。它运行在现有的网络技术之上：

Wi-Fi — 用于高带宽设备（摄像头、网关等）
Thread — 用于低功耗设备（传感器、开关等），基于 IEEE 802.15.4
以太网 — 用于固定设备（智能音响、路由器等）
蓝牙低功耗（BLE） — 仅用于设备配网，不用于日常通信

这种设计使得 Matter 设备可以在 IP 网络中被统一寻址和控制，无需额外的集线器或协议转换器。

1.2 核心特性

特性	说明
多管理员（Multi-Admin）	一个 Matter 设备可以同时加入多个生态系统（Fabric），例如同时被 Google Home 和 Apple HomeKit 控制
本地控制	设备间通信优先走本地网络，延迟低，不依赖云端
安全性	端到端加密、设备证书认证、SPAKE2+密码认证会话建立（PASE）和证书认证会话建立（CASE）双重安全机制
统一数据模型	所有设备使用标准化的 Cluster/Attribute/Command 模型，确保互操作性
零触摸配网	扫码或 NFC 触碰即可完成设备配对

1.3 支持的设备类型

Matter 1.0 支持的设备类别包括：

照明电工（灯泡、开关、调光器）
暖通空调（恒温器、空调）
安防传感（门磁、人体感应、烟雾报警器）
门锁和窗帘
电视和媒体设备
桥接设备（将非 Matter 设备接入 Matter 网络）

二、谷歌 Matter 开发生态

Google 为 Matter 开发者提供了一整套开发工具链和平台支持。

2.1 开发者工具全景

工具	用途	适用阶段
Google Home Developer Console	创建项目、配置 Matter 集成、管理 VID/PID	全流程
Google Home Extension for VS Code	Assistant 模拟器、云日志查看、设备调试	开发调试
Matter Virtual Device（MVD）	Docker 化的虚拟 Matter 设备，无需真实硬件即可开发	早期开发
Google Home Test Suite	自动化测试，验证集成是否符合认证要求	测试认证
Google Home Sample App for Matter	Android 示例应用，演示 Matter 配网与控制	应用开发
Android Studio Plugin	在 IDE 中直接测试 Assistant 命令和查看云日志	应用开发
Home UI Automator	离线监测 Matter 设备状态	调试测试

2.2 Google Play Services Matter API

对于 Android 应用开发者，Google 通过 Play Services 提供了 Matter API，核心功能包括：

设备配网（Commissioning） — 将 Matter 设备加入家庭网络
设备共享（Device Sharing） — 支持跨应用、跨生态的设备授权
操作发现（Operational Discovery） — 发现网络中已配对的 Matter 设备
Thread Network API — 通过 Play Services 共享 Thread 网络凭证

2.3 VID/PID 说明

开发和生产阶段使用不同的供应商标识：

测试 VID：0xFFF1、0xFFF2、0xFFF3、0xFFF4 — 仅限开发调试使用
生产 VID：需通过 CSA 联盟正式申请，Google 验证后方可用于消费者产品

三、开发环境搭建

3.1 基础环境要求

开发 Matter 设备需要以下基础环境：

操作系统：Ubuntu 20.04 LTS（64位）或更高版本（推荐）
Python：3.8+
Git：用于克隆 Matter SDK
开发板（可选）：ESP32-C3/C6/S3、nRF52840、Silicon Labs EFR32MG24 等

注意：虽然 macOS 也可以构建 Matter 项目，但官方强烈推荐使用 Ubuntu Linux 环境。Windows 用户可以通过 VirtualBox 虚拟机或 WSL2 来搭建环境。

3.2 克隆 Matter SDK

git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git submodule update --init --recursive

3.3 安装依赖项

# Ubuntu 环境
sudo apt-get update
sudo apt-get install -y \
    git gcc g++ pkg-config libssl-dev \
    libdbus-1-dev libglib2.0-dev \
    libavahi-client-dev ninja-build \
    python3-venv python3-dev \
    unzip libgirepository1.0-dev \
    libcairo2-dev libreadline-dev

# 初始化 Matter 构建环境
source scripts/activate.sh

3.4 ESP32 平台环境配置（以 ESP-IDF 为例）

对于使用乐鑫 ESP32 芯片的开发者：

# 安装 ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone --branch v5.1 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32 esp32c3 esp32c6 esp32s3
source export.sh

# 克隆 ESP-Matter SDK
cd ~/esp
git clone https://github.com/espressif/esp-matter.git
cd esp-matter
git submodule update --init --recursive

四、Matter 数据模型详解

理解 Matter 的数据模型是设备开发的核心。Matter 采用四层分层结构，可以类比为一栋房子：

4.1 Node（节点）— "房子"

Node 代表一个物理设备实体，是网络中的最小可寻址单元。每个 Node 拥有唯一的节点 ID，在网络层面对应一个 IP 地址。一个物理设备就是一个 Node（例如：一个智能灯泡）。

// 创建 Matter Node
node::config_t node_config;
node_t *node = node::create(&node_config, app_attribute_update_cb, app_identification_cb);

app_attribute_update_cb 是属性更新回调函数，当接收到控制命令时被调用。app_identification_cb 是设备识别回调，用于响应"识别"命令（如让设备闪烁以标识自身）。

4.2 Endpoint（端点）— "房间"

Endpoint 是 Node 内部的功能逻辑单元，对应一种设备类型。一个 Node 可以有多个 Endpoint。例如：一个智能插座可能包含：

Endpoint 0：保留端点，包含 Basic Information、ACL、Network Commissioning 等基础 Cluster
Endpoint 1：On/Off 灯光端点

// 创建扩展彩色灯端点
endpoint_t *endpoint = extended_color_light::create(
    node, &light_config, ENDPOINT_FLAG_NONE, light_handle
);

4.3 Cluster（集群）— "家具/设备"

Cluster 是功能模块，同一功能相关的 Attribute（属性）、Command（命令）和 Event（事件）被组织在一起。常见的 Cluster 包括：

Cluster	功能	示例 Attribute	示例 Command
On/Off	开关控制	`OnOff` (bool)	`Toggle`
Level Control	亮度/等级控制	`CurrentLevel` (uint8)	`MoveToLevel`
Color Control	颜色控制	`ColorTemperatureMireds`	`MoveToHue`
Temperature Measurement	温度测量	`MeasuredValue` (int16)	—
Occupancy Sensing	人体感应	`Occupancy` (bitmap)	—

4.4 Attribute、Command、Event — "设备属性"

Attribute：存储设备状态的数据字段。可读、可写或只读。
Command：触发设备执行某个动作的操作。由 Controller 发起，Device 响应。
Event：设备主动上报的状态变化或告警。

4.5 数据模型配置示例

以扩展彩色灯为例，配置各个 Cluster 的默认 Attribute：

// On/Off Cluster 配置
on_off::config_t on_off_config;
on_off_config.on_off = 0;  // 默认关闭
on_off_config.lighting.start_up_on_off = nullptr;  // 重启后恢复上次状态

// Level Control Cluster 配置
level_control::config_t level_config;
level_config.current_level = 64;  // 默认亮度 25%
level_config.min_level = 1;
level_config.max_level = 254;

// Color Control Cluster 配置
color_control::config_t color_config;
color_config.color_mode = EMBER_ZCL_COLOR_MODE_COLOR_TEMPERATURE;
color_config.color_temperature.startup_color_temperature_mireds = nullptr;

五、设备开发实战

下面以 ESP32 + ESP-Matter 框架为例，演示一个完整的 Matter 灯光设备开发流程。

5.1 项目结构

一个典型的 ESP-Matter 示例项目结构如下：

examples/light/
├── main/
│   ├── app_main.cpp      # 主入口
│   ├── app_driver.cpp    # 硬件驱动层
│   └── app_priv.h        # 私有声明头文件
├── partitions.csv        # 分区表
├── sdkconfig.defaults    # 默认 SDK 配置
└── CMakeLists.txt

5.2 硬件驱动初始化

// 初始化 LED 驱动
app_driver_handle_t light_handle = app_driver_light_init();

// 初始化按键驱动
app_driver_handle_t button_handle = app_driver_button_init();

// 注册复位按键
app_reset_button_register(button_handle);

app_driver_light_init() 会初始化所有 LED 引脚。在示例中虽然初始化了多个 LED，但默认只使用第一个，这也是为什么示例程序"只能控制一个灯泡"。

5.3 创建 Node 和 Endpoint

// 1. 创建 Node
node::config_t node_config;
node_t *node = node::create(&node_config, app_attribute_update_cb, app_identification_cb);

// 2. 配置 Endpoint 属性（参见 4.5 节）

// 3. 创建 Endpoint（自动匹配 Cluster）
extended_color_light::config_t light_config;
// ... 设置 light_config 的各个 Cluster 配置
endpoint_t *endpoint = extended_color_light::create(
    node, &light_config, ENDPOINT_FLAG_NONE, light_handle
);

5.4 启动 Matter 协议栈

// 获取端点 ID
uint16_t light_endpoint_id = endpoint::get_id(endpoint);

// 启动 Matter 协议栈
esp_matter::start(app_event_cb);

// 应用默认值到硬件
app_driver_light_set_defaults(light_endpoint_id);

5.5 实现属性更新回调

当用户通过 Google Home App 或语音助手控制设备时，属性更新回调被触发：

esp_err_t app_driver_attribute_update(
    app_driver_handle_t driver_handle,
    uint16_t endpoint_id,
    uint32_t cluster_id,
    uint32_t attribute_id,
    esp_matter_attr_val_t *val
) {
    // 按 endpoint → cluster → attribute 层级匹配
    if (cluster_id == OnOff::Id) {
        if (attribute_id == OnOff::Attributes::OnOff::Id) {
            bool power = val->val.b;
            app_driver_light_set_power(driver_handle, power);
        }
    }
    else if (cluster_id == LevelControl::Id) {
        if (attribute_id == LevelControl::Attributes::CurrentLevel::Id) {
            uint8_t brightness = val->val.u8;
            app_driver_light_set_brightness(driver_handle, &brightness);
        }
    }
    else if (cluster_id == ColorControl::Id) {
        // 处理颜色/色温变化...
    }
    return ESP_OK;
}

5.6 访问 Cluster 和 Attribute 值

在运行时读取设备状态：

// 获取层级引用
node_t *node = node::get();
endpoint_t *endpoint = endpoint::get(node, endpoint_id);
cluster_t *cluster = cluster::get(endpoint, LevelControl::Id);
attribute_t *attribute = attribute::get(cluster, LevelControl::Attributes::CurrentLevel::Id);

// 读取值
esp_matter_attr_val_t val;
attribute::get_val(attribute, &val);

// 应用到硬件
app_driver_light_set_brightness(handle, &val);

5.7 延迟持久化优化

对于频繁变化的属性（如亮度、色温），建议使用延迟持久化减少 NVM（非易失性存储器）写入，以延长设备寿命：

attribute::set_deferred_persistence(current_level_attribute);
attribute::set_deferred_persistence(current_x_attribute);
attribute::set_deferred_persistence(current_y_attribute);

5.8 构建和烧录

# 设置目标芯片
idf.py set-target esp32c3

# 构建项目
idf.py build

# 烧录到设备
idf.py -p /dev/ttyUSB0 flash monitor

六、自定义数据模型

当标准设备类型无法满足需求时，Matter 支持自定义（Vendor-Specific）数据模型。

6.1 自定义 Endpoint

// 创建自定义端点（不关联标准设备类型）
endpoint_t *endpoint = endpoint::create(node, ENDPOINT_FLAG_NONE);

6.2 自定义 Cluster

使用厂商特定的 Cluster ID（如 0x131BFC00）：

// 创建自定义 Cluster
uint32_t custom_cluster_id = 0x131BFC00;
cluster_t *cluster = cluster::create(
    endpoint, custom_cluster_id, CLUSTER_FLAG_SERVER
);

6.3 自定义 Attribute

// 添加自定义属性
uint32_t custom_attribute_id = 0x00000000;  // 自定义属性 ID
attribute_t *attribute = attribute::create(
    cluster,
    custom_attribute_id,
    ATTRIBUTE_FLAG_NONE,
    esp_matter_uint16(default_value)  // 16位无符号整型
);

6.4 自定义 Command

// 命令回调函数
static esp_err_t custom_command_callback(
    const ConcreteCommandPath &command_path,
    TLVReader &tlv_data,
    void *opaque_ptr
) {
    ESP_LOGI(TAG, "Custom command received!");
    // 处理逻辑...
    return ESP_OK;
}

// 注册自定义命令
uint32_t custom_command_id = 0x00000001;
command::create(
    cluster,
    custom_command_id,
    COMMAND_FLAG_ACCEPTED,
    custom_command_callback  // 回调函数
);

6.5 为 Endpoint 添加额外标准 Cluster

你也可以为已有端点动态添加标准 Cluster：

// 添加 On/Off Cluster 到端点
on_off::config_t config;
on_off::create(endpoint, &config, CLUSTER_FLAG_SERVER,
               on_off::feature::lighting::get_id());

// 添加温度测量 Cluster
temperature_measurement::config_t temp_config;
temperature_measurement::create(endpoint, &temp_config, CLUSTER_FLAG_SERVER);

七、Google Home 集成与测试

7.1 Google Home Developer Console 配置

创建项目：访问 Google Home Developer Console，创建智能家居项目
添加 Matter 集成：选择 Matter 集成类型，配置产品的 VID 和 PID
设置设备信息：填写设备名称、描述、类别等信息
获取测试凭证：生成用于开发阶段调试的测试密钥

7.2 使用 Matter 虚拟设备

在没有真实硬件的情况下，可以使用 Docker 化的虚拟设备进行开发：

# 拉取并运行 Matter 虚拟设备
docker run -it --rm \
    --network host \
    us-central1-docker.pkg.dev/gdhome-google-com/matter-virtual-device/matter-virtual-device:latest

虚拟设备可以被配网到真实的 Google Home Fabric 中，并像物理设备一样被 Assistant 语音命令控制。

7.3 VS Code 扩展调试

安装 Google Home Extension for VS Code 后，你可以在 IDE 中：

查看实时云日志：双向通信的详细日志，按严重级别和时间过滤
发送 Assistant 命令：用脚本化方式测试语音命令交互
检查 JSON 消息内容：查看设备与 Google Home 之间的通信详情

7.4 设备配网流程

设备通过 BLE 进行初始配对，配网完成后切换到 Wi-Fi 或 Thread 网络：

用户扫码/NFC触碰
    ↓
BLE 配网通道建立（PASE 安全会话）
    ↓
设备获取 Wi-Fi/Thread 网络凭证
    ↓
设备加入 IP 网络
    ↓
证书认证会话建立（CASE）
    ↓
设备被添加到 Google Home Fabric
    ↓
用户可以通过 App/语音控制设备

7.5 使用 chip-tool 进行调试

chip-tool 是 Matter SDK 自带的命令行调试工具：

# 控制开关
./chip-tool onoff on <node-id> <endpoint-id>

# 控制亮度
./chip-tool levelcontrol move-to-level 128 10 0 0 <node-id> <endpoint-id>

# 读取温度值
./chip-tool temperaturemeasurement read measured-value <node-id> <endpoint-id>

# 订阅属性变化
./chip-tool onoff subscribe on-off <node-id> <endpoint-id> --min-interval 1 --max-interval 10

八、测试套件与认证

8.1 Google Home Test Suite

Google 提供了自动化测试套件用于验证你的 Matter 集成：

在 Developer Console 中启动测试运行
自动检测设备是否符合 Google Home 生态系统规范
生成详细的测试报告，指示通过/失败项
必须通过测试才能进入 Field Trial 或正式发布

8.2 认证流程全景

需求分析 → 开发实现 → Developer Console 配置
    ↓
Google Home Test Suite 测试
    ↓
Field Trial（可选但推荐，验证真实环境表现）
    ↓
CSA Matter 认证（设备级别，通过授权测试实验室）
    ↓
产品发布

2026年更新：从2026年开始，所有 Matter 集成和测试都要求使用 Alliance Interop Test（联盟互操作测试），请关注 CSA 联盟官网的最新动态。

8.3 常见认证检查项

[ ] 设备能正确响应 On/Off、Level Control 等基本命令
[ ] BLE 配网流程顺畅，二维码可被正确扫描
[ ] 多管理员（Multi-Admin）功能正常工作
[ ] 设备在网络中断后能正确恢复连接
[ ] 固件 OTA 升级功能（如适用）
[ ] 设备重启后状态正确恢复
[ ] 安全凭证（DAC、PAI、CD）正确烧录

九、其他平台的 Matter 开发

9.1 Nordic nRF Connect SDK

Nordic 半导体是 Matter 协议的主要贡献者之一，其 nRF52840 和 nRF5340 芯片对 Matter over Thread 有优秀的支持：

# 安装 nRF Connect SDK
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.5.0
west update

# 构建 Matter 灯光示例
cd nrf/samples/matter/light_bulb
west build -b nrf52840dk/nrf52840

9.2 Silicon Labs Simplicity Studio

Silicon Labs 提供了图形化的开发环境。其 EFR32MG24 系列芯片专为 Matter 优化。关键特色：

通过 Simplicity Studio 5 进行可视化项目配置
内置 ZAP 工具支持图形化 Cluster 配置
提供完整的 Matter 示例（照明、门窗传感器、恒温器等）

9.3 平台选型建议

平台	通信方式	适合产品	开发生态
ESP32 (Espressif)	Wi-Fi / Thread	照明、插座、传感器	ESP-IDF + ESP-Matter
nRF52/nRF53 (Nordic)	Thread / BLE	低功耗传感器、门锁	nRF Connect SDK + Zephyr
EFR32 (Silicon Labs)	Thread / Wi-Fi	各类智能家居设备	Simplicity Studio 5
Matter Virtual Device	虚拟	早期原型验证	Docker + Google Home

十、总结与展望

关键要点回顾

Matter 是应用层协议，基于 IP（Wi-Fi/Thread/以太网），BLE 仅用于配网
数据模型是核心：Node → Endpoint → Cluster → Attribute/Command/Event 的四层结构
Google 提供了全流程工具链：从虚拟设备（MVD）到 VS Code 扩展再到自动化测试套件
开发框架选择丰富：ESP-Matter 适合快速原型，nRF Connect SDK 适合商业产品，Simplicity Studio 适合图形化开发
认证不可跳过：正式发布必须通过 CSA Matter 认证和 Google Home Test Suite

参考资料

本文综合参考了 Google Home Developers 官方文档、ESP-Matter 开发框架实践指南、Nordic Developer Academy Matter 课程以及多位 Matter 开发者的实战经验。Matter 生态仍在快速发展中，建议持续关注 CSA 联盟和 Google Home Developers 的最新更新。