这是不是地址没有保存？会不会导致手机找不到原来的设备？量产时是不是应该给每台设备烧录一个固定 BLE MAC？

对于 Matter 配网广播，答案恰好相反：每次启动都使用新的随机 BLE 地址，通常才是符合规范的行为。

不过，“随机地址”不等于“每次连接都换地址”，也不等于常见的 RPA 定时轮换地址。本文把规范要求、Bluetooth 地址类型、主流参考实现和产品测试方法放到同一条时间线上说明。

一句话结论

对于使用 Bluetooth LE 进行发现和配网的 Matter 待配网设备：

• BLE 广播必须使用 LE Random Device Address；
• 具体使用 Bluetooth 定义的 Random Static Address；
• 地址必须至少在每次设备启动时更换；
• 同一次启动期间，配网重试、断开重连或重新开始广播，不要求再次换地址；
• 永久固定的 Public Address，或者跨重启保持不变的“伪随机地址”，都不满足这项 Matter 配网要求。

因此，更准确的描述不是“每次配网随机一次”，而是：

1
2
3
4
5

每次启动生成一个新的 Random Static Address
              ↓
本次启动期间保持稳定
              ↓
下一次启动重新生成

Matter 规范到底要求了什么？

Matter 1.6 Core Specification 第 5.4.2.5.5 节“Advertising Address”（PDF 第 319 页）给出了两个 SHALL 级要求：

1. 待配网设备的 BLE 广播使用 LE Random Device Address；
2. 地址至少在每次启动时更换。

这里的 SHALL 表示强制要求，不是优化建议。该条款还明确引用 Bluetooth Core Specification 中的 Static Device Address 定义，所以不能只看到“Random Device Address”，就把它理解成任意一种随机地址。

这项要求属于 Matter 使用 BLE 进行 Commissionable Node Discovery 和配网的场景。Matter over Thread 产品经常采用这条路径，但它并非 Thread 独有：只要 Matter 设备使用 BLE 作为配网通道，就要关注这项要求。

为什么“Random Static”既随机又静态？

这个名字第一次看很矛盾，其实两个词描述的是不同维度：

• Random：地址不是永久分配的 Public Address，而是随机生成的 Random Device Address；
• Static：地址初始化后，在当前启动或电源周期中保持稳定，不进行定时轮换。

按照 Bluetooth Core Specification 的 Device Address 定义，Random Device Address 还可以细分为三类：

Public Device Address 则是另一大类，通常来自固定的设备身份分配，不属于 Random Device Address。

因此，看到扫描工具显示 Random 还不够。要判断 Matter 要求是否真正满足，至少还要确认：

1. 地址类型确实是 Random Static；
2. 地址位 [47:46] 为 11；
3. 当前启动期间地址稳定；
4. 下一次启动后地址发生变化。

“每次启动更换”不等于“每次连接更换”

把地址变更粒度搞错，可能造成两种相反的问题。

如果地址永远固定，附近观察者就更容易跨时间关联同一台待配网设备，违背 Matter 这里的隐私目标。

如果地址在同一次启动中频繁变化，手机刚扫描到地址 A，准备连接时设备却已经变成地址 B，也会增加发现、连接和故障恢复的复杂度。Random Static Address 的“Static”正是为了避免这种不稳定。

常见场景可以这样判断：

为什么 Matter 不把 BLE MAC 当作永久设备身份？

BLE 在这里主要解决的是“附近发现并建立临时配网通道”。它不是 Matter 设备投入运行后的长期身份基础。

典型的 Matter over Thread 首次配网可以简化为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

二维码或手动码
  ↓
通过 Discriminator 缩小待配网设备范围
  ↓
BLE 广播、连接和 BTP 传输
  ↓
PASE 建立临时安全会话
  ↓
设备证明、NOC/Fabric 配置、Thread Dataset
  ↓
设备接入 Thread
  ↓
通过 IPv6 建立 CASE
  ↓
CommissioningComplete

进入正常运行阶段后，Controller 通过 Matter Fabric、Node ID、证书和 CASE 识别并访问设备，通信承载变成 Thread 上的 IPv6。BLE 配网地址不需要承担永久设备索引的职责。

这也解释了为什么 Commissioner 或手机 App 不应把 BLE MAC 当作 Matter 设备的长期主键。设备重启后，App 应重新扫描待配网广播，并使用 Onboarding Payload、Discriminator 和 Matter Service Data 完成目标匹配。

还要分清下面几种地址和身份：

主流实现通常怎样做？

没有公开、可信的全市场统计可以证明“多少品牌随机、多少品牌固定”。比市场印象更可靠的证据，是 Matter 开源参考实现和芯片平台适配层。

在 Project CHIP 当前源码中，可以看到多种平台都围绕“启动时生成 Random Static Address”实现：

• Zephyr 平台 BLEManagerImpl 创建 Random Static Identity；
• ESP32 NimBLE BLEManagerImpl 生成并设置新的 Static Random Address；
• Silicon Labs EFR32 BLEManagerImpl 特别处理了“同一次启动内重新初始化 BLE 不能误换地址”；
• Bouffalo Lab BLEManagerImpl 直接按 once per boot 生成 Random Static Address。

这不能代替对每一款量产固件的检查，但足以说明：主流 Matter SDK 的设计方向是每次启动随机，而不是永久固定。 很多厂商直接继承芯片平台或 Matter SDK 的默认行为，因此最终产品通常也会表现为重启后 BLE 地址变化。

如果某台产品一直显示固定地址，可能存在多种原因：

• 使用了旧版 SDK 或厂商自己的 BLE 平台层；
• 把 Public Address 直接用于 Matter 广播；
• 把 Random Static Address 持久化到了 Flash；
• 扫描工具显示的是系统解析后的身份，而不是当前空口地址；
• 当前看到的是厂商私有 BLE 服务，不是 Matter Commissionable Advertising。

不能仅凭“地址固定”立即断言整台产品不合格，但它足以触发一次针对实际 Matter 广播的合规检查。

厂商私有 BLE OTA 为什么可能需要稳定地址？

有些设备除了 Matter 配网，还提供厂商私有 BLE OTA、产测或维护服务。手机 App 可能希望设备重启后仍能被识别，于是产品会设计一个稳定的 BLE Identity。

这和 Matter 配网地址的目标不同：

• Matter 配网强调临时发现与隐私，要求每次启动更换地址；
• 厂商私有服务可能强调重连和设备索引，希望身份稳定。

工程上不能因为私有 OTA 需要稳定地址，就直接让 Matter 配网广播永久使用同一个 MAC。也不能为了满足 Matter 地址轮换，就让依赖固定 MAC 的私有 App 在升级后失去设备。

可选设计要结合控制器能力和隐私模型评估，例如：

• 为 Matter 配网和私有服务使用不同的 BLE Identity 或 Advertising Set；
• 让私有 App 每次重新扫描、重新发现 GATT，而不是缓存旧地址和 Handle；
• 在受保护的应用协议中确认设备身份，不把可被长期跟踪的永久标识直接放进明文广播；
• 明确规定两种模式何时启用，避免同一个广播同时承担冲突的身份目标。

这里没有一种适合所有芯片和手机系统的固定答案，但有一个边界很明确：厂商私有 BLE 需求不能取消 Matter Commissionable Advertising 的规范义务。

怎样在设备上验证？

最小验证不需要先做完整 Matter 配网。使用能够显示 BLE 地址类型和原始广播数据的扫描工具，记录多次启动即可。

建议至少执行下面这组测试：

测试记录应同时保存：

• 启动序号；
• 广播地址和地址类型；
• Matter Service Data；
• Discriminator；
• 是否成功建立 BLE 连接和 BTP；
• 最终是否到达 CommissioningComplete。

只看到 MAC 变化，不能证明配网成功；只看到 BLE Connected，也不能证明 PASE、Thread 或 CASE 成功。地址合规和端到端配网是两条相关但独立的证据链。

实现检查清单

如果正在开发 Matter 设备，可以用下面的清单快速审查平台层：

• 使用密码学安全随机源生成 48-bit 地址的随机部分；
• 设置 Random Static Address 规定的高两位；
• 排除规范禁止的全 0 或全 1 随机部分；
• 在 BLE 广播启动前完成地址初始化；
• 同一次启动中不因配网重试或 BLE 子系统重复初始化而换地址；
• 不从 Flash 恢复上一次启动的 Matter 配网地址；
• 不使用芯片 UID、序列号或量产固定地址确定性生成跨启动地址；
• App 不把 BLE MAC 或旧 GATT Handle 当作永久设备身份；
• 把 Matter 配网 BLE、厂商私有 BLE 和 Thread 地址分别测试；
• 用真实设备记录跨启动地址，而不是只检查配置项或源码。

最后再记住三个边界

1. 随机地址是强制要求，不只是隐私建议。
2. 随机粒度是每次启动，不是每次连接。
3. BLE 配网地址不是 Thread 地址，也不是 Matter 的长期设备身份。

如果调试时发现“设备重启后 BLE MAC 变了”，先不要把它当成数据丢失或 Flash 故障。对于 Matter 配网设备，这往往正是规范要求平台层主动实现的行为。

参考资料

• Connectivity Standards Alliance, Matter 1.6 Core Specification, §5.4.2.5.5, Advertising Address.
• Bluetooth SIG, Bluetooth Core Specification 6.3, Vol 6, Part B, §1.3.2, Random Device Address.
• Project CHIP, connectedhomeip, BLE platform implementations.

问题是，Echo 机身、Alexa App 和 Matter 设备标签上都找不到这个 Key。Amazon Forum 上也有人问过完全相同的问题：到底应该去哪里找？

先给出结论：

如果目标 Thread 网络由 Echo 创建，普通用户通常不应该手工寻找或输入 Network Key。Echo 会自动生成并保存 Thread 凭据，正常配网流程应由 Alexa 自动取得这些凭据，再通过 Matter Network Commissioning 交给新设备。

因此，这个输入框更像一个被暴露到用户界面的凭据取得失败：Alexa 已经走到“选择 Thread 网络”的阶段，却没有成功取得该网络的安全资料。

本文根据亲历现象、Amazon 当前公开文档和 Matter over Thread 的协议分层，还原这个页面到底在问什么、故障发生在哪一段，以及普通用户和设备开发者应该分别怎样处理。

真实网络密钥、设备地址、内部日志和产品身份均不会出现在本文中。

先区分四种完全不同的凭据

这个问题难理解，很大程度上是因为配网过程中同时出现了二维码、密码、Network Key 和证书。它们服务于不同协议层。

扫描 Matter 二维码，只解决第一行的问题。二维码中的 Setup Passcode 不是 Thread Network Key，也不能由它计算出用户家中的 Thread Key。

