0
# PyFtdi
1

2
A pure Python library providing user-space drivers for FTDI USB-to-serial/GPIO/SPI/I2C/JTAG bridge devices. PyFtdi enables direct hardware communication without requiring kernel drivers, supporting a wide range of FTDI chips for various communication protocols and GPIO operations.
3

4
## Package Information
5

6
- **Package Name**: pyftdi
7
- **Language**: Python
8
- **Installation**: `pip install pyftdi`
9
- **Dependencies**: `pyusb>=1.0.0,!=1.2.0`, `pyserial>=3.0`
10
- **Python Versions**: 3.9+
11

12
## Core Imports
13

14
```python
15
import pyftdi
16
from pyftdi.ftdi import Ftdi
17
```
18

19
Protocol-specific imports:
20

21
```python
22
from pyftdi.spi import SpiController
23
from pyftdi.i2c import I2cController
24
from pyftdi.gpio import GpioAsyncController, GpioSyncController, GpioMpsseController
25
from pyftdi.jtag import JtagController
26
from pyftdi.eeprom import FtdiEeprom
27
from pyftdi.usbtools import UsbTools
28
from pyftdi.serialext import serial_for_url
29
```
30

31
## Basic Usage
32

33
```python
34
from pyftdi.spi import SpiController
35

36
# Configure SPI controller with FTDI device
37
spi = SpiController()
38
spi.configure('ftdi:///1')  # Use first available FTDI device, interface 1
39

40
# Get SPI port for chip select 0
41
spi_port = spi.get_port(cs=0, freq=6E6, mode=0)
42

43
# Perform SPI transaction
44
response = spi_port.exchange([0x9F], 3)  # Read device ID
45
print([hex(x) for x in response])
46

47
# Clean up
48
spi.terminate()
49
```
50

51
## Architecture
52

53
PyFtdi provides layered access to FTDI devices:
54

55
- **Device Layer (`ftdi`)**: Low-level FTDI device communication and configuration
56
- **Protocol Controllers**: High-level interfaces for specific protocols (SPI, I2C, JTAG)
57
- **GPIO Controllers**: Specialized GPIO access with different operating modes
58
- **Utility Layer**: USB device discovery, EEPROM management, and debugging tools
59
- **Serial Extension**: PySerial-compatible interface for UART communication
60

61
This design enables both simple protocol-specific usage and advanced multi-protocol applications where one FTDI device handles multiple communication types simultaneously.
62

63
## Device URL Format
64

65
PyFtdi uses URL-based device specification for consistent device addressing:
66

67
- Format: `ftdi://[vendor[:product[:index|:serial]]]/interface`
68
- Examples:
69
  - `ftdi:///1` - Any FTDI device, interface 1
70
  - `ftdi://0x403:0x6014:0/1` - Specific FT232H device, interface 1
71
  - `ftdi://0x403:0x6014:12345678/1` - Device with serial number 12345678
72

73
## Supported Devices
74

75
**Single Port Devices (UART + GPIO):**
76
- FT232R (3Mbps)
77
- FT230X/FT231X/FT234X (3Mbps)
78

79
**Multi-Protocol Devices (UART + GPIO + SPI + I2C + JTAG):**
80
- FT232H (single port, up to 30MHz)
81
- FT2232C/D/H (dual port, up to 6MHz/30MHz)
82
- FT4232H/HA (quad port, up to 30MHz)
83

84
## Capabilities
85

86
### Core FTDI Device Management
87

88
Low-level FTDI device access, configuration, and direct communication for custom protocols or advanced usage scenarios.
89

90
```python { .api }
91
class Ftdi:
92
    def open(self, device, interface, direction=None, **kwargs): ...
93
    def close(self): ...
94
    def read_data(self, size): ...
95
    def write_data(self, data): ...
96
    def set_baudrate(self, baudrate): ...
97
    def reset(self): ...
98
```
99

100
[Core FTDI](./core-ftdi.md)
101

102
### SPI Master Communication
103

104
SPI master controller with support for multiple chip selects, simultaneous GPIO access, variable clock speeds up to 30MHz, and non-byte-aligned transfers.
105

106
```python { .api }
107
class SpiController:
108
    def configure(self, url, **kwargs): ...
109
    def terminate(self): ...
110
    def get_port(self, cs, freq=6000000, mode=0): ...
111
    def get_gpio(self): ...
112

113
class SpiPort:
114
    def exchange(self, out, readlen=0, start=True, stop=True, duplex=False): ...
115
    def read(self, readlen, start=True, stop=True): ...
116
    def write(self, out, start=True, stop=True): ...
117
```
118

