Drv::LinuxUartDriver

1. Introduction

The LinuxUartDriver component provides a Linux-specific implementation of a UART (Universal Asynchronous Receiver-Transmitter) serial communication driver. It implements the byte stream driver model interface (see Drv.ByteStreamDriver) to enable serial communication with external devices through UART ports on Linux systems.

The component wraps Linux termios API functionality to provide configurable serial communication with support for various baud rates, flow control options, and parity settings. It implements bidirectional communication using a dedicated receive thread and synchronous send operations.

For more information on the ByteStreamDriverModel see: Drv::ByteStreamDriverModel.

2. Requirements

3. Design

The LinuxUartDriver component implements the design specified by the Drv.ByteStreamDriver interface.

3.1 Architecture

The component consists of the following key elements:

• UART Configuration: Handles device opening, baud rate, flow control, and parity settings using Linux termios API
• Send Handler: Synchronous transmission of data via the send port (guarded input port)
• Receive Thread: Asynchronous reception of data via a dedicated thread that calls the recv output port
• Buffer Management: Integration with F´ buffer allocation system for memory management
• Telemetry Reporting: Tracks and reports bytes sent and received statistics
• Error Handling: Comprehensive error detection and event reporting

3.2 Send Operation

When data is sent via the send input port:

1. The component validates the file descriptor and buffer
2. Data is written to the UART device using the Linux write() system call
3. Bytes sent counter is updated for telemetry
4. Status is returned indicating success or failure

3.3 Receive Operation

The receive operation runs in a separate thread:

1. A buffer is allocated from the buffer manager
2. The thread blocks on read() waiting for incoming data
3. Received data is packaged in the buffer and sent via recv output port
4. Bytes received counter is updated for telemetry
5. Errors are logged and reported via events

3.4 Threading Model

The component uses a single dedicated thread for receive operations (serialReadTaskEntry). This thread:

• Runs continuously until quitReadThread() is called
• Allocates buffers for each receive operation
• Handles timeouts and errors gracefully
• Can be started with configurable priority and stack size

4. Usage

The LinuxUartDriver must be configured with device parameters before use. The typical usage pattern is:

1. Open Device: Configure the UART device with desired parameters
2. Start Receive Thread: Begin the receive thread for incoming data
3. Send/Receive Data: Use the ByteStreamDriverModel ports for communication
4. Shutdown: Stop the receive thread and close the device

4.1 Configuration Example

The LinuxUartDriver should be instantiated in the FPP topology and configured using separate functions following F´ patterns:

// Configuration function - called during topology setup
void configureTopology() {
    // Open UART device with configuration
    bool success = uart.open("/dev/ttyUSB0",                    // Device path
                             Drv::LinuxUartDriver::BAUD_115K,   // 115200 baud rate
                             Drv::LinuxUartDriver::NO_FLOW,     // No flow control
                             Drv::LinuxUartDriver::PARITY_NONE, // No parity
                             1024);                             // Buffer size
    if (!success) {
        // Handle configuration error
    }
    ...
}

// Startup function - called when starting tasks
void setupTopology() {
    // Start receive thread
    uart.start(UART_PRIORITY,           // Thread priority
               32 * 1024,               // Thread stack size
               Os::Task::TASK_DEFAULT); // Thread CPU affinity mask
}

// Shutdown function - called during teardown
void teardownTopology() {
    uart.quitReadThread();
    uart.join();
}

4.2 Integration with Rate Groups

The component includes a run input port for telemetry reporting that should be connected to a rate group in the FPP topology:

# In topology.fpp connections section
connections RateGroups {
  # Connect UART driver to rate group for telemetry
  rateGroup1Comp.RateGroupMemberOut[N] -> uart.run
}

5. Configuration

5.1 Device Parameters

5.2 Baud Rate Options

The component supports the following baud rates:

5.3 Thread Configuration

The receive thread can be configured with:

5.4 Events and Telemetry

The component generates the following events:

• OpenError: UART device open failures
• ConfigError: UART configuration failures
• WriteError: Data transmission errors
• ReadError: Data reception errors
• PortOpened: Successful device configuration
• NoBuffers: Buffer allocation failures
• BufferTooSmall: Insufficient buffer size

The component reports the following telemetry:

• BytesSent: Total bytes transmitted
• BytesRecv: Total bytes received