capture

Capture IQ data using baseband receiver or transceiver

Since R2022a

Syntax

[data,timestamp,droppedSamples] = capture(bbrx,length)

[data,timestamp,droppedSamples] = capture(bbrx,length,Name=Value)

[data,timestamp,droppedSamples] = capture(bbtrx,length)

Description

Baseband Receiver

[data,timestamp,droppedSamples] = capture(bbrx,length) captures IQ data of length length from the air using the specified baseband receiver. The function returns the captured signal data, capture request timestamp timestamp, and dropped samples status droppedSamples.

[data,timestamp,droppedSamples] = capture(bbrx,length,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in the previous syntax. For example, to write the captured data to a MAT-file called capture.mat, set SaveLocation to 'capture.mat'. (since R2024a)

Baseband Transceiver

[data,timestamp,droppedSamples] = capture(bbtrx,length) captures IQ data of length length from the air using the specified baseband transceiver. The function returns the captured signal data, capture request timestamp timestamp, and dropped samples status droppedSamples.

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));

Configure Baseband Transceiver to Transmit and Capture Data

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

bbtrx = basebandTransceiver("MyRadio")

bbtrx = 
  basebandTransceiver with properties:

          TransmitRadioGain: 10
    TransmitCenterFrequency: 2.4000e+09
           TransmitAntennas: "RF0:TX/RX"
           CaptureRadioGain: 10
     CaptureCenterFrequency: 2.4000e+09
            CaptureAntennas: "RF0:RX2"
            CaptureDataType: "int16"
       DroppedSamplesAction: "error"
                 SampleRate: 250000000

Set the baseband sample rate.

bbtrx.SampleRate = 122.88e6;

Set the transmit and capture center frequencies.

bbtrx.TransmitCenterFrequency = 2.2e9;
bbtrx.CaptureCenterFrequency = 2.2e9;

Generate random transmit waveform.

txWaveform = complex(randn(1000,1),randn(1000,1));

Transmit the generated waveform continuously with the radio associated with the baseband transceiver object using the default transmit antenna.

transmit(bbtrx,txWaveform,"continuous");

Capture IQ data with the radio associated with the baseband transceiver object using the default capture antenna.

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

Stop the continuous transmission after data capture is complete.

stopTransmission(bbtrx);

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 the 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: 250000000
                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');
[dataPath,~] = 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, timestamp, droppedSamples] = captureOutputs(bbrx);
load(dataPath,'data');

Stop Data Capture in the 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: 250000000
                Antennas: "RF0:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

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

mkdir('basebandData');
[dataPath,~] = capture(bbrx,seconds(5),SaveLocation='basebandData/capture1.mat',Background=true);

Check if the capture is in progress.

isCapturing(bbrx)

ans = logical
   1

Stop the capture after 1s.

pause(1);
stopCapture(bbrx);

Check that the capture is no longer in progress.

isCapturing(bbrx)

ans = logical
   0

Input Arguments

bbrx — Baseband receiver

basebandReceiver object

Baseband receiver, specified as a basebandReceiver object.

Note

The first object function call in which you specify this object as an input requires a few extra seconds to load the application onto the hardware.

length — Capture length

integer number of samples | duration

Capture length, specified as an integer number of samples or a duration value in time units. The function converts length into N samples based on the SampleRate property of the bbrx or bbtrx input and captures ceil(N) number of data samples.

If the baseband application is a baseband receiver, the capture behavior depends on the capture length relative to the onboard radio buffer size.

• If you specify the capture length less than the onboard radio memory buffer size, data is buffered on the radio before it is transferred to your host computer.

• If you specify the capture length greater than the onboard radio memory buffer size, the onboard radio memory buffer is bypassed and data is transferred directly to your host computer. (since R2023b)

Radio Device	Memory Buffer Size	Maximum Data Samples
USRP™ N310	2 GB	229
USRP N320	2 GB	229
USRP N321	2 GB	229
USRP X310	1 GB	228
USRP X410	4 GB	230

Note

• Transmit and capture data samples on the baseband transceiver are buffered in the onboard radio memory. Therefore, if the input is a baseband transceiver, bbtrx, you must also take into account the length of the transmit waveform of any continuous transmission that you specify when calling the transmit object function.

• If you specify length greater than the radio buffer size with a baseband receiver object, the maximum data samples will be determined by the memory on your host computer.

