basebandReceiver

Configure SDR as baseband receiver

Since R2022a

Add-On Required: This feature requires the Wireless Testbench™ Support Package for NI™ USRP™ Radios add-on.

Description

Use the basebandReceiver object to configure the specified software-defined radio (SDR) as a baseband receiver to capture raw IQ data from the air.

This diagram shows a conceptual overview of capturing radio signals in Wireless Testbench™ using a radio that you configure with this object. The onboard data buffering ensures contiguous data capture. When you capture more data than the onboard memory buffer size, the data is sent directly to the host computer.

Creation

Syntax

bbrx = basebandReceiver(radio)

bbrx = basebandReceiver(radio,Name=Value)

Description

bbrx = basebandReceiver(radio) creates a baseband receiver configuration object for the specified radio radio.

Note

The object requires exclusive access to radio hardware resources. Before creating this object, clear any existing Wireless Testbench object associated with the specified radio from the workspace.

bbrx = basebandReceiver(radio,Name=Value) sets properties using one or more name-value arguments. For example, CaptureDataType="double" sets the data type of the returned captured data to double.

Input Arguments

radio — Radio setup configuration

string scalar

Radio setup configuration, specified as a string scalar. To create a radio setup configuration, set up your radio and save your radio setup configuration using the Radio Setup wizard. To list all saved radio setup configurations, call the radioConfigurations function.

For a list of supported radios, see Supported Radio Devices.

Example: "MyRadio" indicates that you saved a radio setup configuration under the name MyRadio in the Radio Setup wizard.

Properties

CenterFrequency — Radio center frequency in Hz

2.4e9 (default) | positive numeric scalar | numeric array

Radio center frequency in Hz, specified as one of these options.

• Positive numeric scalar — The object applies this value by scalar expansion to each antenna in the Antennas property.

• Numeric array — The object applies the ith array element value to the ith antenna in the Antennas property.

The valid center frequency range depends on the radio device.

Radio Device	Center Frequency
USRP™ N300	1 MHz to 6 GHz
USRP N310	1 MHz to 6 GHz
USRP N320	1 MHz to 6 GHz
USRP N321	1 MHz to 6 GHz
USRP X300	10 MHz to 6 GHz
USRP X310	10 MHz to 6 GHz
USRP X410	1 MHz to 8 GHz

Note

When setting this property for multiple antennas on a USRP N300 or USRP N310 radio, consider these hardware characteristics.

• The antenna ports on the RF0 and RF1 radio channels use the same center frequency. Therefore, set identical center frequency values for the antennas specified as "RF0:RX2" and "RF1:RX2".

• The antenna ports on the RF2 and RF3 radio channels use the same center frequency. Therefore, set identical center frequency values for the antennas specified as "RF2:RX2" and "RF3:RX2". These antennas are available only on a USRP N310 radio.

Data Types: double

Antennas — Capture radio antennas

string scalar | string array

Capture radio antennas, specified as one of these options.

• String scalar — Specify use of single antenna.

• String array — Specify use of multiple antennas.

Use this table to identify a supported radio antenna port on the radio device and the corresponding string constant that you can specify for this property. The default value depends on the radio.

Radio Device	Supported Antenna Port	String Scalar
USRP N300	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
USRP N310	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
	RF2 channel: RX2 port	"RF2:RX2"
	RF3 channel: RX2 port	"RF3:RX2"
USRP N320	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
USRP N321	RF0 channel: RX2 port	RF0 channel: RX2 port
	RF0 channel: RX2 port	RF0 channel: RX2 port
USRP X300	RFA channel: RX2 port	"RFA:RX2" (default)
	RFB channel: RX2 port	"RFB:RX2"
USRP X310	RFA channel: RX2 port	"RFA:RX2" (default)
	RFB channel: RX2 port	"RFB:RX2"
USRP X410	DB0 RF0 channel: RX 1 port	"DB0:RF0:RX1" (default)
	DB0 RF1 channel: RX 1 port	"DB0:RF1:RX1"
	DB1 RF0 channel: RX 1 port	"DB1:RF0:RX1"
	DB1 RF1 channel: RX 1 port	"DB1:RF1:RX1"

Note

When you update this property, the execution time of the next object function call increases by a few seconds.

Example: Antennas=["RF0:RX2","RF1:RX2"] specifies two capture antennas.

Data Types: string

RadioGain — Capture radio gain in dB

10 (default) | positive numeric scalar | numeric array

Capture radio gain in dB, specified as one of these options.

• Positive numeric scalar — The object applies this value by scalar expansion to each antenna that you specify in the Antennas property.

• Numeric array — The object applies the ith array element value to the ith antenna in the Antennas property.

The valid gain range depends on the radio device.

Radio Device	Capture Radio Gain
USRP N300	0 dB to 75 dB
USRP N310	0 dB to 75 dB
USRP N320	0 dB to 60 dB
USRP N321	0 dB to 60 dB
USRP X300	0 dB to 31.5 dB
USRP X310	0 dB to 31.5 dB
USRP X410	0 dB to 60 dB

Data Types: double

SampleRate — Baseband sample rate in Hz

highest device sample rate (default) | positive numeric scalar

Baseband sample rate in Hz, specified as a positive numeric scalar. For more information on how the radio achieves the specified sample rate, see Baseband Sample Rate in NI USRP Radios.

The valid sample rate depends on the radio device.

