LimeSDR Firmware Management

Democratising Wireless Innovation
Jump to navigation Jump to search

As well as software running on the host PC, the LimeSDR family of software-defined radios has two user-upgradeable pieces of 'soft' ware running directly on its board: these are the firmware and the gateware, the latter defining how the on-board field programmable gate array (FPGA) should operate.

It is important that the firmware and gateware be kept up-to-date, especially when installing a new LimeSDR or upgrading Lime Suite on a system with an existing LimeSDR. Using a LimeSDR with a firmware or gateware version that does not match the version expected by Lime Suite or other controlling software can cause errors or other issues with both transmission and reception, and can in some cases result in the LimeSDR failing to operate at all until its firmware and gateware are both updated.

Updating the Firmware and Gateware

The firmware and gateware files for all supported LimeSDR boards are supplied with the Lime Suite software stack. If you have not yet installed Lime Suite, do so by following the guide at Getting Started with Lime Suite.

The firmware and gateware revisions should match the revisions shipped with Lime Suite; if they do not, Lime Suite will display an error about a version mismatch. Note that this mismatch can occur with firmware and gateware that is older than the version of Lime Suite you are using and that is newer, the latter potentially causing issues if you - for whatever reason - wish to use an older release of Lime Suite with a LimeSDR that has already been updated on a newer Lime Suite installation. In these cases, the term "updating" refers to replacing the existing firmware and gateware on the board with the version supplied with Lime Suite; this can be a newer or older version than is already on the board.

With LimeSuite installed, open your operating system's command line interface - the Terminal in Linux and macOS and Command Prompt or PowerShell in Windows - and, with the LimeSDR connected to your host PC, run the following command:

LimeUtil --update

Note the capital letters in "LimeUtil"; these are required in case-sensitive operating systems.

The update process will take a few minutes to complete, during which time progress information will be printed to the terminal. It is important that the process is allowed to fully complete; during the update process do not close your command line interface window, shut down or suspend your computer, or disconnect any cables connected to the LimeSDR.

Once the process is complete, the LimeSDR will automatically reboot to load the new firmware and gateware. If you are still receiving an error about version mismatches in Lime Suite at this point, disconnect and reconnect the LimeSDR in order to force a refresh.

Obtaining the Latest Firmware and Gateware

The latest firmware and gateware versions are shipped as standard with each new Lime Suite release. Using firmware and gateware images which are not distributed with Lime Suite - for example, by manually downloading the individual files from the GitHub repository - is not advised, as using a newer release of firmware and gateware with an older version of Lime Suite can cause as many problems as using a newer version of Lime Suite with older firmware and gateware.

To upgrade your version of Lime Suite and obtain the latest firmware and gateware files, use your operating system's package manager (where available) or download and install the latest version over the top of your existing version using the instructions on the page Getting Started with Lime Suite.

Recovering from a Bad Update

If the firmware and gateware update process is interrupted, restart it by typing:

LimeUtil --update

This will begin the flash process again, and will overwrite any partial or corrupted flash contents.

Fixing LimeSDR USB FX3 WestBridge Corruption

If using a LimeSDR USB, an interruption in the firmware and gateware update process can result in the FX3 chip, responsible for USB communications, entering 'bootloader' mode; this is not the case for the LimeSDR Mini, which uses a different USB controller. In this mode, the chip will not communicate with the rest of the LimeSDR USB board. The primary symptom of this is that the LimeSDR disappears from the list of connected devices and is replaced with a device named "WestBridge."

The FX3 can be forced into bootloader mode by removing the jumper marked "FX3 BOOT" on the top of the board. If your LimeSDR USB is showing as a WestBridge device, first check that the FX3 BOOT jumper is correctly in place; if it is not, replace it so it is bridging the two pins and reconnect the LimeSDR USB to your host device.

If the FX3 Boot jumper is correctly in place and the LimeSDR USB still shows as a WestBridge device, this indicates corruption in the FX3 firmware. To fix this, first download the latest LimeSDR USB FX3 firmware image. Next, load Lime Suite GUI and use the following steps to flash the firmware:

  1. Load Lime Suite GUI
  2. In Lime Suite GUI, click "Options," then "Connection Settings," choose "WestBridge" from the list, then finally click "Connect".
  3. Click "Modules" then "Programming."
  4. Select "FX3" in the "Device" list, then choose "Firmware to RAM" in the "Programming Mode" list.
  5. Browse to the firmware file you downloaded, making sure to pick the correct file.
  6. Click "Program" and allow the flashing process to complete. The LimeSDR USB will restart.
  7. Return to the "Options" menu, click "Connection Settings, then click "Connect" to re-connect to your LimeSDR USB.
  8. Click "Modules" then "Programming."
  9. Select "Automatic" in the "Device" list and "Automatic Update" in the "Programming Mode" list.
  10. Click "Program" to update the firmware and gateware.

Your LimeSDR USB will now have the correct firmware and gateware files installed.

Next Steps

If you are following these steps in order to set up your new LimeSDR device, continue on to Testing the LimeSDR.