Chapter 13 — Event Transport Protocol

The Event Transport protocol handles producer/consumer identification, event reports, and learn/teach operations. Each node maintains lists of events it produces and consumes, and the protocol handler automatically responds to identification queries.

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

13.1 Consumer/Producer Identified Messages

When a node receives an Identify Consumer or Identify Producer request, it checks whether the requested event ID is in its consumer or producer list. If found, it responds with the appropriate Identified message including the event's current state:

State	Consumer MTI	Producer MTI
Unknown	0x04C7 Consumer Identified Unknown	0x0547 Producer Identified Unknown
Set (active)	0x04C4 Consumer Identified Set	0x0544 Producer Identified Set
Clear (inactive)	0x04C5 Consumer Identified Clear	0x0545 Producer Identified Clear
Reserved	0x04C6 Consumer Identified Reserved	0x0546 Producer Identified Reserved
Range	0x04A4 Consumer Range Identified	0x0524 Producer Range Identified

The event state is tracked per-event in the node's producer/consumer lists. The functions extract_consumer_event_status_mti() and extract_producer_event_status_mti() return the correct MTI based on the stored state.

13.2 Identify Events: Multi-Message Enumeration

The Identify Events message (global 0x0970 or addressed 0x0968) requests a node to report all events it produces and consumes. This is a multi-message response that uses the enumerate flag:

sequenceDiagram participant Requester participant Node participant Dispatcher Requester->>Node: Identify Events (0x0970) loop For each producer event Node->>Dispatcher: set enumerate=true, valid=true Dispatcher-->>Requester: Producer Identified (0x0544/0x0545/0x0547) end loop For each consumer event Node->>Dispatcher: set enumerate=true, valid=true Dispatcher-->>Requester: Consumer Identified (0x04C4/0x04C5/0x04C7) end Note over Node: Clear enumerate flag

The handler walks through all producer events first, then all consumer events, using an internal index that persists across re-enumeration calls. When the last event has been sent, the enumerate flag is cleared and the dispatcher advances to the next node.

13.3 Event Ranges

Event ranges use a power-of-2 encoding where the lowest set bit in the Event ID indicates the range size. For example, an Event ID of 0x0501010100FF0100 with the lowest set bit at position 8 covers a 256-event range. Range messages allow a single response to cover many events.

13.4 Learn Event

The Learn Event message (MTI 0x0594) carries an Event ID that should be stored by nodes in "learn mode." The handler extracts the Event ID and forwards it to the optional on_event_learn application callback. No automatic response is generated.

13.5 PC Event Report (PCER)

The PC Event Report (MTI 0x05B4) announces that an event has occurred on the network. The handler:

Extracts the 8-byte Event ID from the payload.
Searches the node's consumer list for a matching event.
If found, fires on_consumed_event_pcer with the event index and ID.
If not found, fires on_pc_event_report (generic notification).

sequenceDiagram participant Producer as Producer Node participant Network participant Consumer as Consumer Node Producer->>Network: PC Event Report (Event ID) Network->>Consumer: PC Event Report (Event ID) Note over Consumer: Search consumer list alt Event found in list Consumer->>Consumer: on_consumed_event_pcer(index, event_id) else Not in list Consumer->>Consumer: on_pc_event_report(event_id) end

13.6 PCER with Payload

The PCER with Payload variant (MTI 0x05F4) carries additional data bytes beyond the 8-byte Event ID. This is used for extended event information. The handler forwards the event ID and extra payload to the on_pc_event_report_with_payload callback.

13.7 Application Callbacks

All event transport callbacks are optional (NULL is safely ignored). They are defined in interface_openlcb_protocol_event_transport_t:

Callback	When Fired
`on_consumed_event_identified`	A matching consumer event identification was received
`on_consumed_event_pcer`	A PCER matching one of our consumed events arrived
`on_consumer_range_identified`	Consumer Range Identified received
`on_producer_range_identified`	Producer Range Identified received
`on_event_learn`	Learn Event received
`on_pc_event_report`	PCER not matching any consumed event
`on_pc_event_report_with_payload`	PCER with payload received