0
# EEPROM Management
1

2
FTDI device EEPROM access for reading configuration, modifying device parameters, and managing device identity information. Enables customization of USB descriptors, device behavior, and hardware configuration.
3

4
## Capabilities
5

6
### EEPROM Access
7

8
Open and manage EEPROM access on FTDI devices.
9

10
```python { .api }
11
class FtdiEeprom:
12
    def open(self, device):
13
        """
14
        Open EEPROM access on FTDI device.
15
        
16
        Parameters:
17
        - device: FTDI device URL, UsbDevice, or device descriptor
18
        
19
        Raises:
20
        - FtdiEepromError: EEPROM access failed
21
        - FtdiError: Device connection error
22
        """
23
    
24
    def close(self):
25
        """Close EEPROM access and release device."""
26
    
27
    def is_empty(self) -> bool:
28
        """Check if EEPROM is empty (all 0xFF)."""
29
```
30

31
### EEPROM Read Operations
32

33
Read EEPROM content and configuration data.
34

35
```python { .api }
36
def read_eeprom(self) -> bytes:
37
    """
38
    Read entire EEPROM content.
39
    
40
    Returns:
41
    bytes: Complete EEPROM data
42
    
43
    Raises:
44
    - FtdiEepromError: Read operation failed
45
    """
46

47
def dump_config(self, file=None) -> str:
48
    """
49
    Dump current EEPROM configuration in human-readable format.
50
    
51
    Parameters:
52
    - file: Optional file object to write output
53
    
54
    Returns:
55
    str: Configuration dump
56
    """
57

58
def size(self) -> int:
59
    """
60
    Get EEPROM size in bytes.
61
    
62
    Returns:
63
    int: EEPROM size
64
    """
65

66
def data_width(self) -> int:
67
    """
68
    Get EEPROM data width.
69
    
70
    Returns:
71
    int: Data width in bits (typically 16)
72
    """
73
```
74

75
### EEPROM Write Operations
76

77
Write and modify EEPROM content with validation.
78

79
```python { .api }
80
def write_eeprom(self):
81
    """
82
    Write modified configuration to EEPROM.
83
    
84
    Raises:
85
    - FtdiEepromError: Write operation failed
86
    """
87

88
def erase_eeprom(self):
89
    """
90
    Erase entire EEPROM (set all bytes to 0xFF).
91
    
92
    Raises:
93
    - FtdiEepromError: Erase operation failed
94
    """
95

96
def sync(self):
97
    """
98
    Synchronize configuration changes to EEPROM.
99
    
100
    Raises:
101
    - FtdiEepromError: Synchronization failed
102
    """
103

104
def reset_device(self):
105
    """Reset device to apply EEPROM changes."""
106
```
107

108
### Device Identity Configuration
109

110
Modify USB device descriptors and identification strings.
111

112
```python { .api }
113
def set_manufacturer_name(self, name: str):
114
    """
115
    Set USB manufacturer string.
116
    
117
    Parameters:
118
    - name: Manufacturer name (max 255 characters)
119
    
120
    Raises:
121
    - FtdiEepromError: String too long or invalid
122
    """
123

124
def set_product_name(self, name: str):
125
    """
126
    Set USB product string.
127
    
128
    Parameters:
129
    - name: Product name (max 255 characters)
130
    """
131

132
def set_serial_number(self, serial: str):
133
    """
134
    Set USB serial number string.
135
    
136
    Parameters:
137
    - serial: Serial number (max 255 characters)
138
    """
139

140
def get_manufacturer_name(self) -> str:
141
    """Get current manufacturer string."""
142

143
def get_product_name(self) -> str:
144
    """Get current product string."""
145

146
def get_serial_number(self) -> str:
147
    """Get current serial number string."""
148
```
149

150
### Hardware Configuration
151

152
Configure FTDI device hardware behavior and capabilities.
153

154
```python { .api }
155
def set_property(self, name: str, value):
156
    """
157
    Set EEPROM configuration property.
158
    
159
    Parameters:
160
    - name: Property name
161
    - value: Property value
162
    
163
    Common properties:
164
    - 'vendor_id': USB vendor ID (16-bit)
165
    - 'product_id': USB product ID (16-bit)
166
    - 'type': Device type code
167
    - 'self_powered': Self-powered flag (bool)
168
    - 'remote_wakeup': Remote wakeup capability (bool)
169
    - 'max_power': Maximum power consumption (mA)
170
    """
171

172
def get_property(self, name: str):
173
    """
174
    Get EEPROM configuration property.
175
    
176
    Parameters:
177
    - name: Property name
178
    
179
    Returns:
180
    Property value
181
    """
182

183
def has_property(self, name: str) -> bool:
184
    """Check if property exists in configuration."""
185
```
186

187
### Channel Configuration
188

