## Compiling libserialport caused a false positive* by windows defender
###### *at least so i think

# !!! THIS IS OUTDATED

# 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

```c
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

```c
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

```c
struct sp_port **comm_get_port_list()
```

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

```c
void comm_list_serial_ports(struct sp_port **port_list)
```

- **Purpose**: Display available ports
- **Output Format**:

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

```c
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

```c
int comm_await()
```

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

```c
int comm_read_byte(byte *data)
```

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

```c
int comm_write_byte(byte data)
```

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

---

## Helper Function

```c
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

```c
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

---