网络唤醒 Cluster（WakeOnLan）

Cluster ID: 0x0503  |  所在 Endpoint: 媒体端点（电视、机顶盒、游戏主机等） |  角色: Server（只读，无命令）

WakeOnLan 是 Matter 媒体设备中一个非常简单但实用的 Cluster —— 它不包含任何命令，只暴露设备的 MAC 地址和 IPv6 链路本地地址， 让外部系统能够通过发送 WoL Magic Packet（魔术包）将处于待机或休眠状态的设备远程唤醒。

这个 Cluster 通常和 LowPower Cluster（0x0508）配合使用： LowPower 负责让设备进入低功耗待机状态（Sleep 命令）， WakeOnLan 则提供唤醒所需的网络地址信息。两者一个管"睡"，一个管"醒"。

属性详解

WakeOnLan Cluster 只有 2 个属性，全部只读，没有任何命令和事件。 两个属性都是可选的，但至少要支持其中一个，否则这个 Cluster 没有实际意义。

MACAddress —— MAC 地址（0x0000）

设备用于接收 WoL Magic Packet 的以太网 MAC 地址。 格式为标准的 48 位 MAC，以冒号分隔的十六进制字符串表示，例如 AA:BB:CC:DD:EE:FF。

这个地址通常是设备有线网卡的地址。对于只有 WiFi 的设备，也可以是无线网卡的 MAC， 但 WoL 在 WiFi 环境下的可靠性远不如有线连接（需要路由器支持 WiFi WoL 转发）。

↑ 返回属性列表

LinkLocalAddress —— 链路本地地址（0x0001）

设备的 IPv6 链路本地地址（Link-Local Address），以字节数组形式存储，固定 16 字节。 链路本地地址以 fe80:: 开头，仅在同一网络链路（同一子网/VLAN）内有效。

这个地址的用途是让唤醒方知道设备在哪个链路上，以便将 Magic Packet 发送到正确的网段。 对于跨子网唤醒场景，还需要配合定向广播或子网转发。

↑ 返回属性列表

WoL 唤醒机制

Wake-on-LAN（WoL）是一项已有数十年历史的网络标准，允许通过发送一个特殊的以太网帧（Magic Packet） 来远程唤醒处于待机、休眠或关机状态的设备。Matter 的 WakeOnLan Cluster 并不负责发送这个包， 它只是告诉你「往哪个地址发」。

Magic Packet 结构

Magic Packet 的格式非常简单：6 字节的 0xFF 同步头， 后面跟着目标 MAC 地址重复 16 次，总计 102 字节。 可以封装在 UDP 包中（常用端口 7 或 9），也可以直接作为以太网帧发送。

// WoL Magic Packet 结构（共 102 字节）
FF FF FF FF FF FF          // 同步头：6 字节全 0xFF
AA BB CC DD EE FF          // 目标 MAC 地址，重复 16 次
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF
AA BB CC DD EE FF

唤醒流程

1. 从设备的 WakeOnLan Cluster 读取 MACAddress（设备在线时提前缓存）
2. 设备进入待机/休眠（可能由 LowPower Cluster 的 Sleep 命令触发）
3. 需要唤醒时，构造包含目标 MAC 的 Magic Packet
4. 通过 UDP 广播（或定向广播）发送到目标网段
5. 设备网卡硬件检测到匹配的 Magic Packet，触发中断唤醒系统
6. 设备启动后重新加入 Matter Fabric，恢复正常通信

与 LowPower Cluster 的关系

在 Matter 媒体设备中，WakeOnLan 和 LowPower（0x0508）是一对互补的 Cluster：

典型的媒体设备（如电视、机顶盒）会同时实现这两个 Cluster。 用户说「关闭电视」时调用 LowPower 的 Sleep，说「打开电视」时用 WakeOnLan 的地址发送 Magic Packet。

示例数据

读取一台智能电视的 WakeOnLan Cluster 属性：

{
  // --- 网络唤醒地址 ---
  "0x0000": "AA:BB:CC:DD:EE:FF",   // MACAddress = 设备有线网卡的 MAC 地址
  "0x0001": "fe80::a8bb:ccff:fedd:eeff"  // LinkLocalAddress = IPv6 链路本地地址
}

常见场景