Radio Device	Sample Rate
USRP N300	120,945 Hz to 76.8 MHz 122.88 MHz 125.00 MHz 153.60 MHz (default)
USRP N310
USRP N320	196,851 Hz to 125 MHz 200.00 MHz 245.76 MHz 250.00 MHz (default)
USRP N321
USRP X300	181,418 Hz to 100 MHz 184.32 MHz 200.00 MHz (default)
USRP X310
USRP X410	241,890 Hz to 125 MHz 245.76 MHz 250.00 MHz (default)

Note

When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: double

CaptureDataType — Data type of captured data

"int16" (default) | "double" | "single"

Data type of the captured data, specified as "int16", "double", or "single". Use this property to set the data type of the captured data that the capture object function returns.

Note

When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: string

DroppedSamplesAction — Behavior upon dropped samples

"error" (default) | "warning" | "none"

Behavior of the capture object function upon dropped samples, specified as one of these values.

• "error" — The object function stops with an error message.

• "warning" — The object function displays a warning message.

• "none" — The object function ignores dropped samples.

Data Types: string

Object Functions

capture	Capture IQ data using baseband receiver or transceiver
isCapturing	Status of capture running in background using baseband receiver
captureOutputs	Retrieve outputs from capture run in background using baseband receiver
stopCapture	Stop capture running in background using baseband receiver

Examples

Configure Baseband Receiver and Capture Data

Create a baseband receiver object, specifying a radio setup configuration previously saved in the Radio Setup wizard.

bbrx = basebandReceiver("MyRadio")

bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: 2.4000e+09
              SampleRate: 250000000
                Antennas: "RF0:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Set the baseband sample rate and center frequency.

bbrx.SampleRate = 122.88e6;
bbrx.CenterFrequency = 2.2e9;

Capture 3 ms of IQ data with the radio associated with the baseband receiver object using the default antenna.

[data,~] = capture(bbrx,milliseconds(3));

Capture Data on Multiple Antennas with Baseband Receiver

Create a baseband receiver object, specifying a radio setup configuration previously saved in the Radio Setup wizard. Specify two antennas, each with a different center frequency.

bbrx = basebandReceiver("MyRadio", ...
    Antennas=["RF0:RX2" "RF1:RX2"], ...
    CenterFrequency=[2.2e9,2.4e9])

bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: [2.2000e+09 2.4000e+09]
              SampleRate: 153600000
                Antennas: ["RF0:RX2"    "RF1:RX2"]
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Capture 10000 IQ samples with the radio associated with the baseband receiver object.

length = 10000;
[data,~] = capture(bbrx,length);

The output data is a 10000 x 2 array. Each column contains the data captured on one antenna, in the order that they are specified.

Capture Data and Calculate Signal Power with Baseband Receiver

Create an anonymous function, showSignalPower, that calculates the average signal power of captured data and displays it in the command window.

showSignalPower = @(data, timestamp, ~) ...
    disp("Signal captured at " + string(timestamp)...
    + " has average power of " + string(10*log10(mean(abs(data).^2))) + " dB");

Create a basebandReceiver object, specifying a radio setup configuration previously saved using the Radio Setup wizard. Specify the data type of data captured with this object as "double".

bbrx = basebandReceiver("MyRadio","CaptureDataType","double")

bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: 2.4000e+09
              SampleRate: 250000000
                Antennas: "RF0:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "double"

Capture 10 ms of IQ data and specify the showSignalPower function to run when the capture operation completes.

[data, timestamp, droppedSamples] = capture(bbrx,milliseconds(10),CompletionFcn=showSignalPower);

Signal captured at 27-Nov-2023 15:56:38 has average power of -48.506 dB

Capture Data to MAT-File with Baseband Receiver

Create a baseband receiver object, specifying a radio setup configuration previously saved in the Radio Setup wizard.

bbrx = basebandReceiver("MyRadio")

bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: 2.4000e+09
              SampleRate: 250000000
                Antennas: "RF0:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Capture 100 ms of IQ data and save it to a file in the basebandData folder called capture1.mat.

mkdir('basebandData');
[dataPath,~] = capture(bbrx,milliseconds(100),SaveLocation='basebandData/capture1.mat');

Load the data into the workspace.

load(dataPath,'data');

Capture Data in Background with Baseband Receiver

Create a baseband receiver object, specifying a radio setup configuration previously saved in the Radio Setup wizard.

bbrx = basebandReceiver("MyRadio")

bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: 2.4000e+09
              SampleRate: 153600000
                Antennas: "RF0:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Capture 1 s of IQ data in the background and save it to a file in the basebandData folder called capture1.mat.

mkdir('basebandData');
capture(bbrx,seconds(1),SaveLocation='basebandData/capture1.mat',Background=true);

Check if the capture is in progress.

isCapturing(bbrx)

ans = logical
   1

Wait for the capture to complete.

while isCapturing(bbrx)
    pause(0.1);
end

Check that the capture is no longer in progress.

isCapturing(bbrx)

ans = logical
   0

Retrieve the outputs of the capture operation and load the captured IQ data into the workspace.

[dataPath,~] = captureOutputs(bbrx);
load(dataPath,'data');

Tips

• You cannot use save and load to store and reload Wireless Testbench objects. Instead, you can re-create the object with these steps:

  1. Write code to create a basebandReceiver object with a saved radio setup configuration radio and set the properties.

  2. Save the code to a script.

  3. Run the script in a new MATLAB^® session with the same saved radio setup configuration.

• To check your host performance capability for capturing data, see the Evaluate Host Capture Performance example. This example shows you how to identify the highest sample rate at which contiguous IQ data can be captured with your hardware setup.

Version History

Introduced in R2022a

R2023b: Capture data that exceeds the onboard memory buffer size of your radio

Calling the capture function with this object allows you to capture data that exceeds the buffer size of the onboard radio memory by sending the data directly to the host computer.