# bladeRF source, build structure, and first USB device check

> Nuand/bladeRF contains firmware, FPGA HDL, host libraries, drivers, utilities, and samples for a bladeRF USB 3.0 software-defined radio. It suits engineers who need access to the full stack, but setup spans separate hardware images, host tools, and a physical USB-connected board.

**Nuand/bladeRF** — bladeRF USB 3.0 Superspeed Software Defined Radio Source Code

- Repository: https://github.com/Nuand/bladeRF
- Website: http://nuand.com
- Stars: 1,379 · Forks: 514
- Language: C
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nuand-bladerf

## What Nuand/bladeRF actually contains

Nuand/bladeRF is for programmers who need to program and interact with a bladeRF platform. The repository covers several device layers rather than providing a single host application. It includes firmware for the Cypress FX3 USB controller, HDL for the Altera Cyclone IV FPGA, and C code for host-side libraries, drivers, utilities, and samples. A checkout therefore exposes both computer-side software and the source associated with the board's controller and programmable logic.

The directory structure makes the boundaries visible. `firmware_common` contains source and header files shared between firmware and host software. `fx3_firmware` contains the Cypress FX3 firmware. The `hdl` directory holds HDL associated with the Cyclone IV FPGA, while `host` contains the host-side libraries, drivers, utilities, and samples. That division is useful to an engineer deciding which component needs inspection or modification, but it also means that a successful host build is not the same event as building every hardware component.

The quick start also separates source retrieval from hardware-image acquisition. It tells users to clone the repository, fetch a pre-built FPGA image, fetch a pre-built FX3 firmware image, and then follow the `host` instructions for `libbladeRF` and `bladeRF-cli`. This is a source distribution for a specific hardware platform. It is a better fit for developers who understand the boundary among USB-controller firmware, FPGA design, and host software than for someone expecting a download-and-run application.

## How bladeRF divides device and host responsibilities

The documented architecture assigns distinct responsibilities to the FX3 controller, the FPGA, and the computer. The Cypress FX3 runs firmware stored under `fx3_firmware`, with shared definitions and code under `firmware_common`. The Cyclone IV has its HDL under `hdl`. The computer-side library, drivers, utilities, and samples are under `host`, with `bladeRF-cli` serving as the documented command-line entry point.

The README does not describe the low-level transfer protocol, register map, synchronization model, or sample-processing pipeline, so those details cannot be inferred from the repository outline. It does establish the practical control sequence. After installation and connection, `bladeRF-cli -p` lists devices. After a board is detected, `bladeRF-cli -e info -e version` returns device information. If those results indicate that firmware needs updating, the documented path is `bladeRF-cli -f <firmware_file>`.

The FPGA image is a separate concern from host compilation. The quick start directs users to obtain the latest pre-built FPGA image and consult `hdl/README.md` for that process. It separately directs users to obtain the latest pre-built firmware image and consult `fx3_firmware/README.md`. The README also points to the `bladeRF-cli` overview for loading an FPGA image and using the command-line interface, but the loading command itself is not shown in the repository overview provided here.

Recovery forms another defined path. According to the README, unplugging the device in the middle of a firmware upgrade can leave it booting into the FX3 bootloader. For that state, the quick start refers users to the `recovery` command in `bladeRF-cli` rather than treating the issue as ordinary device enumeration.

## Cloning bladeRF and obtaining hardware images

The first command in the README clones the default repository into a local directory:

```bash
git clone https://github.com/Nuand/bladeRF.git
```

Cloning only retrieves the source tree. The next documented steps require the latest pre-built bladeRF FPGA image and the latest pre-built bladeRF firmware image. The README points to the Nuand FPGA download page and the `hdl/README.md` file for the FPGA image. It also points to the Nuand firmware download page and `fx3_firmware/README.md` for the firmware image.

This separation is an important operational constraint. Source checkout, host-library compilation, image acquisition, and board programming are distinct stages. The repository overview does not say that cloning automatically checks out an image, selects a compatible image, or flashes either binary. A user should follow the relevant component README rather than assume that a successful `git clone` completes hardware setup.

The repository also contains a `doc` directory and a separate `bladeRF` wiki link, but the quick start does not make either an automatic part of installation. Their presence in the repository structure is not enough to infer that they contain platform-specific commands beyond the documented flow. The README's sequence should be treated as the known path: clone, fetch both images, build the host components, attach the board, and detect it with `bladeRF-cli`.

## Building host tools with the top-level switches

The top-level `CMakeLists.txt` offers two global switches. `ENABLE_FX3_BUILD` controls whether the FX3 firmware is built and defaults to `OFF`. `ENABLE_HOST_BUILD` controls the host library and utilities and defaults to `ON`. This default favors getting `libbladeRF` and `bladeRF-cli` built first, while leaving USB-controller firmware out of the normal host build unless it is explicitly selected.

