Command-line tool reference¶

Bootloader tool¶

Cypress FX2/FX2LP bootloader tool

This tool can read and write data in three formats:

hex: contiguous hexadecimal dump with non-significant whitespace

bin (.bin extension): contiguous binary

ihex (.ihex, .ihx, .hex extensions): discontiguous Intel HEX records

By default, the format is automatically determined from the file extension, and if reading from standard input or writing to standard output, whether the stream is a terminal (human-readable hexadecimal is used) or not (binary is used).

usage: fx2tool [-h] [-d DEVICE] [-F {hex,bin,ihex,auto}] [-S FILENAME] [-B]
               COMMAND ...

Positional Arguments¶

COMMAND: Possible choices: load, read_ram, write_ram, read_xram, write_xram, read_eeprom, write_eeprom, reenumerate, program, update, dump, uf2, dfu

Named Arguments¶

-d, --device

device VID:PID pair

Default: (1204, 34323)

-F, --format

Possible choices: hex, bin, ihex, auto

data input/output format

Default: “auto”

-S, --stage2

load the specified second stage bootloader before any further action

-B, --bootloader

load the second stage bootloader provided with fx2tool

Default: False

Sub-commands¶

load¶

Loads firmware into on-chip code memory and runs it.

fx2tool load [-h] FIRMWARE

Positional Arguments¶

FIRMWARE: read firmware from the specified file

read_ram¶

Reads data from on-chip code RAM.

“External” RAM means on-chip RAM external to the 8051 core, i.e. RAM where __code or __xdata objects are placed by the toolchain. Internal RAM of the 8051 is not accessible by this tool.

fx2tool read_ram [-h] [-f FILENAME] ADDRESS LENGTH

Positional Arguments¶

ADDRESS: starting address
LENGTH: amount of bytes to read

Named Arguments¶

-f, --file

write data to the specified file

Default: -

write_ram¶

Writes data to on-chip code RAM.

“External” RAM means on-chip RAM external to the 8051 core, i.e. RAM where __code or __xdata objects are placed by the toolchain. Internal RAM of the 8051 is not accessible by this tool.

fx2tool write_ram [-h] [-a ADDRESS] (-f FILENAME | -d DATA)

Named Arguments¶

-a, --offset

starting address

Default: 0

-f, --file

read data from the specified file

-d, --data

hexadecimal bytes to write

read_xram¶

Reads data from RAM using the movx instruction.

“External” RAM means on-chip RAM external to the 8051 core, i.e. RAM where __code or __xdata objects are placed by the toolchain. Internal RAM of the 8051 is not accessible by this tool.

fx2tool read_xram [-h] [-f FILENAME] ADDRESS LENGTH

Positional Arguments¶

ADDRESS: starting address
LENGTH: amount of bytes to read

Named Arguments¶

-f, --file

write data to the specified file

Default: -

write_xram¶

Writes data to RAM using the movx instruction.

“External” RAM means on-chip RAM external to the 8051 core, i.e. RAM where __code or __xdata objects are placed by the toolchain. Internal RAM of the 8051 is not accessible by this tool.

fx2tool write_xram [-h] [-a ADDRESS] (-f FILENAME | -d DATA)

Named Arguments¶

-a, --offset

starting address

Default: 0

-f, --file

read data from the specified file

-d, --data

hexadecimal bytes to write

read_eeprom¶

Reads data from boot EEPROM.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool read_eeprom [-h] [-W WIDTH] [-f FILENAME] ADDRESS LENGTH

Positional Arguments¶

ADDRESS: starting address
LENGTH: amount of bytes to read

Named Arguments¶

-W, --address-width

Possible choices: 1, 2

EEPROM address width in bytes

Default: 2

-f, --file

write data to the specified file

Default: -

write_eeprom¶

Writes data to boot EEPROM.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool write_eeprom [-h] [-W WIDTH] [-a ADDRESS] (-f FILENAME | -d DATA)
                     [-p SIZE]

Named Arguments¶

-W, --address-width

Possible choices: 1, 2

EEPROM address width in bytes

Default: 2

-a, --offset

starting address

Default: 0

-f, --file

read data from the specified file

-d, --data

hexadecimal bytes to write

