capture
Add-On Required: This feature requires the Wireless Testbench™ Support Package for NI™ USRP™ Radios add-on.
Syntax
Description
Baseband Receiver
[
captures IQ data of length data
,timestamp
,droppedSamples
] = capture(bbrx
,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
.
[
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 data
,timestamp
,droppedSamples
] = capture(bbrx
,length
,Name=Value
)capture.mat
,
set SaveLocation
to
'capture.mat'
. (since R2024a)
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 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.
Transmit and Capture Data on Multiple Antennas with Baseband Transceiver
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 x 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);
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');
Stop Data Capture 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: 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 input 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, 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 abasebandReceiver
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.
Dependencies
The input must be a baseband receiver, bbrx
.
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'
Dependencies
The input must be a baseband receiver, bbrx
.
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.
Dependencies
The input must be a baseband receiver, bbrx
.
Data Types: logical
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.
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 input is a baseband receiver, the number of matrix columns is determined by the number of antennas specified by the
Antennas
property onbbrx
.If the input is a baseband transceiver, the number of matrix columns is determined by the number of antennas specified by the
CaptureAntennas
object property onbbtrx
. (since R2024b)
Use the CaptureDataType
property of the
bbrx
or 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].
If the input is a baseband receiver and 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)
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 object 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 R2022aR2024b: Capture data on multiple antennas with baseband transceiver
You can now capture data on multiple antennas with the
basebandTransceiver
object. Specify multiple antennas using the CaptureAntennas
property of the bbtrx
input.
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.
See Also
Functions
Objects
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)