BLADERF-CLI(1)

NAME
bladeRF-cli - command line interface and test utility

SYNOPSIS
bladeRF-cli <options>

DESCRIPTION
The bladeRF-cli utility is used to flash firmware files, load FPGA bitstreams, and perform other tasks on the nuand bladeRF software-defined radio system.

For more information on obtaining or building firmware files and FPGA bitstreams, please visit http://nuand.com/.

bladeRF command line interface and test utility (0.9.0-0.9.0.15.8ba2499)

OPTIONS

-d, --device <device>
    Use the specified bladeRF device.

-f, --flash-firmware <file>
    Flash specified firmware file.

-l, --load-fpga <file>
    Load specified FPGA bitstream.

-L, --flash-fpga <file>
    Flash the specified FPGA image for autoload.

-p, --probe
    Probe for devices, print results, then exit.

-s, --script <file>
    Run provided script.

-i, --interactive
    Enter interactive mode.

--lib-version
    Print libbladeRF version and exit.

-v, --verbosity <level>
    Set the libbladeRF verbosity level. Levels, listed in increasing verbosity, are:

    critical, error, warning, info, debug, verbose

--version
    Print CLI version and exit.

-h, --help
    Show this help text.

  Notes:

    The -d option takes a device specifier string. See the bladerf_open() documentation for more information about the format of this string.

    If the -d parameter is not provided, the first available device will be used for the provided command, or will be opened prior to entering interactive mode.

EXAMPLES

$ bladeRF-cli -l hostedx40.rbf

    Loads an FPGA image named hostedx40.rbf onto the bladeRF's FPGA.

    Note: The FPGA image loaded with --load-fpga will be lost on power-off.

$ bladeRF-cli -f firmware.img

    Flashes firmware.img onto the bladeRF's firmware.

$ bladeRF-cli -L hostedx40.rbf

    Flashes the FPGA image named hostedx40.rbf onto the bladeRF, where it will
    be automatically loaded on power-up.

INTERACTIVE COMMANDS
bladeRF-cli supports a scriptable interactive mode. Run bladeRF-cli --interactive to enter this mode. Type "help" for a listing of all commands, or "help <command>" for more information about <command>.

The available commands are:

calibrate - Calibrate transceiver

    Syntax: calibrate [<module>]

    Calibrate the DC offset for both RX and TX

    Available modules for calibration:

        tuning
        txlpf
        rxlpf
        rxvga2

    Leave blank to calibrate all of the above.

clear - Clear the screen

    Syntax: clear

    Clears the screen

echo - Echo each argument on a new line

    Syntax: echo [arg 1] [arg 2] ... [arg n]

    Echo each argument on a new line.

erase - Erase specified sectors of SPI flash

    Syntax: erase <offset> <count>

    Erase specified sectors of SPI flash

        <offset> Starting sector to erase
        <count> Number of sectors to erase

flash_backup - Back up flash data to a file with metadata.

    Syntax: flash_backup <file> (<type> | <address> <length>)

    Back up flash data to the specified file. This command takes either two or four arguments. The two-argument invocation is generally recommended for non-development use.

    Parameters:
       <type> Type of backup. This selects the appropriate address and length
                   values based upon the selected type. Valid values are:
                       cal - Calibration data
                       fw - Firmware
                       fpga40 - Metadata and bitstream for a 40 kLE FPGA
                       fpga115 - Metadata and bitstream for a 115 kLE FPGA

       <address> Address of data to back up.
       <len> Length of region to back up.

    Note: When an address and length are provided, the image type will default to "raw".

    Examples:
      flash_backup cal.bin cal Back up the calibration data region.
      flash_backup cal_raw.bin 0x30000 0x100 Back up the calibration region as
                            a raw data image.

flash_image - Print a flash image's metadata or create a new flash image

    Syntax: flash_image <image> [output options]

    Print a flash image's metadata or create a new flash image. When provided with the name of a flash image file as the only argument, this command will print the metadata contents of the image.

    The following options may be used to create a new flash image.
        data=<file> File to containing data to store in the image.
        address=<addr> Flash address. Default depends upon 'type' parameter.
        type=<type> Type of flash image. Defaults to "raw".
                         Valid options are:
                           cal - Calibration data
                           fw - Firmware
                           fpga40 - Metadata and bitstream for 40 kLE FPGA
                           fpga115 - Metadata and bitstream for 115 kLE FPGA
                           raw - Raw data. The address and length parameters
                            must be provided if this type is selected.
        serial=<serial> Serial # to store in image. Defaults to zeros.