-p, --page-size

power-of-two EEPROM page size (default: 1)

Default: 1

reenumerate¶

Simulates device disconnection and reconnection.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool reenumerate [-h]

program¶

Writes USB VID, PID, and DID, and if specified, firmware, into boot EEPROM.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool program [-h] [-W WIDTH] [-p SIZE] [-V ID] [-P ID] [-D ID] [-N] [-F]
                [-f FILENAME]

Named Arguments¶

-W, --address-width

Possible choices: 1, 2

EEPROM address width in bytes

Default: 2

-p, --page-size

power-of-two EEPROM page size (default: 1)

Default: 1

-V, --vid

USB vendor ID (default: 04b4)

Default: 1204

-P, --pid

USB product ID (default: 8613)

Default: 34323

-D, --did

USB device ID (default: 0000)

Default: 0

-N, --disconnect

do not automatically enumerate on startup

Default: False

-F, --fast

use 400 kHz clock for loading firmware via I2C

Default: False

-f, --firmware

read firmware from the specified file

update¶

Writes USB VID, PID, DID, boot options, and if specified, firmware, into boot EEPROM, without changing any omitted parameters.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool update [-h] [-W WIDTH] [-p SIZE] [-V ID] [-P ID] [-D ID] [-N] [-E]
               [-F] [-S] [-f FILENAME | -n]

Named Arguments¶

-W, --address-width

Possible choices: 1, 2

EEPROM address width in bytes

Default: 2

-p, --page-size

power-of-two EEPROM page size (default: 1)

Default: 1

-V, --vid

USB vendor ID

-P, --pid

USB product ID

-D, --did

USB device ID

-N, --disconnect

do not automatically enumerate on startup

-E, --no-disconnect

do automatically enumerate on startup

-F, --fast

use 400 kHz clock for loading firmware via I2C

-S, --slow

use 100 kHz clock for loading firmware via I2C

-f, --firmware

read firmware from the specified file

-n, --no-firmware

remove any firmware present

Default: False

dump¶

Reads USB VID, PID, DID, boot options, and if present, firmware, from boot EEPROM.

An appropriate second stage bootloader must be loaded for this command to work, see the –stage2 option. The format of the bootloader firmware file is auto-detected.

fx2tool dump [-h] [-W WIDTH] [-f FILENAME]

Named Arguments¶

-W, --address-width

Possible choices: 1, 2

EEPROM address width in bytes

Default: 2

-f, --firmware

write firmware to the specified file

uf2¶

Assembles USB VID, PID, DID, boot options and firmware into an image that can be flashed into the boot EEPROM using the UF2 firmware update protocol.

fx2tool uf2 [-h] [-V ID] [-P ID] [-D ID] [-N] [-F] FIRMWARE-FILE UF2-FILE

Positional Arguments¶

FIRMWARE-FILE: read firmware from the specified file
UF2-FILE: write UF2 firmware update image to the specified file

Named Arguments¶

-V, --vid

USB vendor ID (default: 04b4)

Default: 1204

-P, --pid

USB product ID (default: 8613)

Default: 34323

-D, --did

USB device ID (default: 0000)

Default: 0

-N, --disconnect

do not automatically enumerate on startup

Default: False

-F, --fast

use 400 kHz clock for loading firmware via I2C

Default: False

dfu¶

Assembles USB VID, PID, DID, boot options and firmware into an image that can be flashed into the boot EEPROM using the standard Device Firmware Update protocol.

fx2tool dfu [-h] [-V ID] [-P ID] [-D ID] [-N] [-F] [--dfu-pid ID]
            FIRMWARE-FILE DFU-FILE

Positional Arguments¶

FIRMWARE-FILE: read firmware from the specified file
DFU-FILE: write DFU image to the specified file

Named Arguments¶

-V, --vid

USB vendor ID (default: 04b4)

Default: 1204

-P, --pid

USB product ID (default: 8613)

Default: 34323

-D, --did

USB device ID (default: 0000)

Default: 0

-N, --disconnect

do not automatically enumerate on startup

Default: False

-F, --fast

use 400 kHz clock for loading firmware via I2C

Default: False

--dfu-pid

DFU mode USB product ID (default: firmware product ID)