captureOutputs

Retrieve outputs from capture run in background using baseband receiver or transceiver

Since R2024a

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

Syntax

[data,timestamp,droppedSamples] = captureOutputs(bba)

Description

[data,timestamp,droppedSamples] = captureOutputs(bba) retrieves the outputs of a capture run in the background 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.

Examples

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

Input Arguments

bba — Baseband application

basebandReceiver object | basebandTransceiver object

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

Output Arguments

data — Captured signal

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

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

If the SaveLocation name-value argument is not set when you call the capture function, 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.

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 when you call the capture function, 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

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

Data Types: logical

Limitations

When you call the captureOutputs function, the captured data is moved into the workspace or the specified MAT file. This operation can take several seconds and the time depends on the size of the file.

Tips

Check the status of the capture by using the isCapturing function before using the captureOutputs function:

isCapturing(bba)

This function returns 1 (true) if a capture is in progress in the background.

Version History

Introduced in R2024a

R2025a: Retrieve data captured in background directly to workspace

The captureOutputs function now enables you to retrieve the outputs from a capture run in the background directly to the MATLAB^® workspace. When you use the capture function, specify the Background name-value argument without specifying a SaveLocation. Then, call the captureOutputs function to return the capture data with the data output argument.

R2025a: Support for baseband transceiver object

The captureOutputs function now enables you to retrieve the outputs from a capture run in the background using a basebandTransceiver object.