flash_init_cal - Write new calibration data to a device or to a file

    Syntax: flash_init_cal <fpga_size> <vctcxo_trim> [output file]

    Create and write a new calibration data region to the currently opened device, or to a file. Be sure to back up calibration data prior to running this command.
     (See the `flash_backup` command.)

       <fpga_size> Either 40 or 115, depending on the device model.
       <vctcxo_trim> VCTCXO/DAC trim value (0x0-0xffff)
       [output file] File to write calibration data to. When this argument
                         is provided, no data will be written to the device's flash.

flash_restore - Restore flash data from a file

    Syntax: flash_restore <file> [<address> <length>]

    Restore flash data from a file, optionally overriding values in the image metadata.

       <address> Defaults to the address specified in the provided flash image file.
       <length> Defaults to length of the data in the provided image file.

help - Provide information about specified command

    Syntax: help [<command>]

    Provides extended help, like this, on any command.

info - Print information about the currently opened device

    Syntax: info

    Prints the following information about an opened device:
      Serial number
      VCTCXO DAC calibration value
      FPGA size
      Whether or not the FPGA is loaded
      USB bus, address, and speed
      Backend (libusb or kernel module)
      Instance number

jump_to_boot - Jump to FX3 bootloader

    Syntax: jump_to_boot

    Jumps to the FX3 bootloader.

load - Load FPGA or FX3

    Syntax: load <fpga|fx3> <filename>

    Load an FPGA bitstream or program the FX3's SPI flash.

mimo - Modify device MIMO operation

    Syntax: mimo [master | slave]

    Modify device MIMO operation

open - Open a bladeRF device

    Syntax: open [device identifiers]

    Open the specified device for use with successive commands. Any previously opened device will be closed. See the bladerf_open() documentation for the device specifier format.

peek - Peek a memory location

    Syntax: peek <dac|lms|si> <address> [num addresses]

    The peek command can read any of the devices hanging off the FPGA which includes the LMS6002D transceiver, VCTCXO trim DAC or the Si5338 clock generator chip.

    If num_addresses is supplied, the address is incremented by 1 and another peek is performed.

        Valid Address Ranges
        --------------------
        dac 0 255
        lms 0 127
        si 0 255

    Example:
      peek si ...

poke - Poke a memory location

    Syntax: poke <dac|lms|si> <address> <data>

    The poke command can write any of the devices hanging off the FPGA which includes the LMS6002D transceiver, VCTCXO trim DAC or the Si5338 clock generator chip.

    If num_addresses is supplied, the address is incremented by 1 and another poke is performed.

        Valid Address Ranges
        --------------------
        dac 0 255
        lms 0 127
        si 0 255

    Example:
      poke lms ...

print - Print information about the device

    Syntax: print <param>

    The print command takes a parameter to print. The parameter is one of:

       bandwidth Bandwidth settings
       config Overview of everything
       frequency Frequency settings
       lmsregs LMS6002D register dump
       loopback Loopback settings
       mimo MIMO settings
       pa PA settings
       pps PPS settings
       refclk Reference clock settings
       rxvga1 Gain setting of RXVGA1 (range: TODO)
       rxvga2 Gain setting of RXVGA2 in dB (range: TODO)
       samplerate Samplerate settings
       trimdac VCTCXO Trim DAC settings
       txvga1 Gain setting of TXVGA1 in dB (range: TODO)
       txvga2 Gain setting of TXVGA2 in dB (range: TODO)

probe - List attached bladeRF devices

    Syntax: probe

    Search for attached bladeRF device and print a list of results.

quit - Exit the CLI

    Syntax: quit

    Exit the CLI

recover - Load firmware when operating in FX3 bootloader mode

    Syntax: recover [<bus> <address> <firmware file>]

    Load firmware onto a device running in bootloader mode, or list all devices currently in bootloader mode.

    With no arguments, this command lists the USB bus and address for FX3-based devices running in bootloader mode.

    When provided a bus, address, and path to a firmware file, the specified device will be loaded with and begin executing the provided firmware.

    In most cases, after successfully loading firmware into the device's RAM, users should open the device with the "open" command, and write the firmware to flash via "load fx3 <firmware file>"

run - Run a script

    Syntax: run <script>

    Run the provided script.