同样，Thread Network Key 也不是 Matter Fabric 身份。多个 Matter Fabric 可以共享同一张 Thread 网络；知道 Thread Key 并不等于拥有某个 Fabric 的 NOC 和控制权限。

可以先用下面这张简图记住它们的关系：

1
2
3
4
5
6
7
8

Matter 二维码 / Setup Passcode
    -> 建立 PASE 临时会话

Thread Operational Dataset
    -> 让设备加入低功耗 IPv6 Mesh

Matter NOC
    -> 让设备加入 Fabric 并建立长期 CASE 会话

正常的 Matter over Thread 配网怎样走？

以一台恢复出厂的新设备和一个已经工作的 Echo Thread Border Router 为例，典型流程可以压缩为六个阶段。

这条时间线有两个很重要的边界：

• 扫码成功不等于 Thread 已经入网；
• Thread Attach 成功也不等于 Matter 配网已经完成。

Alexa 弹出 Network Key 输入框时，设备通常还没有走到 Thread Attach。问题集中在第四阶段：Commissioner 正在选择或取得 Thread 网络凭据。

为什么说这不是设备标签缺了一个密码？

恢复出厂的 Matter over Thread 设备不可能预先知道用户家中未来会使用哪一张 Thread 网络。它出厂时保存的是自己的 Matter Setup Passcode、设备证明材料等数据，而不是 Echo 将来随机生成的家庭 Thread Network Key。

Thread 网络凭据应由拥有或管理该网络的一方提供：

1
2
3
4

Echo 或其他 Border Router 创建 Thread 网络
    -> 平台安全保存 Operational Dataset
    -> 配网时由 Commissioner 取得 Dataset
    -> 通过已建立的 PASE 会话发送给新设备

所以，当 Alexa 一边显示网络名、一边要求用户输入 Key，不能据此断定终端固件没有生成 Key。恰恰相反，终端此时是等待接收目标网络的凭据，而不是负责创造 Echo 网络的凭据。

Amazon 当前是怎样保存 Thread 凭据的？

Amazon 的用户帮助文档说明，Echo 等设备创建 Thread 网络时可以自动生成 Thread credentials，并把它们安全保存到 Amazon，以便后续设备减少手工配置步骤。文档提供了删除已保存 Thread passwords 的入口，却没有给普通用户提供显示原始 Network Key 的步骤。

如果 Thread 网络由 eero 创建，eero 和 Amazon 账户链接后可以同步 Thread network identifiers、passwords 和 keys。这个同步用于快速设备入网，也用于让受支持的 eero 与 Echo 尽量进入同一张 Thread Mesh。

Amazon 还提供 Credential Locker API，可以返回网络的 networkKey、PSKc、PAN ID、信道等资料。不过，这个接口属于受限的 Alexa Smart Home 厂商能力，需要业务授权、Skill 权限和事件网关访问令牌。它不是一个给家庭用户复制 Echo Network Key 的公开查询接口。

因此，目前更准确的说法是：

Amazon 保存并使用 Thread Network Key，但没有公开一个面向普通 Alexa 用户的“显示原始 Key”操作路径。

为什么退出重试后有时又能成功？

公开讨论中，有用户在第一次看到 Key 输入框后退出配网，再次扫描时 Alexa 直接越过了该页面并成功连接。我也遇到了同样的 Key 输入页面；但仅凭这个页面，只能确认自动凭据链没有正常闭合，不能确认现场与公开讨论具有同一个后台根因。

仅凭 App 页面无法证明 Amazon 后台的确切根因，但可以列出几个符合现象的可能性：

1. Echo 刚启用 Thread Border Router，网络已经被发现，但凭据尚未完成同步；
2. Alexa App、Amazon 账户凭据存储与 Echo 当前网络状态暂时不一致；
3. 家庭中存在多张 Thread 网络，Alexa 发现了网络名，却没有对应凭据的读取权限；
4. Border Router 曾恢复出厂或重建网络，手机或云端仍保留旧的 Thread 记录；
5. App 配网状态机进入了本应由平台自动处理的手工兜底分支。

这些是故障模型，不是对某一次现场问题的已证实根因。要确认是哪一种，至少需要同时观察 Alexa/手机侧状态、Border Router 的 MeshCoP 广播信息和终端的 Matter commissioning 日志。

普通用户应该怎样处理？

场景一：新设备要加入 Echo 自己创建的网络

不要把 Matter 二维码中的数字当成 Thread Key，也不要在网上寻找所谓通用 Key。

可以按下面的低风险顺序处理：

1. 确认目标 Echo 型号确实具备 Thread Border Router，而不只是 Matter Controller 能力；
2. 更新 Alexa App 和 Echo 固件；
3. 保持 Echo 在线，等待其 Thread 网络完成初始化；
4. 退出当前配网页面，让 Matter 设备重新进入可配网状态后再试；
5. 记录 Alexa 显示的 Thread Network Name，确认重试时是否选择了同一张网络。

不要一开始就删除 Amazon 保存的 Thread passwords 或恢复 Echo 出厂设置。这些操作可能让 Echo 创建一张新网络，使原有 Thread 设备失去连接。

场景二：Thread 网络由 eero 创建

确认 eero 中已启用 Thread，并在 Amazon Connected Home 中正确链接 eero 与 Amazon 账户，同时允许用于简化设备配置的凭据同步。

这里要解决的仍然是平台之间传递凭据，而不是从 Matter 设备标签上找密码。

场景三：设备已经加入 Apple、Google 或其他 Matter 生态

如果目的是让同一台设备再被 Alexa 控制，优先使用第一个生态生成的 Matter Multi-Admin 配对码，而不是再次使用设备标签上的首次配对码，也不是重新给设备输入 Thread Network Key。

第二个 Matter Controller 可以通过现有 IP 网络建立自己的 Fabric。Multi-Admin 增加的是 Matter 管理关系，通常不需要让已经在线的终端重新加入另一张 Thread 网络。

场景四：Border Router 重置过

先确认旧网络是否仍由家中其他 Thread Border Router 维持。不要只比较 Network Name；同名网络也可能具有不同的 Extended PAN ID 和安全资料。

如果旧网络已经消失，而手机或平台仍保存旧凭据，继续把旧 Dataset 下发给新设备只会让设备反复搜索一张不存在的网络。这时需要按目标平台的正式流程重建或迁移网络，而不是随机输入一个 Key。

设备开发者怎样判断故障阶段？

如果能够取得终端 UART 日志，不要只看最终一条“入网失败”。应按协议阶段寻找下面这些锚点：

1
2
3
4
5
6
7
8

BLE connected
  -> PBKDFParam / PASE_Pake
  -> Network Commissioning 命令
  -> Thread Dataset 被保存
  -> OpenThread role: CHILD / ROUTER
  -> SRP 服务发布
  -> CASE established
  -> CommissioningComplete

判断方法如下：

• 连 PBKDFParam、PASE_Pake 都没有：还不能归因于 Thread；
• PASE 已完成，但没有收到网络配置：重点检查 Commissioner 的凭据选择与下发；
• Dataset 已收到，但一直无法成为 CHILD：再检查信道、网络身份、安全资料、射频和 Parent 可达性；
• 已经 CHILD，却没有 CASE 或 CommissioningComplete：Thread 接入成功，但 Matter 配网链路仍未闭合。

Alexa App 的 Network Key 输入框只能帮助定位到平台正在处理 Thread credentials，不能单独证明 Key 错了，更不能证明终端已经尝试过 Thread Attach。

开发调试时能否从已入网设备读取 Key？

可以，但适用边界很窄。

如果这是自己拥有、自己开发并且已经加入目标 Thread 网络的终端，它本地保存的 Active Operational Dataset 必然包含当前 Network Key。开发者可以在受控 Debug 固件中读取 Dataset 的 Network Key，用于授权范围内的 Wireshark/802.15.4 抓包分析。

这种方法解决的是“调试自己的网络”，不是普通用户使用 Alexa 的正常步骤。安全设计至少应满足：

• 只存在于明确的 Debug 构建；
• Release 在编译阶段完全排除读取和打印路径；
• Key 只进入受控的本地日志或 Wireshark配置；
• 临时缓冲区使用后立即清零；
• 不把 Key 写进源码、Git、文章、工单或聊天记录。

另外，Thread Network Key 只解决 Thread/IEEE 802.15.4 网络层的解密。Matter CASE 仍提供端到端会话保护，拿到 Thread Key 不代表 Wireshark 可以直接看到 Matter 业务明文。

如果新设备从未加入过目标网络，它本地当然也没有这张网络的 Key。此时不能靠终端 Debug 凭空恢复 Echo 尚未下发的凭据。

一套更可靠的现场取证清单

再次遇到这个页面时，可以先保存以下信息，不要保存真实 Key：

1. 手机系统、Alexa App 版本和账户区域；
2. Echo/eero 的具体型号与固件版本；
3. Alexa 显示的 Thread Network Name；
4. 同一局域网中 _meshcop._udp 服务公布的 Network Name、Extended PAN ID 和 Border Agent ID；
5. 设备是全新首次配网，还是已经加入过其他生态；
6. 弹窗出现在扫码后哪个阶段；
7. 设备 UART 是否出现 PASE、Network Commissioning、Thread Attach、CASE 和 CommissioningComplete；
8. 退出重试后，是仍要求 Key，还是直接跳过并成功；
9. Border Router 是否刚启用 Thread、刚升级或刚恢复出厂；
10. 家中是否同时存在 Apple、Google、Amazon、eero 或 Home Assistant 创建的多张 Thread 网络。

这组证据可以把问题分成三类：

1
2
3
4
5

平台没有取得凭据
    vs
平台取得了错误/过期凭据
    vs
设备收到正确 Dataset 后仍然 Attach 失败

三者的修复方向完全不同。

安全提醒：不要公开 Thread Network Key

Thread Network Key 是整张网络共享的敏感材料，不是一个可以贴进论坛求助的普通错误码。截图、UART 日志、pcap 辅助文件和录屏都可能无意中包含它。

如果 Key 已经公开泄露，应把它视为网络凭据泄露，并根据 Border Router/平台支持能力迁移或重建安全资料。不要假设删除一条 App 记录就已经让旧 Key 失效。

最终结论

Alexa 要求输入 32 位 Thread Network Key，不等于 Matter 设备缺少一个出厂密码，也不等于终端固件应该自己生成家庭网络凭据。

对 Echo 创建的网络，正常设计是：Echo 自动生成凭据，Amazon 安全保存，Alexa 配网时自动取得，再通过 Matter commissioning 下发给新设备。手工输入框的出现，说明这条自动凭据链没有按预期闭合。

