Chapter 12 — Message Network Protocol

The Message Network protocol implements the mandatory foundation of OpenLCB: node identification, protocol capability discovery, and error signaling. Every node must support these handlers.

Source files: src/openlcb/protocol_message_network.c, src/openlcb/protocol_message_network.h

12.1 Handled MTIs

MTI	Name	Handler Function	Auto-Reply?
0x0100	Initialization Complete	`handle_initialization_complete()`	Only if duplicate Node ID detected
0x0101	Initialization Complete Simple	`handle_initialization_complete_simple()`	Only if duplicate Node ID detected
0x0828	Protocol Support Inquiry	`handle_protocol_support_inquiry()`	Yes: Protocol Support Reply
0x0668	Protocol Support Reply	`handle_protocol_support_reply()`	No
0x0488	Verify Node ID Addressed	`handle_verify_node_id_addressed()`	Yes: Verified Node ID
0x0490	Verify Node ID Global	`handle_verify_node_id_global()`	Yes if payload matches or is empty
0x0170/0x0171	Verified Node ID / Simple	`handle_verified_node_id()`	Only if duplicate Node ID detected
0x0068	Optional Interaction Rejected	`handle_optional_interaction_rejected()`	No (fires app callback)
0x00A8	Terminate Due to Error	`handle_terminate_due_to_error()`	No (fires app callback)

12.2 Verify Node ID

sequenceDiagram participant Requester participant Node Note over Requester,Node: Addressed Variant Requester->>Node: Verify Node ID Addressed (0x0488) Node-->>Requester: Verified Node ID (0x0170) Note over Requester,Node: Global Variant (empty payload) Requester->>Node: Verify Node ID Global (0x0490) Node-->>Requester: Verified Node ID (0x0170) Note over Requester,Node: Global Variant (with Node ID) Requester->>Node: Verify Node ID Global (payload = target ID) Note over Node: Match? Reply. No match? Ignore. Node-->>Requester: Verified Node ID (0x0170)

Addressed: Always replies with Verified Node ID containing this node's full 48-bit Node ID.
Global (empty payload): Every node on the network replies.
Global (with Node ID): Only the node whose ID matches the payload replies.

The reply MTI is MTI_VERIFIED_NODE_ID (0x0170) or MTI_VERIFIED_NODE_ID_SIMPLE (0x0171) depending on whether the node's protocol_support flags include PSI_SIMPLE.

12.3 Protocol Support Inquiry / Reply

PIP (Protocol Identification Protocol) allows any node to discover what protocols another node supports. The reply carries a 48-bit bitmap in 6 payload bytes:

// Reply payload layout (6 bytes):
// Byte 0: bits [23:16] of protocol_support
// Byte 1: bits [15:8]
// Byte 2: bits [7:0]
// Byte 3: bits [47:40]
// Byte 4: bits [39:32]
// Byte 5: bits [31:24]

Firmware upgrade swap: When state.firmware_upgrade_active is set, the handler replaces PSI_FIRMWARE_UPGRADE with PSI_FIRMWARE_UPGRADE_ACTIVE in the reply, informing the requestor that a firmware upgrade is in progress.

12.4 Optional Interaction Rejected (OIR)

OIR is sent when a node receives an addressed MTI it does not implement. The payload contains:

Bytes	Content
0-1	Error code (e.g., `ERROR_PERMANENT_NOT_IMPLEMENTED_UNKNOWN_MTI_OR_TRANSPORT_PROTOCOL`)
2-3	The rejected MTI value

When receiving an OIR, the handler parses the error code and rejected MTI, then fires the optional on_optional_interaction_rejected application callback.

12.5 Terminate Due to Error

Similar to OIR but signals that a multi-message sequence has been aborted. The payload format is identical (error code in bytes 0-1, triggering MTI in bytes 2-3). The application callback on_terminate_due_to_error fires if non-NULL.

12.6 Duplicate Node ID Detection

Three message types trigger duplicate Node ID detection:

Initialization Complete: If the payload contains this node's own Node ID, another node with the same ID just came online.
Initialization Complete Simple: Same check.
Verified Node ID: If the payload matches this node's ID, a duplicate exists.

When a duplicate is detected, the handler sends a PC Event Report with the well-known event EVENT_ID_DUPLICATE_NODE_DETECTED. This is done at most once per boot (the duplicate_id_detected flag prevents repeat reports).