0
# Core FTDI Device Management
1

2
Low-level FTDI device access and configuration for direct hardware communication. This module provides the foundation for all protocol-specific controllers and enables custom protocol implementation.
3

4
## Capabilities
5

6
### Device Connection Management
7

8
Open, configure, and close connections to FTDI devices with support for multiple interfaces and communication modes.
9

10
```python { .api }
11
class Ftdi:
12
    def open(self, device, interface=1, direction=None, **kwargs):
13
        """
14
        Open connection to FTDI device.
15
        
16
        Parameters:
17
        - device: Device URL, UsbDevice, or device descriptor
18
        - interface: FTDI interface number (1-4 depending on device)
19
        - direction: Data direction (None for bidirectional)
20
        - frequency: Clock frequency for MPSSE mode
21
        - latency: USB latency timer (1-255ms)
22
        
23
        Raises:
24
        - FtdiError: Device connection failed
25
        - FtdiFeatureError: Requested feature not supported
26
        """
27
    
28
    def close(self):
29
        """Close device connection and release resources."""
30
    
31
    def is_connected(self) -> bool:
32
        """Check if device is connected."""
33
```
34

35
### Data Transfer
36

37
Direct data read/write operations for custom protocol implementation.
38

39
```python { .api }
40
def read_data(self, size: int) -> bytes:
41
    """
42
    Read data from FTDI device.
43
    
44
    Parameters:
45
    - size: Number of bytes to read
46
    
47
    Returns:
48
    bytes: Data received from device
49
    
50
    Raises:
51
    - FtdiError: Read operation failed
52
    """
53

54
def write_data(self, data: bytes) -> int:
55
    """
56
    Write data to FTDI device.
57
    
58
    Parameters:
59
    - data: Data bytes to write
60
    
61
    Returns:
62
    int: Number of bytes written
63
    
64
    Raises:
65
    - FtdiError: Write operation failed
66
    """
67

68
def read_data_bytes(self, size: int, attempt: int = 1) -> bytes:
69
    """Read exact number of bytes with retry logic."""
70

71
def write_data_set_chunksize(self, chunksize: int):
72
    """Set write chunk size for large transfers."""
73

74
def read_data_set_chunksize(self, chunksize: int):
75
    """Set read chunk size for large transfers."""
76
```
77

78
### Device Configuration
79

80
Configure communication parameters, timing, and device behavior.
81

82
```python { .api }
83
def set_baudrate(self, baudrate: int):
84
    """
85
    Set device baudrate for UART mode.
86
    
87
    Parameters:
88
    - baudrate: Baudrate in bits per second (300-12000000)
89
    
90
    Raises:
91
    - FtdiError: Invalid baudrate or configuration failed
92
    """
93

94
def set_line_property(self, bits: int, stopbits: int, parity: str, break_: bool = False):
95
    """
96
    Set UART line properties.
97
    
98
    Parameters:
99
    - bits: Data bits (7 or 8)
100
    - stopbits: Stop bits (1 or 2)
101
    - parity: Parity ('N', 'E', 'O', 'M', 'S')
102
    - break_: Send break condition
103
    """
104

105
def set_flowctrl(self, flowctrl: str):
106
    """
107
    Set flow control mode.
108
    
109
    Parameters:
110
    - flowctrl: Flow control ('', 'hw', 'sw')
111
    """
112
```
113

114
### Control Lines
115

116
Manage DTR, RTS, CTS, DSR control lines for UART communication.
117

118
```python { .api }
119
def set_dtr_rts(self, dtr: bool, rts: bool):
120
    """Set DTR and RTS line states simultaneously."""
121

122
def set_dtr(self, state: bool):
123
    """Set DTR (Data Terminal Ready) line state."""
124

125
def set_rts(self, state: bool):
126
    """Set RTS (Request To Send) line state."""
127

128
def get_cts(self) -> bool:
129
    """Get CTS (Clear To Send) line state."""
130

131
def get_dsr(self) -> bool:
132
    """Get DSR (Data Set Ready) line state."""
133

134
def enable_dtr_rts(self):
135
    """Enable DTR/RTS lines."""
136

137
def disable_dtr_rts(self):
138
    """Disable DTR/RTS lines."""
139
```
140

141
### Buffer Management
142

143
Control device buffers and data flow for optimal performance.
144

145
```python { .api }
146
def flush(self):
147
    """Flush both TX and RX buffers."""
148

149
def purge_rx_buffer(self):
150
    """Purge receive buffer."""
151

152
def purge_tx_buffer(self):
153
    """Purge transmit buffer."""
154

155
def reset_tx_buffer(self):
156
    """Reset transmit buffer."""
157

158
def reset_rx_buffer(self):
159
    """Reset receive buffer."""
160
```
161