最有效的排查方式不是继续寻找一个隐藏在二维码里的密码，而是沿着下面这条证据链定位：

1
2
3
4
5
6
7

Matter 扫码与 PASE
  -> 设备证明与 Matter 运行凭据配置
  -> 平台选择 Thread 网络
  -> 平台取得 Operational Dataset
  -> 设备接收 Dataset
  -> Thread Attach
  -> CASE 与 CommissioningComplete

只有看到 Dataset 已经到达设备，才应该把调查重点从 Alexa/凭据同步转向 Thread Attach 和终端实现。

参考资料

• Amazon Forum：How do I find the Thread network key?
• Amazon：Saving Your Wi-Fi Settings to Amazon FAQs
• Amazon Developer：Credential Locker REST API Reference
• Amazon Developer：Matter Simple Setup for Thread Overview
• eero：What is shared when I link my Amazon account?
• Google Home Developers：Thread Network SDK for Android
• OpenThread CLI：Network Key command reference
• Matter over Thread 入网为什么这么复杂？与 Zigbee 一步一步对照看懂
• 一次 Apple Home 配网为什么会出现两个 Matter Fabric？从完整日志还原真相

这是否意味着一台 HomePod 固定占用两个 Fabric？还是日志重复打印、配网重试，或者设备误入了另一个生态？

一份覆盖首次配网、两次凭据写入和重启恢复的完整设备日志给出了更精确的答案：

在这次实测中，Apple 配网流程确实创建了两个独立的 Matter Fabric：一个属于 Apple Inc.，另一个属于 Apple Keychain。但这不能简化成“每台 HomePod 固定占两个 Fabric”，也不能直接推广成 Apple 对所有系统版本的永久承诺。

本文不公开原始设备地址、Node ID、Fabric ID、Thread Dataset 或任何网络密钥，只保留理解协议流程所需的日志锚点。

先把容易混淆的三个概念拆开

Fabric 是 Matter 管理域

Matter Fabric 是一组共享信任根和运行身份体系的 Matter 节点。设备加入新的 Fabric 时，会获得属于该 Fabric 的 NOC、Node ID、访问控制项等数据。

一个设备可以同时属于多个 Fabric。例如，它可以分别接受 Apple Home、Google Home 或 Home Assistant 的直接 Matter 控制。这正是 Matter Multi-Admin 的基础。

Thread 网络是 IPv6 Mesh

Thread Operational Dataset 决定设备加入哪张 Thread Mesh，包括网络名称、信道、PAN 信息和安全材料。它解决的是低功耗 IPv6 网络接入，不定义设备属于哪个 Matter 管理域。

因此：

1
2
3

一张 Thread 网络
    可以承载
多个 Matter Fabric 的加密会话

第二个 Fabric 不等于第二张 Thread 网络。

HomePod 可以同时承担多个角色

HomePod 或 Apple TV 可能同时承担家庭中枢、Matter Controller 和 Thread Border Router 等角色。这些角色装在同一台硬件里，并不意味着它们是同一个协议概念。

Thread Border Router 负责在 Thread 与家庭其他 IP 网络之间路由数据；Fabric 则描述 Matter 身份和信任关系。不能按 HomePod 数量计算 Fabric 数量。

完整日志展示了怎样的时间线？

将唯一标识全部脱敏后，整个流程可以压缩成六个阶段。

接下来逐段看最关键的区别。

第一个 Fabric：典型的首次 BLE/PASE 配网

恢复出厂的设备先通过 Bluetooth LE 与 Commissioner 建立连接，然后完成 PASE。随后日志出现第一组运行凭据写入：

1
2
3
4

Received an AddTrustedRootCertificate command
Received an AddNOC command
Added new fabric at index: 0x1
successfully created fabric index 0x1 via AddNOC

创建 Fabric 还不是最终成功。设备继续加入 Thread，发布运行服务，并使用新 NOC 建立 CASE。直到下面这组日志闭环，Fabric 1 才真正提交：

1
2
3
4

CASE Session established ... fabricIndex 1
Received CommissioningComplete
Fabric index 0x1 was committed to storage
Fail-safe cleanly disarmed

提交日志记录的 Vendor ID 是 0x1349。Matter 开源 SDK 的厂商映射表将它标记为 Apple Inc.。

第二个 Fabric：不是第二次 BLE 配网

第一次 CommissioningComplete 之后，日志没有再次出现 BLE 建连、PBKDF、PASE，也没有再次下发 Thread Dataset。

相反，Fabric 1 中已经通过 CASE 认证的管理员继续发起了第二组操作：

1
2
3
4
5
6

Msg RX from 1:<redacted-controller-node> ... InvokeCommandRequest
GeneralCommissioning: Received ArmFailSafe
OpCreds: Received a CSRRequest command
OpCreds: Received an AddTrustedRootCertificate command
OpCreds: Received an AddNOC command
Added new fabric at index: 0x2

消息来源中的 1: 表示请求来自 Fabric Index 1。也就是说，第二个 Fabric 不是陌生生态偶然扫到设备后重新配网，而是第一个 Apple Fabric 的管理员通过现有 CASE 安全会话主动创建。

随后，新 Fabric 的 Controller 使用自己的 NOC 建立 CASE，并完成第二轮提交：

1
2
3
4
5

CASE matched destination ID: fabricIndex 2
CASE Session established ... fabricIndex 2
Received CommissioningComplete
Fabric index 0x2 was committed to storage
Fail-safe cleanly disarmed

第二次提交记录的 Vendor ID 是 0x1384。Matter SDK 厂商表对它的名称不是 Home Assistant，也不是第二台 HomePod，而是 Apple Keychain。

重启恢复排除了“重复日志”的可能

如果只在配网过程中看到两个 Added new fabric，还要考虑 Fail-safe 回滚、pending Fabric 或失败重试。

这份日志继续记录了设备重启。Matter Server 初始化时，FabricTable 从持久化存储中分别恢复：

1
2

Fabric index 0x1 was retrieved from storage ... VendorId 0x1349
Fabric index 0x2 was retrieved from storage ... VendorId 0x1384

因此可以排除三种误判：

• 不是同一 Fabric 的重复打印；
• 不是只创建但没有提交的 pending Fabric；
• 不是 FabricIndex 显示异常。

设备上确实保存了两套不同的 Matter Fabric 身份。

为什么会出现两次“配网成功”灯效？

如果产品固件把每个 CommissioningComplete 都转换成一次三秒成功提示，那么上述流程自然会产生两次灯效：

1
2
3
4
5
6
7

Apple Inc. Fabric 完成
    -> CommissioningComplete
    -> 成功灯效

Apple Keychain Fabric 完成
    -> CommissioningComplete
    -> 再次成功灯效

这不是设备加入了两次 Thread 网络，而是产品状态机把两个独立 Fabric 的完成事件都当成了用户可见的“整机配网成功”。

对于产品设计，这里有一个值得单独讨论的问题：第二个 Fabric 的建立属于同一次用户操作，LED 是否应该逐 Fabric 提示，还是只在整个生态流程结束后提示一次？协议事件和用户语义并不天然相同。

为什么不能写成“HomePod 固定占两个 Fabric”？

设备日志能证明两个 Apple Fabric 的存在和创建顺序，但不能仅凭设备侧 UART 确认每个 Controller Node 对应哪一台物理 Apple 设备。它更不能证明 Fabric 数量与 HomePod 数量之间存在一一对应关系。

更准确的说法是：

在本次 Apple Home 配网实测中，Apple 的配网体系为设备创建了 Apple Inc. 和 Apple Keychain 两个 Fabric。

下面几种说法则超出了证据：

• “每台 HomePod 都固定占两个 Fabric”；
• “再增加一台 HomePod 就会再增加两个 Fabric”；
• “所有 iOS、HomePod 软件版本永远采用相同流程”；
• “Thread Border Router 数量就是 Fabric 数量”。

Apple 的公开支持文档明确说明，Matter 配对信息会通过 iCloud Keychain 同步，并将 Keychain 与 Connected Services 分开管理。不过，公开文档没有直接写明“添加到 Apple Home 必然创建两个 Fabric”。

目前我们掌握的是两层证据：

1. Matter 开源 SDK 的厂商映射表明确存在 Apple Inc. 和 Apple Keychain 两个 Vendor ID；
2. 完整设备日志证明当前 Apple 软件组合实际使用了这两个 ID，并分别完成了 NOC、CASE、CommissioningComplete、存储提交和重启恢复。

这是很强的实现证据，但仍不应包装成 Apple 面向未来版本作出的公开协议承诺。

对 Matter 设备开发有什么影响？

1. 不要假设一次用户添加只产生一个 Fabric

产品状态机、统计和 UI 提示应把“单个 Fabric 完成”与“用户认为的整次添加完成”分开。仅靠 CommissioningComplete 次数驱动整机灯效，可能在不同生态下产生不同体验。

2. Fabric 容量要按真实条目计算

不要按手机、HomePod 或 Border Router 数量估算。应读取 Operational Credentials Cluster 的 Fabric/NOC 列表、CommissionedFabrics 和设备支持上限，并验证重启后的 FabricTable。

3. Thread 网络名不能识别 Matter 生态

即使 Thread 网络名称带有某个平台特征，也只说明设备使用了那份 Thread Dataset。判断 Matter Fabric 归属，应看 NOC、Fabric Vendor ID、CASE peer 和访问控制信息。

4. 删除、订阅和 OTA 都可能具有 Fabric 维度

两个 Apple 相关 Fabric 是两套身份域。某个 Fabric 的 CASE 或 Subscription 失效，不等于另一个 Fabric 被删除；OTA Provider、订阅和控制会话也必须结合 FabricIndex 分析。

一套可复用的双 Fabric 验证清单

以后再遇到“一次配网为什么出现两个 Fabric”，可以依次检查：

1. 配网开始前 CommissionedFabrics 是否为零；
2. 出现了几次 AddNOC；
3. 每次 AddNOC 创建了哪个 FabricIndex；
4. 请求来自 BLE/PASE、IP/PASE，还是已有 Fabric 的 CASE；
5. 每个 Fabric 是否分别建立 CASE；
6. 是否分别收到 CommissioningComplete；
7. 是否分别出现 committed to storage 和 Fail-safe disarm；
8. 重启后是否分别 retrieved from storage；
9. Vendor ID 在 Matter 厂商表中对应谁；
10. 整个过程中是否真的更换或重复下发 Thread Dataset。

只有把这些证据串起来，才能区分真正的双 Fabric、配网重试、Fail-safe 回滚和日志误读。

最终结论

这份完整日志证明：一次 Apple Home 用户配网操作可以在设备上留下两个持久化 Matter Fabric，即 Apple Inc. 与 Apple Keychain。

