protocol_event_transport.c File Reference

Event Transport protocol implementation. More...

Functions
void	ProtocolEventTransport_initialize (const interface_openlcb_protocol_event_transport_t *interface_openlcb_protocol_event_transport)
	Initializes the Event Transport protocol layer.
uint16_t	ProtocolEventTransport_extract_consumer_event_status_mti (openlcb_node_t *openlcb_node, uint16_t event_index)
	Extracts the appropriate MTI for consumer event status.
uint16_t	ProtocolEventTransport_extract_producer_event_status_mti (openlcb_node_t *openlcb_node, uint16_t event_index)
	Extracts the appropriate MTI for producer event status.
void	ProtocolEventTransport_handle_consumer_identify (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Identify message.
void	ProtocolEventTransport_handle_consumer_range_identified (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Range Identified message.
void	ProtocolEventTransport_handle_consumer_identified_unknown (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Identified Unknown message.
void	ProtocolEventTransport_handle_consumer_identified_set (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Identified Set message.
void	ProtocolEventTransport_handle_consumer_identified_clear (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Identified Clear message.
void	ProtocolEventTransport_handle_consumer_identified_reserved (openlcb_statemachine_info_t *statemachine_info)
	Handles Consumer Identified Reserved message.
void	ProtocolEventTransport_handle_producer_identify (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Identify message.
void	ProtocolEventTransport_handle_producer_range_identified (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Range Identified message.
void	ProtocolEventTransport_handle_producer_identified_unknown (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Identified Unknown message.
void	ProtocolEventTransport_handle_producer_identified_set (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Identified Set message.
void	ProtocolEventTransport_handle_producer_identified_clear (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Identified Clear message.
void	ProtocolEventTransport_handle_producer_identified_reserved (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer Identified Reserved message.
void	ProtocolEventTransport_handle_events_identify (openlcb_statemachine_info_t *statemachine_info)
	Handles global Identify Events message.
void	ProtocolEventTransport_handle_events_identify_dest (openlcb_statemachine_info_t *statemachine_info)
	Handles Identify Events message with destination addressing.
void	ProtocolEventTransport_handle_event_learn (openlcb_statemachine_info_t *statemachine_info)
	Handles Event Learn message.
void	ProtocolEventTransport_handle_pc_event_report (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer/Consumer Event Report message.
void	ProtocolEventTransport_handle_pc_event_report_with_payload (openlcb_statemachine_info_t *statemachine_info)
	Handles Producer/Consumer Event Report message with payload.

Detailed Description

Event Transport protocol implementation.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Handles producer/consumer identification, event reports, and learn/teach operations. Automatically responds to Identify Consumer and Identify Producer when the event is in the node's list. Dispatches to optional application callbacks for all received event notifications.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

ProtocolEventTransport_initialize()

void ProtocolEventTransport_initialize

(

const interface_openlcb_protocol_event_transport_t *

interface_openlcb_protocol_event_transport

)

Initializes the Event Transport protocol layer.

Stores the callback interface. Call once at startup.

Algorithm:

1. Store pointer to callback interface in static variable
2. Interface remains valid for application lifetime

Use cases:

• Called during application startup
• Required before processing any event messages

* @param interface_openlcb_protocol_event_transport Pointer to callback interface structure
* 

Warning

Pointer must remain valid for lifetime of application

NOT thread-safe - call during single-threaded initialization only

Attention

Call before enabling CAN message reception

See also

interface_openlcb_protocol_event_transport_t - Callback interface structure

ProtocolEventTransport_extract_consumer_event_status_mti()

uint16_t ProtocolEventTransport_extract_consumer_event_status_mti	(	openlcb_node_t *	openlcb_node,
		uint16_t	event_index )

Extracts the appropriate MTI for consumer event status.

Returns the Consumer Identified MTI (Unknown/Set/Clear) for consumers.list[event_index].

Algorithm:

1. Access consumer event at specified index
2. Switch on event status field:
   • EVENT_STATUS_SET → return MTI_CONSUMER_IDENTIFIED_SET
   • EVENT_STATUS_CLEAR → return MTI_CONSUMER_IDENTIFIED_CLEAR
   • Default/unknown → return MTI_CONSUMER_IDENTIFIED_UNKNOWN

Use cases:

• Responding to consumer identify requests
• Event enumeration responses

* @param openlcb_node Pointer to node containing consumer event list
* 

* @param event_index Index into the node's consumer event list
* 

Returns

MTI value corresponding to event state:

• MTI_CONSUMER_IDENTIFIED_UNKNOWN for unknown state
• MTI_CONSUMER_IDENTIFIED_SET for set state
• MTI_CONSUMER_IDENTIFIED_CLEAR for clear state

Warning

Pointer must NOT be NULL

Index must be valid (< consumer.count)

Attention

Caller must ensure event_index is within bounds

See also

ProtocolEventTransport_extract_producer_event_status_mti - Producer equivalent

ProtocolEventTransport_extract_producer_event_status_mti()

uint16_t ProtocolEventTransport_extract_producer_event_status_mti	(	openlcb_node_t *	openlcb_node,
		uint16_t	event_index )

Extracts the appropriate MTI for producer event status.

Returns the Producer Identified MTI (Unknown/Set/Clear) for producers.list[event_index].

Algorithm:

1. Access producer event at specified index
2. Switch on event status field:
   • EVENT_STATUS_SET → return MTI_PRODUCER_IDENTIFIED_SET
   • EVENT_STATUS_CLEAR → return MTI_PRODUCER_IDENTIFIED_CLEAR
   • Default/unknown → return MTI_PRODUCER_IDENTIFIED_UNKNOWN

Use cases:

• Responding to producer identify requests
• Event enumeration responses

* @param openlcb_node Pointer to node containing producer event list
* 

* @param event_index Index into the node's producer event list
* 

Returns

MTI value corresponding to event state:

• MTI_PRODUCER_IDENTIFIED_UNKNOWN for unknown state
• MTI_PRODUCER_IDENTIFIED_SET for set state
• MTI_PRODUCER_IDENTIFIED_CLEAR for clear state

Warning

Pointer must NOT be NULL

Index must be valid (< producer.count)

Attention

Caller must ensure event_index is within bounds

See also

ProtocolEventTransport_extract_consumer_event_status_mti - Consumer equivalent

ProtocolEventTransport_handle_consumer_identify()

void ProtocolEventTransport_handle_consumer_identify

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Identify message.

Responds with Consumer Identified if this node consumes the requested event.

Algorithm:

1. Extract target event ID from incoming message payload
2. Search node's consumer list for matching event
3. If event not found:
   • Mark outgoing message as invalid (no response)
   • Return early
4. If event found:
   • Construct Consumer Identified response message
   • Set MTI based on current consumer event state
   • Copy event ID to response payload
   • Mark outgoing message as valid

Use cases:

• Remote node querying if this node consumes an event
• Configuration tools discovering event consumers

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Incoming message must have valid event ID payload

Note

If event not consumed by this node, no response is generated

Response MTI depends on current event state (unknown/set/clear)

Payload count is set automatically by OpenLcbUtilities_copy_event_id_to_openlcb_payload

See also

ProtocolEventTransport_extract_consumer_event_status_mti - Determines response MTI

ProtocolEventTransport_handle_consumer_range_identified()

void ProtocolEventTransport_handle_consumer_range_identified

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Range Identified message.

Forwards Consumer Range Identified to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Discovering event consumers on the network
• Building event routing tables

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Callback receives the base event ID of the range

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_consumer_identified_unknown()

void ProtocolEventTransport_handle_consumer_identified_unknown

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Identified Unknown message.

Forwards Consumer Identified Unknown to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking consumer states on the network
• Updating event state displays

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_consumer_identified_set()

void ProtocolEventTransport_handle_consumer_identified_set

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Identified Set message.

Forwards Consumer Identified Set to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking consumer states on the network
• Synchronizing event states across nodes

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_consumer_identified_clear()

void ProtocolEventTransport_handle_consumer_identified_clear

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Identified Clear message.

Forwards Consumer Identified Clear to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking consumer states on the network
• Synchronizing event states across nodes

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_consumer_identified_reserved()

void ProtocolEventTransport_handle_consumer_identified_reserved

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Consumer Identified Reserved message.

Forwards Consumer Identified Reserved to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Handling future protocol extensions
• Logging unusual event states

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Reserved states are defined by future OpenLCB specifications

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_producer_identify()

void ProtocolEventTransport_handle_producer_identify

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Identify message.

Responds with Producer Identified if this node produces the requested event.

Algorithm:

1. Extract target event ID from incoming message payload
2. Search node's producer list for matching event
3. If event not found:
   • Mark outgoing message as invalid (no response)
   • Return early
4. If event found:
   • Construct Producer Identified response message
   • Set MTI based on current producer event state
   • Copy event ID to response payload
   • Mark outgoing message as valid

Use cases:

• Remote node querying if this node produces an event
• Configuration tools discovering event producers

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Incoming message must have valid event ID payload

Note

If event not produced by this node, no response is generated

Response MTI depends on current event state (unknown/set/clear)

Payload count is set automatically by OpenLcbUtilities_copy_event_id_to_openlcb_payload

See also

ProtocolEventTransport_extract_producer_event_status_mti - Determines response MTI

ProtocolEventTransport_handle_producer_range_identified()

void ProtocolEventTransport_handle_producer_range_identified

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Range Identified message.

Forwards Producer Range Identified to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Discovering event producers on the network
• Building event routing tables

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Callback receives the base event ID of the range

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_producer_identified_unknown()

void ProtocolEventTransport_handle_producer_identified_unknown

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Identified Unknown message.

Forwards Producer Identified Unknown to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking producer states on the network
• Updating event state displays

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_producer_identified_set()

void ProtocolEventTransport_handle_producer_identified_set

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Identified Set message.

Forwards Producer Identified Set to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking producer states on the network
• Synchronizing event states across nodes

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_producer_identified_clear()

void ProtocolEventTransport_handle_producer_identified_clear

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Identified Clear message.

Forwards Producer Identified Clear to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Tracking producer states on the network
• Synchronizing event states across nodes

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_producer_identified_reserved()

void ProtocolEventTransport_handle_producer_identified_reserved

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer Identified Reserved message.

Forwards Producer Identified Reserved to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Handling future protocol extensions
• Logging unusual event states

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Reserved states are defined by future OpenLCB specifications

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_events_identify()

void ProtocolEventTransport_handle_events_identify

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles global Identify Events message.

Enumerates all producer then consumer events, responding with Identified messages. Uses the enumerate flag for multi-message sequencing.

Algorithm:

1. Check if more producer events need enumeration (enum_index < count):
   • If yes: Call _identify_producers() to handle next producer event
   • Return to caller for transmission
2. If all producers enumerated:
   • Mark producer enumeration as complete
3. Check if more consumer events need enumeration (enum_index < count):
   • If yes: Call _identify_consumers() to handle next consumer event
   • Return to caller for transmission
4. If all consumers enumerated:
   • Reset both enumeration indices to 0
   • Mark consumer enumeration as complete
   • Clear enumeration flag

Use cases:

• Network-wide event discovery
• Configuration tools building complete event maps
• Node initialization and announcement

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Enumerates all producer events first, then all consumer events

Uses enumeration state machine to handle multiple responses

Responses are generated incrementally across multiple calls

Caller must continue calling until enumerate flag becomes false

See also

ProtocolEventTransport_extract_producer_event_status_mti - Get producer response MTI

ProtocolEventTransport_extract_consumer_event_status_mti - Get consumer response MTI

ProtocolEventTransport_handle_events_identify_dest()

void ProtocolEventTransport_handle_events_identify_dest

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Identify Events message with destination addressing.

Checks addressing then delegates to handle_events_identify for addressed variant.

Algorithm:

1. Check if incoming message is addressed to this node
2. If addressed to this node:
   • Call ProtocolEventTransport_handle_events_identify() for processing
   • Return to caller
3. If not addressed to this node:
   • Mark outgoing message as invalid (no response)

Use cases:

• Configuration tools requesting complete event list from specific node
• Targeted event discovery without network-wide broadcast

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Checks message destination before processing

If not addressed to this node, no response is generated

See also

ProtocolEventTransport_handle_events_identify - Actual event identification logic

ProtocolEventTransport_handle_event_learn()

void ProtocolEventTransport_handle_event_learn

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Event Learn message.

Forwards Learn Event to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Teaching this node a new event to produce or consume
• Configuration mode for event learning
• Dynamic event configuration

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Callback must implement actual event learning logic

See also

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_pc_event_report()

void ProtocolEventTransport_handle_pc_event_report

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer/Consumer Event Report message.

Forwards PC Event Report to the app callback. No automatic response.

Algorithm:

1. Check if callback is registered (!= NULL)
2. If callback registered:
   • Extract event ID from incoming message payload
   • Invoke callback with node context and event ID
3. Mark outgoing message as invalid (no automatic response)

Use cases:

• Receiving event notifications from producers
• Triggering consumer actions in response to events
• Event logging and monitoring

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Callback is responsible for consuming the event and taking action

See also

ProtocolEventTransport_handle_pc_event_report_with_payload - Event report with additional data

interface_openlcb_protocol_event_transport_t - Callback registration

ProtocolEventTransport_handle_pc_event_report_with_payload()

void ProtocolEventTransport_handle_pc_event_report_with_payload

(

openlcb_statemachine_info_t *

statemachine_info

)

Handles Producer/Consumer Event Report message with payload.

Forwards PC Event Report with payload to the app callback. No automatic response.

Algorithm:

1. Check if payload count is greater than event ID size (8 bytes)
2. If payload too small:
   • Mark outgoing message as invalid (no response)
   • Return early (malformed message)
3. Check if callback is registered (!= NULL)
4. If callback registered:
   • Extract event ID from first 8 bytes of payload
   • Calculate payload data count (total - 8 bytes)
   • Get pointer to payload data (after event ID)
   • Invoke callback with node, event ID, count, and payload pointer
5. Mark outgoing message as invalid (no automatic response)

Use cases:

• Receiving event reports with sensor data
• Events carrying configuration or state information
• Extended event notifications with context

* @param statemachine_info Pointer to state machine context containing incoming message
* 

Warning

Pointer must NOT be NULL

Payload must be at least sizeof(event_id_t) + 1 bytes

Note

Always sets outgoing_msg_info.valid to false (no automatic response)

Callback receives payload data pointer and byte count

Payload count excludes the event ID (8 bytes)

See also

ProtocolEventTransport_handle_pc_event_report - Event report without payload

interface_openlcb_protocol_event_transport_t - Callback registration