162
### Timing Control
163

164
Configure latency and timing parameters for optimal performance.
165

166
```python { .api }
167
def set_latency_timer(self, latency: int):
168
    """
169
    Set USB latency timer.
170
    
171
    Parameters:
172
    - latency: Latency in milliseconds (1-255)
173
    """
174

175
def get_latency_timer(self) -> int:
176
    """Get current USB latency timer value."""
177

178
def set_write_timeout(self, timeout: int):
179
    """Set write timeout in milliseconds."""
180

181
def set_read_timeout(self, timeout: int):
182
    """Set read timeout in milliseconds."""
183
```
184

185
### Device Reset and Recovery
186

187
Reset device state and recover from error conditions.
188

189
```python { .api }
190
def reset(self):
191
    """Reset FTDI device to initial state."""
192

193
def reset_device(self):
194
    """Perform USB device reset."""
195

196
def get_error_string(self) -> str:
197
    """Get description of last error."""
198
```
199

200
### Device Information
201

202
Query device capabilities, status, and identification information.
203

204
```python { .api }
205
def device_name(self) -> str:
206
    """Get FTDI device name (e.g., 'ft232h', 'ft2232h')."""
207

208
def device_version(self) -> int:
209
    """Get device version identifier."""
210

211
def has_wide_port(self) -> bool:
212
    """Check if device supports 16-bit MPSSE mode."""
213

214
def has_drivezero_mode(self) -> bool:
215
    """Check if device supports drive-zero mode."""
216

217
def mpsse_bit_delay(self, frequency: float) -> int:
218
    """Calculate bit delay for given MPSSE frequency."""
219

220
def validate_mpsse(self):
221
    """Validate MPSSE mode availability and configuration."""
222
```
223

224
## Device Constants
225

226
```python { .api }
227
class Ftdi:
228
    # URL scheme
229
    SCHEME = 'ftdi'
230
    
231
    # Vendor/Product IDs  
232
    FTDI_VENDOR = 0x403
233
    VENDOR_IDS = {'ftdi': 0x403}
234
    DEFAULT_VENDOR = 0x403
235
    
236
    # Supported devices
237
    PRODUCT_IDS = {
238
        0x403: {
239
            'ft232h': 0x6014,
240
            'ft2232h': 0x6010, 
241
            'ft4232h': 0x6011,
242
            'ft232r': 0x6001,
243
            'ft230x': 0x6015,
244
            # ... additional device mappings
245
        }
246
    }
247
    
248
    # Device capabilities
249
    DEVICE_NAMES = {
250
        0x0500: 'ft2232c',
251
        0x0700: 'ft232r', 
252
        0x0800: 'ft2232h',
253
        0x0900: 'ft4232h',
254
        0x1000: 'ft232h',
255
        # ... additional device mappings
256
    }
257
```
258

259
## Usage Examples
260

261
### Basic Device Connection
262

263
```python
264
from pyftdi.ftdi import Ftdi
265

266
# Open device
267
ftdi = Ftdi()
268
ftdi.open('ftdi:///1')  # First available device, interface 1
269

270
# Configure for custom protocol
271
ftdi.set_baudrate(115200)
272
ftdi.reset()
273

274
# Direct data exchange
275
ftdi.write_data(b'\x01\x02\x03')
276
response = ftdi.read_data(10)
277

278
# Clean up
279
ftdi.close()
280
```
281

282
### Custom Protocol Implementation
283

284
```python
285
from pyftdi.ftdi import Ftdi
286

287
class CustomProtocol:
288
    def __init__(self, url):
289
        self.ftdi = Ftdi()
290
        self.ftdi.open(url)
291
        self.ftdi.reset()
292
        
293
    def send_command(self, cmd, data=b''):
294
        # Custom protocol frame
295
        frame = bytes([cmd, len(data)]) + data
296
        self.ftdi.write_data(frame)
297
        
298
        # Read response
299
        header = self.ftdi.read_data(2)
300
        if header:
301
            data_len = header[1]
302
            return self.ftdi.read_data(data_len)
303
        return b''
304
    
305
    def close(self):
306
        self.ftdi.close()
307
```
308

309
## Exception Handling
310

311
```python
312
from pyftdi.ftdi import Ftdi, FtdiError, FtdiFeatureError
313

314
try:
315
    ftdi = Ftdi()
316
    ftdi.open('ftdi://0x403:0x6014/1')
317
    # Device operations...
318
except FtdiFeatureError as e:
319
    print(f"Feature not supported: {e}")
320
except FtdiError as e:
321
    print(f"FTDI error: {e}")
322
finally:
323
    if ftdi.is_connected():
324
        ftdi.close()
325
```