serial/docs/readme.md

Serial Communication Module Documentation

Overview

This module provides serial communication functionality using libserialport to interface with USB/UART devices. It handles port enumeration, configuration, and basic I/O operations.

---

Data Structures

sp_port

struct sp_port
Represents a serial port (opaque type from libserialport).

sp_port_list

struct sp_port **
Linked list of available serial ports.

sp_event_set

struct sp_event_set *
Event monitoring structure for asynchronous I/O.

---

Core Functions

Initialization & Cleanup

void comm_init_communication()

• Purpose: Initialize serial communication
• Workflow:
  1. Lists available ports
  2. Prompts user for port selection
  3. Configures port parameters (19200 baud, 8N1)
  4. Sets up RX event monitoring
• Note: Must be called first

void comm_end_communication(struct sp_port *port)

• Purpose: Clean up communication resources
• Parameters:
  • port: Active port to close
• Effects:
  • Closes port connection
  • Releases port memory

---

Port Management

struct sp_port **comm_get_port_list()

• Returns: Linked list of available serial ports
• Failure: Exits program on error

void comm_list_serial_ports(struct sp_port **port_list)

• Purpose: Display available ports
• Output Format:

Port 0: /dev/ttyUSB0 Port 1: /dev/ttyACM0

void comm_open_port(struct sp_port *port)

• Purpose: Configure port parameters
• Settings Applied:
  • Baudrate: 19200
  • Data Bits: 8
  • Parity: None
  • Stop Bits: 1
  • Event: RX Ready monitoring

---

I/O Operations

int comm_await()

• Purpose: Check for incoming data
• Returns:
  • 1: Data available
  • 0: No data/timeout
• Timeout: 50ms

int comm_read_byte(byte *data)

• Purpose: Read single byte (UNIMPLEMENTED)
• TODO: Implement actual read logic
• Returns: Placeholder (0)

int comm_write_byte(byte data)

• Purpose: Write single byte (UNIMPLEMENTED)
• TODO: Implement actual write logic
• Returns: Placeholder (0)

---

Helper Function

int check(enum sp_return result)

• Error Handling: Converts libserialport error codes to human-readable messages
• Failure Modes:
  • Invalid arguments
  • Operation failure
  • Unsupported features
  • Memory allocation errors
• Behavior: Aborts program on error

---

Usage Example

int main() {
comm_init_communication();

    while(1) {
        if(comm_await()) {
            byte data;
            if(comm_read_byte(&data)) {
                // Process data
            }
        }
        
        // comm_write_byte(0x55);
    }
    
    comm_end_communication(port);
    return 0;
}

---

Dependencies

• libserialport: Required for low-level serial operations
• stdio.h: For I/O operations
• stdlib.h: For memory management

---

Error Handling

The module uses aggressive error handling through the check() helper:

• Critical Errors: Program termination via abort()
• Error Types:
  • Invalid arguments
  • Hardware failures
  • Unsupported operations
  • Memory issues

---

Implementation Notes

1. Port Selection: Current implementation uses console input
2. Baudrate: Fixed at 19200 (modify in comm_open_port())
3. Thread Safety: Not thread-safe in current implementation
4. Event Handling: Only monitors RX events currently

---

TODO List

• Implement comm_read_byte()
• Implement comm_write_byte()
• Add timeout configuration
• Add error recovery logic
• Implement thread-safe operations

---