Chapter 3 — Types and Constants (Transport-Independent)

This chapter covers the core type definitions in openlcb_types.h and the protocol constants in openlcb_defines.h. These files are the foundation of the entire library -- every other module includes them.

3.1 Fundamental Typedefs

3.2 The openlcb_msg_t Structure

The core message structure. Every message flowing through the library is represented by this type.

typedef struct {
    openlcb_msg_state_t state;      // Bitfield: allocated, inprocess, invalid, loopback
    uint16_t mti;                   // Message Type Indicator
    uint16_t source_alias;          // 12-bit CAN alias of sender
    uint16_t dest_alias;            // 12-bit CAN alias of recipient (0 = global)
    node_id_t source_id;            // 48-bit Node ID of sender
    node_id_t dest_id;              // 48-bit Node ID of recipient (0 = global)
    payload_type_enum payload_type; // BASIC, DATAGRAM, SNIP, or STREAM
    uint16_t payload_count;         // Valid bytes currently in payload
    openlcb_payload_t *payload;     // Pointer to payload buffer
    openlcb_msg_timer_t timer;      // Timer/retry union
    uint8_t reference_count;        // Number of active references
} openlcb_msg_t;

3.2.1 openlcb_msg_state_t Bitfield

Packed state flags that track the lifecycle of a message buffer:

typedef struct {
    bool allocated : 1;   // Buffer is in use (owned by buffer store)
    bool inprocess : 1;   // Multi-frame message being assembled
    bool invalid : 1;     // Invalidated (e.g., by AMR) -- discard on next access
    bool loopback : 1;    // Sibling dispatch copy -- skip source node, no re-loopback
} openlcb_msg_state_t;

3.2.2 openlcb_msg_timer_t Union

A single byte shared between two mutually exclusive uses depending on the message lifecycle stage:

typedef union {
    uint8_t assembly_ticks;         // Full 8-bit tick for multi-frame assembly timeout

    struct {
        uint8_t tick_snapshot : 5;  // 5-bit tick snapshot (0-31) for datagram retry
        uint8_t retry_count : 3;   // Datagram retry counter (0-7)
    } datagram;

} openlcb_msg_timer_t;

• assembly_ticks: Used during multi-frame message assembly. The CAN RX handler snapshots the current tick when the first frame arrives; the buffer list timeout scanner compares elapsed ticks to detect stalled assemblies.
• datagram.tick_snapshot + retry_count: Used during datagram retry logic. When a Datagram Rejected reply arrives with a temporary error, the tick snapshot and retry counter track when to resend and how many attempts remain.

3.2.3 payload_type_enum

typedef enum {
    BASIC,      // 16-byte payload buffer
    DATAGRAM,   // 72-byte payload buffer
    SNIP,       // 256-byte payload buffer
    STREAM      // 512-byte payload buffer
} payload_type_enum;

3.3 Event Types

3.3.1 event_id_struct_t

An event ID paired with its current status, used in producer and consumer lists:

typedef struct {
    event_id_t event;           // 64-bit Event ID
    event_status_enum status;   // EVENT_STATUS_UNKNOWN, EVENT_STATUS_SET, EVENT_STATUS_CLEAR
} event_id_struct_t;

3.3.2 event_id_range_t

A contiguous range of event IDs for range-identified events:

typedef struct {
    event_id_t start_base;              // Starting Event ID
    event_range_count_enum event_count; // Number of consecutive Event IDs
} event_id_range_t;

The event_range_count_enum provides power-of-two sizes from 1 up to 32768:

typedef enum {
    EVENT_RANGE_COUNT_1 = 0,
    EVENT_RANGE_COUNT_2 = 2,
    EVENT_RANGE_COUNT_4 = 4,
    // ... powers of 2 ...
    EVENT_RANGE_COUNT_32768 = 32768
} event_range_count_enum;

3.4 Node Types

3.4.1 openlcb_node_t Structure

The complete representation of a virtual node:

typedef struct openlcb_node_TAG {
    openlcb_node_state_t state;              // Bitfield: run_state, allocated, permitted, etc.
    uint64_t id;                             // 48-bit Node ID
    uint16_t alias;                          // 12-bit CAN alias
    uint64_t seed;                           // Seed for alias generation (LFSR)
    event_id_consumer_list_t consumers;      // Consumed event list + enumerator
    event_id_producer_list_t producers;      // Produced event list + enumerator
    const node_parameters_t *parameters;     // Pointer to const configuration
    uint16_t timerticks;                     // 100ms timer tick counter
    uint64_t owner_node;                     // Node ID that has locked this node
    openlcb_msg_t *last_received_datagram;   // Saved for reply processing
    uint8_t index;                           // Index in node array
    struct train_state_TAG *train_state;     // NULL if not a train node
} openlcb_node_t;

3.4.2 openlcb_node_state_t Bitfield

typedef struct {
    uint8_t run_state : 5;              // Login state machine state (0-31)
    bool allocated : 1;                 // Node is allocated
    bool permitted : 1;                 // CAN alias allocated and claimed
    bool initialized : 1;              // Node fully initialized (Init Complete sent)
    bool duplicate_id_detected : 1;     // Duplicate Node ID conflict
    bool openlcb_datagram_ack_sent : 1; // Datagram ACK sent, awaiting reply
    bool resend_datagram : 1;           // Resend last datagram (retry logic)
    bool firmware_upgrade_active : 1;   // Firmware upgrade in progress
} openlcb_node_state_t;

3.4.3 node_parameters_t Structure

Configuration parameters for a node. Typically stored in const (flash) memory:

typedef struct node_parameters_TAG {
    user_snip_struct_t snip;                    // SNIP strings (manufacturer info)
    uint64_t protocol_support;                  // Protocol Support Indicator bits
    uint8_t consumer_count_autocreate;          // Auto-create N consumer events from Node ID
    uint8_t producer_count_autocreate;          // Auto-create N producer events from Node ID
    uint8_t cdi[USER_DEFINED_CDI_LENGTH];       // CDI XML data
    uint8_t fdi[USER_DEFINED_FDI_LENGTH];       // FDI data (train nodes)
    user_address_space_info_t address_space_configuration_definition;  // Space 0xFF
    user_address_space_info_t address_space_all;                       // Space 0xFE
    user_address_space_info_t address_space_config_memory;             // Space 0xFD
    user_address_space_info_t address_space_acdi_manufacturer;         // Space 0xFC
    user_address_space_info_t address_space_acdi_user;                 // Space 0xFB
    user_address_space_info_t address_space_train_function_definition_info;  // Space 0xFA
    user_address_space_info_t address_space_train_function_config_memory;    // Space 0xF9
    user_configuration_options configuration_options;
    user_address_space_info_t address_space_firmware;                  // Space 0xEF
} node_parameters_t;

3.5 MTI Constants

All Message Type Indicator values are defined in openlcb_defines.h. The MTI is a 16-bit value carried in the mti field of openlcb_msg_t.

3.5.1 Message Network MTIs

3.5.2 Event Transport MTIs

3.5.3 SNIP, Train, Stream, and Datagram MTIs

3.6 Protocol Support Indicator Bits

A 48-bit bitfield returned in the Protocol Support Reply message. Each bit indicates support for a protocol:

3.7 Error Codes

Permanent Errors (0x1xxx)

Temporary Errors (0x2xxx)

3.8 Run States

The run_state field in openlcb_node_state_t tracks the login state machine progression: