capture

Capture IQ data using baseband receiver or transceiver

Since R2022a

collapse all in page

Syntax

[data,timestamp,droppedSamples] = capture(bba,length)
[data,timestamp,droppedSamples] = capture(bba,length,Name=Value)
capture(bba,length,Background=true)
capture(bba,length,Background=true,Name=Value)

Description

Capture in Foreground

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

example

[data,timestamp,droppedSamples] = capture(bba,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'.

example

Capture in Background

Since R2024a

capture(bba,length,Background=true) captures IQ data in the background. Use this syntax to run MATLAB® code during prolonged data capture.

example

capture(bba,length,Background=true,Name=Value) captures IQ data in the background and specifies options using one or more additional name-value arguments. For example, to write the captured data to a MAT file called capture.mat, set SaveLocation to 'capture.mat'.

example

Examples

collapse all

Open Live Script

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));
Open Live Script

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 a 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);
Open Live Script

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 10,000 IQ samples with the radio associated with the baseband receiver object. 

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

The output data is a 10,000-by-2 array. Each column contains the data captured on one antenna, in the order that they are specified.

Since R2024b

Open Live Script

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

bbtrx = basebandTransceiver("MyRadio", ...
    TransmitAntennas=["RF0:TX/RX","RF1:TX/RX"], ...
    TransmitCenterFrequency=[2.2e9,2.4e9], ...
    CaptureAntennas=["RF0:RX2","RF1:RX2"], ...
    CaptureCenterFrequency=[2.2e9,2.4e9])
bbtrx = 
  basebandTransceiver with properties:

          TransmitRadioGain: 10
    TransmitCenterFrequency: [2.2000e+09 2.4000e+09]
           TransmitAntennas: ["RF0:TX/RX"    "RF1:TX/RX"]
           CaptureRadioGain: 10
     CaptureCenterFrequency: [2.2000e+09 2.4000e+09]
            CaptureAntennas: ["RF0:RX2"    "RF1:RX2"]
            CaptureDataType: "int16"
       DroppedSamplesAction: "error"
                 SampleRate: 153600000

Generate two random complex transmit waveforms with a length of 1000 samples.

length = 1000;
txWaveform = [complex(randn(length,1),randn(length,1)), ...
    complex(randn(length,1),randn(length,1))];

Transmit the generated waveform continuously with the radio associated with the baseband transceiver object.

transmit(bbtrx,txWaveform,"continuous");

Capture IQ data with the radio associated with the baseband transceiver object.

[data,~] = capture(bbtrx,length);

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

Stop the continuous transmission when the capture is complete.

stopTransmission(bbtrx);

Since R2026a

Open Live Script

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

radio = radioConfigurations("MyRadio");

Create a baseband receiver object, specifying your radio object.

bbrx = basebandReceiver(radio);

Capture 1.5 megasamples of IQ data directly to the host computer by setting the UseRadioBuffer name-value argument to false.

[data,~] = capture(bbrx,1.5e6,UseRadioBuffer=false);

Since R2026a

Open Live Script

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

radio = radioConfigurations("MyRadio");

Create a baseband transceiver object, specifying your radio object. Specify three capture antennas.

bbtrx = basebandTransceiver(radio,CaptureAntennas=["RF0:RX2","RF1:RX2","RF2:RX2"])
bbtrx = 
  basebandTransceiver with properties:

          TransmitRadioGain: 10
    TransmitCenterFrequency: 2.4000e+09
           TransmitAntennas: "RF0:TX/RX"
           CaptureRadioGain: 10
     CaptureCenterFrequency: 2.4000e+09
            CaptureAntennas: ["RF0:RX2"    "RF1:RX2"    "RF2:RX2"]
            CaptureDataType: "int16"
       DroppedSamplesAction: "error"
                 SampleRate: 153600000
           TransmitDataType: "int16"

Generate a random transmit waveform.

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

Capture 1 gigasamples of IQ data directly to the host computer using both capture antennas. Since the combined number of transmit and capture samples is greater than the buffer size of the onboard radio memory, capture data directly to the host computer by setting the UseRadioBuffer name-value argument to false.

