SCOUT

A SCOUT message is sent by a node that wants to discover Zenoh peers or routers on the network. SCOUT messages are sent before any transport session is established, typically over UDP multicast or broadcast.

Behaviour

  • A node MAY send SCOUT at any time to discover nodes matching its WhatAmIMatcher filter.

  • SCOUT SHOULD be transmitted via multicast or broadcast so that all reachable nodes can receive it.

  • On receiving a SCOUT, a node MUST check whether its role (WhatAmI) matches the sender’s WhatAmIMatcher bitmap; if it matches, the node SHOULD reply with a HELLO in unicast.

  • A node MUST NOT respond to its own SCOUT (compare ZenohIDs when I==1).

Flow

A                   B                   C
|       SCOUT       |                   |   (multicast/broadcast)
|─────────────────>|                   |
|         \──────────────────────────>|
|                   |                   |
|       HELLO       |                   |   (unicast, if B matches)
|<─────────────────|                   |
|                   |      HELLO        |   (unicast, if C matches)
|<──────────────────────────────────── |

A node SHOULD retransmit SCOUT with exponential back-off until at least one HELLO is received or a platform-specific timeout expires.

Wire Format

Flags:
  Z  If Z==1, extension chain follows.

 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+
|Z|X|X|  SCOUT  |   ID = 0x01
+-+-+-+---------+
|    version    |   Protocol version (u8); current value: 0x09
+---------------+
|zid_len|I|WHAT |   Packed byte (see below)
+-+-+-+-+-+-+-+-+
~      ZID      ~   if I==1: ZenohID (1 + zid_len bytes)
+---------------+
~  [ScoutExts]  ~   if Z==1: extension chain
+---------------+

Flag Constants

Flag Bit Value

I

3

0x08

Z

7

0x80

Packed Byte Layout

 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+
|  zid_len  |I|W|
+-------+-+-+-+-+
Sub-field Bits Meaning

zid_len

7:4

If I==1: actual ZID byte count = 1 + zid_len (range 1–16)

I

3

ZenohID present; if 0, no ZID bytes follow

WHAT

2:0

WhatAmIMatcher bitmap: bit0=Router, bit1=Peer, bit2=Client

Fields

version (u8)

Protocol version. MUST be 0x09 in the current protocol. Implementations MUST silently discard SCOUT messages with an unrecognised version.

zid_len (4 bits)

Encoded ZID length. Only meaningful when I==1.

I (bit 3)

When set, the sender’s ZenohID follows. Including the ZenohID allows responders to suppress self-responses.

WHAT (bits 2:0)

Bitmap of WhatAmI roles the sender wishes to discover. See WhatAmIMatcher.

ZID (variable, 1–16 bytes)

Present only when I==1. The sender’s ZenohID.