Skip to content

Getting Started: Verifying Basic Device Operation

Ryan Thompson edited this page Apr 6, 2022 · 22 revisions

This guide shows how to exercise some very basic device operations using the bladeRF-cli program in order to verify that the device is functioning and that the required host software is installed.

This guide shows invocations and prompts from a Linux system. Windows users may simply replace bladeRF-cli invocations with bladeRF-cli.exe and use the same commands.

If you encounter errors, warnings, or unexpected output, be sure to check the Troubleshooting page before continuing in this guide. For additional information, be sure to check out the bladeRF-cli Tips and Tricks wiki page.

Table of Contents

Detecting the bladeRF

First, take a look at bladeRF-cli's command-line options, via bladeRF-cli --help.

Note that the -p option may be used to probe for device. Plug in your device, and run the following command. You should see similar output.

$ bladeRF-cli -p
    Backend:        libusb
    Serial:         f12ce1037830a1b27f3ceeba1f521413
    USB Bus:        4
    USB Address:    8

Querying device information

More information about the attached device can be viewed while running bladeRF-cli in interactive mode, Enter this mode and issue the help command to see a list of available commands.

Use the info command to print information about the device, and version to view version information, most notably, the firmware:

$ bladeRF-cli -i

bladeRF> help

... (Help text shown here ) ...

bladeRF> info

  Serial #:                 f12ce1037830a1b27f3ceeba1f521413                          
  VCTCXO DAC calibration:   0x894e
  FPGA size:                40 KLE
  FPGA loaded:              no
  USB bus:                  2
  USB address:              3
  USB speed:                SuperSpeed
  Backend:                  libusb
  Instance:                 0

bladeRF> version
  bladeRF-cli version:        0.11.0-git-58c3ff4
  libbladeRF version:         0.16.1-git-58c3ff4

  Firmware version:           1.7.1-git-ca697ee
  FPGA version:               Unknown (FPGA not loaded)

Here we see the device's serial number, the VCTCXO DAC calibration value, FPGA information, and USB connection information. Take note of the FPGA size, as this will help determine which FPGA file to load.

Note that this information could have also been gathered using multiple -e <command> argument: bladeRF-cli -e version -e info

Before going further, the devices FPGA must be configured.

Loading the FPGA

FPGA images can be obtained from the Nuand website. If you are using Ubuntu, the bladeRF PPA has bladerf-fpga-hostedx40, bladerf-fpga-hostedx115, bladerf-fpga-hostedxa4, and bladerf-fpga-hostedxa4 packages which will auto-download a recent FPGA image from the Nuand website.

Ensure you download the correct image for your FPGA size.


To load an image from the command line: $ bladeRF-cli -l <path/to/fpga/file>

To load an image while in interactive mode: bladeRF> load fpga <path/to/fpga/file>


After the FPGA loads, you should see LED1, LED2 and LED3 light up. When is in use, LED2 will be blinking.

If you do not want to manually load the FPGA at every power on, see the FPGA Autoloading page.

Adjusting Device Parameters

A number of device parameters can be printed and set via the bladeRF-cli print and set commands, respectively. Run help print and help set for a list of parameters.

Gain

Gain is implemented using one or more gain stages, depending on the model. In libbladeRF 2.0.0 and later, the recommended method is to let the system apportion gain between the various gain stages.

Note that the range of available gain may vary depending on frequency.

RX Gain

An overall RX gain of 60 dB is defined as the maximum.

Note: FPGA v0.7.0 / libbladeRF v1.8.0 and later support automatic gain control, and it is enabled by default. This will automatically adjust the gain to maintain maximum dynamic range and minimum clipping. print agc [channel] will display the current status, and set agc [channel] <on|off> will toggle it on or off.

bladeRF> print gain

  Gain RX1 overall:   60 dB (Range: [-15, 60])
              full:   71 dB (Range: [-4, 71])
  Gain RX2 overall:   60 dB (Range: [-15, 60])
              full:   71 dB (Range: [-4, 71])
  Gain TX1 overall:   56 dB (Range: [-23.75, 66])
               dsa:  -10 dB (Range: [-89.75, 0])
  Gain TX2 overall:   56 dB (Range: [-23.75, 66])
               dsa:  -10 dB (Range: [-89.75, 0])

bladeRF> set gain rx1 42

If you receive an error like Gain on RX1 cannot be changed while AGC is enabled, use set agc off to turn off the automatic gain control:

bladeRF> set gain rx1 42

  Gain on RX1 cannot be changed while AGC is enabled.


  Error: Operation invalid in current state

bladeRF> set agc rx1 off

  RX1 AGC: Disabled  

bladeRF> set gain rx1 42

Note: This change will not be visible until the channel is enabled.
Setting RX1 overall gain to 42 dB
  Gain RX1 overall:   42 dB (Range: [-15, 60])
              full:   53 dB (Range: [-4, 71])

