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 CBus

CBUSH

Alternate features for FT232H/FT2232H/FT4232H devices.

alias of CBusH

CBUSX

Alternate features for FT230X devices.

alias of CBusX

CFG1

Configuration bits stored @ 0x01.

alias of Cfg1

CHANNEL

Alternate port mode.

alias of Channel

DRIVE

Driver options for I/O pins.

alias of Drive

UART_BITS

Inversion flags for FT232R and FT-X devices.

alias of 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.

Returns:

CBUS mask

property cbus_pins: List[int]

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

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.

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.

Returns:

the size in bytes

property device_version: int

Report the version of the FTDI device.

Returns:

the release

dump_config(file=None)

Dump the configuration to a file.

Parameters:

file (Optional[BinaryIO]) – 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]) – 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.

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.

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

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.

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]) – a custom EEPROM size

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

Return type:

None

property properties: Set[str]

Returns the supported properties for the current device.

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]) – 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.

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

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