OpenLCB C Library — Implementation Guide

A guide for maintainers, contributors, and anyone who needs to understand how this library works, how data flows through it, and where to look when debugging.

About this guide

This guide covers the implementation of the OpenLCB C library — how the code is structured, how messages flow, and how the pieces connect. For the generated API reference (individual function signatures, struct fields, etc.), see the Doxygen API Reference.

Part I — Orientation

Chapter 1 Project Overview What OpenLCB is, the four design principles, architecture boundary between core and transport drivers, directory structure.
Chapter 2 Building and Running Compile-time configuration constants, build overview, link to dedicated build guide.

Part II — Core Infrastructure

Chapter 3 Types and Constants (Transport-Independent) openlcb_types.h master tour — Node IDs, MTI codes, payload types, message structure, node state.
Chapter 3b CAN-Specific Types and Constants can_types.h — CAN frame structure, 29-bit identifier layout, CAN control frame constants.
Chapter 4 OpenLCB Buffer and Message System Segregated payload pools, reference counting, FIFO, buffer list, allocation and lifecycle.
Chapter 4b CAN Buffer System CAN frame buffer pool, CAN FIFO, how CAN buffers feed into OpenLCB buffers.
Chapter 5 Node Management Node pool, state bits, multi-key enumerator, node parameters, adding virtual nodes.
Chapter 6 Thread Safety The lock/unlock contract, what must be protected, bare-metal vs RTOS implementations.
Chapter 6b Callback Interface Pattern Dependency injection via function pointer structs, required vs optional callbacks.
Chapter 7 Utilities Payload insert/extract, event ranges, broadcast time encoding, train search encoding, float16.

Part III — State Machines (Transport-Independent)

Chapter 8 Main Dispatcher State Machine The central message router — priority dispatch, MTI table, node enumeration, worker buffer.
Chapter 9 Login State Machine Node startup sequence — Initialization Complete, event announcements, state progression.

Part IIIb — CAN Transport State Machines

Chapter 10 CAN Transport State Machine CAN orchestrator — duplicate alias resolution, frame type routing, CAN identifier layout.
Chapter 11 CAN RX and TX Pipelines Frame-to-message assembly, message-to-frame fragmentation, multi-frame tracking.

Part IV — Protocol Handlers

Chapter 12 Message Network Protocol Verify Node ID, Protocol Support Inquiry/Reply, OIR, Terminate Due to Error.
Chapter 13 Event Transport Protocol Consumer/Producer Identified, PCER, Learn Event, event ranges and state tracking.
Chapter 14 Datagram Protocol Two-phase ACK, address space routing, read/write/write-under-mask, retry logic.
Chapter 15 Simple Node Information (SNIP) SNIP response format, field loaders, manufacturer and user information.
Chapter 16 Configuration Description Information (CDI) XML device self-description, CDI structure, address space 0xFF.
Chapter 17 Train Control Protocol Speed, functions, E-stop, controller assignment, consist system, heartbeat.
Chapter 18 Broadcast Time Protocol Event-based time distribution, clock IDs, time/date/year/rate encoding.

Part V — CAN Driver Layer

Chapter 19 Alias Mapping: Global Table Alias-to-NodeID registry, registration, lookup, duplicate detection and resolution.
Chapter 20 Alias Mapping: Listener Table On-demand alias resolution for consist listener nodes, AME/AMD lifecycle.
Chapter 21 Multi-Node Message Routing Virtual nodes sharing a CAN interface, the loopback problem, approaches under consideration.
Chapter 22 CAN Login Sequence CID frame construction, LFSR alias generation, RID/AMD, timing and collision detection.

Part VI — Integration and Debugging

Chapter 23 Wiring It All Together Full initialization walkthrough, main loop, timer tick, platform-specific implementations.
Chapter 24 Data Flow Walkthrough End-to-end message traces with Mermaid diagrams — incoming, outgoing, login, datagram.
Chapter 25 Debugging Guide Buffer exhaustion, alias collisions, datagram timeouts, stuck state machines, test patterns.

Part VII — Extending the Library

Chapter 26 Adding a New Protocol Step-by-step: define MTI, create interface, register handler, implement, test.
Chapter 27 Adding a New Transport Creating a driver alongside canbus/, what a transport must provide, the openlcb_msg_t boundary.
Chapter 28 Porting to a New Platform What the application must provide, bare-metal vs RTOS, memory tuning.

Appendices

Appendix A MTI Quick Reference Table All MTI values with names, addressing mode, and handling module.
Appendix B CAN Frame Format Reference 29-bit identifier bit-field diagram, control frame layouts, datagram/stream sequencing.
Appendix C Configuration Memory Address Space Map All address spaces (0xF9-0xFF) with purpose, permissions, typical sizes.
Appendix D Event ID Encoding Reference Well-known events, broadcast time encoding, train search encoding, range encoding.
Appendix E Compile-Time Configuration Reference All USER_DEFINED_* macros with purpose, defaults, and tuning guidance.
Appendix F OpenLCB Specification Traceability 170+ spec requirements mapped to source files and documentation chapters.
Appendix G Glossary OpenLCB/LCC terminology: Node ID, alias, MTI, CDI, SNIP, PCER, datagram, etc.