第二个 Fabric 由第一个 Apple Fabric 的管理员通过已有 CASE 会话创建；没有第二次 BLE/PASE，也没有加入第二张 Thread 网络。重启后两个 Fabric 分别恢复，排除了 pending 数据和重复打印。

因此，最准确的总结不是“HomePod 固定占两个 Fabric”，而是：

当前实测到的 Apple Home 配网实现会同时使用 Apple Home 控制域与 Apple Keychain 控制域；物理家庭中枢、Thread Border Router 和 Matter Fabric 必须分层理解。

参考资料

• Apple：Pair and manage your Matter accessories
• Apple Developer：Matter support in iOS
• CSA：Matter Specifications 下载页
• Matter connectedhomeip：Manufacturer Code 映射
• Matter over Thread 入网为什么这么复杂？与 Zigbee 一步一步对照看懂

不一定。

BLE 连接成功，只表示两台设备已经建立了一条无线链路。 后面通常还要发现 Service、找到 Characteristic、确认读写方式、订阅通知，应用数据才真正开始流动。

本文不从复杂的协议分层开始，而是跟着一台简单的 BLE 温度计，看清手机从“发现设备”到“收到温度变化”之间发生了什么。

读完后，你应该能够回答三个问题：

1. Service、Characteristic 和 Descriptor 分别是什么？
2. BLE 显示 Connected 后，手机为什么还要继续发现和订阅？
3. 怎样判断问题卡在连接、GATT，还是设备自己的业务协议？

先看结论：一次常见的 BLE 通信过程

先不管每个名词的精确定义，只看一条最常见的时间线：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

温度计发送广播
  ↓
手机扫描并发现温度计
  ↓
手机发起连接
  ↓
BLE 链路建立：Connected
  ↓
双方可能进行配对、加密和 MTU 交换
  ↓
手机发现设备提供的 Service
  ↓
手机发现 Service 里的 Characteristic 和 Descriptor
  ↓
手机读取数据、写入命令，或者订阅通知
  ↓
温度变化时，设备主动向手机发送新值

这里最容易混淆的是中间那条线：

1

建立 BLE 连接 ≠ 已经找到 GATT 服务 ≠ 已经订阅数据 ≠ 业务功能正常

每一步成功，都只能证明这一小步已经完成。

连接前：广播和扫描是在做什么？

BLE 设备在没有连接时，可以周期性发送很短的广播数据。广播通常可能包含：

• 设备名称；
• 设备地址或身份相关信息；
• 某些重要 Service 的 UUID；
• 厂商自定义数据；
• 设备是否允许连接等信息。

温度计不断发送广播，就像它在说：

“我在这里，我叫客厅温度计，现在可以连接。”

手机进行扫描，是在附近收听这些广播。收到广播，只证明手机“看见”了设备，并不代表双方已经连接。

当手机决定连接时，它会向目标设备发起连接请求。连接建立后，双方按照约定的时间间隔交换无线数据。此时调试工具通常会显示 Connected。

三组角色不要混在一起

BLE 中会遇到几组看起来相似的角色：

在常见的手机连接传感器场景中：

• 手机通常是 Central，也是 GATT Client；
• 传感器通常是 Peripheral，也是 GATT Server。

但这只是常见组合，不是强制绑定。Central 不一定永远是 GATT Client，Peripheral 也不一定永远是 GATT Server。

连接后：GATT 像一组整理好的资料柜

连接只解决“怎样把数据送到对方”。设备究竟提供哪些数据、哪些可以读取、哪些可以写入，则主要由 GATT 描述。

可以把一台 GATT Server 想成一个资料柜：

1
2
3
4
5
6
7
8
9

GATT Server
├── Service：电池
│   └── Characteristic：当前电量
├── Service：设备信息
│   ├── Characteristic：厂商名称
│   └── Characteristic：固件版本
└── Service：温度计功能
    ├── Characteristic：当前温度
    └── Characteristic：测量间隔

Service、Characteristic 和 Descriptor，就是整理这个资料柜的三种基本结构。

Service：一组相关功能

Service 用来把同一类功能放在一起，可以先把它理解成一个文件夹。

常见的标准 Service 有：

设备也可以定义自己的 Service。例如，一台温度计可以使用自定义 Service 表达测量结果和设置项。

Characteristic：真正要读写的数据项

Characteristic 是 Service 中具体的数据项。它通常包含：

• UUID：这是什么类型的数据；
• Value：当前数据值；
• Properties：允许怎样操作，例如 Read、Write、Notify；
• Descriptor：对这个数据项的补充说明或配置。

Properties 回答“支持什么操作”，Permissions 则回答“满足什么安全条件才允许操作”。所以，一个 Characteristic 即使带有 Read 属性，也可能要求链路先加密才能读取。

例如，标准 Battery Service 的 UUID 是 0x180F，其中 Battery Level Characteristic 的 UUID 是 0x2A19。如果它当前的 Value 是十进制 83，就表示剩余电量为 83%。

1
2
3
4
5

Battery Service（0x180F）
└── Battery Level Characteristic（0x2A19）
    ├── Value：83
    ├── Properties：Read、Notify
    └── Descriptor：通知开关

标准功能通常使用 Bluetooth SIG 分配的 UUID。产品自己的功能则常使用 128-bit 自定义 UUID。

Descriptor：Characteristic 的补充信息和开关

Descriptor 属于某个 Characteristic，可以描述数据格式，也可以控制它的行为。

初学者最常见的是 Client Characteristic Configuration Descriptor，通常简称 CCCD，UUID 为 0x2902。

如果一个 Characteristic 支持 Notify 或 Indicate，Client 通常要先写入 CCCD，告诉 Server：

“这个数据变化时，请主动发给我。”

因此，看见 Characteristic 支持 Notify，不等于手机已经能收到通知。支持通知是一种能力，写入 CCCD 才是实际订阅。

UUID 和 Handle 有什么区别？

调试工具里经常同时显示 UUID 和 Handle，它们不是一回事。

同一种标准 Characteristic 在不同设备上可以使用相同 UUID，但它在各自数据库里的 Handle 不一定相同。

应用通常先通过 UUID 发现目标，再使用发现到的 Handle 访问它。不要因为某次连接中 Handle 是 0x0012，就假设所有设备和所有固件版本都永远相同。

Read、Write、Notify 和 Indicate

找到 Characteristic 后，双方常用下面几种方式交换数据：

假设温度计每次变化都要上报：

1. 手机发现温度 Characteristic；
2. 手机写入它的 CCCD，开启 Notify；
3. 温度从 24.1°C 变为 24.3°C；
4. 设备发送 Notification；
5. 手机收到新值并更新页面。

如果第 2 步没有完成，设备即使一直在测温，手机也可能什么都收不到。

Notify 没有 ATT 层的逐条确认，Indicate 则有。这里说的是 GATT/ATT 这一层，不表示底层无线链路完全没有校验或重传。

ATT 又是什么？它和 GATT 有什么关系？

可以先记住一句话：

GATT 负责把数据组织成 Service、Characteristic 和 Descriptor；ATT 负责发现、读取、写入和传送这些 Attribute。

如果 GATT 像餐厅菜单，ATT 就像点单和上菜时使用的规则：

• 菜单怎样分组、一道菜叫什么，由 GATT 描述；
• “读取这个值”“写入那个值”“这个值变化了”等消息怎样发送，由 ATT 处理。

开发时经常直接使用平台提供的 GATT API，不需要手工拼每一个 ATT 数据包。但抓包、看日志或定位超时时，ATT Read、Write、Notification、MTU Exchange 等名字就会出现。

MTU：一次 ATT 消息能装多少

MTU 可以先理解成“一次允许携带多大的包裹”。BLE 的默认 ATT MTU 是 23 字节，但这 23 字节还包含 ATT 自己的字段，并不全是应用数据。

连接后，Client 和 Server 可以交换各自支持的 MTU，最终使用双方都能接受的大小。更大的 MTU 通常能让较长数据减少拆分，但需要注意：

• MTU 交换成功，不代表 Service 已经发现；
• MTU 更大，不代表通知已经订阅；
• MTU 更大，也不保证业务一定更快；
• 真正能放入的 Characteristic Value 通常小于 ATT MTU。

初学阶段不用急着计算每一层开销。先把 MTU 当成连接建立后可能进行的一项“传输能力协商”即可。

配对、绑定和加密是不是每次都有？

不一定。

有些 Characteristic 允许连接后直接读取；有些数据要求链路加密，甚至要求经过身份验证。此时双方可能进行配对，生成安全密钥并启用加密。

• Pairing：协商安全能力并生成密钥；
• Bonding：把密钥保存下来，方便以后重连；
• Encryption：使用密钥保护当前链路中的数据。

它们有关联，但不是同义词。BLE Connected 也不自动等于已经配对、已经绑定或已经加密。

如果读取某个 Characteristic 时提示权限或认证错误，应检查它的访问权限和当前安全级别，而不是只看连接状态。

从连接到收到数据，逐步证明了什么？

下面这张表很适合在调试时使用：

所以，“连接上了但不能用”并不矛盾。它只是说明故障范围已经从广播和连接阶段，缩小到了后续阶段。

初学者最容易遇到的五个误区

误区一：广播里有 Service UUID，连接后就一定能用

广播中的 Service UUID 主要帮助扫描端识别设备。真正的 Service、Characteristic、权限和数据仍要在连接后通过 GATT 访问。

误区二：能 Read，就一定能 Notify

Read 和 Notify 是不同能力。Notify 还需要 Client 完成订阅，Server 也要在合适时机主动发送数据。

误区三：Notify 和 Indicate 完全一样

两者都由 Server 主动发送，但 Indicate 要求 ATT 层确认，Notify 不要求。具体选择要看实时性、流量和可靠性需求。

误区四：UUID 就是数据内容

UUID 只说明数据类型，真正内容在 Value 中。Value 往往是一串字节，还要按照该 Characteristic 的格式解释。

误区五：MTU 越大，速度一定越快

MTU 只是影响一次 ATT 消息可以携带的大小。实际速度还受到连接间隔、PHY、数据长度、设备处理速度和应用交互方式等因素影响。

最简单的动手顺序

准备一台支持 BLE 的设备和一个能够查看 GATT 的调试工具，然后只做下面几步：

1. 扫描设备，观察名称、信号强度和广播内容；
2. 建立连接，确认 Connected；
3. 展开 Service 列表，先找 Device Information 和 Battery Service；
4. 查看 Characteristic 的 UUID、Properties 和 Value；
5. 对允许 Read 的 Characteristic 执行一次读取；
6. 对允许 Notify 的 Characteristic 开启订阅，观察 CCCD 和后续数据；
7. 断开再连接一次，观察哪些步骤需要重新执行。

不要随意向含义未知的 Characteristic 写入数据。它可能代表重启、清空数据、进入升级模式或其他控制命令。

第一次动手的目标不是记住所有 UUID，而是建立一条判断链：

1
2
3
4
5
6
7

能扫描到吗？
  -> 能连接吗？
  -> 能发现目标 Service 吗？
  -> 能找到目标 Characteristic 吗？
  -> 权限和安全条件满足吗？
  -> CCCD 订阅成功吗？
  -> 第一条读、写或通知出现了吗？

一页小抄

最后再看一次完整过程

一台 BLE 设备“真正可用”，通常不是一个瞬间，而是一串连续的小成功：

1
2
3
4
5
6
7

广播可见
  -> 连接建立
  -> 安全条件满足
  -> 如有需要，完成 MTU 等传输参数协商
  -> Service / Characteristic / Descriptor 被发现
  -> Read、Write 或 CCCD 订阅完成
  -> 第一条业务数据成功传输

以后再看到“BLE 已连接但没有数据”，不要把所有问题都叫作“连接失败”。沿着这条时间线向下检查，很快就能知道自己是在找不到服务、订阅没有完成，还是业务命令根本没有开始。

参考资料

• Bluetooth SIG：Bluetooth Low Energy Primer
• Bluetooth SIG：Generic Attribute Profile
• Bluetooth SIG：Battery Service 1.1
• Zephyr：Generic Attribute Profile 文档
• Zephyr：MTU Update 示例

这些步骤是在把简单问题复杂化，还是在解决不同的问题？

本文跟随一台刚恢复出厂的门磁传感器，从拆箱一直走到 App 能稳定显示“门已打开”或“门已关闭”。每走一步，我们都回答五个问题：

1. 现在是谁在和谁通信？
2. 设备得到了什么？
3. 为什么需要这一步？
4. Zigbee 在相近阶段怎样处理？
5. 成功到这里，还不能证明什么？

先限定比较范围

“Matter 入网”和“Zigbee 入网”都不只有一种路径。为了让两条时间线能够真正对齐，本文只比较两个最常见的首次入网场景：

• Matter over Thread：恢复出厂的设备，通过常见的 Bluetooth LE 临时通道，加入已有 Thread 网络和 Matter Fabric；
• Zigbee：Factory New 设备，通过 Network Steering，加入采用集中式安全模型的 Zigbee 网络。

本文不把下面这些分支混进主线：

• 已经连接 IP 网络的 Matter On-network Commissioning；
• Matter 的第二管理员和多 Fabric；
• Zigbee Rejoin、Touchlink、分布式安全网络；
• 新版 Zigbee 增加的 Zigbee Direct、动态密钥协商和批量 commissioning。

这些分支会改变部分消息和安全步骤，但不会改变本文最重要的分析方法：先分清网络接入、初始信任、长期身份和应用可用是四件不同的事。

第 0 章：阅读前先认识几个角色

先不要急着记 PASE、CASE、NOC 等缩写。理解下面这些角色，已经足够开始阅读。

在实际产品里，一个家庭中枢可能同时承担 Matter Commissioner、Matter Controller 和 Thread Border Router；一个 Zigbee 网关也可能同时包含 Coordinator、Trust Center 和应用管理功能。

装在同一个盒子里，不代表这些角色是同一件事。

两边的简化关系

1
2
3
4
5
6
7
8
9
10
11
12
13

Matter over Thread

手机或家庭中枢
  ├── Commissioner：办理入网
  ├── Controller：日常读取和控制
  └── 可能还包含 Thread Border Router
                         │
                         │ 在 Thread 与家庭 IP 网络间路由
                         ▼
                 Thread Mesh 中的门磁

Matter Fabric：
记录长期身份、管理关系和访问权限

1
2
3
4
5
6
7
8
9
10
11
12

Zigbee

Zigbee 网关
  ├── Coordinator：创建网络
  ├── Trust Center：管理准入和安全
  └── 应用管理：识别门磁能力
             │
             ▼
      Router 或直接父节点
             │
             ▼
          Zigbee 门磁

如果还分不清三者的位置，可以先阅读《Matter、Thread 与 Zigbee：先分清它们在哪一层》。

第 1 章：两台门磁加入的是同一种“网”吗？

先提出疑问

Matter over Thread 和 Zigbee 都可能使用 2.4 GHz IEEE 802.15.4。既然无线底层相似，为什么入网流程不能也做成一样？

Zigbee 更像一套完整的小区系统

在本文讨论的经典集中式 Zigbee 网络里，设备从扫描网络开始，随后建立父子关系、获得网络地址和 Network Key，最后被网关识别出应用能力。

Zigbee 自己定义了：

• Mesh 网络怎样形成；
• 网络地址怎样使用；
• Trust Center 怎样管理安全准入；
• NWK、APS 层怎样保护通信；
• Endpoint、Cluster、Attribute 怎样表达设备功能。

它很像一个同时负责道路、门禁、住户管理和物业服务的小区系统。

Matter over Thread 是两层组合

Matter over Thread 则把问题拆开：

• Thread 回答：设备怎样获得一条低功耗 IPv6 通信道路？
• Matter 回答：设备是谁、属于哪个家庭信任域、谁可以控制它、它有哪些标准能力？

因此，一台 Matter over Thread 门磁要完成两类登记：

1. 获得 Thread 网络资料并接入 Thread Mesh；
2. 获得 Matter 运行身份并加入一个 Fabric。

这两个结果经常在同一次用户操作中完成，但不是同一层协议状态。

为什么要这样拆开？

拆开的好处是：

• Matter 身份不必绑定在某个父节点或某个临时 IPv6 路由位置上；
• 同一个 Matter Fabric 可以包含 Thread、Wi-Fi 和 Ethernet 设备；
• Thread Border Router 只需要路由 IP 数据，不必理解门磁、灯或门锁；
• Matter 可以在应用层统一身份、权限和数据模型。

代价也很直接：

• 网络凭据和 Matter 身份凭据要分别管理；
• 配网要跨越 Bluetooth LE、Thread、IPv6 和 Matter 安全会话；
• “连接成功”出现了更多不同层次。

如果不拆开会怎样？

网络拓扑、应用身份和生态管理会更加紧密地绑定在一起。系统可能更直接，但跨不同 IP 承载、多管理员和统一访问控制会更依赖网关或厂商自己的设计。

到这里证明了什么？

我们只理解了两种架构的目标，还没有开始真正入网。

第 2 章：为什么要先打开一个“允许加入”的窗口？

Matter：设备先表示“我现在可以办理登记”

恢复出厂的 Matter 设备通常会进入可 commissioning 状态，或者由用户按键主动打开 Commissioning Window。设备随后通过支持的发现方式告诉附近的 Commissioner：“我现在接受入网。”

在本文的典型场景里，这通常包括 Bluetooth LE 广播。

窗口不会永远开放，因为长期允许陌生控制端尝试建立初始会话，会增加无意义连接和攻击面。用户明确触发配网，也能把一次现实世界中的操作与后续网络操作联系起来。

Zigbee：网关和设备两边都要准备好

Zigbee 网关通常先打开 Permit Join。Factory New 设备启动 Network Steering，在配置的信道集合中寻找允许加入的网络。

这里要区分两件事：

• Permit Join：网络允许新设备提出申请；
• 设备最终被接纳：还要经过关联和安全准入。

看到 Permit Join 已打开，不代表任何附近设备都已经成为网络成员。

可以怎样类比？

Commissioning Window 和 Permit Join 的目的相近，但它们不是同一条协议命令。

如果没有窗口会怎样？

设备或网络可能长期接受未经用户触发的入网尝试，既浪费资源，也难以把“用户正在添加这台设备”与无线世界里的请求对应起来。

到这里证明了什么？

只证明双方进入了“可以尝试添加”的状态，还没有找到彼此，更没有建立安全关系。

第 3 章：为什么 Matter 要扫码，而 Zigbee 常常自己搜索网络？

扫码不是无线连接

Matter 二维码或手动配对码携带的是 Onboarding Payload，也就是帮助 Commissioner 找到目标设备并建立初始信任的引导信息。

对本文主线最重要的两项是：

• Discriminator：帮助从附近多个待配网设备中缩小目标；
• Setup Passcode：后面建立初始安全会话时使用的秘密。

二维码不包含真实家庭的 Thread Dataset，也不会因为被摄像头扫到，就自动连接设备。

可以把它理解为：

二维码告诉接待员“应该找哪位新住户，以及第一次见面用什么暗号”，而不是直接把小区总钥匙印在包装上。

Matter 怎样发现设备？

典型过程是：

1
2
3
4
5

用户扫描二维码
  -> App 解析引导信息
  -> 手机扫描附近 Commissionable 广播
  -> 使用 Discriminator 等信息筛选目标
  -> 建立 Bluetooth LE 连接

Bluetooth LE Connected 只说明手机和设备之间有了一条近距离通信链路。

Zigbee 怎样发现网络？

经典 Network Steering 更像设备主动找小区：

1
2
3
4
5
6

设备扫描候选信道
  -> 发送 Beacon Request
  -> 接收周围网络的 Beacon
  -> 判断网络是否允许加入
  -> 比较候选网络和父节点
  -> 选择目标网络

设备看到 Beacon，只证明它发现了网络。它还没有完成 Association，也没有获得可用的 Network Key。

为什么两边选择不同？

Matter 的用户通常是在 App 中明确添加某一台商品设备，二维码能帮助用户指认目标，并提供设备独有的初始秘密。Zigbee Network Steering 则更强调由设备扫描附近符合条件的 Zigbee 网络，再进入网络侧准入流程。

这不是“扫码一定比扫描安全”，而是两种系统如何把现实世界中的用户操作与网络申请绑定起来的不同选择。

如果 Matter 只有 BLE 广播、没有配对码会怎样？

手机可能知道附近有待配网设备，却缺少设备独有的初始秘密来建立后续安全会话，也更难确认用户指向的是哪一台同型号设备。

到这里证明了什么？

扫码证明 App 获得了引导信息；BLE 连接证明双方可以传数据。两者都不能证明 Thread 或 Matter 入网成功。

第 4 章：Bluetooth LE 已经连接，为什么还需要 PASE？

“电话接通”不等于“进入保密会议室”

Bluetooth LE 解决的是近距离传输问题。它不自动证明对端就是二维码对应的设备，也不意味着 Thread 网络资料可以直接明文发送。

手机和设备会利用 Setup Passcode 建立一条本次 commissioning 使用的临时安全会话。Matter 把这一步称为 PASE，全称 Passcode Authenticated Session Establishment。

先记住一句话：

