Upgrading bladeRF firmware

alexstjean edited this page Dec 13, 2016 · 27 revisions

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.

Table of Contents

Prerequisites

Before continuing, ensure you've...

  1. Installed all libraries and utilities, per the Getting Started Guides.
  2. Downloaded the latest FX3 image. In Linux:
    $ wget http://nuand.com/fx3/bladeRF_fw_latest.img

Normal upgrade procedure

The bladeRF-cli program may be used in Linux, Mac OSX, and Windows (from cmd.exe) to upgrade firmware.

  1. Write the firmware to the bladeRF's SPI flash using one of the two approaches:
    1. From the command line:
      $ bladeRF-cli -f bladeRF_fw_latest.img
    2. From within the bladeRF-cli:
      bladeRF> load fx3 bladeRF_fw_latest.img
  2. When the write operation completes, power-cycle the device.
  3. The interactive mode command, version should 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)

Using the firmware upgrade included in the Windows installer

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.

Upgrading using the FX3 bootloader

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.

Using the bladeRF-cli

  1. Unplug all bladeRF devices from your machine.
    1. If you are powering the device(s) from a DC barrel jack, ensure this is disconnected.
  2. Connect a jumper on J64, as shown in the above image.
    1. This forces the loading of firmware from SPI flash to fail, which results in the device falling back to the USB bootloader.
  3. Power the board on.
    1. You should see the bootloader enumerate as 04b4:00f3 Cypress Semiconductor Corp. in dmesg output, or a Cypress WestBridge device in Device Manager.
      1. 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.
  4. Remove the jumper on J64.
    1. This is very important, as otherwise the SPI flash writes will not be able to succeed in the following steps.
  5. From a shell (or cmd.exe), run bladeRF-cli -i.
    1. You should now be at a bladeRF> prompt, with a message indicating that the bootloader detected via a string like: [INFO] Found FX3 bootloader device on bus=1 addr=10. This may be a bladeRF.
    2. All of the following commands should be entered in the bladeRF-cli's prompt -- not from your shell.
  6. Run recover <bus> <addr> <path to firmware>
    1. bus and addr are the values shown in your [INFO] message, and path to firmware is the path to the firmware you want to load.
    2. 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.
  7. Run open.
    1. 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.
  8. Run load fx3 <firmware>.
    1. This will will write the firmware to SPI flash.
  9. Unplug and replug the device.
    1. A power cycle is required to boot the new firmware.

Example Log

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 %

Using the Cypress Control Center

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.