MAC Commands

A MAC command payload consists of:

• 1 byte: command identifier
• optional bytes: command-specific payload

Support for MAC commands is optional.

Command Registry

Identity Request (1)

Requests that the destination respond with its node identity.

A common use is resolving a node hint to a full address. A node that knows only a peer’s hint sends this command as a broadcast or multicast carrying a FILTER_NODE_HINT filter; a matching node replies with an encrypted unicast (or blind unicast) response carrying its full node identity. When the requester believes the peer may not yet know the requester’s own address, it sends its full source address in the request so the peer can reply directly.

Because a broadcast Identity Request can solicit many replies:

• A node MAY decline to respond to a request from an unknown source.
• A repeater MAY decline to forward a broadcast Identity Request, particularly when its filters are broad enough to solicit a large number of replies.

In order to manage the potential flood of responses, the following rules MUST be applied for broadcast (always) and (by default) multicast:

• The Route option must either be absent or empty, otherwise the request should be dropped.
• Responses must be delayed by a random amount of time drawn from a window of 0.5 to 30 seconds, so that the selected nodes do not all answer at once. A delayed response that then fails channel-activity assessment follows the responder’s normal bounded CCA backoff-and-retry before being dropped.

A FILTER_NODE_HINT filter names a single node, so a request carrying one solicits a single reply however far it travels. A request without one selects by role or capability, and every node it reaches may answer; such a request is therefore confined to the requester’s own neighbourhood:

• The FHOPS byte must either be absent or set to 0x00. A request that is flood routed — FHOPS present with either nibble nonzero — MUST NOT be answered.
• The response MUST NOT carry a FHOPS field (the FCF flood hop count flag is clear), keeping the reply within the single hop the request was allowed to cross.

These requirements MAY be relaxed for specific private channels, but MUST remain in place for all public channels. Note that these requirements are specifically designed to allow discovering identities from a specific repeater location on the mesh network.

An Identity Request is answered with a targeted unicast identity response, never by flooding an advertisement to the whole network.

Identity Request Options

A unicast Identity Request requires no payload. A multicast or broadcast request MUST carry at least one filter option, so that only the intended nodes respond.

Options use the CoAP-style delta-length encoding defined in Packet Options. As in CoAP, an option’s key encodes its criticality: odd-numbered keys (least-significant bit set) are critical, even-numbered keys are elective. A node that encounters a critical option it does not understand MUST treat itself as excluded and MUST NOT respond.

Filter options select which nodes respond. They combine as a logical AND across different filter types and a logical OR among repeated filters of the same type: a node responds only if it satisfies every filter type present, and it satisfies a given filter type if it matches any one of that type’s values. Non-filter options (such as NONCE) do not participate in this matching.

Signal Report Request (2)

Requests that the destination respond with signal quality information about the link.

No command-specific payload.

Signal Report Response (3)

Reports signal quality measurements in response to a Signal Report Request.

Echo Request (4)

Requests that the destination respond with an Echo Response.

Echo requests may be used for:

• round-trip latency measurement
• reachability testing
• frame-counter synchronization (by observing the frame counter in the response’s SECINFO)

Echo Response (5)

Carries a response to a prior Echo Request, including any echo data from the request.

PFS Session Request (6)

Initiates a PFS session. The sender generates a fresh ephemeral node address and transmits it along with a requested session duration. See Perfect Forward Secrecy Sessions for the session establishment mechanism, key derivation, and wire-level privacy properties.

PFS Session Response (7)

Sent in response to a PFS Session Request. The responder generates its own ephemeral node address, returns it along with the accepted duration, and both sides derive session keys from the ephemeral addresses. See Perfect Forward Secrecy Sessions.

End PFS Session (8)

Terminates an active PFS session. May be sent by either party. Upon receipt, both sides securely erase the private keys for their ephemeral addresses and revert to using their long-term keys. See Session Lifetime for all conditions under which a session ends.

No command-specific payload. The sender and recipient are identified by the packet’s addressing fields.

No-Op (9)

This command does nothing, however it will produce a UACK when sent via a packet type that requests an ACK.