openlcb_application.c File Reference

Implementation of the application layer interface. More...

Functions
void	OpenLcbApplication_initialize (const interface_openlcb_application_t *interface_openlcb_application)
	Stores the application callback interface for use by all application layer functions.
bool	OpenLcbApplication_send_event_with_mti (openlcb_node_t *openlcb_node, event_id_t event_id, uint16_t mti)
	Sends an event message with an arbitrary MTI.
void	OpenLcbApplication_clear_consumer_eventids (openlcb_node_t *openlcb_node)
	Clears the consumer event list for a node by resetting its count to zero.
void	OpenLcbApplication_clear_producer_eventids (openlcb_node_t *openlcb_node)
	Clears the producer event list for a node by resetting its count to zero.
uint16_t	OpenLcbApplication_register_consumer_eventid (openlcb_node_t *openlcb_node, event_id_t event_id, event_status_enum event_status)
	Adds a consumer event ID to the node's consumer list.
uint16_t	OpenLcbApplication_register_producer_eventid (openlcb_node_t *openlcb_node, event_id_t event_id, event_status_enum event_status)
	Adds a producer event ID to the node's producer list.
void	OpenLcbApplication_clear_consumer_ranges (openlcb_node_t *openlcb_node)
	Clears the consumer event-range list by resetting its range count to zero.
void	OpenLcbApplication_clear_producer_ranges (openlcb_node_t *openlcb_node)
	Clears the producer event-range list by resetting its range count to zero.
bool	OpenLcbApplication_register_consumer_range (openlcb_node_t *openlcb_node, event_id_t event_id_base, event_range_count_enum range_size)
	Registers an event ID range in the node's consumer range list.
bool	OpenLcbApplication_register_producer_range (openlcb_node_t *openlcb_node, event_id_t event_id_base, event_range_count_enum range_size)
	Registers an event ID range in the node's producer range list.
bool	OpenLcbApplication_send_event_pc_report (openlcb_node_t *openlcb_node, event_id_t event_id)
	Sends a Producer/Consumer Event Report (PCER) message to the network.
bool	OpenLcbApplication_send_teach_event (openlcb_node_t *openlcb_node, event_id_t event_id)
	Sends a Learn Event (teach) message to the network.
bool	OpenLcbApplication_send_initialization_event (openlcb_node_t *openlcb_node)
	Sends an Initialization Complete message for the specified node.
uint16_t	OpenLcbApplication_read_configuration_memory (openlcb_node_t *openlcb_node, uint32_t address, uint16_t count, configuration_memory_buffer_t *buffer)
	Reads bytes from the node's configuration memory via the application callback.
uint16_t	OpenLcbApplication_write_configuration_memory (openlcb_node_t *openlcb_node, uint32_t address, uint16_t count, configuration_memory_buffer_t *buffer)
	Writes bytes to the node's configuration memory via the application callback.

Detailed Description

Implementation of the application layer interface.

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.

Implements the high-level application programming interface for the OpenLCB protocol stack. Maintains a single static pointer to the application-provided callback structure set by OpenLcbApplication_initialize(). All public functions are thin wrappers that either manipulate node data directly or call through to those callbacks.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

OpenLcbApplication_initialize()

void OpenLcbApplication_initialize

(

const interface_openlcb_application_t *

interface_openlcb_application

)

Stores the application callback interface for use by all application layer functions.

Algorithm:

1. Cast away the const qualifier from the interface pointer.
2. Store the pointer in the static _interface variable.

* @param interface_openlcb_application  Pointer to a fully initialised interface_openlcb_application_t.
* 

Warning

MUST be called exactly once before any other function in this module.

The pointed-to structure must remain valid for the lifetime of the program.

All three function pointers in the structure must be non-NULL.

OpenLcbApplication_send_event_with_mti()

bool OpenLcbApplication_send_event_with_mti	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id,
		uint16_t	mti )

Sends an event message with an arbitrary MTI.

Algorithm:

1. Declare msg and payload on the stack.
2. Point msg.payload at the local payload buffer; set payload_type to BASIC.
3. Call OpenLcbUtilities_load_openlcb_message() with the node's alias/ID, a zero destination alias, NULL_NODE_ID destination, and the caller-supplied MTI.
4. Call OpenLcbUtilities_copy_event_id_to_openlcb_payload() to place event_id in the payload.
5. If the send callback is non-NULL, call it and return its result; otherwise return false.

* @param openlcb_node  Pointer to the sending openlcb_node_t.
* @param event_id      64-bit event_id_t to include in the payload.
* @param mti           16-bit MTI for the message.
* 

Returns

true if queued successfully, false if the transmit buffer is full or the callback is NULL.

Warning

NULL pointer on the node causes a crash — no NULL check is performed.

OpenLcbApplication_clear_consumer_eventids()

void OpenLcbApplication_clear_consumer_eventids

(

openlcb_node_t *

openlcb_node

)

