Chapter 27 — Adding a New Transport

This chapter explains how to add a new transport layer alongside the existing CAN driver. The architecture cleanly separates transport-independent protocol logic (in openlcb/) from transport-specific code (in drivers/), so a new transport only needs to convert between its wire format and openlcb_msg_t.

27.1 Architecture Boundary

The key boundary: transport drivers produce and consume openlcb_msg_t structures. Everything above that boundary is shared code that works identically regardless of the transport.

27.2 What a Transport Must Provide

Every transport driver must implement three fundamental operations:

27.3 Driver Folder Structure

Create a new folder under drivers/ for your transport:

drivers/
    canbus/                     // Existing CAN transport
        can_config.h
        can_config.c
        can_main_statemachine.h
        can_main_statemachine.c
        can_rx_statemachine.h
        can_tx_statemachine.h
        ...
    tcpip/                      // New TCP/IP transport
        tcpip_config.h          // User-facing config struct
        tcpip_config.c          // Internal wiring
        tcpip_main_statemachine.h
        tcpip_main_statemachine.c
        tcpip_rx_handler.h
        tcpip_rx_handler.c
        tcpip_tx_handler.h
        tcpip_tx_handler.c

27.4 CAN vs. TCP/IP Comparison

The CAN transport has significant complexity due to the constrained bus format. A TCP/IP transport is substantially simpler:

27.5 Integration with the Core

The transport driver connects to the core through the same interfaces the CAN driver uses:

Key Integration Points

1. Buffer allocation: The transport allocates openlcb_msg_t from the shared buffer pool (OpenLcbBufferStore_allocate_buffer()) for incoming messages.
2. FIFO push: Converted messages are pushed to the OpenLCB incoming FIFO using OpenLcbBufferFifo_push().
3. TX path: The core calls the transport's send function (via function pointer in the interface struct) when it has a message to transmit.
4. Login coordination: The transport drives the early login states (CAN-specific alias allocation), then hands off to the core login state machine for the OpenLCB-level login (Initialization Complete, event enumeration).

27.6 Configuration Struct Pattern

Follow the same pattern as can_config.h. Create a user-facing config struct with hardware driver function pointers:

// tcpip_config.h

typedef struct {
    // REQUIRED: Send raw TCP data
    bool (*transmit_tcp_message)(uint8_t *data, uint16_t length);

    // REQUIRED: Check if TCP socket is ready to send
    bool (*is_tx_ready)(void);

    // REQUIRED: Lock/unlock (same as openlcb_config_t)
    void (*lock_shared_resources)(void);
    void (*unlock_shared_resources)(void);

    // OPTIONAL: Diagnostic callbacks
    void (*on_rx)(openlcb_msg_t *msg);
    void (*on_tx)(openlcb_msg_t *msg);

} tcpip_config_t;

extern void TcpipConfig_initialize(const tcpip_config_t *config);

27.7 What Changes in the Application

When using a different transport, the application's main loop changes to call the new transport's state machine instead of the CAN state machine:

// CAN application main loop:
while (1) {
    OpenLcb_run();  // Internally calls CanMainStateMachine_run()
                    // then OpenLcb login/main state machines
}

// TCP/IP application main loop:
while (1) {
    TcpipMainStateMachine_run();    // Transport-specific
    OpenLcbLoginMainStatemachine_run();  // Shared
    OpenLcbMainStatemachine_run();       // Shared
}

27.8 Checklist for a New Transport