If you receive a note like Note: This change will not be visible until the channel is enabled, note that the new gain value will not appear if you do print gain, but will appear after you start receiving:

bladeRF> set gain rx1 42

Note: This change will not be visible until the channel is enabled.
Setting RX1 overall gain to 42 dB
  Gain RX1 overall:   60 dB (Range: [-15, 60])
              full:   71 dB (Range: [-4, 71])

bladeRF> rx config file=/dev/null n=0
bladeRF> rx start
bladeRF> print gain rx1

  Gain RX1 overall:   42 dB (Range: [-15, 60])
              full:   53 dB (Range: [-4, 71])

On the bladeRF x40/x115, RX gain is implemented using three gain stages: lna, rxvga1, and rxvga2. On the bladeRF xA4/xA9, there is one gain stage, full.

TX Gain

An overall TX gain of 60 dB is defined as approximately 0 dBm output power.

bladeRF> print gain

  Gain RX1 overall:   42 dB (Range: [-15, 60])
              full:   53 dB (Range: [-4, 71])
  Gain RX2 overall:   60 dB (Range: [-15, 60])
              full:   71 dB (Range: [-4, 71])
  Gain TX1 overall:   56 dB (Range: [-23.75, 66])
               dsa:  -10 dB (Range: [-89.75, 0])
  Gain TX2 overall:   56 dB (Range: [-23.75, 66])
               dsa:  -10 dB (Range: [-89.75, 0])

bladeRF> set gain tx1 60

Setting TX1 overall gain to 60 dB
  Gain TX1 overall:   60 dB (Range: [-23.75, 66])
               dsa:   -6 dB (Range: [-89.75, 0])

On the bladeRF x40/x115, TX gain is implemented using two gain stages: txvga1 and txvga2. On the bladeRF xA4/xA9, there is one gain stage, dsa.

Bandwidth

Use the bandwidth parameter to query and adjust the current bandwidth settings. This may be done for both RX and TX modules simultaneously, or on a per-module basis. Note that there are discrete bandwidth settings available. bladeRF-cli prints out the requested bandwidth, and the closest actual setting used.

bladeRF> print bandwidth

  RX Bandwidth:  28000000Hz
  TX Bandwidth:  28000000Hz

bladeRF> set bandwidth 1.5MHz

  Set RX bandwidth - req:  1500000Hz actual:  1500000Hz
  Set TX bandwidth - req:  1500000Hz actual:  1500000Hz

bladeRF> set bandwidth RX 4MHz

  Set RX bandwidth - req:  4000000Hz actual:  5000000Hz

Frequency

Use the frequency parameter to view and changed the frequencies the RX and TX modules are tuned to. Similar to the bandwidth parameter, this may be applied to both the RX and TX modules simultaneously, or just one of them.

bladeRF> print frequency

  RX Frequency: 1000000000Hz
  TX Frequency: 1000000000Hz

bladeRF> set frequency 2.4GHz

  Set RX frequency: 2400000000Hz
  Set TX frequency: 2400000000Hz

bladeRF> set frequency rx 455.55MHz

  Set RX frequency:  455550000Hz

Sample Rate

As you may have guessed by this point, the samplerate parameter controls the RX and TX sample rates. RX and TX may be configured to operate at different sample rates. The units in these commands are samples per second. As sample rates are rounded to achievable rational numbers, the actual value set is printed back.

bladeRF> print samplerate

  RX sample rate: 1000000 0/1
  TX sample rate: 1000000 0/1

bladeRF> set samplerate rx 40M

  Setting RX sample rate - req:  40000000 0/1Hz, actual:  40000000 0/1Hz

Loopback

It's often very handy to be able to internally loopback signals from the TX module back to the RX module, without an external cable and attenuator. (Generally, it's recommended to keep an attenuator on an unconnected TX port, just to be cautious.)

The LMS6002D RFIC (used on the bladeRF x40 and x115) provides internal loopback modes, which loopback the analog signals; this means you will not receive the exact data you transmit. See the Loopback and Bypass Modes section of the LMS6002D Programming and Calibration Guide to understand how each loopback mode is achieved. The LMS-based loopback modes have a bb_ (baseband) or rf_ (Post-mixer RF path) prefixes.

The AD9361 RFIC (used on the bladeRF xA4 and xA9) provides a single loopback mode, rfic_bist, which is an internal digital loopback within the RFIC.

If you want to receive the exact same data that you transmit, use the firmware loopback mode.

Loopback mode: none

bladeRF> set loopback

