Skip to content

Commit 965109b

Browse files
CopilotLeStarchthomas-bc
authored
Add SDD documentation for LinuxUartDriver component (#4124)
* Initial plan * Add complete SDD documentation for LinuxUartDriver component Co-authored-by: LeStarch <[email protected]> * Address all SDD review comments: numbering, requirement IDs, FPP examples Co-authored-by: thomas-bc <[email protected]> * manual fixes * Remove one level of section numbering in LinuxUartDriver SDD Co-authored-by: thomas-bc <[email protected]> * woop woop --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: LeStarch <[email protected]> Co-authored-by: thomas-bc <[email protected]>
1 parent 054c51a commit 965109b

File tree

2 files changed

+177
-1
lines changed
  • Drv

2 files changed

+177
-1
lines changed

‎Drv/ByteStreamDriverModel/docs/sdd.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The following components implement the byte stream model using the synchronous i
3737
- [`Drv::TcpClient`](../../TcpClient/docs/sdd.md): a F´ component wrapper of the tcp client
3838
- [`Drv::TcpServer`](../../TcpServer/docs/sdd.md): a F´ component wrapper of the tcp server
3939
- [`Drv::Udp`](../../Udp/docs/sdd.md): a F´ component wrapper of the udp
40-
- `Drv::LinuxUartDriver`
40+
- [`Drv::LinuxUartDriver`](../../LinuxUartDriver/docs/sdd.md): a F´ component wrapper of the Linux UART driver
4141

4242

4343
## Requirements

‎Drv/LinuxUartDriver/docs/sdd.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Drv::LinuxUartDriver
2+
3+
## 1. Introduction
4+
5+
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`](../../Interfaces/ByteStreamDriver.fpp)) to enable serial communication with external devices through UART ports on Linux systems.
6+
7+
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.
8+
9+
For more information on the ByteStreamDriverModel see: [`Drv::ByteStreamDriverModel`](../../ByteStreamDriverModel/docs/sdd.md).
10+
11+
## 2. Requirements
12+
13+
| Name | Description | Validation |
14+
|---|---|---|
15+
| LINUX-UART-COMP-001 | The LinuxUartDriver component shall implement the Drv.ByteStreamDriver interface | inspection |
16+
| LINUX-UART-COMP-002 | The LinuxUartDriver component shall provide configurable baud rates from 9600 to 4MHz | inspection |
17+
| LINUX-UART-COMP-003 | The LinuxUartDriver component shall provide configurable flow control (none/hardware) | inspection |
18+
| LINUX-UART-COMP-004 | The LinuxUartDriver component shall provide configurable parity (none/odd/even) | inspection |
19+
| LINUX-UART-COMP-005 | The LinuxUartDriver component shall provide a dedicated read thread for receiving data | inspection |
20+
| LINUX-UART-COMP-006 | The LinuxUartDriver component shall report telemetry for bytes sent and received | inspection |
21+
| LINUX-UART-COMP-007 | The LinuxUartDriver component shall handle UART errors and report them via events | inspection |
22+
| LINUX-UART-COMP-008 | The LinuxUartDriver component shall support buffer allocation for receive operations | inspection |
23+
24+
## 3. Design
25+
26+
The LinuxUartDriver component implements the design specified by the [`Drv.ByteStreamDriver`](../../Interfaces/ByteStreamDriver.fpp) interface.
27+
28+
### 3.1 Architecture
29+
30+
The component consists of the following key elements:
31+
32+
- **UART Configuration**: Handles device opening, baud rate, flow control, and parity settings using Linux termios API
33+
- **Send Handler**: Synchronous transmission of data via the `send` port (guarded input port)
34+
- **Receive Thread**: Asynchronous reception of data via a dedicated thread that calls the `recv` output port
35+
- **Buffer Management**: Integration with F´ buffer allocation system for memory management
36+
- **Telemetry Reporting**: Tracks and reports bytes sent and received statistics
37+
- **Error Handling**: Comprehensive error detection and event reporting
38+
39+
### 3.2 Send Operation
40+
41+
When data is sent via the `send` input port:
42+
1. The component validates the file descriptor and buffer
43+
2. Data is written to the UART device using the Linux `write()` system call
44+
3. Bytes sent counter is updated for telemetry
45+
4. Status is returned indicating success or failure
46+
47+
### 3.3 Receive Operation
48+
49+
The receive operation runs in a separate thread:
50+
1. A buffer is allocated from the buffer manager
51+
2. The thread blocks on `read()` waiting for incoming data
52+
3. Received data is packaged in the buffer and sent via `recv` output port
53+
4. Bytes received counter is updated for telemetry
54+
5. Errors are logged and reported via events
55+
56+
### 3.4 Threading Model
57+
58+
The component uses a single dedicated thread for receive operations (`serialReadTaskEntry`). This thread:
59+
- Runs continuously until `quitReadThread()` is called
60+
- Allocates buffers for each receive operation
61+
- Handles timeouts and errors gracefully
62+
- Can be started with configurable priority and stack size
63+
64+
## 4. Usage
65+
66+
The LinuxUartDriver must be configured with device parameters before use. The typical usage pattern is:
67+
68+
1. **Open Device**: Configure the UART device with desired parameters
69+
2. **Start Receive Thread**: Begin the receive thread for incoming data
70+
3. **Send/Receive Data**: Use the ByteStreamDriverModel ports for communication
71+
4. **Shutdown**: Stop the receive thread and close the device
72+
73+
### 4.1 Configuration Example
74+
75+
The LinuxUartDriver should be instantiated in the FPP topology and configured using separate functions following F´ patterns:
76+
77+
```cpp
78+
// Configuration function - called during topology setup
79+
void configureTopology() {
80+
// Open UART device with configuration
81+
bool success = uart.open("/dev/ttyUSB0", // Device path
82+
Drv::LinuxUartDriver::BAUD_115K, // 115200 baud
83+
Drv::LinuxUartDriver::NO_FLOW, // No flow control
84+
Drv::LinuxUartDriver::PARITY_NONE, // No parity
85+
1024); // Buffer size
86+
if (!success) {
87+
// Handle configuration error
88+
}
89+
...
90+
}
91+
92+
// Startup function - called when starting tasks
93+
void setupTopology() {
94+
// Start receive thread
95+
Os::TaskString name("UartReceiveTask");
96+
uart.start(name, UART_PRIORITY, Default::STACK_SIZE);
97+
}
98+
99+
// Shutdown function - called during teardown
100+
void teardownTopology() {
101+
uart.quitReadThread();
102+
uart.join();
103+
}
104+
```
105+
106+
### 4.2 Integration with Rate Groups
107+
108+
The component includes a `run` input port for telemetry reporting that should be connected to a rate group in the FPP topology:
109+
110+
```fpp
111+
# In topology.fpp connections section
112+
connections RateGroups {
113+
# Connect UART driver to rate group for telemetry
114+
rateGroup1Comp.RateGroupMemberOut[N] -> uart.run
115+
}
116+
```
117+
118+
## 5. Configuration
119+
120+
### 5.1 Device Parameters
121+
122+
| Parameter | Type | Description | Valid Values |
123+
|-----------|------|-------------|--------------|
124+
| device | const char* | Path to UART device | Linux device path (e.g., "/dev/ttyUSB0") |
125+
| baud | UartBaudRate | Communication baud rate | See baud rate enumeration |
126+
| fc | UartFlowControl | Flow control setting | NO_FLOW, HW_FLOW |
127+
| parity | UartParity | Parity setting | PARITY_NONE, PARITY_ODD, PARITY_EVEN |
128+
| allocationSize | FwSizeType | Receive buffer size | Positive integer (bytes) |
129+
130+
### 5.2 Baud Rate Options
131+
132+
The component supports the following baud rates:
133+
134+
| Enumeration | Numeric Value | Availability |
135+
|-------------|---------------|--------------|
136+
| BAUD_9600 | 9600 | All platforms |
137+
| BAUD_19200 | 19200 | All platforms |
138+
| BAUD_38400 | 38400 | All platforms |
139+
| BAUD_57600 | 57600 | All platforms |
140+
| BAUD_115K | 115200 | All platforms |
141+
| BAUD_230K | 230400 | All platforms |
142+
| BAUD_460K | 460800 | Linux only |
143+
| BAUD_921K | 921600 | Linux only |
144+
| BAUD_1000K | 1000000 | Linux only |
145+
| BAUD_1152K | 1152000 | Linux only |
146+
| BAUD_1500K | 1500000 | Linux only |
147+
| BAUD_2000K | 2000000 | Linux only |
148+
| BAUD_2500K | 2500000 | Linux only (if supported) |
149+
| BAUD_3000K | 3000000 | Linux only (if supported) |
150+
| BAUD_3500K | 3500000 | Linux only (if supported) |
151+
| BAUD_4000K | 4000000 | Linux only (if supported) |
152+
153+
### 5.3 Thread Configuration
154+
155+
The receive thread can be configured with:
156+
157+
| Parameter | Type | Default | Description |
158+
|-----------|------|---------|-------------|
159+
| priority | FwTaskPriorityType | TASK_PRIORITY_DEFAULT | Thread priority |
160+
| stackSize | Os::Task::ParamType | TASK_DEFAULT | Thread stack size |
161+
| cpuAffinity | Os::Task::ParamType | TASK_DEFAULT | CPU affinity mask |
162+
163+
### 5.4 Events and Telemetry
164+
165+
The component generates the following events:
166+
- **OpenError**: UART device open failures
167+
- **ConfigError**: UART configuration failures
168+
- **WriteError**: Data transmission errors
169+
- **ReadError**: Data reception errors
170+
- **PortOpened**: Successful device configuration
171+
- **NoBuffers**: Buffer allocation failures
172+
- **BufferTooSmall**: Insufficient buffer size
173+
174+
The component reports the following telemetry:
175+
- **BytesSent**: Total bytes transmitted
176+
- **BytesRecv**: Total bytes received

0 commit comments

Comments
 (0)