rx - Receive IQ samples

    Syntax: rx <start | stop | wait | config [param=val [param=val [...]]>

    Receive IQ samples and write them to the specified file. Reception is controlled and configured by one of the following:

        start Start receiving samples
        stop Stop Receiving samples
        wait Wait for sample transmission to complete, or until a specified
                      amount of time elapses
        config Configure sample reception. If no parameters
                      are provided, the current parameters are printed.

    Running 'rx' without any additional commands is valid shorthand for 'rx config'.

    The wait command takes an optional timeout parameter. This parameter defaults to units of ms. The timeout unit may be specified using the ms, s, m, or h suffixes. If this parameter is not provided, the command will wait until the reception completes or Ctrl-C is pressed.

    Configuration parameters take the form 'param=value', and may be specified in a single or multiple 'rx config' invocations. Below is a list of available parameters.

        n Number of samples to receive. 0 = inf.

        file Filename to write received samples to

        format Output file format. One of the following:
                          csv CSV of SC16 Q12 samples
                          bin Raw SC16 Q12 DAC samples

        samples Number of samples per buffer to use in the asynchronous
                      stream. Must be divisible by 1024 and >= 1024.

        buffers Number of sample buffers to use in the asynchronous
                      stream. The min value is 4.

        xfers Number of simultaneous transfers to allow the asynchronous
                      stream to use. This should be < the 'buffers' parameter.

        The n, samples, buffers, and xfers parameters support the suffixes
        'K', 'M', and 'G', which are multiples of 1024.

    Example:
      rx config file=/tmp/some_file format=bin n=10K

    Notes:

      An 'rx stop' followed by an 'rx start' will result in the samples file
      being truncated. If this is not desired, be sure to run 'rx config' to set
      another file before restarting the rx stream.

tx - Transmit IQ samples

    Syntax: tx <start | stop | wait | config [parameters]>

    Read IQ samples from the specified file and transmit them. Transmission is controlled and configured by one of the following:

        start Start transmitting samples
        stop Stop transmitting samples
        wait Wait for sample transmission to complete, or until a specified
                      amount of time elapses
        config Configure sample transmission . If no parameters
                      are provided, the current parameters are printed.

    Running 'tx' without any additional commands is valid shorthand for
     'tx config'.

    The wait command takes an optional timeout parameter. This parameter defaults to units of ms. The timeout unit may be specified using the ms, s, m, or h suffixes. If this parameter is not provided, the command will wait until the transmission completes or Ctrl-C is pressed.

    Configuration parameters take the form 'param=value', and may be specified in a single or multiple 'tx config' invocations. Below is a list of available parameters.

        file Filename to read samples from

        format Output file format. One of the following:
                          csv CSV of SC16 Q12 samples
                          bin Raw SC16 Q12 DAC samples

        repeat The number of times the file contents should be
                      transmitted. 0 implies repeat until stopped.

        delay The number of microseconds to delay between retransmitting
                      file contents. 0 implies no delay.

        samples Number of samples per buffer to use in the asynchronous
                      stream. Must be divisible by 1024 and >= 1024.

        buffers Number of sample buffers to use in the asynchronous
                      stream. The min value is 4.

        xfers Number of simultaneous transfers to allow the asynchronous
                      stream to use. This should be < the 'buffers' parameter.

        The n, samples, buffers, and xfers parameters support the suffixes
        'K', 'M', and 'G', which are multiples of 1024.

    Example:
      tx config file=data.bin format=bin repeat=2 delay=250000

set - Set device settings

    Syntax: set <param> <arguments>

    The set command takes a parameter and an arbitrary number of arguments for that particular command. The parameter is one of:

       bandwidth Bandwidth settings
       config Overview of everything
       frequency Frequency settings
       lmsregs LMS6002D register dump
       loopback Loopback settings
       mimo MIMO settings
       pa PA settings
       pps PPS settings
       refclk Reference clock settings
       rxvga1 Gain setting of RXVGA1 (range: TODO)
       rxvga2 Gain setting of RXVGA2 in dB (range: TODO)
       samplerate Samplerate settings
       trimdac VCTCXO Trim DAC settings
       txvga1 Gain setting of TXVGA1 in dB (range: TODO)
       txvga2 Gain setting of TXVGA2 in dB (range: TODO)

version - Host software and device version information

    Syntax: version

    Prints version information for host software and the current device

AUTHOR
This utility was written by the contributors to the bladeRF Project. See the CONTRIBUTORS file for more information.

REPORTING BUGS
Bugs may be reported via the issue tracker at https://github.com/nuand/bladerf.

COPYRIGHT
Copyright © 2013 Nuand LLC.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

SEE ALSO
bladeRF-flash(1).

More documentation is available at http://nuand.com/ and https://github.com/nuand/bladerf.