# `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