Chapter 3b — CAN-Specific Types and Constants

This chapter covers types defined in can_types.h that are specific to the CAN transport layer. These supplement the transport-independent types from Chapter 3.

3b.1 The can_msg_t Structure

A complete CAN 2.0B extended frame:

typedef struct can_msg_struct {
    can_msg_state_t state;        // Allocation flag (1-bit bitfield)
    uint32_t identifier;          // 29-bit extended CAN identifier
    uint8_t payload_count;        // Number of valid data bytes (0-8)
    payload_bytes_can_t payload;  // 8-byte data array
} can_msg_t;

The can_msg_state_t contains a single allocated bit, used by the CAN buffer store to track ownership:

typedef struct can_msg_state_struct {
    uint8_t allocated : 1;
} can_msg_state_t;

3b.2 CAN Identifier Bit Layout

OpenLCB uses the CAN 2.0B 29-bit extended identifier. The bits are divided into fields depending on whether the frame is a CAN control frame or an OpenLCB message frame:

29-bit CAN Extended Identifier Layout:
+----+-----+--------+--------------+------------------+
| 28 | 27  | 26-24  |    23-12     |      11-0        |
+----+-----+--------+--------------+------------------+
| R  | Msg | Frame  |  Variable    |   Source Alias    |
|    | Ind | Type / |  Field /     |   (12 bits)       |
| 0  |     | Seq #  |  MTI field   |                   |
+----+-----+--------+--------------+------------------+

Bit 28:    Reserved (always 0)
Bit 27:    1 = OpenLCB message frame, 0 = CAN control frame
Bits 26-24: Frame Type (OpenLCB) or Sequence Number (CAN control)
Bits 23-12: Variable Field (MTI bits in messages, command in control frames)
Bits 11-0:  Source Alias (12-bit CAN alias of the sending node)

3b.3 Frame Type Constants

When bit 27 is set (OpenLCB message), bits 26-24 identify the frame type:

3b.4 CAN Control Frame Constants

When bit 27 is clear (CAN control frame), bits 26-24 carry a sequence number for CID frames, or the variable field encodes the control command:

3b.5 Multi-Frame Indicator Bits

For addressed messages that span multiple CAN frames, bits 5-4 of the first data byte indicate the frame position in the sequence:

The mask MASK_MULTIFRAME_BITS (0x30) isolates these two bits from the first data byte.

3b.6 CAN Identifier Field Masks

These masks extract individual fields from the 29-bit CAN identifier:

3b.7 can_statemachine_info_t

Context block passed through the CAN state machine on every iteration:

typedef struct can_statemachine_info_struct {
    openlcb_node_t *openlcb_node;            // Node currently being processed
    can_msg_t *login_outgoing_can_msg;        // Statically-allocated login frame (CID/RID/AMD)
    uint8_t login_outgoing_can_msg_valid : 1; // Set when login frame needs transmitting
    can_msg_t *outgoing_can_msg;              // Pool-allocated reply frame; freed after TX
    uint8_t enumerating : 1;                  // Set when handler will produce N reply frames
    uint8_t current_tick;                     // Snapshot of global 100ms tick
} can_statemachine_info_t;

3b.8 Alias Mapping Types

alias_mapping_t

One entry in the alias mapping table -- a Node ID / 12-bit alias pair:

typedef struct alias_mapping_struct {
    node_id_t node_id;        // Permanent 48-bit Node ID
    uint16_t alias;           // Temporary 12-bit CAN alias (0x001-0xFFF)
    uint8_t is_duplicate : 1; // Set by ISR when another node claims this alias
    uint8_t is_permitted : 1; // Set after successful login (AMD transmitted)
} alias_mapping_t;

alias_mapping_info_t

Container for all alias mapping entries plus a fast-check duplicate flag:

typedef struct alias_mapping_info_struct {
    alias_mapping_t list[ALIAS_MAPPING_BUFFER_DEPTH]; // All registered mappings
    bool has_duplicate_alias;  // True if any entry has is_duplicate set
} alias_mapping_info_t;

The has_duplicate_alias flag enables the main loop to quickly check if any alias conflict needs resolution, without scanning the entire table on every iteration.

3b.9 listener_alias_entry_t

Used by the listener alias table for train consist members:

typedef struct listener_alias_entry_struct {
    node_id_t node_id; // Listener Node ID (from protocol layer attach). 0 = unused.
    uint16_t alias;    // Resolved CAN alias (0 = not yet resolved)
} listener_alias_entry_t;

The total number of listener alias table slots is computed as:

#define LISTENER_ALIAS_TABLE_DEPTH \
    (USER_DEFINED_MAX_LISTENERS_PER_TRAIN * USER_DEFINED_TRAIN_NODE_COUNT)

3b.10 CAN-Specific Constants