PASE 是配网阶段的临时安全通道，不是设备日常运行的长期身份证。

PASE 成功后能做什么？

Commissioner 可以通过受保护的 Matter 会话执行后续 commissioning 操作，例如：

• 读取设备的 commissioning 能力；
• 启动 Fail-safe；
• 配置法规或时间相关信息；
• 请求设备认证材料；
• 写入 Matter 运行凭据；
• 配置 Thread 网络。

Fail-safe 可以理解为“配网安全绳”：如果流程中途失败或超时，设备能够回退未最终确认的配置，避免长期停在只完成一半的状态。

Zigbee 中哪个步骤最像 PASE？

没有一个完全相同的步骤。

Zigbee Association 主要建立设备的网络成员关系和父子关系；初始 Link Key、Install Code 派生 Key 等则承担初始安全引导的一部分目的。它们与 PASE 有交集，但协议层次和生命周期不同。

如果没有 PASE 会怎样？

Thread Dataset、证书配置和其他 commissioning 数据将缺少 Matter 定义的初始安全会话保护，初始秘密也难以安全过渡到长期身份。

到这里证明了什么？

PASE 成功只证明双方建立了临时安全会话。设备仍可能没有 Thread 网络资料、没有 NOC，也没有加入 Fabric。

第 5 章：有了配网码，为什么还要验证设备是不是可信产品？

知道暗号，不等于拥有可信身份证

Setup Passcode 证明的是双方掌握同一个初始秘密。它不能单独回答：

• 设备是否由它声称的厂商制造；
• 设备是否持有对应的设备私钥；
• 产品身份和合规声明是否能形成可信链条；
• 当前响应是否来自一次旧通信的重放。

Matter 因此还有 Device Attestation，也就是设备认证。

用“身份证链”理解 Attestation

不用先背缩写，先看角色：

1. 每台设备有自己的设备证书和私钥；
2. 设备证书由上级产品认证机构签发；
3. Commissioner 信任更上层的根；
4. Commissioner 发送一次性随机挑战；
5. 设备使用私钥对本次挑战相关数据签名；
6. Commissioner 验证证书链、签名和产品声明。

专业名称对应如下：

PAA 根证书通常来自 Commissioner 的信任库，不是简单要求设备“自己拿一张根证书证明自己”。

Attestation 能证明到什么程度？

它帮助 Commissioner 验证设备持有的认证身份和产品声明。它不自动证明：

• 固件永远没有漏洞；
• 设备运行环境没有被破坏；
• 用户一定应该授权这台设备进入家庭；
• 入网后的每一次业务操作都天然允许。

设备认证是准入证据之一，最终策略仍由 Commissioner 和生态决定。

Zigbee 有没有完全对应的步骤？

在本文比较的经典 Zigbee 3.x 集中式安全加入中，没有与 Matter 设备证书链认证完全等价的通用步骤。

Trust Center 可以根据设备信息和安全策略决定是否接纳；Install Code 可以让设备与 Trust Center 拥有设备唯一的初始秘密。但“证明双方知道唯一秘密”与“验证厂商、产品声明和设备证书链”仍然是不同问题。

较新的 Zigbee 版本继续扩展 commissioning 和安全能力，因此具体项目必须回到目标 Zigbee Core、BDB 与安全策略确认，不能把本文的经典路径当成所有版本的唯一实现。

如果没有 Attestation 会怎样？

Commissioner 仍可能依靠配网码建立初始加密，但更难用标准化证书链验证设备声称的产品身份和设备私钥。

到这里证明了什么？

Attestation 成功证明认证材料通过了 Commissioner 的验证流程；它不证明 Thread 已连接，也不证明最终 CommissioningComplete 已完成。

第 6 章：为什么既要 Thread Dataset，又要 Matter NOC？

这是整篇文章最重要的问题。

两份材料回答两个不同问题

Thread Active Operational Dataset 回答：

设备怎样进入这张 Thread 网络？

它描述目标 Thread 网络的关键参数和安全材料，例如信道、网络标识、Mesh-Local Prefix 和网络安全信息。它不是适合公开分享的普通配置文本。

Node Operational Certificate，NOC 回答：

设备以什么 Node 身份加入哪个 Matter Fabric？

可以把二者理解为：

• Thread Dataset：小区道路和门禁的入场资料；
• NOC：写有住户身份和家庭归属的长期电子证件。

Matter 长期身份怎样产生？

典型流程可以简化为：

1
2
3
4
5
6

设备生成运行密钥对
  -> 设备提交 CSR
  -> Fabric 管理侧签发 NOC
  -> Commissioner 写入受信任根
  -> Commissioner 写入 NOC
  -> 建立 Node ID、Fabric 和初始管理关系

设备的运行私钥应留在设备内部。CSR 是证书签名请求，不是把私钥交给 Commissioner。

在典型流程中，AddNOC 还会帮助建立初始管理员主体和访问控制关系。日后 Matter 的读取、写入、命令和订阅仍要经过访问控制判断，而不是“知道设备 IP 地址就可以任意操作”。

Zigbee 用哪些材料？

Zigbee 没有一张与 NOC 完全等价的单一证件。几个常见概念分别承担不同作用：

Network Key 让设备参与受保护的 Zigbee 网络通信，但它不是某台设备独有的运行证书。短地址适合当前网络中的高效寻址，但也不等于长期产品身份。

最容易记错的几个等式

1
2
3
4
5
6

Thread Dataset ≠ Matter NOC
Matter Fabric ≠ Thread Network
Matter Fabric ≠ Zigbee PAN
Matter NOC ≠ Zigbee Network Key
Matter Node ID ≠ Zigbee Short Address
Setup Passcode ≠ Zigbee Install Code

它们可以在“网络凭据”“长期身份”“初始秘密”等目的层面比较，但不能在实现、抓包或日志里互换。

如果只有 Dataset、没有 NOC 会怎样？

设备可以获得 Thread 网络连接，却缺少加入 Matter Fabric 的标准长期身份。

如果只有 NOC、没有 Dataset 会怎样？

设备可能已经准备好 Matter 身份，却没有进入目标 Thread 网络的道路。

到这里证明了什么？

NOC 写入证明 Fabric 运行凭据已经配置到相应阶段。它不等于设备已经成功 Thread Attach，也不等于 CASE 和 CommissioningComplete 已完成。

第 7 章：设备怎样真正加入 Thread？Zigbee 又怎样加入自己的网络？

Matter：通过 PASE 下发 Thread 入场资料

在本文场景里，Commissioner 已经从家庭系统获得目标 Thread Dataset，再通过 PASE 保护的 commissioning 会话配置设备的 Thread 网络。

高层过程是：

1
2
3
4
5
6
7

Commissioner 配置 Thread Dataset
  -> 要求设备连接目标网络
  -> 设备扫描并找到目标 Thread Partition
  -> 设备寻找可用 Router 或 REED
  -> 建立 Parent-Child 关系
  -> 获得 Thread 网络数据和 IPv6 地址能力
  -> 成为 Child

Thread 使用 Mesh Link Establishment，简称 MLE，发现和维护邻居关系。本文的电池门磁通常作为 End Device，通过一个 Parent Router 通信。即使是 Router-Eligible 设备，首次 Attach 也先以 Child 身份进入网络。

Thread Border Router 的任务是把 Thread 与相邻 IP 网络连接起来。它不是负责给门磁解释 Matter Cluster 的应用网关，也不一定是门磁当前的无线父节点。

Zigbee：先建立网络位置，再完成安全准入

经典首次 Network Steering 可以简化为：

1
2
3
4
5
6
7
8

扫描信道和 Beacon
  -> 选择目标 PAN 与父节点
  -> Association Request
  -> Association Response
  -> 获得 16 位短地址
  -> Trust Center 安全准入
  -> 接收并安装 Network Key
  -> 开始受保护的 NWK 通信

Association 由 IEEE 802.15.4 MAC 层提供，用来建立网络成员关系。获得短地址说明设备已经有了初步网络位置，但它还必须正确接收、验证并安装安全材料。

所以：

• Transport Key 已经从发送端发出，不等于接收端已经解密；
• 收到 MAC ACK，不等于 Network Key 已安装；
• 获得短地址，不等于 BDB commissioning 全部完成。

两条路径真正对应在哪里？

两边都要解决“找网络、选父节点、获得网络安全材料、开始正常通信”，但凭据怎样送到设备、长期身份放在哪一层，设计明显不同。

如果只看到 Thread 设备成为 Child 会怎样？

可以确认 Thread 网络层已经进展到 Attach 成功附近，但仍不能确认 Matter CASE、CommissioningComplete 和应用订阅。

如果只看到 Zigbee Association Success 会怎样？

可以确认父子关系和短地址分配已经进展，但仍不能确认 Network Key 安装、TCLK 流程和应用发现。

第 8 章：Thread 已经连上，为什么 Matter 还要重新找设备？

从临时接待通道切换到正式道路

前面的 Matter 操作主要通过 Bluetooth LE 上的 PASE 会话完成。设备加入 Thread 后，后续日常通信应走 Thread 承载的 IPv6，而不是长期依赖手机与设备之间的 BLE 连接。

Commissioner 需要在正式 IP 网络中找到设备。这称为 Operational Discovery。Matter 使用 DNS-SD 等机制解析设备当前可用的地址和端口。

这里有一个很重要的设计：

Matter 身份是 Node 与 Fabric 身份，不是某个固定 IPv6 地址。

Thread 节点可能拥有多类 IPv6 地址，某些地址还会随拓扑变化。Controller 应通过运行态发现解析设备，而不是把 commissioning 时看到的某个地址永久当成设备身份。

为什么还要建立 CASE？

找到设备地址以后，双方使用 Fabric 的运行证书建立长期单播安全会话。这称为 CASE，全称 Certificate Authenticated Session Establishment。

可以这样区分：

PASE 像门口的一次性接待室，CASE 像正式住户凭证建立的长期安全通信。

Zigbee 为什么没有同样的通道切换？

经典 Zigbee 入网从扫描、Association 到后续 Cluster 通信，都留在 Zigbee 协议栈中。设备安装 Network Key 后，会继续通过 Zigbee NWK、APS 和 ZCL 交互。

它不需要经历“BLE 临时通道 → Thread/IPv6 正式通道”的相同切换，因此也没有与 Operational Discovery + CASE 完全等价的一组步骤。

Zigbee 仍然要处理地址映射、Device Announcement、Link Key 和应用发现，只是问题被组织在另一套协议结构里。

如果没有 Operational Discovery 会怎样？

Commissioner 可能知道设备的 Fabric 身份，却不知道它现在可以通过哪个 IP 地址和端口访问。

如果继续只用 PASE、不建立 CASE 会怎样？

