Skip to content
Snippets Groups Projects

Changes

Page history
  • New page
  • Templates
    • added navigation and updated bladeRF documentation authored by Glenn Bradford's avatar Glenn Bradford
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 171 additions and 33 deletions
    bladerf.md
    View page @ f16c5047
    # Nuand bladeRF 2.0 micro
    The bladeRF 2.0 micro is the second generation of highly capable SDRs produced
    by Nuand, LLC. The key component on the board is an Analog Devices AD9361
    wideband transceiver which is also found in many other common SDRs (Ettus USRP
    B series and ADALM-PLUTOs).
    by Nuand, LLC.
    ## Content
    1. [Overview](#overview)
    2. [Command Line Interface](#command-line-interface)
    3. [gr-bladeRF](#gr-bladerf)
    - [Block Configuration](#block-configuration)
    - [Message Port Interface](#message-port-interface)
    - [Stream Tag Interface](#stream-tag-interface)
    4. [libbladeRF](#libbladerf)
    5. [Performance](#performance)
    ## Overview
    The key component on the bladeRF 2.0 board is an Analog Devices AD9361 wideband
    transceiver, an RFIC which is also found in many other common SDRs (Ettus USRP B
    series and ADALM-PLUTOs).
    The following is a list of useful references for understanding and using the
    bladeRF. The bladeRF wiki is the best place to start.
    ......@@ -26,7 +41,17 @@ only in the size of the onboard FPGA.
    | xA5 | 77k |
    | xA9 | 301k |
    ## Command line interface
    > **Important Note:** To avoid violating governmental regulations and damaging
    > the hardware, please acknowledge and adhere to the following guidelines:
    > - Never transmit or receive on any band on which you are not licensed to
    > operate
    > - Always terminate TX and RX ports with a 50 Ohm load (either an antenna or SMA
    > terminator)
    > - Never connect a TX port directly to an RX port without proper attenuation
    > at least 30 dB)
    ## Command Line Interface
    The `bladeRF-cli` command line utility can be used to verify device connectivity
    as well as query and set device parameters. For complete information, see the
    ......@@ -36,8 +61,8 @@ following references.
    - [bladeRF CLI Tips and Tricks](https://github.com/Nuand/bladeRF/wiki/bladeRF-CLI-Tips-and-Tricks)
    For our purposes, we will only use `bladeRF-cli` to verify connectivity and not
    to set device parameters. To ensure the bladeRF is correctly attached, the probe
    command can be used.
    to set device parameters. To ensure the bladeRF is correctly attached, the
    `--probe` or `-p` command can be used.
    ```
    $ bladeRF-cli -p # probe for connected bladeRF devices
    ......@@ -49,15 +74,15 @@ $ bladeRF-cli -p # probe for connected bladeRF devices
    USB Address: 2
    ```
    Additional information can be inspected by first entering the command's
    interactive mode.
    The command line tool also has an interactive mode, which can be a more
    convenient way of querying and configuring the board.
    ```
    $ bladeRF-cli -i # enter interactive mode
    ```
    Within the interactive mode you can check the bladeRF driver, device firmware,
    and FPGA versions currently loaded.
    Within interactive mode you can check the bladeRF driver, device firmware, and
    FPGA versions currently loaded.
    ```
    bladeRF> version
    ......@@ -69,6 +94,7 @@ bladeRF> version
    FPGA version: 0.11.0 (configured by USB)
    ```
    You can also read expanded device information.
    ```
    bladeRF> info
    ......@@ -93,40 +119,152 @@ See `bladeRF --help` for a full list of possible commands.
    To integrate the bladeRF into our GNU Radio applications we will use a version
    of the gr-bladeRF out-of-tree (OOT) module customized for CDC.
    - [gr-bladeRF](TBD)
    - [CDC gr-bladeRF repo](https://gitlab.eng.unimelb.edu.au/elen90089-cdc/gr-bladerf)
    This fork of the [Nuand gr-bladeRF OOT](https://github.com/Nuand/gr-bladeRF)
    adds additional message passing and stream tagging configuration interfaces that
    should be useful in completing the CDC design project. The interface will be
    updated throughout the semester to expose this additional functionality. At
    times you many need to update the version of gr-bladeRF installed on the Ubuntu
    VM. From a terminal:
    ```
    # clone CDC fork of gr-bladeRF
    git clone https://gitlab.eng.unimelb.edu.au/elen90089-cdc/gr-bladerf.git
    cd gr-bladerf
    # checkout elen90089 branch
    git checkout elen90089
    This fork of the Nuand [gr-bladeRF](https://github.com/Nuand/gr-bladeRF) adds
    additional message passing and stream tagging configuration interfaces that should be useful in completing the CDC design project.
    # build gr-bladeRF library
    mkdir build
    cd build
    cmake ..
    make
    # install gr-bladeRF library
    sudo make install
    ```
    ### Block Configuration
    To include the bladeRF in a flowgraph we use either the *bladeRF Sink* or
    *bladeRF Source* blocks.
    ![bladeRF Sink](images/bladerf_sink.png) ![bladeRF Source](images/bladerf_source.png)
    <div align="center">
    These blocks and configuration
    Device parameters (frequency, sample rate, gain, etc.) can be changed during
    runtime by using *QT GUI Widgets*.
    ![bladeRF Sink](images/bladerf_sink.png) ![bladeRF Source](images/bladerf_source.png)
    </div>
    These blocks handle configuring the bladeRF device, starting its operation, and
    transferring samples to and from the device and your GRC flowgraph.
    The following is a list of configurable parameters under the *General*.
    | Parameter | Description |
    | ----------------- | ----------- |
    | metadata | Provide metadata with samples. **Enable metadata to use message and stream tag interfaces.** |
    | device | Device serial id. If 'device' is not specified, the first available device is used. |
    | Num channels | Selects the total number of channels in this multi-device configuration. Required when specifying multiple device arguments. |
    | Verbosity | Sets the filter level for displayed log messages. |
    | Sample Rate (sps) | The sample rate is the number of samples per second produced (source) or consumed (sink) by this block on each channel. |
    | Reference clock | Value of reference clock. **Set to 0 for automatic clock selection.** |
    | Frequency (Hz) | The center frequency is the frequency the RF chain is tuned to. |
    | Bandwidth (Hz) | Set the bandpass filter on the radio frontend. **To use the default (automatic) bandwidth filter setting, this should be zero.** |
    There is a minimal set of block parameters, bolded below, you should configure
    before each use. The *General* tab includes the following parameters.
    | Parameter | Description |
    | --------------------- | ---------------------------------------------------- |
    | metadata | Provide metadata with samples.<br>*Enable metadata to use stream tag interface below.* |
    | device | Device serial id. If 'device' is not specified, the first available device is used. |
    | Num channels | Selects the total number of channels in this multi-device configuration. Required when specifying multiple device arguments. |
    | Verbosity | Sets the filter level for displayed log messages. |
    | **Sample Rate (sps)** | The sample rate is the number of samples per second (sps) produced (source) or consumed (sink) by this block on each channel. |
    | **Reference clock** | Value of reference clock.<br>*Set to 0 for automatic clock selection.* |
    | **Frequency (Hz)** | The center frequency to which the RF chain is tuned. |
    | **Bandwidth (Hz)** | Set the bandpass filter on the radio frontend.<br>*Set to 0 to use the default (automatic) bandwidth filter setting.* |
    The following is a list of configurable parameters under each *Channel N* tab.
    | Parameter | Description |
    | --------- | ----------- |
    | DC Offset Mode | Controls the behavior of hardware DC offset corrrection. Off: Disable correction algorithm (pass through). Manual: Keep last estimated correction when switched from Automatic to Manual. Automatic: Periodicallly find the best solution to compensate for DC offset. |
    | IQ Balance Mode | Controls the behavior of software IQ imbalance corrrection. Off: Disable correction algorithm (pass through). Manual: Keep last estimated correction when switched from Automatic to Manual. Automatic: Periodicallly find the best solution to compensate for image signals.
    | Parameter | Description |
    | --------------- | ---------------------------------------------------------- |
    | DC Offset Mode | Controls the behavior of hardware DC offset corrrection. <br>*Off:* Disable correction algorithm (pass through). <br>*Manual:* Keep last estimated correction when switched from Automatic to Manual. <br>*Automatic:* Periodicallly find the best solution to compensate for DC offset. |
    | IQ Balance Mode | Controls the behavior of software IQ imbalance corrrection. <br>*Off:* Disable correction algorithm (pass through). <br>*Manual:* Keep last estimated correction when switched from Automatic to Manual. <br>*Automatic:* Periodicallly find the best solution to compensate for image signals.
    | AGC | Chooses between the manual (False) and automatic (True) gain mode where appropriate. To allow manual control of RF/IF gain stages, manual gain mode must be configured. |
    | RF Gain | Overall RF gain of the device. |
    | **RF Gain** | Overall RF gain of the device. <br>*Tx range:* [-23.75, 66] dB <br>*Rx range:* [-15, 60] dB |
    Device parameters (frequency, sample rate, gain, etc.) can be changed during
    runtime through the use of *QT GUI Widgets*.
    ### Message Port Interface
    The CDC fork of gr-bladeRF adds a *command* input message port and a
    *status* output message port to *bladeRF Source* and *bladeRF Sink* blocks.
    These ports are intended to simplify the control of the bladeRF from other
    blocks within your GNU Radio flowgraphs. These ports rely on GNU Radio's
    [message passing interface](gnuradio#message-passing).
    A group of commands can be passed to a bladeRF block's *command* port as a GNU
    Radio message, where the message *MUST* be a
    [PMT dictionary](gnuradio#polymorphic-types-pmt).
    The bladeRF block will interpret each key in the dictionary as the parameter to
    set with the corresponding value. An example of creating such a command message
    in Python is shown below.
    ```python
    # create PMT dict of bladeRF commands - set frequency and gain of channel 0
    cmd = pmt.make_dict()
    cmd = pmt.dict_add(cmd, pmt.intern("chan"), pmt.from_long(0))
    cmd = pmt.dict_add(cmd, pmt.intern("freq"), pmt.from_double(2.45e9))
    cmd = pmt.dict_add(cmd, pmt.intern("gain"), pmt.from_double(30))
    ```
    The following table is the list of commands currently supported on this
    interface.
    | Command | Type | Description |
    | --------- | ------ | --------------------------------------------------- |
    | chan | int | Specify which channel commands apply to (0 or 1). |
    | gain | double | Set Tx or Rx RF gain. |
    | freq | double | Set Tx or Rx center frequency. |
    | rate | double | Set Tx or Rx sample rate - applies to all channels. |
    | bandwidth | double | Set Tx or Rx bandwidth - 0 for default bandwidth. |
    | tag | bool | Tag *bladeRF Source* output with current timestamp. |
    > **Note:** The *status* port is a work in progress.
    ### Stream Tag Interface
    > **Note:** The stream tag interface is a work in progress.
    [GNU Radio's stream tags](gnuradio#stream-tags)
    Tags in receive stream.
    | Tag | Type | Description |
    | ------- | ------ | ------------------------- |
    | rx_time | uint64 | FPGA receiver timestamp. |
    | rx_freq | double | Receive center frequency. |
    | rx_rate | double | Receive sample rate. |
    Tags in transmit stream.
    | Tag | Type | Description |
    | ---------- | ------ | ----------- |
    | tx_sob | bool | Sample is start of transmit burst. |
    | tx_eob | bool | Sample is end of transmit burst. |
    | tx_freq | double | Set new transmit center frequency (Hz). |
    | tx_command | dict | Apply multiple commands. See [message port interface](#message-port-interface). |
    ## libbladeRF
    The blocks of gr-bladeRF utilize the API provided by libbladeRF for configuring
    and streaming data to/from bladeRF devices. It is also possible to integrate
    bladeRF devices directly into Python and C/C++ programs without the use of GNU
    Radio.
    - [libbladeRF documentation](https://nuand.com/bladeRF-doc/libbladeRF/v2.2.1/)
    ## Performance
    This section will describe procedures for characterizing performance of the
    bladeRF boards and report typical results.
    Metrics:
    - USB throughput
    - Noise figure/floor
    - Frequency Stability
    - DC offset
    - IQ imbalance