189
Configure individual FTDI channels for multi-port devices.
190

191
```python { .api }
192
def set_channel_config(self, channel: int, config: dict):
193
    """
194
    Configure specific channel properties.
195
    
196
    Parameters:
197
    - channel: Channel number (0-based)
198
    - config: Configuration dictionary
199
    
200
    Configuration options:
201
    - 'type': Channel type ('uart', 'fifo', 'cpu_fifo', etc.)
202
    - 'driver': Driver type ('vcp', 'd2xx')
203
    - 'invert': Signal inversion flags
204
    """
205

206
def get_channel_config(self, channel: int) -> dict:
207
    """Get configuration for specific channel."""
208
```
209

210
### CBUS Configuration
211

212
Configure CBUS pins for devices that support them.
213

214
```python { .api }
215
def set_cbus_function(self, cbus: int, function: str):
216
    """
217
    Set CBUS pin function.
218
    
219
    Parameters:
220
    - cbus: CBUS pin number (0-3 or 0-9 depending on device)
221
    - function: Pin function ('tristate', 'txled', 'rxled', 'txrxled', 
222
                'pwren', 'sleep', 'drive0', 'drive1', 'iomode', 'bitbang_wr',
223
                'bitbang_rd', 'timestamp', 'awake')
224
    """
225

226
def get_cbus_function(self, cbus: int) -> str:
227
    """Get current CBUS pin function."""
228

229
def get_cbus_pins(self) -> int:
230
    """Get number of available CBUS pins."""
231
```
232

233
## Utility Classes
234

235
Helper classes for EEPROM data representation.
236

237
```python { .api }
238
class Hex2Int(int):
239
    """2-digit hexadecimal integer representation."""
240

241
class Hex4Int(int):
242
    """4-digit hexadecimal integer representation."""
243
```
244

245
## Device Support
246

247
### EEPROM Sizes
248

249
EEPROM sizes by FTDI device:
250
- **FT232R**: 128 bytes
251
- **FT232H**: 256 bytes  
252
- **FT2232C/D**: 128 bytes
253
- **FT2232H**: 256 bytes
254
- **FT4232H**: 256 bytes
255

256
### Default Configuration
257

258
Standard FTDI device configuration includes:
259
- **Vendor ID**: 0x0403 (FTDI)
260
- **Product ID**: Device-specific
261
- **Manufacturer**: "FTDI"
262
- **Product**: Device-specific name
263
- **Serial**: Unique serial number
264
- **Max Power**: 90mA (USB bus powered)
265

266
## Usage Examples
267

268
### Basic EEPROM Access
269

270
```python
271
from pyftdi.eeprom import FtdiEeprom
272

273
# Open EEPROM
274
eeprom = FtdiEeprom()
275
eeprom.open('ftdi:///1')
276

277
# Read current configuration
278
config_dump = eeprom.dump_config()
279
print(config_dump)
280

281
# Read raw EEPROM data
282
raw_data = eeprom.read_eeprom()
283
print(f"EEPROM size: {len(raw_data)} bytes")
284
print(f"Raw data: {raw_data.hex()}")
285

286
eeprom.close()
287
```
288

289
### Modify Device Identity
290

291
```python
292
from pyftdi.eeprom import FtdiEeprom
293

294
eeprom = FtdiEeprom()
295
eeprom.open('ftdi:///1')
296

297
# Change device identity
298
eeprom.set_manufacturer_name("My Company")
299
eeprom.set_product_name("Custom FTDI Device")
300
eeprom.set_serial_number("CUST001")
301

302
# Write changes to EEPROM
303
eeprom.sync()
304

305
# Reset device to apply changes
306
eeprom.reset_device()
307

308
eeprom.close()
309
```
310

311
### Custom USB Configuration
312

313
```python
314
from pyftdi.eeprom import FtdiEeprom
315

316
eeprom = FtdiEeprom()
317
eeprom.open('ftdi:///1')
318

319
# Set custom USB configuration
320
eeprom.set_property('vendor_id', 0x1234)  # Custom vendor ID
321
eeprom.set_property('product_id', 0x5678)  # Custom product ID
322
eeprom.set_property('max_power', 500)      # 500mA max power
323
eeprom.set_property('self_powered', False) # Bus powered
324
eeprom.set_property('remote_wakeup', True) # Enable remote wakeup
325

326
# Apply changes
327
eeprom.sync()
328
eeprom.close()
329
```
330

331
### CBUS Pin Configuration
332