Clears the consumer event list for a node by resetting its count to zero.

Algorithm:

1. Set openlcb_node->consumers.count to 0.

* @param openlcb_node  Pointer to the openlcb_node_t to clear.
* 

Warning

NULL pointer causes a crash — no NULL check is performed.

OpenLcbApplication_clear_producer_eventids()

void OpenLcbApplication_clear_producer_eventids

(

openlcb_node_t *

openlcb_node

)

Clears the producer event list for a node by resetting its count to zero.

Algorithm:

1. Set openlcb_node->producers.count to 0.

* @param openlcb_node  Pointer to the openlcb_node_t to clear.
* 

Warning

NULL pointer causes a crash — no NULL check is performed.

OpenLcbApplication_register_consumer_eventid()

uint16_t OpenLcbApplication_register_consumer_eventid	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id,
		event_status_enum	event_status )

Adds a consumer event ID to the node's consumer list.

Algorithm:

1. If consumers.count < USER_DEFINED_CONSUMER_COUNT:
   • Store event_id and event_status at consumers.list[count].
   • Increment consumers.count.
   • Return the new entry's 0-based index (count - 1).
2. Otherwise return 0xFFFF.

* @param openlcb_node   Pointer to the openlcb_node_t receiving the registration.
* @param event_id       64-bit event_id_t to register (8 bytes, MSB first).
* @param event_status   Initial status: one of the event_status_enum values.
* 

Returns

0-based index of the newly registered entry, or 0xFFFF if the array is full.

Warning

NULL pointer causes a crash — no NULL check is performed on the node.

OpenLcbApplication_register_producer_eventid()

uint16_t OpenLcbApplication_register_producer_eventid	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id,
		event_status_enum	event_status )

Adds a producer event ID to the node's producer list.

Algorithm:

1. If producers.count < USER_DEFINED_PRODUCER_COUNT:
   • Store event_id and event_status at producers.list[count].
   • Increment producers.count.
   • Return the new entry's 0-based index (count - 1).
2. Otherwise return 0xFFFF.

* @param openlcb_node   Pointer to the openlcb_node_t receiving the registration.
* @param event_id       64-bit event_id_t to register (8 bytes, MSB first).
* @param event_status   Initial status: one of the event_status_enum values.
* 

Returns

0-based index of the newly registered entry, or 0xFFFF if the array is full.

Warning

NULL pointer causes a crash — no NULL check is performed on the node.

OpenLcbApplication_clear_consumer_ranges()

void OpenLcbApplication_clear_consumer_ranges

(

openlcb_node_t *

openlcb_node

)

Clears the consumer event-range list by resetting its range count to zero.

Clears the consumer event-range list for a node by resetting its range count to zero.

Algorithm:

1. Set openlcb_node->consumers.range_count to 0.

* @param openlcb_node  Pointer to the openlcb_node_t to clear.
* 

Warning

NULL pointer causes a crash — no NULL check is performed.

OpenLcbApplication_clear_producer_ranges()

void OpenLcbApplication_clear_producer_ranges

(

openlcb_node_t *

openlcb_node

)

Clears the producer event-range list by resetting its range count to zero.

Clears the producer event-range list for a node by resetting its range count to zero.

Algorithm:

1. Set openlcb_node->producers.range_count to 0.

* @param openlcb_node  Pointer to the openlcb_node_t to clear.
* 

Warning

NULL pointer causes a crash — no NULL check is performed.

OpenLcbApplication_register_consumer_range()

bool OpenLcbApplication_register_consumer_range	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id_base,
		event_range_count_enum	range_size )

Registers an event ID range in the node's consumer range list.

Algorithm:

1. If consumers.range_count < USER_DEFINED_CONSUMER_RANGE_COUNT:
   • Store event_id_base and range_size in the next range_list slot.
   • Increment consumers.range_count.
   • Return true.
2. Otherwise return false.

* @param openlcb_node    Pointer to the openlcb_node_t receiving the registration.
* @param event_id_base   Base event_id_t of the range.
* @param range_size      Number of consecutive event IDs (event_range_count_enum).
* 

Returns

true if registered successfully, false if the range array is full.

Warning

NULL pointer causes a crash — no NULL check is performed on the node.

OpenLcbApplication_register_producer_range()

bool OpenLcbApplication_register_producer_range	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id_base,
		event_range_count_enum	range_size )

Registers an event ID range in the node's producer range list.

Algorithm:

1. If producers.range_count < USER_DEFINED_PRODUCER_RANGE_COUNT:
   • Store event_id_base and range_size in the next range_list slot.
   • Increment producers.range_count.
   • Return true.
2. Otherwise return false.

* @param openlcb_node    Pointer to the openlcb_node_t receiving the registration.
* @param event_id_base   Base event_id_t of the range.
* @param range_size      Number of consecutive event IDs (event_range_count_enum).
* 

Returns