119
[SPI Communication](./spi.md)
120

121
### I2C Master Communication
122

123
I2C master controller with support for device addressing, register access, bus scanning, simultaneous GPIO access, and clock stretching handling.
124

125
```python { .api }
126
class I2cController:
127
    def configure(self, url, **kwargs): ...
128
    def terminate(self): ...
129
    def get_port(self, address): ...
130
    def get_gpio(self): ...
131

132
class I2cPort:
133
    def read(self, readlen, relax=True): ...
134
    def write(self, out, relax=True): ...
135
    def read_from(self, regaddr, readlen, relax=True): ...
136
    def write_to(self, regaddr, out, relax=True): ...
137
    def exchange(self, out, readlen, relax=True): ...
138
```
139

140
[I2C Communication](./i2c.md)
141

142
### GPIO Control
143

144
Multiple GPIO controller types supporting different operating modes: asynchronous bitbang, synchronous clocked operation, and high-performance MPSSE mode.
145

146
```python { .api }
147
class GpioAsyncController:
148
    def set_direction(self, pins, direction): ...
149
    def read(self, with_output=False): ...
150
    def write(self, value): ...
151

152
class GpioSyncController:
153
    def set_direction(self, pins, direction): ...
154
    def read(self, with_output=False): ...
155
    def write(self, value): ...
156

157
class GpioMpsseController:
158
    def set_direction(self, pins, direction): ...
159
    def read(self, with_output=False): ...
160
    def write(self, value): ...
161
```
162

163
[GPIO Control](./gpio.md)
164

165
### JTAG Interface
166

167
JTAG controller supporting TAP state machine management, instruction and data register access, chain discovery, and basic debugging operations.
168

169
```python { .api }
170
class JtagController:
171
    def configure(self, url, **kwargs): ...
172
    def close(self): ...
173
    def reset(self): ...
174
    def write_ir(self, instruction): ...
175
    def write_dr(self, data): ...
176
    def read_dr(self, length): ...
177
    def shift_register(self, out, length): ...
178
```
179

180
[JTAG Interface](./jtag.md)
181

182
### EEPROM Management
183

184
FTDI device EEPROM access for reading configuration, modifying device parameters, and managing device identity information.
185

186
```python { .api }
187
class FtdiEeprom:
188
    def open(self, device): ...
189
    def close(self): ...
190
    def read_eeprom(self): ...
191
    def write_eeprom(self): ...
192
    def erase_eeprom(self): ...
193
    def set_manufacturer_name(self, name): ...
194
    def set_product_name(self, name): ...
195
    def set_serial_number(self, serial): ...
196
    def sync(self): ...
197
```
198

199
[EEPROM Management](./eeprom.md)
200

201
### USB Device Discovery
202

203
USB device enumeration, FTDI device detection, URL parsing, and device capability identification.
204

205
```python { .api }
206
class UsbTools:
207
    @staticmethod
208
    def find_all(vps, nb=0): ...
209
    @staticmethod
210
    def get_device(vendor, product, index=0, serial=None, path=None): ...
211
    @staticmethod
212
    def show_devices(vendor, product, serial=None): ...
213
    @staticmethod
214
    def parse_url(url, scheme): ...
215
```
216

217
[USB Tools](./usb-tools.md)
218

219
### Serial Communication
220

221
PySerial-compatible interface for UART communication using FTDI devices, enabling drop-in replacement for standard serial ports.
222

223
```python { .api }
224
from pyftdi.serialext import serial_for_url
225

226
def serial_for_url(url, **kwargs):
227
    """Create serial connection from FTDI URL"""
228
```
229

230
[Serial Communication](./serial.md)
231

232
## Types
233

234
```python { .api }
235
# Exception types
236
class FtdiError(IOError): ...
237
class FtdiFeatureError(FtdiError): ...
238
class FtdiMpsseError(FtdiFeatureError): ...
239
class FtdiEepromError(FtdiError): ...
240
class SpiIOError(FtdiError): ...
241
class I2cIOError(IOError): ...
242
class I2cNackError(I2cIOError): ...
243
class I2cTimeoutError(TimeoutError): ...
244
class GpioException(FtdiError): ...
245
class JtagError(Exception): ...
246
class UsbToolsError(Exception): ...
247

248
# Logging utilities
249
class FtdiLogger:
250
    log: Logger
251
    @classmethod
252
    def set_formatter(cls, formatter): ...
253
    @classmethod
254
    def get_level(cls): ...
255
    @classmethod
256
    def set_level(cls, level): ...
257
```