日常通信将依赖初始配网秘密，难以利用 Fabric 证书、Node 身份和访问控制建立长期管理关系。

到这里证明了什么？

CASE 成功证明双方已通过正式网络和 Fabric 身份建立安全会话。最终 commissioning 仍要完成确认。

第 9 章：为什么还需要 CommissioningComplete？

配置写完，不等于验收结束

Commissioner 已经完成设备认证、运行凭据配置和 Thread 网络连接，也已经通过正式网络建立 CASE。最后，它会发送 CommissioningComplete。

这一步的意义可以理解为：

• 确认新的运行身份和网络路径确实可用；
• 正式结束本次 commissioning；
• 解除前面用于失败回滚的 Fail-safe；
• 不再把设备停留在“正在办理入住”的中间状态。

它像装修、通电和证件登记都完成后的最终交房签字。

Zigbee 怎样宣布完成？

Zigbee 设备安装 Network Key 并开始受保护通信后，通常还会：

• 发送 Device Announcement；
• 完成由目标 BDB 版本和 Trust Center 策略要求的 Link Key 相关流程；
• 由 BDB 状态机报告 commissioning 结果。

具体的 TCLK 更新或交换路径取决于目标版本和安全策略。不能看到 Network Key 就一概宣称所有安全步骤完成。

两边的成功阶梯

1
2
3
4
5
6
7
8
9
10
11

Matter over Thread

发现设备
  -> BLE 连接
  -> PASE
  -> Device Attestation
  -> NOC / Fabric 身份
  -> Thread Attach
  -> Operational Discovery
  -> CASE
  -> CommissioningComplete

1
2
3
4
5
6
7
8
9
10

Zigbee

发现网络
  -> 选择父节点
  -> Association
  -> 获得短地址
  -> 接收并安装 Network Key
  -> 受保护的 NWK 通信
  -> Device Announcement
  -> TCLK / BDB 相应流程完成

如果没有最终完成确认会怎样？

设备可能保留只完成一部分的网络或身份配置，系统也难以区分“仍在办理”与“已经正式可用”。Matter 的 Fail-safe 正是为了约束这种中间状态。

到这里证明了什么？

CommissioningComplete 成功证明本次 Matter commissioning 正式闭环。它仍不保证生态已经建立稳定订阅，也不保证 App 的设备模型完全正确。

第 10 章：为什么 App 显示“添加成功”，设备仍可能不可用？

入网成功与业务可用是两个阶段

一台门磁真正好用，至少还要让平台知道：

• 它有哪些 Endpoint；
• 它是什么 Device Type；
• 它实现了哪些 Cluster；
• 门开、门关状态从哪里读取；
• 状态变化怎样持续上报；
• 当前 Controller 是否有读取或订阅权限。

Matter Controller 通常会读取设备结构和属性，并建立 Subscribe。订阅建立后，设备才能在约定条件下持续报告状态变化。

如果 CommissioningComplete 已成功，但从未建立 Subscribe，门磁可能“在网、可信、可寻址”，App 却无法持续得到门状态。

Zigbee 网关也要做设备 Interview

Zigbee 网络接入完成后，网关通常还会：

• 查询 Node Descriptor；
• 查询 Active Endpoints；
• 读取 Simple Descriptor；
• 读取 Basic 属性；
• 识别支持的 Cluster；
• 配置 Reporting；
• 按需要建立 Binding。

所以 Zigbee 设备获得短地址或发送 Device Announcement，也不等于网关已经完整识别它。

把“成功”分成四级

这四级比一个模糊的“配网成功”更适合分析真实问题。

到这里证明了什么？

只有平台成功识别设备并稳定收发业务状态，才能说门磁对用户真正可用。

第 11 章：断线以后，为什么有时自动回来，有时必须重新配网？

设备离线不等于所有身份和密钥都已丢失。

Matter over Thread

如果设备仍保存 Thread Dataset 和 Fabric 凭据：

• Thread 可以重新选择父节点并 Reattach；
• IPv6 地址或路由位置可能变化；
• Controller 可以重新执行 Operational Discovery；
• CASE 会话可以按需重新建立；
• 原有 Fabric 身份不需要因为一次无线掉线重新签发。

因此：

1
2
3

Thread Reattach ≠ Matter Recommissioning
CASE 重建 ≠ 重新扫码入网
IPv6 地址变化 ≠ Matter Node 身份变化

只有凭据被清除、Fabric 被移除、网络资料失效或设备恢复出厂等情况，才可能需要重新走完整 commissioning。

Zigbee

设备如果保留网络参数和安全材料，可以通过 Rejoin 或恢复父子关系重新接入。Rejoin 与 Factory New 设备的首次 Network Steering 不是同一条路径。

1
2
3

Zigbee Rejoin ≠ 首次 Network Steering
父节点变化 ≠ EUI-64 身份变化
短地址变化 ≠ 换了一台物理设备

具体 Rejoin 安全条件仍取决于网络和 BDB 策略。

第 12 章：Matter 这样设计，究竟比 Zigbee 好在哪里？

不能用“步骤更多”直接推出“协议更安全”，也不能用“步骤更少”直接推出“体验更好”。更公平的比较是看两边选择解决什么问题，以及复杂度放在哪里。

Matter over Thread 的主要设计收益

• 把低功耗 IP 网络与 Matter 应用身份分开；
• 把初始配网秘密与长期运行证书分开；
• 定义设备认证和产品身份验证流程；
• 使用 Fabric、Node 身份和访问控制管理权限；
• 允许同一应用协议运行在 Thread、Wi-Fi 和 Ethernet 等 IP 承载上；
• Thread Border Router 不需要翻译 Matter 应用数据；
• 每个阶段都有相对清晰的成功边界。

Matter over Thread 付出的成本

• 角色、凭据和状态更多；
• 需要从 Bluetooth LE 临时通道切换到 Thread/IP；
• 要处理 PASE、Attestation、证书、CASE 和访问控制；
• Border Router、DNS-SD 或 IPv6 路径问题也会影响 commissioning；
• 日志里会出现更多“部分成功”状态。

经典 Zigbee 架构的主要特点

• 网络、安全和应用模型在同一套协议体系中；
• 典型网关架构下，首次加入链路比较集中；
• Coordinator、Trust Center 和应用管理经常由同一网关统一提供；
• 低功耗 Mesh、Cluster、Binding 和 Reporting 形成成熟体系；
• 跨 IP 网络或跨 Matter 生态时，通常由网关或 Bridge 终止两边协议并做应用语义转换。

Zigbee 的复杂度并没有消失

Zigbee 用户界面可能只显示“正在搜索设备”，但底层仍可能经历：

• 多信道扫描；
• 父节点选择；
• Association；
• Trust Center 准入；
• Transport Key；
• Network Key 安装；
• Frame Counter 与 Key Sequence 管理；
• TCLK 相关流程；
• Descriptor 查询；
• Binding 与 Reporting。

很多复杂度被网关集中处理，不代表它不存在。

第 13 章：如果把每个 Matter 步骤删掉，会失去什么？

这张表也回答了开篇问题：Matter over Thread 的长流程并不是围绕一个“无线连接”问题反复加步骤，而是连续解决不同问题。

第 14 章：用两个故障练习检查是否真的看懂

故障一：Matter 设备已经成为 Thread Child，但 App 最后超时

已经证明：

• 设备找到了 Thread 网络；
• Parent-Child 关系已经建立；
• Thread Attach 至少进展到网络层成功附近。

还要继续检查：

1. 设备是否发布或代理了运行态发现信息；
2. Commissioner 是否完成 Operational Discovery；
3. CASE 是否建立；
4. CommissioningComplete 是否成功；
5. 后续 Read、Subscribe 和 Report 是否出现。

不能因为 Thread Attached 就直接修改应用 Cluster，也不能把超时一概归因于射频。

故障二：Zigbee 门磁已经获得短地址，但网关没有显示设备

已经证明：

• Association 至少进展到地址分配；
• 设备与父节点之间有基本链路。

还要继续检查：

1. Transport Key 是否到达接收端；
2. 设备是否成功验证并安装 Network Key；
3. 是否开始受保护的 NWK 通信；
4. BDB 和目标 TCLK 流程是否完成；
5. Device Announcement 和 Descriptor 查询是否成功；
6. Reporting 是否正确配置。

不能把 MAC ACK、Association Response 或短地址当成完整业务成功。

一张最终时间线

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Matter over Thread

用户打开配网
  -> 扫码获得引导信息
  -> 发现并连接 BLE 设备
  -> PASE 临时安全会话
  -> Fail-safe 与基础配置
  -> Device Attestation
  -> CSR / NOC / Fabric 身份
  -> 配置 Thread Dataset
  -> Thread Attach
  -> Operational Discovery
  -> CASE 正式安全会话
  -> CommissioningComplete
  -> 读取设备能力并建立 Subscribe
  -> 门磁业务可用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

经典 Zigbee 集中式首次加入

网关打开 Permit Join
  -> 设备启动 Network Steering
  -> 扫描信道与 Beacon
  -> 选择网络和父节点
  -> Association
  -> 获得短地址
  -> Trust Center 安全准入
  -> 接收并安装 Network Key
  -> 受保护的 Zigbee 通信
  -> Device Announcement
  -> TCLK / BDB 相应流程
  -> Descriptor / Cluster 识别
  -> Binding / Reporting
  -> 门磁业务可用

最后只记住三句话

Thread 解决设备怎样接入低功耗 IPv6 网络。

Matter 解决设备是谁、属于哪个信任域、谁能控制它，以及怎样表达设备能力。

Zigbee 使用另一套更集中的网络、安全和应用体系完成相似的产品目标。

Matter over Thread 不是简单地把 Zigbee 的一次入网拆成更多消息。它把网络接入、初始秘密、产品身份、长期 Fabric 身份、正式安全会话和应用权限分别建模。

它的优势来自这种拆分，它的复杂度也来自这种拆分。

术语速查

继续阅读与资料来源

站内延伸：

• Matter 基础概念：Node、Fabric、Endpoint 与安全会话
• Thread 基础概念：IPv6 Mesh、设备角色与 Border Router
• Matter 与 Zigbee 关系映射：相似名词不等于相同协议
• Zigbee 入网流程：从 Network Steering 到可用设备
• Zigbee 各类 Key 的作用范围

公开技术资料：

• CSA 规范下载入口
• Matter 官方开源 SDK：CHIP Tool Commissioning Guide
• Matter SDK Access Control Guide
• OpenThread：Network Discovery and Formation
• OpenThread：Node Roles and Types
• Thread Group：Border Router 的职责
• CSA Zigbee Specification

