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.
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
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.
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.
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 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.
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.
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.
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
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
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 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
- 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.
At this point, the CSV could be easily be loaded into FreeMat, Octave, MATLAB, or your favorite scripting language for further analysis.
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.
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