DOCSEARCHbyAlgolia
Submit Docs

bladeRF Source Code and Documentation

repository·master·Indexed 23 days ago

https://github.com/nuand/bladerf

Complete source code for programming and interacting with bladeRF platforms. Includes FPGA HDL, FX3 firmware for the Cypress FX3 USB 3.0 controller, and host-side C libraries and utilities. Provides detailed instructions for building FX3 firmware on Linux and Windows, debugging NIOS II software via GDB and Eclipse, and implementing FPGA reference designs.

Tokens
36.5K
Snippets
78
Records
241
Agent score
75%

What's inside bladeRF

  1. Overview of HDL Reference Designs

    master
    The HDL libraries and projects are provided by Analog Devices Inc. They contain reference designs for FPGA development. Users should be aware of the branching strategy: each release has its own dedicated branch, and the master branch is kept synchronized with the latest release. Branches containing dev in their name are development branches and should be used with caution.

  2. Overview of bladeRF Utilities

    master

    The host/utilities directory contains several standalone applications built on top of libbladeRF. These tools are designed for development, debugging, and specific hardware tasks:

    • bladeRF-cli: A command-line interface used for general development and debugging of bladeRF hardware.
    • bladeRF-fsk: A specialized program for transferring text or files between two bladeRF devices using a custom FSK (Frequency Shift Keying) modem.
    • bladeRF-power: A command-line tool used to measure and output power levels.

  3. Overview of libbladeRF functionality

    master

    The libbladeRF library provides an intuitive interface for interacting with bladeRF hardware and general radio systems. Key capabilities include:

    • Device Management: Opening/closing devices and querying device information.
    • Frequency & Sampling: Tuning to various frequencies and configuring sample rates.
    • RF Chain Configuration: Configuring bandwidth, RF gains, and manipulating board switches for different paths.
    • Data Transfer: Transmitting and receiving complex baseband samples.
    • Maintenance: Updating device firmware and FPGA bitstreams.
    • Debugging: Low-level access to on-board devices for testing and debugging.

  5. bladeRF Source Repository Structure

    master

    The repository is organized into the following functional areas:

    • firmware_common: Source and header files common between firmware and host software.
    • fx3_firmware: Firmware for the Cypress FX3 USB controller.
    • hdl: All HDL code associated with the Altera Cyclone IV FPGA.
    • host: Host-side libraries, drivers, utilities, and samples.

  6. Overview of bladeRF FX3 Firmware Interfaces

    master

    The bladeRF FX3 firmware is compiled for the Cypress FX3 USB 3.0 Superspeed controller. The controller manages three primary interfaces:

    • Cyclone IV FPGA Loader: Responsible for loading or reloading the FPGA over the USB link.
    • RF Link: Transfers baseband IQ samples between the FPGA and the host over the USB link.
    • Control Interface: Uses the built-in UART to communicate with the FPGA. This interface handles general GPIO settings, LMS6002D register accesses, VCTCXO trim DAC settings, and Si5338 clock generator register accesses.

  7. Understand the bladeRF versioning scheme

    master

    The bladeRF project uses two distinct versioning systems: one for individual components and one for the project as a whole.

    Individual Components

    Components follow Semantic Versioning 2.0.0 (major.minor.patch[-extra]). This describes changes to a component's primary interface:

    • Major: Reverse-incompatible changes.
    • Minor: Reverse-compatible additions.
    • Patch: Reverse-compatible bug fixes or internal changes.
    • -extra: Typically includes the git revision.

    Project-wide Version

    The project-wide version is based on the release date using the format YYYY.MM[-rcN].

    • YYYY: Four-digit year.
    • MM: Two-digit month.
    • -rcN: Release-candidate suffix (indicates a beta version).

    Users and package maintainers should primarily focus on the project-wide version rather than individual component versions.

  8. Configure FPGA autoloading for bladeRF

    master

    To avoid manually loading the FPGA bitstream every time the device is powered on, use one of two mechanisms:

    • Host-based autoloading (Recommended): Store the bitstreams in specific locations so libbladeRF can find and load them automatically when opening a device handle. The files should be named hostedx40.rbf or hostedx115.rbf depending on your hardware variant.
    • Flash-based autoloading: Write the FPGA image to the device's SPI flash using the bladeRF-cli program. This allows the FPGA to be autoloaded without a host machine.

  9. Use interactive commands in bladeRF-cli

    master

    Once in interactive mode, you can use several categories of commands:

    • Help: help lists top-level commands; help <cmd> provides details for a specific command.
    • Low-level Register Access: peek and poke for setting/reading registers.
    • System Configuration: set and print for high-level tasks like frequency, bandwidth, sample rate, and gains.
    • Data Transfer: rx and tx for background data transmission and reception.
    • Execution: run <script> to execute a script from within the interactive session.
    • Scripting Control: rx wait or tx wait to ensure data transfers complete before a script exits.

  10. Understand the bladeRF HDL structure

    master

    The HDL repository is organized into two main directories:

    • fpga/: Contains source HDL in the form of IP blocks or platform-specific top levels.
    • quartus/: Contains specific files for Quartus Prime project creation and building.

    Top-Level Design: The project uses a single bladerf.vhd top level to define a VHDL entity called bladerf. This entity defines the pin assignments, IO levels, and directionality for the FPGA.

    Architectures (Revisions): Instead of creating entirely new projects, the build system uses Quartus Prime 'Revisions' to implement different architectures. This allows a base design (top level, part, and pins) to be duplicated and modified for specific use cases. Currently supported architectures include:

    ArchitectureDescription
    hostedListens for commands from the USB connection to perform operations or send/receive RF.
    atsc_txATSC transmitter - Reads 4-bit ATSC symbols via USB and performs pilot insertion, filtering, and baseband shift.

  11. Understand bladeRF NIOS II software and packet formats

    master

    The bladeRF program executes on a NIOS II soft processor within the FPGA. It handles control and configuration requests from the host via the FX3 UART. Requests and responses are transmitted in 16-byte packets. The first byte is a 'magic' value indicating the packet format type.

    Common packet formats include:

    • pkt_8x8 (Magic 0x41): 8-bit address, 8-bit data.
    • pkt_8x16 (Magic 0x42): 8-bit address, 16-bit data.
    • pkt_8x32 (Magic 0x43): 8-bit address, 32-bit data.
    • pkt_8x64 (Magic 0x44): 8-bit address, 64-bit data.
    • pkt_32x32 (Magic 0x4b): 32-bit address, 32-bit data.
    • pkt_retune (Magic 0x54)
    • pkt_legacy (Magic 0x4e)

    Detailed descriptions of these formats are located in the pkt_*.h files in the fpga_common/include directory.