FWLoader is the Firmware and Bitstream upload utility of the EZ-USB SDK.


There are two ways of starting FWLoader. Either by executing the bash script FWLoader in the directory java/FWLoader of the SDK package or by calling

java -cp [<path to>]FWLoader.jar FWLoader <options>

where <path to> stands for the directory where FWLoader.jar is installed (e.g. the java directory of the SDK package).

If the bash script is used it has to be installed in the same directory as FWLoader.jar.

At start-up FWLoader scans for compatible devices. By default it searches for devices with ZTEX vendor and product ID. Other device classes can be specified by the options -c (scans for unconfigured EZ-USB devices) and -v (devices with ZTEX firmware but non-standard vendor and prduct ID).

A list of devices can by printed using -p. The device which shall be configured is specified by -d.


There are two kinds of options, ordered ones and global ones. The global options are evaluated first. Ordered options are evaluated after that in the order they appear.

Global options

Option Description
-c Scan for Cypress EZ-USB devices without ZTEX firmware
-v <VID> <PID> Scan for devices with the given Vendor ID and Product ID
-vc Equal to -v 0x4b4 0x8613
-s <sn string> Only scan for devices with that serial number
-d <number> Device index (default: 0, use -p to get a list)
-f Force uploads of firmware and bitstream. This allows to overwrite incompatible firmwares or configured FPGA's
-p Print a list of available devices
-h Prints help

Ordered options

Option Description
-i Print device info
-ru Reset EZ-USB
-uu <firmware file> Upload Firmware to EZ-USB
The following options require an installed ZTEX Firmware (e.g. by -uu <firmware>)
-ii Print device info + capabilities
-if Print FPGA state
-ic Print configuration data and flash info
-il Print log messages of FX3 based FPGA Boards
-re Disable EZ-USB firmware in nonvolatile memory
-ue <firmware file> Upload EZ-USB Firmware to nonvolatile memory
-ss <sn string> Set the serial number, see serial_numbers
-su <VID> <PID> Set the USB ID's in configuration memory, 0 to load ID's defined by firmware
-sp <string> Set the product string in configuration memory, empty string to load firmware default
-sf <number> Select FPGA (default: 0)
-rf Reset FPGA
-uf <bitstream> Upload bitstream to FPGA
-um <bitstream> Upload bitstream to Flash
-rm Reset bitstream in Flash
-bs 0|1|A Bit swapping for bitstreams: 0: disable, 1: enable, A: automatic detection
-ff 0|1 Inform the Default firmware whether the FPGA may access Flash memory. 1: FPGA can access Flash (default on FX2 based boards). 0: FPGA will not access Flash (default on FX3 based boards). Note: Changes take effect after restarting the firmware (-ru).
-fu <offset> <file> Upload user data from file <file> to Flash memory. Start address in bytes relative to user space is given by <offset> and must be a sector boundary.
-fd <offset> <file> <len> Download <len> bytes of user data from flash to file <file>. Start address in bytes relative to user space is given by <offset> and must be a sector boundary.
-uxf <ihx file> Upload Firmware / data to ATxmega Flash
-uxe <ihx file> Upload data to ATxmega EEPROM
-rxf <index> Read ATxmega Fuse
-wxf <index> <bitmask> <value> Write ATxmega Fuse

Serial numbers

In configurations with multiple equal devices serial numbers can be used to identify particular devices. Serial numbers are strings with 10 characters. Shorter strings are filled with zeros, longer strings are truncated and a warning is printed.

Serial numbers should be set either using the API or the FWLoader utility by the -ss option. This option only takes effect if a firmware file is uploaded afterwards (-uu or -ue) or if configuration data space is available.

The default Serial number is `0000000000'. On devices with MAC EEPROM this default value is replaced by a unique MAC number.

The option -s can be used to scan only for devices with a given serial number.


List all devices with ZTEX Firmware and unconfigured EZ-USB devices:

FWLoader -c -p

Print info and capabilities of the first device:

FWLoader -c -ii

Upload firmware to EZ-USB and configure Flash.

FWLoader -c -uu <firmware: ihx file> -uf <bitstream: bit file> 

From the standalone example: (1) Upload firmware to EZ-USB, (2) Upload Firmware to EEPROM and (3) Upload bitstream to FLASH. Step 1 (-uu standalone.ihx) can be omitted if a ZTEX Firmware is already installed.

FWLoader -c -uu standalone.ihx -ue standalone.ihx -um <bitstream> 

Upload firmware to EZ-USB and AVR ATxmega

FWLoader -c -uu <EZ-USB firmware: ihx file> -uxf <XMEGA firmware: ihx file>

(1) Read and print FUSEBYTE4, (2) disable JTAG (by clearing bit 0 of FUSEBYTE 4) and read back FUSEBYTE 4 of a XMEGA

FWLoader -rxf 4 -wxf 4 1 1 -rxf 4

Scan for the device with the serial number `000000123a' and upload the firmware image <ihx file> together with the same serial number.

FWLoader -s 123a -ss 123a -uu <ihx file>
en/software/fwloader.txt · Last modified: 2023/10/30 17:32 by stefan
Recent changes RSS feed Creative Commons License Powered by PHP Debian Driven by DokuWiki
[ZTEX Home] [Imprint] [Privacy policy]