Chapter 23 — Wiring It All Together

This chapter describes how a user application brings up the entire OpenLCB stack: configuring the two configuration structs, calling the initialization functions in the correct order, allocating nodes, running the main loop, and providing the 100ms timer tick.

23.1 The can_config_t Structure

The CAN transport layer is configured by populating a can_config_t struct and passing it to CanConfig_initialize(). This struct contains only hardware driver functions -- all internal CAN wiring is handled automatically by can_config.c.

23.2 The openlcb_config_t Structure

The OpenLCB protocol layer is configured by populating an openlcb_config_t struct and passing it to OpenLcb_initialize(). Fields are grouped by feature flag.

Required Fields (Always)

Optional Fields (Grouped by Feature Flag)

23.3 Initialization Sequence

The correct order for bringing up the stack is:

What happens inside CanConfig_initialize()

1. Save the user config pointer.
2. Initialize CAN buffer infrastructure: CanBufferStore_initialize(), CanBufferFifo_initialize().
3. Build all 7 internal CAN interface structs from user config + library functions.
4. Initialize all CAN modules in dependency order: RX handler, RX SM, TX handler, TX SM, login handler, login SM, main SM, alias mappings, listener alias table.

What happens inside OpenLcb_initialize()

1. Save the user config pointer.
2. Initialize OpenLCB buffer infrastructure: OpenLcbBufferStore, OpenLcbBufferList, OpenLcbBufferFifo.
3. Build all internal interface structs from user config and compile flags.
4. Initialize all compiled-in protocol modules: SNIP, Datagram, Config Mem (read/write/ops), Events, Message Network, Broadcast Time, Train, Train Search.
5. Initialize Node management, Login SM, Main SM, Application layer.

23.4 The Main Loop

The application's main loop calls OpenLcb_run() as fast as possible. This single function runs one iteration of all state machines:

void OpenLcb_run(void) {
    CanMainStateMachine_run();       // CAN transport layer
    OpenLcbLoginMainStatemachine_run(); // OpenLCB login (Init Complete, events)
    OpenLcbMainStatemachine_run();   // OpenLCB protocol dispatch

    _run_periodic_services();        // 100ms timer-driven tasks
}

The periodic services, driven by the 100ms tick, include:

• OpenLcbNode_100ms_timer_tick() -- user timer callback
• ProtocolDatagramHandler_100ms_timer_tick() / _check_timeouts() -- datagram retry/timeout
• OpenLcbApplicationBroadcastTime_100ms_time_tick() -- clock minute accumulation
• OpenLcbApplicationTrain_100ms_timer_tick() -- heartbeat countdown

23.5 The 100ms Timer Tick

The library's timekeeping is built on a single volatile uint8_t counter incremented every 100ms:

static volatile uint8_t _global_100ms_tick = 0;

void OpenLcb_100ms_timer_tick(void) {
    _global_100ms_tick++;
}

The application must call OpenLcb_100ms_timer_tick() from a hardware timer interrupt or periodic RTOS task. This is the ONLY action performed in the interrupt context. All real protocol work runs in the main loop.

Elapsed time is computed by subtraction: elapsed = current_tick - snapshot. The uint8_t wraps at 256, and unsigned subtraction handles the wrap correctly for durations up to 25.5 seconds.

23.6 Platform-Specific Lock/Unlock Examples

23.7 Feature Flag Dependency Tree

Compile-time feature flags control which protocol modules are included. Dependencies are enforced at compile time with #error directives:

23.8 Minimal Application Template

// openlcb_user_config.h defines all USER_DEFINED_* macros
// plus feature flags like OPENLCB_COMPILE_EVENTS

#include "drivers/canbus/can_config.h"
#include "openlcb/openlcb_config.h"

static const can_config_t can_cfg = {
    .transmit_raw_can_frame  = &MyCanDriver_transmit,
    .is_tx_buffer_clear      = &MyCanDriver_is_tx_clear,
    .lock_shared_resources   = &MyPlatform_lock,
    .unlock_shared_resources = &MyPlatform_unlock,
};

static const openlcb_config_t olcb_cfg = {
    .lock_shared_resources   = &MyPlatform_lock,
    .unlock_shared_resources = &MyPlatform_unlock,
    .config_mem_read         = &MyEeprom_read,
    .config_mem_write        = &MyEeprom_write,
    .reboot                  = &MyPlatform_reboot,
    .on_login_complete       = &my_login_handler,
};

int main(void) {
    // 1. Initialize hardware (CAN, timers, GPIO)
    MyPlatform_init();

    // 2. Initialize library (order matters!)
    CanConfig_initialize(&can_cfg);
    OpenLcb_initialize(&olcb_cfg);

    // 3. Create nodes
    OpenLcb_create_node(0x050101010001ULL, &my_node_params);

    // 4. Start 100ms timer (calls OpenLcb_100ms_timer_tick)
    MyPlatform_start_timer();

    // 5. Main loop
    while (1) {
        OpenLcb_run();
    }
}

23.9 Source Files