Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Getting Started: Verifying Basic Device Operation
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
First, take a look at bladeRF-cli's command-line options, via
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
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.
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.
FPGA images can be obtained from the Nuand website or from a continuous build of "bleeding edge" images. If you are using Ubuntu, the bladeRF PPA has
bladerf-fpga-hostedx115 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.
A number of device parameters can be printed and set via the bladeRF-cli
set commands, respectively. Run
help print and
help set for a list of parameters.
rxvga2 parameters may be used to view and adjust RX gains:
bladeRF> print lnagain LNA Gain: 6 dB bladeRF> print rxvga1 RXVGA1 Gain: 30dB bladeRF> print rxvga2 RXVGA2 Gain: 3dB bladeRF> set rxvga2 6 bladeRF> print rxvga2 RXVGA2 Gain: 6dB
txvga2 parameters may be used to view and adjust TX gains.
bladeRF> print txvga1 TXVGA1 Gain: -14dB bladeRF> print txvga2 TXVGA2 Gain: 0dB bladeRF> set txvga1 -18 bladeRF> print txvga1 TXVGA1 Gain: -18dB
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 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
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
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 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.
If you want to receive the exact same data that you transmit, use the firmware loopback modes.
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
- 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.
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.
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.
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.
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