Usage: set loopback <mode>, where <mode> is one of the following:

  bb_txlpf_rxvga2   Baseband loopback: TXLPF output --> RXVGA2 input
  bb_txlpf_rxlpf    Baseband loopback: TXLPF output --> RXLPF input
  bb_txvga1_rxvga2  Baseband loopback: TXVGA1 output --> RXVGA2 input.
  bb_txvga1_rxlpf   Baseband loopback: TXVGA1 output --> RXLPF input
  rf_lna1           RF loopback: TXMIX --> RXMIX via LNA1 path.
  rf_lna2           RF loopback: TXMIX --> RXMIX via LNA2 path.
  rf_lna3           RF loopback: TXMIX --> RXMIX via LNA3 path.
  firmware          Firmware-based sample loopback.
  none              Loopback disabled - Normal operation.

bladeRF> set loopback rf_lna1
bladeRF> print loopback

Loopback mode: rf_lna1

bladeRF> set loopback none
bladeRF> print loopback

Loopback mode: none

Streaming Samples

Important Notes

  • As with all SDRs, you are responsible for ensuring that you understand and follow local laws and regulations.
    • Do not transmit or receive on bands that you are not licensed to operate on.
    • Ensure you utilize appropriate filters for the bands you operate on.
  • Ensure you're using 50 Ohm loads on the bladeRF RX and TX ports.
    • Do not transmit to the TX port without a proper load!
  • Do not connect the bladeRF TX port directly to the RX port without an attenuator.

Receiving samples

After configuring device parameters, you can receive samples to either to a CSV file or a binary file, using the rx command. Run help rx in the bladeRF-cli program to view information about this command.

Below is a basic example for receiving 10737418240 (10 * 1024 * 1024 * 1024) samples to a CSV file, at a sample rate of 1 Msps. This is a little over 10s of samples, and totals 40MiB.

bladeRF> set samplerate 1M

  Setting RX sample rate - req:   1000000 0/1Hz, actual:   1000000 0/1Hz
  Setting TX sample rate - req:   1000000 0/1Hz, actual:   1000000 0/1Hz

bladeRF> rx config file=samples.csv format=csv n=10M
bladeRF> rx
    State: Idle
    Last error: None
    File: samples.csv
    File format: SC16 Q11, CSV
    # Samples: 10485760
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000
bladeRF> rx start
bladeRF> rx
    State: Running
    Last error: None
    File: samples.csv
    File format: SC16 Q11, CSV
    # Samples: 10485760
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000

bladeRF> rx wait
bladeRF> rx
    State: Idle
    Last error: None
    File: samples.csv
    File format: SC16 Q11, CSV
    # Samples: 10485760
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000

As shown above, with no arguments, rx shows the current state of the RX module. After starting the RX module, samples will be received in the background of the CLI. rx wait may be used to wait until reception is complete (or Ctrl-C is pressed), and then return to the prompt.

When complete, the samples.csv file will contain two columns, the first being I, and the second being Q. These values will be in the range of [-2048 to 2048), which represents [-1.0, 1.0). Note that the upper bound here is exclusive; the max value will be 2047.

At this point, the CSV could be easily be loaded into FreeMat, Octave, MATLAB, or your favorite scripting language for further analysis.

Transmitting samples

Please double check the above Important Notes if you haven't already read them.

Similar to the rx command, the tx command can transmit samples in the background, with the data coming from either CSV or binary files.

Run help tx for usage information for this command. For a CSV file formatted as described in the previous section, you can transmit the contents of the CSV 10 times at 3.25 Msps via the following.

Note that we first place the device into internal loopback here to avoid transmitting on the external TX port in this example.

bladeRF> set loopback rf_lna1
bladeRF> print loopback

Loopback mode: rf_lna1

bladeRF> set samplerate tx 3.25M

  Setting TX sample rate - req:   3250000 0/1Hz, actual:   3250000 0/1Hz

bladeRF> tx config file=samples.csv format=csv repeat=10
bladeRF> tx

    State: Idle
    Last error: None
    File: samples.csv
    File format: SC16 Q11, CSV
    Repetitions: 10
    Repetition delay: none
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000

bladeRF> tx start
    Converted CSV to SC16 Q11 file and switched to converted file.

bladeRF> tx

    State: Running
    Last error: None
    File: bladeRF_samples_from_csv.bin
    File format: SC16 Q11, Binary
    Repetitions: 10
    Repetition delay: none
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000

bladeRF> tx wait
bladeRF> tx

    State: Idle
    Last error: None
    File: bladeRF_samples_from_csv.bin
    File format: SC16 Q11, Binary
    Repetitions: 10
    Repetition delay: none
    # Buffers: 32
    # Samples per buffer: 32768
    # Transfers: 16
    Timeout (ms): 1000

Note the similarity to the rx command -- with no arguments, tx will report the current status, and the tx wait can be used to block until the transmission has finished.

Other notes

In the binary file format, samples are read/stored in the SC16Q11 format -- interleaved, little endian 16-bit I and Q values, sign-extended and in the range of -2048 to 2047.

When using Linux or OSX, if you have bladeRF-cli built with libtecla support, you can tab-complete on filenames, and ~ will be expanded to your home directory: rx config file=~/Desktop/samples.csv format=csv n=10M

Clone this wiki locally