本文描述的是便于理解的高层主线，不替代目标版本的 Matter Core、Thread、Zigbee Core、BDB 与生态实现要求。认证、量产和故障定责还应结合目标版本规范、设备日志、Controller 或网关日志与抓包证据。

先理解完整链路

一条可复用的发布链是：

1
2
3
4
5
6
7
8
9
10

本地源码
  -> fingerprint / profile / handler 静态检查
  -> 本地 build-only 打包
  -> 上传 Driver，产生 Driver ID 与 Version
  -> 创建或选择 Driver Channel
  -> 把指定 Driver Version 分配到 Channel
  -> 将测试 Hub 注册到 Channel
  -> 从 Channel 安装 Driver 到 Hub
  -> 创建 Channel Invitation
  -> 通过真实设备完成运行验证

其中有三个容易混淆的对象：

邀请链接不是登录 Token。创建邀请后，不需要把 PAT 一起发给测试者；PAT 过期也不等于已经创建的邀请立即失效。

CLI 认证：PAT 适合临时操作

SmartThings CLI 默认支持浏览器 OAuth 登录，也支持使用 Personal Access Token。当前新建 PAT 的有效期是 24 小时，不能设置成永久 Token。

在临时测试或无图形界面的开发机上，可以把 PAT 放进 CLI 配置：

1
2

default:
  token: "<YOUR_PAT>"

配置文件通常位于：

1

~/.config/@smartthings/cli/config.yaml

限制文件权限：

1

chmod 600 ~/.config/@smartthings/cli/config.yaml

不要把真实 Token 写进 Git、脚本、截图或文章，也尽量不要通过 --token 直接放在命令行中，以免进入 Shell history。出现 401 Unauthorized 时，先检查 Token 是否已过期，以及创建 PAT 时是否选择了所需 Scope。管理 Driver Channel 时，至少要注意官方文档要求的 Channel 读写权限。

如果是长期运行的服务集成，应使用 OAuth 2.0 和刷新机制，而不是定期手工更换 PAT。对于偶尔执行一次的 CLI 发布任务，短期 PAT 更简单，但要接受每天重新签发的限制。

设备身份：允许别名，但不要放宽匹配

实际项目中，同一类硬件可能因固件批次、销售渠道或身份迁移而报告不同 Model。此时可以让多个精确 fingerprint 指向同一个 Profile：

1
2
3
4
5
6
7
8
9
10
11
12

zigbeeManufacturer:
  - id: "example/motion-a"
    manufacturer: "Example"
    model: "MOTION-A"
    deviceProfileName: "motion-light-battery"
    deviceLabel: "Motion sensor"

  - id: "example/motion-b"
    manufacturer: "Example"
    model: "MOTION-B"
    deviceProfileName: "motion-light-battery"
    deviceLabel: "Motion sensor"

这表示两个身份共享同一组平台能力，不表示它们的 Zigbee 行为必然完全相同。至少要逐项比较：

• Endpoint、Device ID 与 Server/Client Cluster；
• Attribute 类型、单位、倍率和无效值；
• 上报方式、Reporting 配置与休眠行为；
• 厂商自定义 Cluster、Attribute 和 Command；
• 首次加入、rejoin、重启和恢复出厂行为。

Sub-driver 的 can_handle 也要覆盖同一组身份，并同时检查 Manufacturer 和 Model：

1
2
3
4
5
6
7
8
9

local supported_models = {
  ["MOTION-A"] = true,
  ["MOTION-B"] = true,
}

local function can_handle(_, _, device)
  return device:get_manufacturer() == "Example"
    and supported_models[device:get_model()] == true
end

只检查 Model、只检查 Manufacturer，或让 fingerprint 与 can_handle 使用不同的身份集合，都会造成“选中了 Profile，却没有进入预期 Handler”的隐蔽故障。

Profile 只声明真实支持的能力

一个运动传感器 Profile 可能包含：

1
2
3
4
5
6
7
8
9
10
11
12

name: motion-light-battery
components:
  - id: main
    capabilities:
      - id: motionSensor
        version: 1
      - id: illuminanceMeasurement
        version: 1
      - id: battery
        version: 1
    categories:
      - name: MotionSensor

如果 Driver 还支持检测保持时间、照度补偿等参数，可以通过 Preference 或自定义 Capability 暴露，但必须确认：

1. Driver 能把 App 命令正确转换成 Zigbee Write 或 Command；
2. 设备会接受该值；
3. Read Back 或后续 Report 能校正平台状态；
4. 参数范围和单位与固件一致。

UI 中出现一个字段，只证明 Profile 被平台接受，不证明设备端功能已经闭环。

本地门禁：先打包，不上传

在执行任何云端写操作前，先完成本地检查：

1
2

luac -p src/init.lua
luac -p src/sub_drivers/example/init.lua

再检查 YAML、JSON、fingerprint、Profile 和 Handler 的一致性。最关键的交叉关系包括：

1
2
3
4

fingerprint.deviceProfileName -> profiles/<name>.yml
fingerprint Manufacturer/Model -> can_handle 支持集合
profile capability -> 默认 Handler 或自定义 Handler
config.yml permissions -> 实际使用的 Zigbee Cluster

SmartThings CLI 的无上传构建命令是：

1
2
3

smartthings edge:drivers:package \
  --build-only /tmp/example-driver.zip \
  <driver-directory>

注意命令中的 drivers 是复数。--build-only 只生成 Zip，用于验证目录和包结构，不会创建云端 Driver 版本。

本地打包通过仍然不能证明：

• fingerprint 能匹配真实设备；
• Hub 上能加载 Driver；
• Zigbee 上报能转成正确 Capability event；
• App 下发能到达设备；
• rejoin、重启和低功耗场景正常。

上传 Driver

确认本地门禁通过后，再执行上传：

1

smartthings edge:drivers:package --json <driver-directory>

保存返回结果中的：

1
2

Driver ID
Driver Version

同一个 Driver 每次重新打包上传都会产生新 Version。后续给 Channel 分配时要使用这次返回的准确版本，不要只记 Driver ID。

执行云端写操作前，建议先列出现有资源：

1
2
3

smartthings edge:drivers --json
smartthings edge:channels --json
smartthings devices --type=HUB --json

这样可以避免重复创建 Channel，也能确认当前账号、区域和 Hub 是否正确。

创建 Channel 并绑定版本

第一次发布时创建 Driver Channel：

1

smartthings edge:channels:create

CLI 会交互式询问名称、描述和服务条款链接。也可以先准备 JSON/YAML，再使用 --input。

将刚上传的指定版本分配到 Channel：

1
2
3
4

smartthings edge:channels:assign \
  <DRIVER_ID> \
  <DRIVER_VERSION> \
  --channel <CHANNEL_ID>

Channel 锁定的是一个具体 Driver Version。以后上传新版本，不会自动替换 Channel 中的旧版本，也不会自动更新 Hub 上已安装的版本。

如果创建 Channel 时遇到 502 或响应体为空，不要立即连续重试。先重新查询：

1

smartthings edge:channels --json

确认服务端是否已经创建成功，再决定是否重试，避免产生重复 Channel。

Enroll Hub 并安装 Driver

先把自己的测试 Hub 注册到 Channel：

1
2
3

smartthings edge:channels:enroll \
  <HUB_ID> \
  --channel <CHANNEL_ID>

然后从该 Channel 安装 Driver：

1
2
3
4

smartthings edge:drivers:install \
  <DRIVER_ID> \
  --hub <HUB_ID> \
  --channel <CHANNEL_ID>

这两步解决的问题不同：

• enroll：让 Hub 能看到 Channel；
• install：把 Channel 中的某个 Driver 安装到 Hub。

只有 Channel 中存在正确版本、Hub 已注册、Driver 已安装，真实设备加入时才有机会匹配该 Driver。

更新版本时，可以重新 Assign 并 Install，也可以使用官方提供的组合方式：

1
2
3
4
5

smartthings edge:drivers:package \
  <driver-directory> \
  --install \
  --channel <CHANNEL_ID> \
  --hub <HUB_ID>

组合命令更方便，拆分命令则更适合首次发布和故障定位，因为每一步的输入与结果更清楚。

生成并核对邀请链接

为指定 Channel 创建邀请：

1
2

smartthings edge:channels:invites:create \
  --channel <CHANNEL_ID>

CLI 会根据交互选项创建 Invitation，并返回分享 URL。创建后再查询一次：

1
2

smartthings edge:channels:invites \
  --channel <CHANNEL_ID>

核对邀请是否存在、状态是否符合预期、URL 是否对应目标 Channel。不要只以“命令没有报错”作为成功证据。

收到链接的测试者通常需要：

1. 打开 Invitation URL 并登录 Samsung Account；
2. 接受邀请；
3. 选择自己的 Hub 加入 Channel；
4. 在可用 Driver 中选择并安装；
5. 在 SmartThings App 中重新添加或迁移目标设备。

第三方 Edge Driver 不等于 SmartThings 官方审核或认证 Driver。邀请页可访问、Driver 可安装，也不能替代真实设备验证和正式生态认证。

验证结果必须分层

建议用下面的矩阵记录结果：

查看 Hub 运行日志可使用：

1

smartthings edge:drivers:logcat --hub-address=<HUB_IP>

日志公开前要删除设备 EUI、Hub 地址、Location、账号信息、Channel/Driver UUID 和任何网络密钥。

发布前隐私清单

提交 Driver 或技术文章前，至少搜索：

• PAT、OAuth Client Secret、Refresh Token；
• Invitation URL 与短码；
• Hub、Location、Channel、Driver、Device UUID；
• 设备 EUI、Network Key、Install Code；
• 内部仓库地址、本机绝对路径和公司环境名称；
• 未公开产品型号、固件版本和测试记录。

示例应使用 <CHANNEL_ID>、<DRIVER_ID>、<HUB_ID> 等占位符。邀请链接虽然不是账号 Token，但获得链接的人可能因此访问测试 Channel，仍应按预期受众控制传播。

最后形成可重复的发布节奏

一次稳妥的迭代可以压缩为：

1
2
3
4
5
6
7
8

精确身份匹配
  -> 本地静态检查
  -> build-only
  -> 上传新 Version
  -> Channel 重新 Assign
  -> Hub 重新 Install
  -> Live log + 真实设备回归
  -> 最后才分享 Invitation URL

把每一步的 ID、Version、命令结果和验证结论保存在私有发布记录中；公开文章只保留方法、占位符和经过脱敏的错误现象。这样既能让发布流程可追溯，也不会把认证凭证和测试环境暴露出去。

官方资料：

• SmartThings CLI 与认证
• Driver Channels
• 接受共享 Channel 并安装 Driver
• Authorization and Permissions
• Edge Driver 结构