openlcb_node.h File Reference

OpenLCB node allocation, enumeration, and lifecycle management. More...

Go to the source code of this file.

Data Structures
struct	interface_openlcb_node_t
	Dependency injection interface for the OpenLCB Node module. More...

Functions
void	OpenLcbNode_initialize (const interface_openlcb_node_t *interface)
	Initializes the node management module.
openlcb_node_t *	OpenLcbNode_allocate (uint64_t node_id, const node_parameters_t *node_parameters)
	Allocates a new node with the given ID and configuration.
openlcb_node_t *	OpenLcbNode_get_first (uint8_t key)
	Returns the first allocated node for enumeration.
openlcb_node_t *	OpenLcbNode_get_next (uint8_t key)
	Returns the next allocated node for the given enumerator key.
bool	OpenLcbNode_is_last (uint8_t key)
	Returns true if the current enumeration position is the last node.
openlcb_node_t *	OpenLcbNode_find_by_alias (uint16_t alias)
	Finds a node by its 12-bit CAN alias.
openlcb_node_t *	OpenLcbNode_find_by_node_id (uint64_t node_id)
	Finds a node by its 64-bit OpenLCB node ID.
void	OpenLcbNode_reset_state (void)
	Resets all allocated nodes to their initial login state.
uint16_t	OpenLcbNode_get_count (void)
	Returns the number of allocated nodes.
void	OpenLcbNode_100ms_timer_tick (uint8_t current_tick)
	100ms timer tick handler — gates the application callback.

Detailed Description

OpenLCB node allocation, enumeration, and lifecycle management.

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.

Manages a fixed-size pool of openlcb_node_t structures. Supports allocation with auto-generated event IDs, multiple simultaneous enumerators for iterating through allocated nodes, and lookup by CAN alias or 64-bit node ID. Must be initialized before any node operations.

Author

Jim Kueneman

Date

28 Feb 2026

Function Documentation

OpenLcbNode_initialize()

void OpenLcbNode_initialize ( const interface_openlcb_node_t * interface )

extern

Initializes the node management module.

Clears all node structures, resets the node count, and stores the optional callback interface. Must be called once at startup before any other OpenLcbNode function.

Parameters

interface

Pointer to interface_openlcb_node_t with optional callbacks, or NULL.

Algorithm:

1. Store interface pointer (may be NULL)
2. Clear all node structures via _clear_node()
3. Reset node count to zero
4. Zero all enumeration index entries

* @param interface Pointer to @ref interface_openlcb_node_t with optional callbacks, or NULL
* 

OpenLcbNode_allocate()

openlcb_node_t * OpenLcbNode_allocate ( uint64_t node_id, const node_parameters_t * node_parameters )

extern

Allocates a new node with the given ID and configuration.

Finds the first free slot in the pool, initializes it with the provided node ID, stores the configuration pointer (not copied), and auto-generates event IDs. Returns NULL if the pool is full.

Parameters

node_id	64-bit unique OpenLCB node identifier.
node_parameters	Pointer to node_parameters_t defining node capabilities.

Returns

Pointer to the allocated openlcb_node_t, or NULL if the pool is full.

Warning

Configuration pointer is stored, not copied — it must remain valid.

Algorithm:

1. Search pool for first unallocated slot
2. Clear the slot via _clear_node()
3. Store node_parameters pointer (not copied) and node_id
4. Generate auto-created event IDs via _generate_event_ids()
5. Increment node count and mark as allocated (last step)
6. Return pointer, or NULL if pool is full

* @param node_id 64-bit unique OpenLCB node identifier
* @param node_parameters Pointer to @ref node_parameters_t defining node capabilities
* 

Returns

Pointer to the allocated openlcb_node_t, or NULL if the pool is full

OpenLcbNode_get_first()

openlcb_node_t * OpenLcbNode_get_first ( uint8_t key )

extern

Returns the first allocated node for enumeration.