true if registered successfully, false if the range array is full.

Warning

NULL pointer causes a crash — no NULL check is performed on the node.

OpenLcbApplication_send_event_pc_report()

bool OpenLcbApplication_send_event_pc_report	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id )

Sends a Producer/Consumer Event Report (PCER) message to the network.

Algorithm:

1. Declare msg and payload on the stack.
2. Point msg.payload at the local payload buffer; set payload_type to BASIC.
3. Call OpenLcbUtilities_load_openlcb_message() with the node's alias/ID, a zero destination alias, NULL_NODE_ID destination, and MTI_PC_EVENT_REPORT (0x05B4).
4. Call OpenLcbUtilities_copy_event_id_to_openlcb_payload() to place event_id in the payload.
5. If the send callback is non-NULL, call it and return its result; otherwise return false.

* @param openlcb_node  Pointer to the sending openlcb_node_t.
* @param event_id      64-bit event_id_t to report.
* 

Returns

true if queued successfully, false if the transmit buffer is full or the callback is NULL.

Warning

NULL pointer on the node causes a crash — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

OpenLcbApplication_send_teach_event()

bool OpenLcbApplication_send_teach_event	(	openlcb_node_t *	openlcb_node,
		event_id_t	event_id )

Sends a Learn Event (teach) message to the network.

Algorithm:

1. Declare msg and payload on the stack.
2. Point msg.payload at the local payload buffer; set payload_type to BASIC.
3. Call OpenLcbUtilities_load_openlcb_message() with the node's alias/ID, a zero destination alias, NULL_NODE_ID destination, and MTI_EVENT_LEARN (0x0594).
4. Call OpenLcbUtilities_copy_event_id_to_openlcb_payload() to place event_id in the payload.
5. If the send callback is non-NULL, call it and return its result; otherwise return false.

* @param openlcb_node  Pointer to the sending openlcb_node_t.
* @param event_id      64-bit event_id_t to teach.
* 

Returns

true if queued successfully, false if the transmit buffer is full or the callback is NULL.

Warning

NULL pointer on the node causes a crash — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

OpenLcbApplication_send_initialization_event()

bool OpenLcbApplication_send_initialization_event

(

openlcb_node_t *

openlcb_node

)

Sends an Initialization Complete message for the specified node.

Algorithm:

1. Declare msg and payload on the stack.
2. Point msg.payload at the local payload buffer; set payload_type to BASIC.
3. Call OpenLcbUtilities_load_openlcb_message() with the node's alias/ID, a zero destination alias, NULL_NODE_ID destination, and MTI_INITIALIZATION_COMPLETE (0x0100).
4. Call OpenLcbUtilities_copy_node_id_to_openlcb_payload() to place the 6-byte Node ID at payload offset 0.
5. If the send callback is non-NULL, call it and return its result; otherwise return false.

* @param openlcb_node  Pointer to the openlcb_node_t that has just finished login.
* 

Returns

true if queued successfully, false if the transmit buffer is full or the callback is NULL.

Warning

NULL pointer on the node causes a crash — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

Per the OpenLCB Message Network Standard this message must be sent before any other OpenLCB messages after alias negotiation completes.

OpenLcbApplication_read_configuration_memory()

uint16_t OpenLcbApplication_read_configuration_memory	(	openlcb_node_t *	openlcb_node,
		uint32_t	address,
		uint16_t	count,
		configuration_memory_buffer_t *	buffer )

Reads bytes from the node's configuration memory via the application callback.

Algorithm:

1. If config_memory_read callback is non-NULL, call it with all parameters and return the result.
2. Otherwise return 0xFFFF.

* @param openlcb_node  Pointer to the requesting openlcb_node_t.
* @param address       Starting address within the configuration address space.
* @param count         Number of bytes to read.
* @param buffer        Destination configuration_memory_buffer_t.
* 

Returns

Number of bytes read, or 0xFFFF if the callback is NULL or the read failed.

Warning

NULL pointer on the node is passed directly to the callback unchecked.

OpenLcbApplication_write_configuration_memory()

uint16_t OpenLcbApplication_write_configuration_memory	(	openlcb_node_t *	openlcb_node,
		uint32_t	address,
		uint16_t	count,
		configuration_memory_buffer_t *	buffer )

Writes bytes to the node's configuration memory via the application callback.

Algorithm:

1. If config_memory_write callback is non-NULL, call it with all parameters and return the result.
2. Otherwise return 0xFFFF.

* @param openlcb_node  Pointer to the requesting openlcb_node_t.
* @param address       Starting address within the configuration address space.
* @param count         Number of bytes to write.
* @param buffer        Source configuration_memory_buffer_t.
* 

Returns

Number of bytes written, or 0xFFFF if the callback is NULL or the write failed.

Warning

NULL pointer on the node is passed directly to the callback unchecked.

Writes to read-only address spaces are rejected by the application callback, not here.