Basic Transceiver Control¶

Applications for the AIR-T may be developed using almost any software language, but C/C++ and Python are the primary supported languages. Various Application Programming Interfaces (APIs) are supported by AirStack Core and a few of the most common APIs are described below.

While other APIs are supported, Deepwave recommends leveraging the SoapSDR driver whenever possible.

Hardware Control¶

SoapySDR¶

SoapySDR is the primary API for interfacing with the AIR-T via the built-in SoapyAIRT driver. SoapySDR is an open-source API and run-time library for interfacing with various SDR devices. The AirStack Core environment includes the SoapySDR and the SoapyAIRT driver to enable communication with the radio interfaces using Python or C++. The Python code below provides an operational example of how to receive data from the radio using the SoapyAIRT driver.

Based upon the block diagram in the AirStack Core Application Development Overview section, we present the following Python example using the SoapyAIRT API:

#!/usr/bin/env python3
from SoapySDR import Device, SOAPY_SDR_RX, SOAPY_SDR_CF32
import numpy as np
# Setup
sdr = Device(dict(driver="SoapyAIRT"))           # Instantiate Device Class
sdr.setSampleRate(SOAPY_SDR_RX, 0, 125e6)        # Set sample rate on chan 0
sdr.setGainMode(SOAPY_SDR_RX, 0, True)           # Use AGC on channel 0
sdr.setFrequency(SOAPY_SDR_RX, 0, 2.4e9)         # Set frequency on chan 0
buff = np.empty(16384, np.complex64)             # Create memory buffer
stream = sdr.setupStream(SOAPY_SDR_RX,           # Setup data stream on chan 0
                         SOAPY_SDR_CF32,
                         [0])
# Work
for i in range(10):
    sdr.activateStream(stream)                   # Start streaming samples
    e = sdr.readStream(stream, [buff], 16384)    # Read 16k I/Q samples
    assert e.ret == 16384, f'Error code {e.ret}' # Error Check
    # <Perform Inference or Computation on buff>
    sdr.deactivateStream(stream)                 # Stop streaming samples
# Close
sdr.closeStream(stream)                          # Turn off radio

GNU Radio¶

Device Arguments in GNU Radio¶

Built into AirStack Core are the SoapyAIRT source and sync blocks. Deepwave recommends using these blocks to interact with the AIR_T hardware.

To get started using GNU Radio on the AIR-T, see the GNU Radio on the AIR-T tutorial.

In the figure below, the Soapy AIR-T Source block is shown in GNU Radio. The properties menu displayed is accessed by right-clicking on the Soapy AIR-T Source block. The AIR-T device arguments for the SoapySDR API can be configured via the device arguments dialogue box. In this example, with the SoapyAIRT driver enabled, the rx_path is set to the LNA path, and the clk_src is set to the internal 10MHz frequency reference. Any of the device arguments shown above in Table 1 can be configured in GNU Radio blocks in this way.

Using Device Arguments in GNU Radio

UHD¶

A key feature of SoapySDR is its ability to translate to/from other popular SDR APIs, such as UHD. The SoapyUHD plugin is included with AirStack Core and enables developers to create applications using UHD or execute existing UHD-based applications on the AIR-T. This interface is described in the figure below.

flowchart LR
  %% Define Shapes
  subgraph AIRSTACK[**AirStack Core**]
    direction LR
    A[**SoapyAIRT**<br>Deepwave]
    B[**SoapySDR**<br>3rd Party]
    C[**UHD**<br>3rd Party]
  end

  %% Define Connections
  A <==> B <==> C

UHD Support Overview

If you are interested in using GNU Radio or UHD for your application, please see the associated AirStack Core Application Notes for details regarding compatibility and other important considerations.

AIR-T Specifics: Shared RF Hardware and API Side Effects¶

The AIR-T itself has some unique hardware considerations that are in turn reflected in the software to control it. Namely, certain key hardware components are shared among RF signal chains. As a result, for certain device settings and configurations, care must be exercised when configuring the device as described below.

Center Frequency¶

All current AIR-T models utilize the AD9371 RFIC by Analog Devices. This RFIC shares a common LO for all RX or TX channels. As a result, on the AIR-T, setting the frequency of a channel will also set the frequency of a neighboring channel. For two channel AIR-Ts, this means that there is only one global center frequency setting for the device. That is, changing the frequency of RX1 also changes the frequency of RX2. For AIR-Ts with multiple daughtercards (and therefore multiple RFICs) there is a single frequency setting for each daughtercard. That is, changing the frequency of RX3 will also change the frequency of RX4, but not RX1 or RX2.

RX Gain Settings¶

AGC¶

Similar to center frequency, the AGC setting is shared among all pairs of RX channels. For two channel AIR-Ts, this means that there is a single global AGC setting and that changing whether or not AGC is used also affects the other RX channel. For AIR-Ts with multiple daughtercards, changing the AGC state will only affect the other RX channel on the same daughtercard.

Extra care should be taken when disabling AGC as the device will fall back to whatever manual gain was set previously. If no manual gain was previously set, this value defaults to the maximum possible attenuation available to prevent damage to the RFIC.

Manual Gain¶

If RX manual gain is set, AGC is first disabled. As mentioned in the previous section, this AGC setting is applied to a pair of channels. Therefore, setting the manual gain of a channel will also set a neighboring channel to be in manual gain mode and in turn set the gain of that channel (defaults to maximum attenuation if not previously set).