[data,~] = capture(bbtrx,1e9,UseRadioBuffer=false);

Since R2026a

Open Live Script

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

radio = radioConfigurations("MyRadio")
radio = 
  X310 with properties:

             Name: "MyRadio"
         Hardware: "USRP X310"

    Daughterboard: ["TwinRX"    "TwinRX"]

        IPAddress: "192.168.10.2"

      ClockSource: "internal"
       TimeSource: "internal"

         LOSource: ["internal"    "companion"    "external"    "external"]
       LOExported: [1 0 0 0]

Create a baseband receiver object, specifying your radio object.

bbrx = basebandReceiver(radio,Antennas=["RFA:TX/RX","RFA:RX2","RFB:TX/RX","RFB:RX2"])
bbrx = 
  basebandReceiver with properties:

               RadioGain: 10
         CenterFrequency: 2.4000e+09
              SampleRate: 200000000
                Antennas: ["RFA:TX/RX"    "RFA:RX2"    "RFB:TX/RX"    "RFB:RX2"]
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Capture 10 ms of IQ data directly to the host computer. You cannot use the onboard radio memory to buffer data captured on more than two antennas using a USRP X310 radio with TwinRX daughterboards.

[data,~] = capture(bbrx,milliseconds(10),UseRadioBuffer=false);

Since R2024a

Open Live Script

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 baseband receiver 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

Since R2023b

Open Live Script

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

Since R2024a

Open Live Script

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: 200000000
                Antennas: "RFA:RX2"
    DroppedSamplesAction: "error"
         CaptureDataType: "int16"

Capture 1 s of IQ data in the background.