333
```python
334
from pyftdi.eeprom import FtdiEeprom
335

336
eeprom = FtdiEeprom()
337
eeprom.open('ftdi:///1')  # FT232R with CBUS pins
338

339
# Configure CBUS pins
340
eeprom.set_cbus_function(0, 'txled')    # CBUS0 = TX LED
341
eeprom.set_cbus_function(1, 'rxled')    # CBUS1 = RX LED  
342
eeprom.set_cbus_function(2, 'sleep')    # CBUS2 = Sleep indicator
343
eeprom.set_cbus_function(3, 'drive1')   # CBUS3 = Always high
344

345
# Check configuration
346
for i in range(4):
347
    func = eeprom.get_cbus_function(i)
348
    print(f"CBUS{i}: {func}")
349

350
eeprom.sync()
351
eeprom.close()
352
```
353

354
### Multi-Channel Device Configuration
355

356
```python
357
from pyftdi.eeprom import FtdiEeprom
358

359
eeprom = FtdiEeprom()
360
eeprom.open('ftdi:///1')  # FT2232H dual channel device
361

362
# Configure channel A
363
channel_a_config = {
364
    'type': 'uart',
365
    'driver': 'vcp',
366
    'invert': 0x00
367
}
368
eeprom.set_channel_config(0, channel_a_config)
369

370
# Configure channel B  
371
channel_b_config = {
372
    'type': 'fifo',
373
    'driver': 'd2xx',
374
    'invert': 0x00
375
}
376
eeprom.set_channel_config(1, channel_b_config)
377

378
eeprom.sync()
379
eeprom.close()
380
```
381

382
### EEPROM Backup and Restore
383

384
```python
385
from pyftdi.eeprom import FtdiEeprom
386

387
def backup_eeprom(device_url, filename):
388
    """Backup EEPROM to file."""
389
    eeprom = FtdiEeprom()
390
    eeprom.open(device_url)
391
    
392
    data = eeprom.read_eeprom()
393
    with open(filename, 'wb') as f:
394
        f.write(data)
395
    
396
    eeprom.close()
397
    print(f"EEPROM backed up to {filename}")
398

399
def restore_eeprom(device_url, filename):
400
    """Restore EEPROM from file."""
401
    with open(filename, 'rb') as f:
402
        data = f.read()
403
    
404
    eeprom = FtdiEeprom()
405
    eeprom.open(device_url)
406
    
407
    # This is a simplified example - actual restore would need
408
    # to parse and validate the EEPROM structure
409
    print("Warning: Direct restore not implemented for safety")
410
    
411
    eeprom.close()
412

413
# Usage
414
backup_eeprom('ftdi:///1', 'eeprom_backup.bin')
415
```
416

417
### Factory Reset
418

419
```python
420
from pyftdi.eeprom import FtdiEeprom
421

422
def factory_reset(device_url):
423
    """Reset EEPROM to factory defaults."""
424
    eeprom = FtdiEeprom()
425
    eeprom.open(device_url)
426
    
427
    # Erase EEPROM
428
    eeprom.erase_eeprom()
429
    
430
    # Set basic configuration
431
    eeprom.set_manufacturer_name("FTDI")
432
    eeprom.set_product_name("FT232R USB UART")  # Device specific
433
    eeprom.set_property('vendor_id', 0x0403)
434
    eeprom.set_property('product_id', 0x6001)   # Device specific
435
    
436
    # Apply changes
437
    eeprom.sync()
438
    eeprom.reset_device()
439
    
440
    eeprom.close()
441
    print("Device reset to factory defaults")
442

443
# Use with caution!
444
# factory_reset('ftdi:///1')
445
```
446

447
## Exception Handling
448

449
```python
450
from pyftdi.eeprom import FtdiEeprom, FtdiEepromError
451
from pyftdi.ftdi import FtdiError
452

453
try:
454
    eeprom = FtdiEeprom()
455
    eeprom.open('ftdi:///1')
456
    
457
    eeprom.set_manufacturer_name("Test Company")
458
    eeprom.sync()
459
    
460
except FtdiEepromError as e:
461
    print(f"EEPROM operation error: {e}")
462
except FtdiError as e:
463
    print(f"FTDI device error: {e}")
464
finally:
465
    if 'eeprom' in locals():
466
        eeprom.close()
467
```
468

469
## Types
470

471
```python { .api }
472
# Exception types
473
class FtdiEepromError(FtdiError):
474
    """EEPROM access error"""
475

476
# CBUS function constants
477
CBUS_FUNCTIONS = {
478
    'tristate': 0,
479
    'rxled': 1,
480
    'txled': 2, 
481
    'txrxled': 3,
482
    'pwren': 4,
483
    'sleep': 5,
484
    'drive0': 6,
485
    'drive1': 7,
486
    'iomode': 8,
487
    'bitbang_wr': 9,
488
    'bitbang_rd': 10
489
}
490

491
# Channel type constants
492
CHANNEL_TYPES = {
493
    'uart': 0,
494
    'fifo': 1,
495
    'cpu_fifo': 2,
496
    'opto': 3,
497
    'fpi': 4
498
}
499
```