openlcb_node.c File Reference

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

Macros
#define	OPENLCB_EVENT_ID_OFFSET   16
	Bit shift to convert a 48-bit node ID into a 64-bit event ID base.

Functions
void	OpenLcbNode_initialize (const interface_openlcb_node_t *interface)
	Initializes the node management module.
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_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_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_100ms_timer_tick (uint8_t current_tick)
	100ms timer tick handler — gates the application callback.
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.

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.

Fixed-size pool of openlcb_node_t structures with allocation, multi-key enumeration, alias/ID lookup, and auto-generated event IDs.

Author

Jim Kueneman

Date

4 Mar 2026

Macro Definition Documentation

OPENLCB_EVENT_ID_OFFSET

#define OPENLCB_EVENT_ID_OFFSET   16

Bit shift to convert a 48-bit node ID into a 64-bit event ID base.

Function Documentation

OpenLcbNode_initialize()

void OpenLcbNode_initialize

(

const interface_openlcb_node_t *

interface

)

Initializes the node management module.

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

openlcb_node_t * OpenLcbNode_get_first

(

uint8_t

key

)

Returns the first allocated node for enumeration.

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

)

Returns the next allocated node for the given enumerator key.

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

)

Returns true if the current enumeration position is the last 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_allocate()

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.

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

openlcb_node_t * OpenLcbNode_find_by_alias

(

uint16_t

alias

)

Finds a node by its 12-bit CAN alias.

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

)

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

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

void OpenLcbNode_100ms_timer_tick

(

uint8_t

current_tick

)

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. 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.
* 

OpenLcbNode_reset_state()

void OpenLcbNode_reset_state

(

void

)

Resets all allocated nodes to their initial login state.

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

)

Returns the number of allocated nodes.

Returns

Current allocated node count.