• If your host computer does not have enough free memory to receive the captured data, the function call can hang or error out. To free up memory space on your host computer, try closing other software or reduce the capture length.

Example: seconds(5)

Data Types: double | duration

bbtrx — Baseband transceiver

basebandTransceiver object

Baseband transceiver, specified as a basebandTransceiver object.

Note

The first object function call in which you specify this object as an input requires a few extra seconds to load the application onto the hardware.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: SaveLocation='capture1.mat', Background=1 specifies the capture to run in the background and writes the captured data to a file with the name 'capture1.mat'.

CompletionFcn — Function to process captured data

function handle

Since R2024a

Function to process the captured data, specified as a function handle. The function must have three input arguments corresponding to the number of output arguments that the capture function returns.

The function runs when the capture operation completes, or if Background is 1 (true), when you call the captureOutputs function.

Data Types: function_handle

SaveLocation — Path to MAT-file including filename

character vector | string scalar

Since R2023b

Path to the MAT-file including filename, specified as a character vector or string scalar. Use this option to write the capture outputs to a file. Specify a full or relative path that contains a filename. If the path does not include an extension, the function appends with .mat.

If the file does not exist, the function creates a Version 7.3 MAT-file. If the file already exists, the function overwrites the file with a Version 7.3 MAT-file.

Example: 'capture1.mat'

Data Types: char | string

Background — Flag to enable background capture

0 (false) (default) | 1 (true)

Since R2024a

Flag to enable a background capture, specified as 0 (false) or 1 (true).

When Background is set to true, the capture runs in the background and writes the captured data to a file, specified by the SaveLocation name-value argument. Use this option to run MATLAB^® code during prolonged data capture. Use the following functions with a capture that you run in the background:

• isCapturing — Check if a capture is in progress in the background.

• captureOutputs — Retrieve the outputs of a capture run in the background.

• stopCapture — Stop a capture running in the background.

When Background is not set or is set to false, the capture function runs in the foreground. You can run MATLAB code only when the capture operation completes.

Data Types: logical

Output Arguments

data — Captured signal

complex-valued column vector | complex-valued matrix | character vector

Baseband Receiver

Captured signal, returned as a complex-valued column vector, a complex-valued matrix, or a character vector, depending on the input arguments.

If the SaveLocation name-value argument is not set, data is returned as one of these options.

• Complex-valued column vector — The vector contains data that is captured on a single capture antenna.

• Complex-valued matrix — The matrix contains data that is captured on multiple capture antennas. The number of antennas specified by the Antennas property of the bbrx input determines the number of matrix columns.

Use the CaptureDataType property of the bbrx input object to specify the data type of the returned data. If you specify the return data type as single or double, the function scales the captured data sample values to the range [–1, 1].

If the SaveLocation name-value argument is set, data is returned as the path to MAT-file where captured data is saved. The full path is returned, including the file name and extension, for example, 'H:/user/matlab/capture1.mat'. (since R2023b)

Baseband Transceiver

Captured signal, returned as a complex-valued column vector.

Use the CaptureDataType property of the bbtrx input object to specify the data type of the returned data. If you specify the return data type as single or double, the function scales the captured data sample values to the range [–1, 1].

Note

The first data samples of the captured signal can contain transient values from the radio data path.

Data Types: int16 | single | double | char
Complex Number Support: Yes

timestamp — Capture request timestamp

datetime value

Capture request timestamp, returned as a datetime value. The function creates this timestamp just before requesting data capture from the hardware.

Data Types: datetime

droppedSamples — Status of dropped samples

1 | 0

Status of dropped samples, returned as one of these logical values.

• 1 — Samples are dropped during capture.

• 0 — Samples are not dropped during capture.

Use the DroppedSamplesAction property of the bbrx or bbtrx input to specify the behavior of the function upon dropped samples.

Data Types: logical

Tips

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

R2024a: Capture data in the background

The Background name-value argument enables you to capture data in the background when calling the capture function with a basebandReceiver object.

R2024a: Process captured data with a callback function

The CompletionFcn name-value argument enables you to specify a callback function to post-process the captured IQ data when calling the capture function with a basebandReceiver object.

R2023b: Save captured data to a MAT-file

Calling the capture function with a basebandReceiver object enables you to write captured data directly to a MAT-file when you specify the SaveLocation name-value argument.