Chapter 8 — Main Dispatcher State Machine

The main dispatcher is the central message-routing engine for the OpenLCB protocol stack. It lives in openlcb_main_statemachine.c/.h and is driven by a single entry point called as fast as possible from the application main loop.

8.1 Entry Point

The entire dispatch loop is driven by OpenLcbMainStatemachine_run(). Each call performs exactly one atomic operation and returns immediately, maintaining a non-blocking cooperative design. The application calls this as fast as possible:

while (1) {
    OpenLcbMainStatemachine_run();   // protocol dispatch
    OpenLcbLoginMainStatemachine_run();  // login sequencing
    CanMainStateMachine_run();       // CAN layer
}

8.2 Priority Dispatch Flowchart

Each call to _run() evaluates five priorities in order. The first one that returns true (meaning it did work) causes the function to return immediately. This ensures the highest-priority task always gets serviced first.

8.3 The State Machine Context

The dispatcher maintains a single static context structure, openlcb_statemachine_info_t, that is passed to every protocol handler. This structure provides:

typedef struct {
    openlcb_msg_info_t   incoming_msg_info;   // current incoming message + enumerate flag
    openlcb_msg_info_t   outgoing_msg_info;   // worker buffer for reply + valid flag
    openlcb_node_t      *openlcb_node;        // node currently being enumerated
    uint8_t              current_tick;         // snapshot of 100ms timer
} openlcb_statemachine_info_t;

Key fields

8.4 Node Address Filtering

Before dispatching a message to a protocol handler, the function OpenLcbMainStatemachine_does_node_process_msg() determines whether the current node should process the message. The rules are:

1. If the node is NULL or not initialized, reject.
2. If the message is a loopback from this same node (self-skip), reject.
3. If the message is global (no destination address bit set), accept.
4. If the message is addressed, accept only if the destination alias or Node ID matches this node.
5. Special case: MTI_VERIFY_NODE_ID_GLOBAL is always accepted (it carries an optional Node ID in the payload).

8.5 Fan-Out to All Nodes

Every incoming message is dispatched to every node in the system by the enumerate-first / enumerate-next loop. Global messages reach all nodes; addressed messages are filtered by does_node_process_msg() so only the target node processes them. This fan-out design supports multi-node configurations where a single microcontroller hosts several virtual nodes.

8.6 Sibling Loopback

When a node generates a response (e.g., an Init Complete message), sibling nodes on the same microcontroller need to see it too. The dispatcher handles this with _loopback_to_siblings():

1. After successfully sending an outgoing message, allocate a buffer copy.
2. Copy the header and payload bytes into the new buffer.
3. Mark the copy with state.loopback = true.
4. Push to the head of the incoming FIFO (processed next).

8.7 The Enumerate Flag

Some protocol handlers need to send multiple messages in response to a single incoming message. For example, Identify Events must report every producer and consumer event the node knows about. The mechanism:

1. The handler builds the first response, sets outgoing_msg_info.valid = true, and sets incoming_msg_info.enumerate = true.
2. Priority 1 sends the outgoing message.
3. Priority 2 sees the enumerate flag and re-enters the handler.
4. The handler builds the next response. When the last message is sent, it clears the enumerate flag.
5. The dispatcher advances to the next node (or the next incoming message).

8.8 MTI Dispatch Table

OpenLcbMainStatemachine_process_main_statemachine() contains a large switch statement that routes each MTI to the correct protocol handler callback. If an optional handler is NULL, request-type MTIs trigger an Interaction Rejected response automatically; reply/indication MTIs are silently ignored.

8.9 Special MTI Intercepts

Several MTIs have special routing before falling through to the normal event transport handlers:

• MTI_PRODUCER_IDENTIFY (0x0914): If the event ID is a train search event, it is dispatched to train_search_event_handler for train nodes only. If no train matches across all nodes, train_search_no_match_handler fires on the last node.
• MTI_PRODUCER_IDENTIFIED_SET (0x0544): If the event ID is a broadcast time event, it is dispatched to broadcast_time_event_handler (node index 0 only).
• MTI_PC_EVENT_REPORT (0x05B4): Checked first for broadcast time events (node 0 only), then for emergency events (dispatched to all train nodes), before falling through to the regular event handler.

8.10 Interaction Rejected

OpenLcbMainStatemachine_load_interaction_rejected() builds an OIR response with error code ERROR_PERMANENT_NOT_IMPLEMENTED_UNKNOWN_MTI_OR_TRANSPORT_PROTOCOL and includes the triggering MTI in the payload (bytes 2-3). This is called:

• When a request-type MTI has a NULL handler callback.
• For any unknown addressed MTI in the default case.
• Unknown global MTIs are silently ignored (no OIR).