Resets the enumeration index for the given key and returns the first node. Multiple independent enumerators are supported using different key values (0 to MAX_NODE_ENUM_KEY_VALUES - 1).

Parameters

key	Enumerator index (0 to MAX_NODE_ENUM_KEY_VALUES - 1).

Returns

Pointer to the first openlcb_node_t, or NULL if no nodes or key invalid.

Algorithm:

1. Validate key is within range
2. Reset enumeration index for this key to 0
3. Return first node, or NULL if no nodes allocated

* @param key Enumerator index (0 to MAX_NODE_ENUM_KEY_VALUES - 1)
* 

Returns

Pointer to the first openlcb_node_t, or NULL if empty or key invalid

OpenLcbNode_get_next()

openlcb_node_t * OpenLcbNode_get_next ( uint8_t key )

extern

Returns the next allocated node for the given enumerator key.

Parameters

key	Same enumerator index used in the corresponding get_first call.

Returns

Pointer to the next openlcb_node_t, or NULL if at end or key invalid.

Algorithm:

1. Validate key is within range
2. Increment enumeration index
3. Return node at new index, or NULL if past the end

* @param key Same enumerator index used in the corresponding get_first call
* 

Returns

Pointer to the next openlcb_node_t, or NULL if at end or key invalid

OpenLcbNode_is_last()

bool OpenLcbNode_is_last ( uint8_t key )

extern

Returns true if the current enumeration position is the last node.

Parameters

key	Same enumerator index used in the corresponding get_first/get_next calls.

Returns

true if current enumeration position is the last allocated node.

Algorithm:

1. Validate key is within range
2. Return false if no nodes allocated
3. Return true if current index equals count minus one

* @param key Same enumerator index used in the corresponding get_first/get_next calls
* 

Returns

true if current enumeration position is the last allocated node

OpenLcbNode_find_by_alias()

openlcb_node_t * OpenLcbNode_find_by_alias ( uint16_t alias )

extern

Finds a node by its 12-bit CAN alias.

Parameters

alias

12-bit CAN alias to search for.

Returns

Pointer to matching openlcb_node_t, or NULL if not found.

Algorithm:

1. Search all allocated nodes for matching alias
2. Return first match, or NULL if not found

* @param alias 12-bit CAN alias to search for
* 

Returns

Pointer to matching openlcb_node_t, or NULL if not found

OpenLcbNode_find_by_node_id()

openlcb_node_t * OpenLcbNode_find_by_node_id ( uint64_t node_id )

extern

Finds a node by its 64-bit OpenLCB node ID.

Parameters

node_id

64-bit OpenLCB node identifier to search for.

Returns

Pointer to matching openlcb_node_t, or NULL if not found.

Algorithm:

1. Search all allocated nodes for matching node ID
2. Return first match, or NULL if not found

* @param node_id 64-bit OpenLCB node identifier to search for
* 

Returns

Pointer to matching openlcb_node_t, or NULL if not found

OpenLcbNode_reset_state()

void OpenLcbNode_reset_state ( void )

extern

Resets all allocated nodes to their initial login state.

Sets run_state to RUNSTATE_INIT and clears permitted and initialized flags. Does not deallocate nodes or clear configuration.

Algorithm:

1. For each allocated node, set run_state to RUNSTATE_INIT
2. Clear permitted and initialized flags

OpenLcbNode_get_count()

uint16_t OpenLcbNode_get_count ( void )

extern

Returns the number of allocated nodes.

Returns

Current allocated node count.

OpenLcbNode_100ms_timer_tick()

void OpenLcbNode_100ms_timer_tick ( uint8_t current_tick )

extern

100ms timer tick handler — gates the application callback.

Called from the main loop with the current global tick. Fires the application callback at most once per unique tick value.

Parameters

current_tick

Current value of the global 100ms tick counter.

Called from the main loop with the current global tick. Fires the application callback at most once per unique tick value. The per-node timerticks increment has been removed — all modules now use the global clock via subtraction-based elapsed-time checks.

* @param current_tick  Current value of the global 100ms tick counter.
*