Upgrading bladeRF FX3 Firmware
This page describes how to update the firmware on the bladeRF.
Pre-built firmware is hosted on the nuand website. The latest firmware is pointed to by: http://nuand.com/fx3/bladeRF_fw_latest.img. Make note of any library or FPGA version dependencies provided on the FX3 firmware download page.
Below are a few approaches for upgrading the bladeRF firmware. The first method listed here is the easiest method.
However, some firmware versions are incompatible with the current tools. If know or suspect your firmware to be earlier than version 1.5.3 or run into errors while trying to upgrade the firmware, it is recommended that you try the second approach of upgrading via the bootloader.
"Don't Panic!" - Unless you're loading custom firmware that incorrectly configures device pins, it's generally not possible to "brick" the device. If a failure occurs during the firmware update process, you should always be able to recover via the FX3 bootloader.
Before continuing, ensure you've...
- Installed all libraries and utilities, per the Getting Started Guides.
- Downloaded the latest FX3 image. In Linux:
$ wget http://nuand.com/fx3/bladeRF_fw_latest.img
The bladeRF-cli program may be used in Linux, Mac OSX, and Windows (from cmd.exe) to upgrade firmware.
- Write the firmware to the bladeRF's SPI flash using one of the two approaches:
- From the command line:
$ bladeRF-cli -f bladeRF_fw_latest.img
- From within the bladeRF-cli:
bladeRF> load fx3 bladeRF_fw_latest.img
- From the command line:
- When the write operation completes, power-cycle the device.
- The interactive mode command,
versionshould now reflect the new firmware version:
$ bladeRF-cli -i bladeRF> version bladeRF-cli version: 1.2.0 libbladeRF version: 1.4.0 Firmware version: 1.9.1 FPGA version: Unknown (FPGA not loaded)
When running the Windows installer (see the bladeRF Windows Install Guide), an option to upgrade the firmware is provided. Under the hood, this runs the bladeRF-cli as described above.
Thus, it is possible to upgrade firmware by re-running the installer, but using the bladeRF-cli remains the simplest approach.
The bladeRF is configured to fall back to a USB bootloader if valid firmware is not in SPI flash. By placing a jumper across one of the SPI communication pins, it is possible to force the SPI boot to fail and place the device into bootloader mode. From there, one can load and execute bladeRF firmware, and then follow the above procedure to write the firmware to SPI flash.
For bladeRF Classic, short pins 1 and 2 of the J64 header:
For bladeRF2‑micro, short pins 1 and 2 of the J6 header (may not be populated):
- Unplug all bladeRF devices from your machine.
- If you are powering the device(s) from a DC barrel jack, ensure this is disconnected.
- Short across pins 1 and 2 of either J6 or J64 depending on your bladeRF model, shown in the images above.
- This forces the loading of firmware from SPI flash to fail, which results in the device falling back to the USB bootloader.
- Power on the board.
- You should see the bootloader enumerate as
04b4:00f3 Cypress Semiconductor Corp.in dmesg output, or a CypressWestBridgedevice in Device Manager.- Windows Users: Windows will automatically install the CYUSB3 driver for this bootloader. This will work with the Cypress Control Center utility shipped with the FX3 SDK , as shown in this video. To recover the device as shown below, you will need to use Zadig (as you did when following the Getting Started Guide) to associate the VID/PID of the Cypress bootloader with a libusb-driver (libusbK or WinUSB) before continuing on.
- You should see the bootloader enumerate as
-
Remove the jumper or wire that was installed earlier.
- This is very important! If the jumper is not removed, SPI flash writes will not succeed in the following steps.
- From a shell (or cmd.exe), run
bladeRF-cli -i.- You should now be at a bladeRF> prompt, with a message indicating that the bootloader detected via a string like: NOTE: One or more FX3-based devices operating in bootloader mode were detected.
- All of the following commands should be entered in the bladeRF-cli's prompt -- not from your shell.
- Run
recoverwith no arguments- This will get the Bus and Address that you'll need for the next step.
- Run
recover <bus> <addr> <path to firmware>- bus and addr are the values shown as Bus and Address above, and path to firmware is the path to the firmware you want to load.
- This command does not write the firmware to flash; it only loads it into RAM. We will write the firmware to the SPI flash in the next two steps.
- Run
open.- This will attach to the first available bladeRF. Specifically, this will attach to the device that you just booted bladeRF firmware on via the recover command.
- Run
load fx3 <firmware>.- This will will write the firmware to SPI flash.
- Unplug and replug the device.
- A power cycle is required to boot the new firmware.
Below is a bladeRF-cli log that shows example output for the above procedure:
jon@example % bladeRF-cli -i
NOTE: One or more FX3-based devices operating in bootloader mode
were detected. Run 'help recover' to view information about
downloading firmware to the device(s).
No device(s) attached.
bladeRF> help recover
Usage: recover [<bus> <address> <firmware file>]
Load firmware onto a device running in bootloader mode, or list all
devices currently in bootloader mode.
With no arguments, this command lists the USB bus and address for
FX3-based devices running in bootloader mode.
When provided a bus, address, and path to a firmware file, the
specified device will be loaded with and begin executing the provided
firmware.
In most cases, after successfully loading firmware into the device's
RAM, users should open the device with the "open" command, and write
the firmware to flash via "load fx3 <firmware file>"
bladeRF> recover
FX3 bootloader devices:
---------------------------------------------------------
Backend: libusb
Bus: 1
Address: 7
Use 'recover <bus> <addr> <firmware>' to download and boot
firmware to the specified device.
bladeRF> echo "Remember to remove the jumper from J64 before continuing"
Remember to remove the jumper from J64 before continuing
bladeRF> echo "If you forget to remove the jumper, the following 'open' will fail"
If you forget to remove the jumper, the following 'open' will fail
bladeRF> recover 1 7 ~/.config/Nuand/bladeRF/bladeRF_fw_v1.8.0.img
Success! Use "open" to switch to this device.
Note that a "load fx3 <firmware>" is required to write the firmware to flash.
bladeRF> open
bladeRF> info
Serial #: f12ce1037830a1b27f3ceeba1f521413
VCTCXO DAC calibration: 0x9f50
FPGA size: 40 KLE
FPGA loaded: yes
USB bus: 2
USB address: 8
USB speed: SuperSpeed
Backend: libusb
Instance: 0
bladeRF> version
bladeRF-cli version: 1.2.0
libbladeRF version: 1.4.0
Firmware version: 1.8.0
FPGA version: 0.3.1
bladeRF> load fx3 ~/.config/Nuand/bladeRF/bladeRF_fw_v1.8.0.img
Flashing firmware from /home/jon/.config/Nuand/bladeRF/bladeRF_fw_v1.8.0.img...
[INFO @ usb.c:498] Erasing 3 blocks starting at block 0
[INFO @ usb.c:503] Erased block 2
[INFO @ usb.c:511] Done erasing 3 blocks
[INFO @ usb.c:705] Writing 479 pages starting at page 0
[INFO @ usb.c:709] Writing page 478
[INFO @ usb.c:718] Done writing 479 pages
[INFO @ flash.c:110] Verifying 479 pages, starting at page 0
[INFO @ usb.c:603] Reading 479 pages starting at page 0
[INFO @ usb.c:606] Reading page 478
[INFO @ usb.c:617] Done reading 479 pages
Done. Cycle power on the device.
bladeRF> q
jon@example % dmesg
<snip>
[96232.958622] usb 2-1: SerialNumber: f12ce1037830a1b27f3ceeba1f521413
[96235.572759] usb 2-1: reset SuperSpeed USB device number 8 using xhci_hcd
[96235.589353] usb 2-1: LPM exit latency is zeroed, disabling LPM.
[96269.073285] usb 2-1: USB disconnect, device number 8
[96270.697345] usb 2-1: new SuperSpeed USB device number 9 using xhci_hcd
[96270.714153] usb 2-1: LPM exit latency is zeroed, disabling LPM.
[96270.715387] usb 2-1: New USB device found, idVendor=1d50, idProduct=6066
[96270.715395] usb 2-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[96270.715399] usb 2-1: Product: bladeRF
[96270.715402] usb 2-1: Manufacturer: Nuand
[96270.715406] usb 2-1: SerialNumber: f12ce1037830a1b27f3ceeba1f521413
</snip>
jon@example % bladeRF-cli -p
Backend: libusb
Serial: f12ce1037830a1b27f3ceeba1f521413
USB Bus: 2
USB Address: 9
jon@example % bladeRF-cli -i
bladeRF> info
Serial #: f12ce1037830a1b27f3ceeba1f521413
VCTCXO DAC calibration: 0x9f50
FPGA size: 40 KLE
FPGA loaded: yes
USB bus: 2
USB address: 9
USB speed: SuperSpeed
Backend: libusb
Instance: 0
bladeRF> version
bladeRF-cli version: 1.2.0
libbladeRF version: 1.4.0
Firmware version: 1.8.0
FPGA version: 0.3.1
bladeRF> q
jon@example %This video also shows a procedure similar to that outlined above, but using the Cypress Control Center (provided with the FX3 SDK) to load firmware, instead of using the bladeRF-cli.
Note that this Cypress software is only available for Windows.
While newer FX3 images (v2.2.0 and newer) will work on both bladeRF Classic and bladeRF2‑micro, it is possible to flash an older image onto a bladeRF2‑micro. These older firmware versions only know about the bladeRF Classic and simply report a USB device ID of 0x5246 to the host without first checking the underlying hardware. Newer firmware versions perform this check and report either 0x5246 for bladeRF Classic or 0x5250 for bladeRF2‑micro. Host software older than Git hash e5fb3e9 (8/21/2018) will fail to open the device and immediately fall back to the command shell:
$ ./bladeRF-cli -i
[ERROR @ .../bladerf1.c:921] Invalid FPGA size 49.
Failed to open device (first available): An unexpected error occurred
$This can be confirmed using the lsusb command and filtering for vendor ID 0x2cf0. If a bladeRF2‑micro is connected, and 2cf0:5246 shows up, then old firmware was flashed and it needs to be updated.
$ lsusb -d 2cf0:
Bus 002 Device 008: ID 2cf0:5246If the firmware is even older (pre-v2.0.0), it is possible for the vendor ID to be reported as OpenMoko, 0x1d50.
$ lsusb -d 1d50:
Bus 002 Device 008: ID 1d50:6066To correct this, it is recommended to update to the latest host software, which will report a critical warning and allow the user to correct the issue (i.e. flash updated firmware), instead of reporting an error and terminating abruptly.
$ ./bladeRF-cli -i
[CRITICAL @ .../bladerf1.c:889] Device type mismatch! FPGA size 49 is a bladeRF2 characteristic, but the USB PID indicates bladeRF1. Initialization cannot continue.
[INFO @ .../bladerf1.c:892] You must download firmware v2.2.0 or later from https://www.nuand.com/fx3/ and flash it (bladeRF-cli -f /path/to/bladeRF_fw.img) before using this device.
[WARNING @ .../bladerf1.c:904] Skipping further initialization...
bladeRF> quit
$ ./bladeRF-cli -f bladeRF_fw_v2.2.0.img
<snip>
Flashing firmware...
<snip>
Done. A power cycle is required for this to take effect.
$
<power cycle>
$ ./bladeRF-cli -i -l hostedxA4-latest.rbf
Deferring device init until after FPGA load
Loading fpga...
Done.
bladeRF> version
bladeRF-cli version: 1.6.0-git-df07dd94
libbladeRF version: 2.0.0-git-df07dd94
Firmware version: 2.2.0-git-3d38fac2
FPGA version: 0.7.3
bladeRF> quitIf updating the host software is not possible, the only way to correct this is to force the FX3 into bootloader mode and update the firmware using the recovery procedure.