WakeOnLan Cluster

Cluster ID: 0x0503  |  Endpoint: Media endpoint (TV, set-top box, game console, etc.) |  Role: Server (Read-only, no commands)

WakeOnLan is a very simple yet practical Cluster in Matter media devices — it contains no commands, only exposes the device's MAC address and IPv6 link-local address, allowing external systems to remotely wake devices in standby or sleep mode by sending WoL Magic Packets.

This Cluster is typically used in conjunction with LowPower Cluster (0x0508): LowPower handles putting the device into low-power standby (Sleep command), while WakeOnLan provides the network address information needed for waking. One manages "sleep", the other manages "wake".

Attributes

The WakeOnLan Cluster has only 2 attributes, all read-only, with no commands or events. Both attributes are optional, but at least one must be supported; otherwise this Cluster serves no practical purpose.

MACAddress — MAC Address (0x0000)

The Ethernet MAC address used by the device to receive WoL Magic Packets. Format is a standard 48-bit MAC, represented as a colon-separated hexadecimal string, e.g., AA:BB:CC:DD:EE:FF.

This address is typically the device's wired NIC address. For WiFi-only devices, it can be the wireless NIC's MAC, but WoL reliability over WiFi is much lower than wired connections (requires router support for WiFi WoL forwarding).

↑ Back to Attributes

LinkLocalAddress — Link-Local Address (0x0001)

The device's IPv6 link-local address, stored as a byte array, fixed at 16 bytes. Link-local addresses start with fe80:: and are valid only within the same network link (same subnet/VLAN).

The purpose of this address is to let the waking party know which link the device is on, so the Magic Packet can be sent to the correct network segment. For cross-subnet wake scenarios, directed broadcast or subnet forwarding is also needed.

↑ Back to Attributes

WoL Wake Mechanism

Wake-on-LAN (WoL) is a decades-old network standard that allows remotely waking devices in standby, sleep, or powered-off states by sending a special Ethernet frame (Magic Packet). Matter's WakeOnLan Cluster does not send this packet; it simply tells you "which address to send to".

Magic Packet Structure

The Magic Packet format is very simple: a 6-byte 0xFF sync header, followed by the target MAC address repeated 16 times, totaling 102 bytes. It can be encapsulated in a UDP packet (commonly port 7 or 9) or sent directly as an Ethernet frame.

// WoL Magic Packet structure (102 bytes total)
FF FF FF FF FF FF          // Sync header: 6 bytes of 0xFF
AA BB CC DD EE FF          // Target MAC address, repeated 16 times
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

Wake-up Process

1. Read MACAddress from the device's WakeOnLan Cluster (cache in advance while device is online)
2. Device enters standby/sleep (may be triggered by LowPower Cluster's Sleep command)
3. When wake-up is needed, construct a Magic Packet containing the target MAC
4. Send via UDP broadcast (or directed broadcast) to the target network segment
5. Device NIC hardware detects the matching Magic Packet, triggers interrupt to wake the system
6. After device boots, it rejoins the Matter Fabric and resumes normal communication

Relationship with LowPower Cluster

In Matter media devices, WakeOnLan and LowPower (0x0508) are a complementary pair of Clusters:

Typical media devices (such as TVs, set-top boxes) implement both Clusters simultaneously. When the user says "Turn off the TV", LowPower's Sleep is invoked; when they say "Turn on the TV", a Magic Packet is sent using WakeOnLan's address.

Example Data

Read a smart TV's WakeOnLan Cluster attributes:

{
  // --- Wake-on-LAN Addresses ---
  "0x0000": "AA:BB:CC:DD:EE:FF",   // MACAddress = device's wired NIC MAC address
  "0x0001": "fe80::a8bb:ccff:fedd:eeff"  // LinkLocalAddress = IPv6 link-local address
}

Common Scenarios