FTDI Programming at the Command Line

The Efinity software includes a Python script you can use for programming FTDI modules at the command line.

ftdi_pgm.py [--help] [--mode MODE] [--output_file OUTPUT_FILE] [--url URL] [--aurl AURL] 
    [--xml XML] [--num NUM] [--board_profile BOARD_PROFILE] [--address ADDRESS] 
    [--num_bytes NUM_BYTES] [--burst_size BURST_SIZE] [--jtag_bridge_mode JTAG_BRIDGE_MODE] 
    [--jtag_clock_freq JTAG_CLOCK_FREQ] [--verify_method VERIFY_METHOD]
    [--check_flash_if_supported CHECK_FLASH_IF_SUPPORTED] [--spi_active_freq SPI_ACTIVE_FREQ]
    [--spi_passive_freq SPI_PASSIVE_FREQ] [--list_usb] [input_file]
Table 1. ftdi_pgm.py Positional Arguments
Argument Description
input_file HEX file generated from efx_pgm.
Table 2. ftdi_pgm.py Options
Option (Long) Option (Short) Input Description
--help -h None Show help.
--mode -m passive, active, jtag, jtag_chain, erase_flash, read_flash, jtag_bridge, jtag_bridge_x8 Programming mode.
See the Efinity Programmer User Guide.
In Efinity software versions prior to v2025.1, the jtag_bridge and jtag_bridge_new options were named jtag_bridge_new and jtag_bridge_x8_new, respectively.
1
To use the JTAG bridge modes, you must have already configured the with the JTAG SPI flash loader.
The Efinity software v2023.2 and higher includes pre-built flash loader.bit files in < installation directory>/pgm/fli/<family>. Refer to the JTAG SPI Flash Loader Core User Guide for information on using the legacy flash loader.
--output_file -o Filename Output file used for read_flash mode.
--url -u URL FTDI URL (see Identifying FTDI URLs).
--aurl -a URL Alternative URL (Deprecated).
--xml -x Filename XML file for JTAG programming.
--num -n Number Chip target number for JTAG chain programming.
--board_profile -b Generic Board Profile Using FT232, Digilent JTAG-HS3, FireAnt Development Board, Generic Board Profile Using FT2232H, ISX Programming Cable, Titanium Ti180J484 Dev Board, Titanium Ti180M484 Development Kit, Generic Board Profile Using FT4232, JinChen Programming Cable, TJ180A484S Development Kit, Xyloni Development Board, Generic Board Profile Using FT4234HA Name of the board profile used.
--address N/A Hex number Starting flash address for flash read and write operations.
--num_bytes N/A Number Number of bytes to erase or read. For modes erase and read only.
--burst_size N/A Number Individual read or write burst size in multiples of 256 bytes. For legacy JTAG bridge modes only (jtag_bridge and jtag_bridge_x8).
--jtag_bridge_​mode N/A Erase, write, erase_and_write, read, all, all_no_erase JTAG bridge programming mode.
--jtag_clock_freq N/A Number JTAG clock frequency.
--verify_method N/A None, onchipx1, onchipx2, onchipx4 The method used to verify the downloaded bitstream.
Default: onchipx2 (On-chip hash calculation with SPI x2 mode)
--check_flash_​​​​if_supported N/A Hex string Check if flash is supported using the JEDEC ID hex string (e.g., C84012).
--spi_active_​freq N/A Number Set SPI active frequency.
Default: 6000000 Hz
--spi_passive_​freq N/A Number Set SPI passive frequency.
Default: 3000000 Hz
--list_usb -l None List the available USB target's URL.

Linux Examples

To program in Linux:

  1. Open a terminal and change to the Efinity® installation directory.
  2. Type: source ./bin/setup.sh and press enter.
  3. Use the ftdi_program.py command.

Example: Titanium Ti60 F225 Development Board as the only board attached to your computer:

ftdi_program.py <filename>.bit -m jtag

Example: Titanium Ti60 F225 Development Board with serial number FT5ECP6E when another board with an FTDI chip is connected to your computer:

ftdi_program.py <filename>.bit -m jtag --url ftdi://ftdi:4232h:FT5ECP6E/1 
    --aurl ftdi://ftdi:4232h:FT5ECP6E/1

Example: Xyloni Development Board as the only board attached to your computer:

ftdi_program.py <filename>.bit -m jtag

Example: Trion T120 BGA324 Development Board with serial number FT5ECP6E when another board with an FTDI chip is connected to your computer:

ftdi_program.py <filename>.bit -m jtag --url ftdi://ftdi:2232h:FT5ECP6E/1 
    --aurl ftdi://ftdi:2232h:FT5ECP6E/1

Windows Examples

To program in Windows:

  1. Open a command prompt and change to the Efinity® installation directory.
  2. Type: .\bin\setup.bat and press enter.
  3. Use the ftdi_program.py command.

Example: Titanium Development board as the only board attached to your computer:

%EFINITY_HOME%\bin\python3
%EFINITY_HOME%\pgm\bin\efx_pgm\ftdi_program.py <filename>.bit -m jtag

Example: Titanium Ti60 F225 Development Board with serial number FT5ECP6E when another board with an FTDI chip is connected to your computer:

%EFINITY_HOME%\bin\python3
%EFINITY_HOME%\pgm\bin\efx_pgm\ftdi_program.py <filename>.bit 
    -m jtag --url ftdi://ftdi:4232h:FT5ECP6E/1 --aurl ftdi://ftdi:4232h:FT5ECP6E/1

Example: Xyloni Development Board as the only board attached to your computer:

%EFINITY_HOME%\bin\python3 
%EFINITY_HOME%\pgm\bin\efx_pgm\ftdi_program.py <filename>.bit -m jtag

Example: Trion T120 BGA324 Development Board with serial number FT5ECP6E when another board with an FTDI chip is connected to your computer:

%EFINITY_HOME%\bin\python3 
%EFINITY_HOME%\pgm\bin\efx_pgm\ftdi_program.py <filename>.bit 
    -m jtag --url ftdi://ftdi:2232h:FT5ECP6E/1 --aurl ftdi://ftdi:2232h:FT5ECP6E/1
1 The jtag_bridge_x8 mode is only supported in some Titanium and Topaz FPGAs. Refer to the data sheet for the modes your FPGA supports.