docs: add Matter pairing troubleshooting handbook; record bulb state + DHCP reservation mismatch (W1N-207)
This commit is contained in:
windyboy
@@ -205,6 +205,14 @@ prefixes (`fd00:5a7:6415:1::/64`, `fd97:d580:16fe:1::/64`); several LAN55 hosts
|
||||
routers in NDP. This is normal Thread-BDR behaviour and was not the Matter
|
||||
failure cause.
|
||||
|
||||
**Matter 灯泡（2026-08-21 实测，W1N-207）：** 两盏 ESP32-C2 Matter 灯泡
|
||||
（VP `0x4891/0x4100`，OUI `34:98:7a`）——工作盏 MAC `34:98:7a:25:a1:f0`；故障盏
|
||||
MAC `34:98:7a:27:7f:08`（hostname `matter`，动态 .145）。故障盏已在 Aqara fabric
|
||||
`4DF2B1455D19402D` 内、宣告 `CM=0`（不在配对模式）且缺 GUA → 找回需**恢复出厂**
|
||||
后扫它自己的二维码。DHCP 保留 `matter`（.45 → MAC `34:98:7a:27:10:bc`）与故障盏
|
||||
MAC 不符，保留从未租出（待修，见 [hosts/gw.md](../hosts/gw.md)）。完整排障知识：
|
||||
[docs/matter-pairing-troubleshoot.md](matter-pairing-troubleshoot.md)。
|
||||
|
||||
---
|
||||
|
||||
## Quick orientation (who runs what)
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
# Matter 配网排障手册
|
||||
|
||||
> 基于 Matter 1.5.1 Core Spec §4.3.1 与本环境（EdgeRouter X + UniFi AP + Aqara M3 +
|
||||
> Home Assistant）2026-08-21 实测整理。配套 Linear W1N-207。
|
||||
|
||||
## 1. Matter 配网协议要点（发现即一切）
|
||||
|
||||
- **发现走 mDNS（DNS-SD）**，UDP **5353**，组播 `224.0.0.251` / `ff02::fb`。
|
||||
**不经过单播 DNS（如 AdGuard .36）、不需要反向 DNS、不需要 DHCPv6**（SLAAC 即满足 Matter
|
||||
的 IPv6 要求）。
|
||||
- 服务类型：
|
||||
- `_matterc._udp` — 可配网设备（Commissionable），**配对模式才有效**
|
||||
- `_matter._tcp` — 已配设备（Operational），TXT 里含 fabric 信息
|
||||
- 子类型（配对方按此过滤）：
|
||||
- `_L<全12位 discriminator>`（如 `_L3266`）— 按二维码里的完整 discriminator 精确匹配
|
||||
- `_S<高4位>`（如 `_S12`）
|
||||
- `_V<vendorId>`、`_T<deviceType>`（可选）
|
||||
- `_CM`（仅真正处于配对模式时发布）
|
||||
- TXT 关键键：`D=`（discriminator，规范 **SHALL** 必填）、`VP=`（vendor+product）、
|
||||
**`CM=`**、`RI=`（rotating id）、`PH=`/`PI=`（配对提示）。
|
||||
- 配对端口：**TCP 5540**（PASE/CASE）。部分生态（Aqara M3）为 Thread 中继节点用 **5552**。
|
||||
- 实例名：64 位随机 hex；**进入配对模式时更换**（可用作"是否重新进过配对"的信号）。
|
||||
- 规范参考：[Matter 1.5.1 Core Spec §4.3.1](https://csa-iot.org/wp-content/uploads/2026/03/23-27349-010_Matter-1.5.1-Core-Specification.pdf)、
|
||||
[Google Home: Commissionable and Operational Discovery](https://developers.home.google.com/matter/primer/commissionable-and-operational-discovery)、
|
||||
[Matter Handbook: Discovery](https://handbook.buildwithmatter.com/how-it-works/discovery/)、
|
||||
[connectedhomeip: IP commissioning](https://pigweed.googlesource.com/third_party/github/project-chip/connectedhomeip/+show/59edd2ff8506b1e3dabb7040d716f0e75a2312d1/docs/guides/ip_commissioning.md)。
|
||||
|
||||
## 2. 关键判据：CM=0 = 不在配对模式
|
||||
|
||||
规范 §4.3.1.2 / §4.3.1.7：
|
||||
|
||||
- 设备可以长期宣告 `_matterc`（**Extended Discovery**），但 **`CM=0` 表示"当前不接受配网"**。
|
||||
- **已在 fabric 里的设备**（宣告里同时有 `_matter._tcp` + `_I<fabric>._sub` 运营记录）重配时
|
||||
通常报 `CM=0` —— 它已配好，不是新设备。
|
||||
- **配对方不能把已配设备当新设备加** → 重加/找回必须先**恢复出厂**（清 fabric，重启后以
|
||||
`CM=1` 全新配对模式宣告），再用**它自己的二维码**添加。
|
||||
- 常见误判：抓包看到 `_matterc` 宣告就以为"在配对模式"——**必须看 `CM=`**。
|
||||
|
||||
## 3. 本环境实测事实（2026-08-21，W1N-207）
|
||||
|
||||
| 事实 | 状态 |
|
||||
|---|---|
|
||||
| LAN55 IPv6/mDNS 链路 | ✅ 全正常（RA→交换机→AP→客户端；mDNS 双向通；igmp snooping off、mdns on、无客户端隔离、无组播增强、PMF off、WPA2、仅 2.4G） |
|
||||
| Matter 不依赖单播 DNS/.36、反向 DNS、DHCPv6 | ✅ 已排除（.36 健康且不在路径上） |
|
||||
| HA matter-server 曾宣告两代前的旧 GUA | ✅ 已修复（重启 `core_matter_server`；宣告恢复当前前缀） |
|
||||
| ISP PD /60 随重拨轮换 → Matter IPv6 缓存反复失效 | ⚠️ 环境性根因；对策 = 重拨后重启 matter-server + 重启 M3 |
|
||||
| EdgeOS 上静态 ULA 不可行 | ✅ 已尝试并回滚（switch0 不支持静态 `ipv6 address`；显式 router-advert 会替换 PD-slaac RA） |
|
||||
| 两盏 ESP32-C2 Matter 灯泡（VP `0x4891/0x4100`，OUI `34:98:7a`） | 工作盏 `34:98:7a:25:a1:f0`；故障盏 `34:98:7a:27:7f:08`（hostname `matter`，动态 .145） |
|
||||
| 故障盏已在 Aqara fabric `4DF2B1455D19402D`，宣告 `CM=0` 且缺 GUA | ⚠️ 找回需**恢复出厂**（清 fabric + 重拿 IPv6），再扫它自己的二维码 |
|
||||
| DHCP 保留 `matter`（.45 → MAC `…10:bc`）与实际灯泡 MAC（`…7f:08`）不符 | ⚠️ 保留从未租出，待修（见 hosts/gw.md） |
|
||||
| 遗留 SSID（element/vwire/vport） | ✅ 已清理 |
|
||||
|
||||
## 4. 抓包方法（BusyBox 兼容）
|
||||
|
||||
**视角必须在 LAN55**（推荐 AP `br0`：同时看到有线 M3/HA 与无线灯泡/手机）。用 66 网段电脑
|
||||
看不到 55 的组播。AP 是 BusyBox：**不要用 `--line-buffered`**；引号外层双引号、内层单引号。
|
||||
|
||||
完整抓取（跑配对时保持窗口开着，`Ctrl+C` 结束）：
|
||||
|
||||
```bash
|
||||
ssh zhiqiangf@192.168.55.5 "tcpdump -ni br0 -s 0 -vvv -tt 'udp port 5353 or tcp port 5540 or tcp port 5552'"
|
||||
```
|
||||
|
||||
精简过滤（只看 Matter 信号）：
|
||||
|
||||
```bash
|
||||
ssh zhiqiangf@192.168.55.5 "tcpdump -ni br0 -s 0 -vvv -tt 'udp port 5353 or tcp port 5540 or tcp port 5552' | grep -E '_matterc|_matter|_L[0-9]+|_S[0-9]+|_CM|_V[0-9]+|_T[0-9]+|\.5540|\.5552'"
|
||||
```
|
||||
|
||||
存 pcap 供 Wireshark：把上面 `-w /tmp/matter.pcap` 追加到 tcpdump 参数（去掉 `-vvv`），
|
||||
`scp zhiqiangf@192.168.55.5:/tmp/matter.pcap .` 拉回本地分析。
|
||||
|
||||
### 阶段对照表
|
||||
|
||||
| 阶段 | 应该看到 | 对应问题 |
|
||||
|---|---|---|
|
||||
| 发现（设备侧） | `_matterc._udp` + `_L3266._sub` + `_S12._sub` + TXT `D=3266 CM=1` + SRV `:5540` + AAAA | **无宣告**=设备没入网/没进配对模式；**`CM=0`**=不在配对模式（已配设备）；**无 `_L3266`**=固件子类型缺失 |
|
||||
| 发现（配对方侧） | M3/手机查询 `_L3266._sub._matterc._udp` | 查询有、无应答 = 码/discriminator 不匹配或设备不在线 |
|
||||
| 配对握手 | 到设备 IP **TCP 5540 SYN/SYN-ACK** 双向 | **SYN 无 ACK**=设备不可达/防火墙；**完全无 5540**=发现阶段没完成 |
|
||||
| 配完后 | 设备宣告 `_matter._tcp` + `_I<fabric>._sub` | 出现 = 已入网成功 |
|
||||
|
||||
## 5. 排障决策树（按顺序）
|
||||
|
||||
1. 抓包看**有没有 `_matterc` 宣告**：没有 → 设备不通电 / 没连上 Wi-Fi / 没进配对模式
|
||||
（先解决"设备在线"，网络侧已反复验证正常）。
|
||||
2. 有宣告但 **`CM=0`** → 设备已配 / 不在配对模式 → **恢复出厂**后重试（用它自己的二维码）。
|
||||
3. 有宣告 `CM=1` 但**无 `_L<disc>` 子类型** → 固件 mDNS 缺陷 → 升固件或换通用发现配对方。
|
||||
4. `CM=1` + 子类型齐全但**无 TCP 5540** → 配对方没匹配上（查码/discriminator）或设备不可达。
|
||||
5. 有 5540 但配对中断 → 查 `CM` 源（码是否正确）、设备电源、fabric 状态（是否需先清）。
|
||||
|
||||
## 6. 相关文档
|
||||
|
||||
- [docs/lan-overview.md](lan-overview.md) — LAN 拓扑、SSID 清理、ULA 不可行
|
||||
- [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) — matter-server 重拨运维规范
|
||||
- [docs/unifi-network.md](unifi-network.md) — UniFi 网络/IPv6/SSID 记录
|
||||
- [hosts/gw.md](../hosts/gw.md) — DHCP 保留 `matter` MAC 错位（待修）
|
||||
@@ -129,3 +129,9 @@ IPv6 was re-verified by read-only SSH on 2026-08-20 during the UniFi AP/AC
|
||||
check: the IPv6 routing table shows connected `/64`s on `eth0` (LAN66) and
|
||||
`switch0` (LAN55) plus `::/0` via `pppoe0`; both UniFi APs obtained SLAAC
|
||||
addresses from the router's RAs. No configuration changes were made.
|
||||
|
||||
**DHCP 保留 `matter` MAC 错位（2026-08-21 发现，待修，W1N-207）：** 静态映射
|
||||
`matter` → .45 / MAC `34:98:7a:27:10:bc`，但实际 Matter 灯泡的 MAC 是
|
||||
`34:98:7a:27:7f:08`（动态租约 .145，hostname `matter`）。保留 .45 从未被租出。
|
||||
修正需在 `service dhcp-server shared-network-name LAN2 ... static-mapping matter`
|
||||
里把 MAC 改为 `34:98:7a:27:7f:08`（或删除该保留），**未执行**。
|
||||
|
||||
Reference in New Issue
Block a user