eeprom - EEPROM API

Quickstart

Example: dump the EEPROM content

# Instantiate an EEPROM manager
eeprom = FtdiEeprom()

# Select the FTDI device to access (the interface is mandatory but any
# valid interface for the device fits)
eeprom.open('ftdi://ftdi:2232h/1')

# Show the EEPROM content
eeprom.dump_config()

# Show the raw EEPROM content
from pyftdi.misc import hexdump
print(hexdump(eeprom.data))

Example: update the serial number

# Instantiate an EEPROM manager
eeprom = FtdiEeprom()

# Select the FTDI device to access
eeprom.open('ftdi://ftdi:2232h/1')

# Change the serial number
eeprom.set_serial_number('123456')

# Commit the change to the EEPROM
eeprom.commit(dry_run=False)

Classes

class pyftdi.eeprom.FtdiEeprom

FTDI EEPROM management

CBUS

Alternate features for legacy FT232R devices.

alias of pyftdi.eeprom.CBus

CBUSH

Alternate features for FT232H/FT2232H/FT4232H devices.

alias of pyftdi.eeprom.CBusH

CBUSX

Alternate features for FT230X devices.

alias of pyftdi.eeprom.CBusX

CFG1

Configuration bits stored @ 0x01.

alias of pyftdi.eeprom.Cfg1

CHANNEL

Alternate port mode.

alias of pyftdi.eeprom.Channel

DRIVE

Driver options for I/O pins.

alias of pyftdi.eeprom.Drive

UART_BITS

Inversion flags for FT232R and FT-X devices.

alias of pyftdi.eeprom.UartBits

VAR_STRINGS = ('manufacturer', 'product', 'serial')

EEPROM strings with variable length.

property cbus_mask: int

Return the bitmask of CBUS pins configured as GPIO.

The bitmap contains four bits, ordered in natural order.

Return type

int

Returns

CBUS mask

property cbus_pins: List[int]

Return the list of CBUS pins configured as GPIO, if any

Return type

List[int]

Returns

list of CBUS pins

close()

Close the current connection to the FTDI USB device,

Return type

None

commit(dry_run=True, no_crc=False)

Commit any changes to the EEPROM.

Parameters
  • dry_run (bool) – log what should be written, do not actually change the EEPROM content

  • no_crc (bool) – do not compute EEPROM CRC. This should only be used to perform a full erasure of the EEPROM, as an attempt to recover from a corrupted config.

Return type

bool

Returns

True if some changes have been committed to the EEPROM

connect(ftdi, ignore=False)

Connect a FTDI EEPROM to an existing Ftdi instance.

Parameters
  • ftdi (Ftdi) – the Ftdi instance to use

  • ignore (bool) – whether to ignore existing content

Return type

None

property data: bytes

Returns the content of the EEPROM.

Return type

bytes

Returns

the content as bytes.

property default_size: int

Report the default EEPROM size based on the FTDI type.

The physical EEPROM size may be greater or lower, depending on the actual connected EEPROM device.

Return type

int

Returns

the size in bytes

property device_version: int

Report the version of the FTDI device.

Return type

int

Returns

the release

dump_config(file=None)

Dump the configuration to a file.

Parameters

file (Optional[BinaryIO, None]) – the output file, default to stdout

Return type

None

enable_mirroring(enable)

Enable EEPROM write mirroring. When enabled, this divides the EEPROM into 2 sectors and mirrors configuration data between them.

For example on a 256 byte EEPROM, two 128 byte ‘sectors’ will be used to store identical data. Configuration properties/strings will be writen to both of these sectors. For some devices (like the 4232H), this makes the PyFtdi EEPROM functionally similar to FT_PROG.

Note: Data will only be mirrored if the has_mirroring property returns true (after establishing a connection to the ftdi)

Parameters

enable (bool) – enable or disable EEPROM mirroring

Return type

None

erase(erase_byte=255)

Erase the whole EEPROM.

Parameters

erase_byte (Optional[int, None]) – Optional erase byte to use. Default to 0xFF

Return type

None

property has_mirroring: bool

Report whether the device supports EEPROM content duplication across its two sectors.

Return type

bool

Returns

True if the device support mirorring

initialize()

Initialize the EEPROM with some default sensible values.

Return type

None

property is_empty: bool

Reports whether the EEPROM has been erased, or no EEPROM is connected to the FTDI EEPROM port.

Return type

bool

Returns

True if no content is detected

property is_mirroring_enabled: bool

Check if EEPROM mirroring is currently enabled for this EEPROM. See enable_mirroring for more details on EEPROM mirroring functionality

Return type

bool

load_config(file, section=None)

Load the EEPROM content from an INI stream.

The section argument selects which section(s) to load:

  • raw only loads the raw data (hexabytes) from a previous dump

  • values only loads the values section, that is the human readable configuration.

  • all, which is the default section selection, load the raw section, then overwrite part of it with any configuration value from the values section. This provides a handy way to use an existing dump from a valid EEPROM content, while customizing some parameters, such as the serial number.

Parameters

file (TextIO) – input stream

Paran section

which section to load from the ini file

Return type

None

property mirror_sector: int

Report start address of the mirror sector in the EEPROM. This is only valid if the FTDI is capable of mirroring EEPROM data.

Return type

int

Returns

the start address

open(device, ignore=False, size=None, model=None)

Open a new connection to the FTDI USB device.

Parameters
  • device (Union[str, Device]) – the device URL or a USB device instance.

  • ignore (bool) – whether to ignore existing content

  • size (Optional[int, None]) – a custom EEPROM size

  • model (Optional[str, None]) – the EEPROM model used to specify a custom size

Return type

None

property properties: Set[str]

Returns the supported properties for the current device.

Return type

Set[str]

Returns

the supported properies.

reset_device()

Execute a USB device reset.

save_config(file)

Save the EEPROM content as an INI stream.

Parameters

file (TextIO) – output stream

Return type

None

set_manufacturer_name(manufacturer)

Define a new manufacturer string.

Return type

None

set_product_name(product)

Define a new product name.

Return type

None

set_property(name, value, out=None)

Change the value of a stored property.

See

properties() for a list of valid property names. Note that for now, only a small subset of properties can be changed.

Parameters
  • name (str) – the property to change

  • value (Union[str, int, bool]) – the new value (supported values depend on property)

  • out (Optional[TextIO, None]) – optional output stream to report hints

Return type

None

set_serial_number(serial)

Define a new serial number.

Return type

None

property size: int

Report the EEPROM size.

Use the most common (default) EEPROM size of the size is not yet known.

Return type

int

Returns

the size in bytes

property storage_size: int

Report the number of EEPROM bytes that can be used for configuration storage. The physical EEPROM size may be greater

Return type

int

Returns

the number of bytes in the eeprom that will be used for configuration storage

sync()

Force re-evaluation of configuration after some changes.

This API is not useful for regular usage, but might help for testing when the EEPROM does not go through a full save/load cycle

Return type

None

Exceptions

exception pyftdi.eeprom.FtdiEepromError

FTDI EEPROM error.

Tests

# optional: specify an alternative FTDI device
export FTDI_DEVICE=ftdi://ftdi:2232h/1
PYTHONPATH=. python3 pyftdi/tests/eeprom.py