openlcb_application.h File Reference

Application layer interface for the OpenLCB library. More...

Go to the source code of this file.

Data Structures
struct	interface_openlcb_application_t
	Application-provided callbacks required by the OpenLCB library. 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.
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 for a node by resetting its range count to zero.
void	OpenLcbApplication_clear_producer_ranges (openlcb_node_t *openlcb_node)
	Clears the producer event-range list for a node 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_event_with_mti (openlcb_node_t *openlcb_node, event_id_t event_id, uint16_t mti)
	Sends an event message with an arbitrary MTI.
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

Application layer interface for the OpenLCB library.

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.

Application layer interface for the OpenLCB protocol stack. Provides functions for producer/consumer event registration, event transmission, and configuration memory access. Fill in a interface_openlcb_application_t with valid callback pointers and pass it to OpenLcbApplication_initialize() before making any other call in this module.

Author

Jim Kueneman

Date

28 Feb 2026

Function Documentation

OpenLcbApplication_initialize()

void OpenLcbApplication_initialize ( const interface_openlcb_application_t * interface_openlcb_application )

extern

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

Must be called exactly once during startup, before any other call in this module. The pointed-to structure must remain valid for the lifetime of the program.

Parameters

interface_openlcb_application

Pointer to a fully initialised interface_openlcb_application_t.

Warning

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

Calling more than once replaces the stored pointer and loses the previous context.

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_clear_consumer_eventids()

void OpenLcbApplication_clear_consumer_eventids ( openlcb_node_t * openlcb_node )

extern

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

Parameters

openlcb_node

Pointer to the openlcb_node_t to clear.

Warning

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

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 )

extern

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

Parameters

openlcb_node

Pointer to the openlcb_node_t to clear.

Warning

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

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 )

extern

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

Stores the event and its initial status at the next available slot in the fixed-size consumer array. Returns the 0-based array index on success so the caller can reference the entry directly later.

Parameters

openlcb_node	Pointer to the openlcb_node_t receiving the registration.
event_id	64-bit event_id_t to register (8 bytes, MSB first).
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.

Check the return value for 0xFFFF before assuming registration succeeded.

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 )

extern

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

Stores the event and its initial status at the next available slot in the fixed-size producer array. Returns the 0-based array index on success so the caller can reference the entry directly later.

Parameters

openlcb_node	Pointer to the openlcb_node_t receiving the registration.
event_id	64-bit event_id_t to register (8 bytes, MSB first).
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.

Check the return value for 0xFFFF before assuming registration succeeded.

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 )

extern

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

Parameters

openlcb_node

Pointer to the openlcb_node_t to clear.

Warning

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

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 )

extern

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

Parameters

openlcb_node

Pointer to the openlcb_node_t to clear.

Warning

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

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 )

extern

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

Stores the base event ID and range size at the next available slot in the fixed-size consumer range array.

Parameters

openlcb_node	Pointer to the openlcb_node_t receiving the registration.
event_id_base	Base event_id_t of the range.
range_size	Number of consecutive event IDs in the range (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.

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 )

extern

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

Stores the base event ID and range size at the next available slot in the fixed-size producer range array.

Parameters

openlcb_node	Pointer to the openlcb_node_t receiving the registration.
event_id_base	Base event_id_t of the range.
range_size	Number of consecutive event IDs in the range (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.

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 )

extern

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

Builds a global PCER message (MTI 0x05B4) with the given event ID and queues it via the send_openlcb_msg callback. Returns immediately; actual transmission happens when the transport layer drains its queue.

Parameters

openlcb_node	Pointer to the sending openlcb_node_t.
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 causes a crash on the node — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

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_event_with_mti()

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

extern

Sends an event message with an arbitrary MTI.

Builds a global OpenLCB message carrying the given event ID and MTI, then queues it via the send_openlcb_msg callback. Useful for sending event MTIs that do not have a dedicated helper function.

Parameters

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

Returns

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

Warning

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

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_send_teach_event()

bool OpenLcbApplication_send_teach_event ( openlcb_node_t * openlcb_node, event_id_t event_id )

extern

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

Builds a global Learn Event message (MTI 0x0594) with the given event ID and queues it via the send_openlcb_msg callback. Used during teach/learn configuration to inform other nodes of a new event association.

Parameters

openlcb_node	Pointer to the sending openlcb_node_t.
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 causes a crash on the node — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

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 )

extern

Sends an Initialization Complete message for the specified node.

Builds a global Initialization Complete message (MTI 0x0100) whose 6-byte payload carries the node's full 48-bit Node ID, then queues it via the send_openlcb_msg callback. Per the OpenLCB Message Network Standard this message must be sent after alias negotiation completes and before any other OpenLCB messages.

Parameters

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 causes a crash on the node — no NULL check is performed.

Returns false if OpenLcbApplication_initialize() was not called first.

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 )

extern

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

Passes the request through to the config_memory_read callback. Returns 0xFFFF immediately if the callback pointer is NULL.

Parameters

openlcb_node	Pointer to the requesting openlcb_node_t.
address	Starting address within the configuration address space.
count	Number of bytes to read.
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.

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 )

extern

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

Passes the request through to the config_memory_write callback. Returns 0xFFFF immediately if the callback pointer is NULL.

Parameters

openlcb_node	Pointer to the requesting openlcb_node_t.
address	Starting address within the configuration address space.
count	Number of bytes to write.
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.

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.