The README does not provide the complete host prerequisite list or a copyable configuration and installation command in its overview. Instead, it directs users to the `host` directory for the build and installation instructions. That is the correct source for platform-specific dependencies and commands. The repository also exposes subdirectory-specific options, but the overview does not enumerate them, so inventing a build invocation would risk selecting the wrong toolchain or installing into an incorrect location.

The `ENABLE_FX3_BUILD` switch does not collapse firmware into the host workflow. Enabling it adds a separate firmware build target, and the quick start still requires a firmware image for board programming. Similarly, the presence of FPGA HDL under `hdl` does not mean the quick start rebuilds it. Users wanting to reproduce the documented starting point should first follow `host/README.md` and treat firmware or FPGA changes as separate component work unless the component-specific documentation says otherwise.

## First bladeRF-cli device detection and firmware check

Connect the board to its fastest USB port after following the host installation instructions. The first real verification in the README is enumeration with `bladeRF-cli -p`:

```bash
bladeRF-cli -p
```

The expected result is that the attached bladeRF device appears in the list output. If it does not appear, the repository overview does not document separate driver, permission, cable, or operating-system troubleshooting steps. Those checks would need to come from the `host` documentation or the project wiki.

Once enumeration succeeds, query additional device and version information:

```bash
bladeRF-cli -e info -e version
```

The README specifically says to review any warning that indicates a firmware update is needed. If that condition appears, the documented command is:

```bash
bladeRF-cli -f <firmware_file>
```

The firmware file must come from the firmware-image process described in the quick start. Do not remove USB power during this operation. The README identifies interruption during a firmware upgrade as one route into the FX3 bootloader. It then directs users to the `recovery` command documentation for restoring a usable recovery path, rather than providing an ordinary firmware-flash sequence for that special state.

After detection and version checks, the README points to the `bladeRF-cli` overview for FPGA loading and further interface use. The top-level instructions do not include that command or document rollback, so neither should be added to a setup procedure without consulting the component-specific documentation.

## bladeRF maintenance, licensing, and upgrade costs

The repository is not archived, and its last push was on 2026-10-02. Recent releases include `2025.10` on 2025-10-06, `2025.05-rc2` on 2025-05-20, and `2024.05` on 2024-05-24. Those facts show recent repository and release activity, but they do not establish that the host library, FX3 firmware, FPGA HDL, and image downloads all follow the same schedule or compatibility policy.

Upgrade cost depends on the component being changed. Work within `host` affects libraries, drivers, utilities, and samples. Controller work enters `fx3_firmware`, with shared interfaces potentially involving `firmware_common`. FPGA changes enter `hdl`. The quick start handles the firmware image and FPGA image separately, and the `ENABLE_FX3_BUILD` option only determines whether firmware compilation is part of a source build. It does not establish image compatibility for the board.

GitHub classifies the license as `Other`, referring users to `LICENSE`. The repository also contains `COPYING` and a `legal` directory. The top-level README does not reproduce the license terms, so it would be inaccurate to call the project permissive or copyleft without reading those files. Engineers planning to redistribute binaries or incorporate components should inspect the terms for every relevant directory before deciding how to use the output.

A practical limitation is that the documented starting point assumes compatible hardware and access to separately published images. The README also does not provide benchmark results, a rollback procedure, or a supported-platform matrix. That does not make the source tree unusable, but it does limit what can be concluded before consulting the component documentation.

## Conclusion

Adopt Nuand/bladeRF when you need command-line interaction with a compatible bladeRF board and can manage the FX3 firmware, FPGA image, USB connection, and host build as separate concerns. Do not choose it as a self-contained radio application installer. Before adoption, check `host/README.md` and the image-specific README files, inspect the custom terms in `LICENSE`, `COPYING`, and `legal/`, then confirm that `bladeRF-cli -p` detects the board without an unresolved firmware warning.

## FAQ

### What does the Nuand/bladeRF repository include?

It includes Cypress FX3 firmware, Altera Cyclone IV FPGA HDL, and C code for host libraries, drivers, utilities, and samples. It also contains shared files used by firmware and host software.

### How do I check whether bladeRF-cli detects a bladeRF board?

Connect the board to the fastest USB port and run `bladeRF-cli -p`. The README says the attached device should then appear in the list output.

### What should I do if bladeRF reports that a firmware update is needed?

Run `bladeRF-cli -f <firmware_file>` with the appropriate firmware file. The README warns that unplugging the device during this operation can leave it booting into the FX3 bootloader, for which it points to the `recovery` command documentation.

### Does cloning Nuand/bladeRF also install the FPGA and FX3 firmware images?

The quick start separately directs users to fetch pre-built FPGA and firmware images, consult their respective README files, and build the host tools. It does not describe cloning as an image-installation step.

## Sources

- [Issues](https://github.com/Nuand/bladeRF/issues)
- [Nuand/bladeRF on GitHub](https://github.com/Nuand/bladeRF)
- [Project website](http://nuand.com)
- [README](https://github.com/Nuand/bladeRF/blob/master/README.md)
- [Releases](https://github.com/Nuand/bladeRF/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nuand-bladerf