mkdir('basebandData');
capture(bbrx,seconds(1),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.

[data,timestamp,droppedSamples] = captureOutputs(bbrx);

Since R2024a

Open Live Script

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 1 s.

pause(1);
stopCapture(bbrx);

Check that the capture is no longer in progress. 

isCapturing(bbrx)
ans = logical
   0

Since R2024a

Open Live Script

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: "RFA:TX/RX"
           CaptureRadioGain: 10
     CaptureCenterFrequency: 2.4000e+09
            CaptureAntennas: "RFA:RX2"
            CaptureDataType: "int16"
       DroppedSamplesAction: "error"
                 SampleRate: 200000000

Generate a 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 1 s of IQ data in the background.

capture(bbtrx,seconds(1),Background=true);

Check if the capture is in progress.

isCapturing(bbtrx)
ans = logical
   1

Wait for the capture to complete.

while isCapturing(bbtrx)
    pause(0.1);
end

Check that the capture is no longer in progress. 

isCapturing(bbtrx)
ans = logical
   0

Retrieve the outputs of the capture operation.

[data,timestamp,droppedSamples] = captureOutputs(bbtrx);

Since R2025a

Open Live Script

Create a radio object, specifying a radio setup configuration previously saved using the Radio Setup wizard.

radio = radioConfigurations("MyRadio")
radio = 
  X310 with properties:

           Name: "MyRadio"
       Hardware: "USRP X310"

      IPAddress: "192.168.10.2"

    ClockSource: "internal"
     TimeSource: "internal"

       LOSource: "internal"
     LOExported: 0

Create a baseband receiver object, specifying your radio object. Specify the Preload name-value argument as true to load the application onto the radio during object creation. Specify the RF properties during object creation.

bbrx = basebandReceiver(radio,Preload=true, ...
    SampleRate=50e6,CenterFrequency=2.4e9)
bbrx = 
  basebandReceiver with properties:

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

Schedule the start time for the capture operation to be 5 seconds in the future.

startTime = getRadioTime(radio) + 5
startTime = 
5.2707

Capture 3 ms of IQ data at the scheduled start time.

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

Get the current radio time.

endTime = getRadioTime(radio)
endTime = 
5.3606

Input Arguments

collapse all

Baseband application, specified as a basebandReceiver object or basebandTransceiver object.

Note

If you do not preload the application onto the radio during object creation, 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 radio. To load the application onto the radio during object creation, specify the Preload name-value argument:

bbtrx = basebandTransceiver("MyRadio",Preload=true);

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 bba input and captures ceil(N) number of data samples.

The capture behavior depends on the value of the UseRadioBuffer name-value argument (since R2026a). To capture more data than the radio memory buffer can accommodate, set UseRadioBuffer to false. This bypasses the radio memory buffer and transfers data directly to your host computer.

Radio DeviceMemory Buffer SizeMaximum Data Samples

USRP™ E320

2 GB229

USRP N300

2 GB229

USRP N310

2 GB229

USRP N320

2 GB229

USRP N321

2 GB229

USRP X300

1 GB228

USRP X310

1 GB228

USRP X410

4 GB230

Note

  • If you use a baseband transceiver and do not select to capture data directly to the host, both transmit and capture data samples are buffered in the onboard radio memory. In this case, to determine the maximum capture length, you must also take into account the length of the transmit waveform of any continuous transmission that you specify when calling the transmit function.

  • If you select to capture data directly to the host computer, the available memory on your host computer determines the maximum number of data samples.

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

Example: seconds(5)

Data Types: double | duration

Name-Value Arguments

collapse all

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'.

Since R2026a

Flag to specify data buffering behavior, specified as true or false.

Set UseRadioBuffer to false to bypass the onboard radio memory buffer and capture data directly to the host computer. Use this option in these scenarios:

  • The capture length is greater than the onboard radio memory buffer size.

  • Your are using a USRP X310 radio with a TwinRX daughterboard and are capturing data on more than two antennas. This requirement is a hardware limitation.

If you do not specify UseRadioBuffer, the capture function tries to use the radio memory buffer. If the capture length exceeds the radio memory buffer size, or data buffering is not supported for your hardware configuration, the capture function warns and captures data directly to the host.

If you set UseRadioBuffer to true and the capture length exceeds the radio memory buffer size, or data buffering is not supported for your hardware configuration, the capture function errors.

Data Types: logical

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

Since R2024a

Flag to enable a background capture, specified as false or true.

Set Background to true 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

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 the Background name-value argument is specified as true, when you call the captureOutputs function.

Data Types: function_handle

Since R2025a

Start time for capture, specified as a positive numeric scalar. To schedule a capture to start at a future time, first use the getRadioTime function to get the current radio time in seconds. Then, specify the radio time at which you want to start capturing data.

Note

  • A delay occurs when initializing the capture function, which depends on the specific application and your host capability. The start time you specify must allow enough time for the function to be initialized.

  • When you use this name-value argument, specify Preload=true when you create your bba object. Loading the application onto the radio at object creation prevents the radio time from being reset when you call the capture function. Because updating object properties can cause the radio time to reset, be sure to specify properties during object creation.

For more information about how to schedule transmit and capture operations, see Time-Synchronize Operations.

Example: getRadioTime(radio)+0.5 schedules the capture operation to start 500 milliseconds in the future.

Data Types: double

Output Arguments

collapse all

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.

    • If the bba input is a baseband receiver, the number of matrix columns is determined by the number of antennas specified by the Antennas object property.

    • If the bba input is a baseband transceiver, the number of matrix columns is determined by the number of antennas specified by the CaptureAntennas object property (since R2024b).

Use the CaptureDataType property of the bba 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'.

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

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

Data Types: datetime

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 bba input object to specify the behavior of the function upon dropped samples.

If samples are dropped, this indicates that there is a problem with the network connection between the host and the radio. For possible solutions, see Resolve Issues with Data Transfer.

Data Types: logical

Limitations

If you have a USRP X410 radio, consider the following limitations.

  • If set the SampleRate property of the bba input object to 491.52 MHz or 500 MHz:

    • You can capture data only in the foreground.

    • You must specify the capture length to be less than or equal to the onboard radio memory buffer size.

  • If you change the SampleRate property of the bba input object between a sample rate greater than 250 MHz and a sample rate less than or equal to 250 MHz, a new FPGA image is loaded to the radio when you call the capture function. This can take up to a minute.

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

expand all

See Also

Functions

Objects

Topics