capture
Add-On Required: This feature requires the Wireless Testbench™ Support Package for NI™ USRP™ Radios add-on.
Syntax
Description
[
captures a signal of interest of length data
,timestamp
,droppedSamples
,status
] = capture(detector
,length
,timeout
)length
from the air using the preamble or energy detector
detector
with the detection timeout
timeout
. The function returns the captured
signal data
, capture request timestamp
timestamp
, dropped samples status
droppedSamples
, and capture outcome status
status
.
[
specifies the number of consecutive signals to capture, in addition to
the input arguments in the previous syntax. (since R2024a)data
,timestamp
,droppedSamples
,status
] = capture(___,NumCaptures
=value)
Examples
Configure Preamble Detector and Capture Data
Define a preamble sequence with good correlation properties. For example, generate and normalize a Zadoff-Chu sequence of length 137.
seq = zadoffChuSeq(38,137); preamble = seq/norm(seq,2);
Create and configure a preamble detector object, specifying a radio setup configuration previously saved in the Radio Setup wizard. Set the sample rate to 10.24 MHz and the center frequency to 2.2 GHz.
pd = preambleDetector("MyRadio")
pd = preambleDetector with properties: Antennas: "RF0:RX2" CenterFrequency: 2.4000e+09 SampleRate: 250000000 RadioGain: 10 Preamble: [16×1 double] CaptureDataType: "int16" TriggerOffset: 0 DroppedSamplesAction: "error" ThresholdMethod: "adaptive" TimestampUnit: "datetime" AdaptiveThresholdOffset: 0 AdaptiveThresholdGain: 0
pd.SampleRate = 10.24e6;
pd.CenterFrequency = 2.2e9;
pd.CaptureDataType = "double";
Specify the preamble.
pd.Preamble = preamble;
Set the trigger offset to a negative value to capture 500 samples before the trigger point.
pd.TriggerOffset = -500;
Capture 10 ms of data with a timeout of 1 s.
[data,timestamp,droppedSamples,status] = capture(pd,milliseconds(10),seconds(1));
Configure Energy Detector and Capture Data
Create and configure an energy detector object, specifying a radio setup configuration previously saved in the Radio Setup wizard.
ed = energyDetector("MyRadio")
ed = energyDetector with properties: Antennas: "RF0:RX2" CenterFrequency: 2.4000e+09 SampleRate: 250000000 RadioGain: 10 CaptureDataType: "int16" WindowLength: 300 TriggerOffset: 0 DroppedSamplesAction: "error" ThresholdMethod: "adaptive" TimestampUnit: "datetime" MinimumEnergy: 1.0000e-04 EnergyDeltaThreshold: 1
ed.SampleRate = 30.72e6;
ed.CenterFrequency = 2.45e9;
ed.CaptureDataType = "double";
Set the energy increase threshold to 3 dB.
ed.EnergyDeltaThreshold = 3;
Set the trigger offset to a negative value to capture 100 samples before the trigger point.
ed.TriggerOffset = -100;
Capture 3 ms of data with a timeout of 1 s.
[data,timestamp,droppedSamples,status] = capture(ed,milliseconds(3),seconds(1));
Capture Multiple Consecutive Signals with Preamble Detector
Define a preamble sequence with good correlation properties. For example, generate and normalize a Zadoff-Chu sequence of length 137.
seq = zadoffChuSeq(38,137); preamble = seq/norm(seq,2);
Create and configure a preamble detector object, specifying a radio setup configuration previously saved in the Radio Setup wizard. Set the sample rate to 10.24 MHz and the center frequency to 2.2 GHz.
pd = preambleDetector("MyRadio",SampleRate=10.24e6,CenterFrequency=2.2e9)
pd = preambleDetector with properties: Antennas: "RF0:RX2" CenterFrequency: 2.2000e+09 SampleRate: 10240000 RadioGain: 10 Preamble: [16×1 double] CaptureDataType: "int16" TriggerOffset: 0 DroppedSamplesAction: "error" ThresholdMethod: "adaptive" TimestampUnit: "datetime" AdaptiveThresholdOffset: 0 AdaptiveThresholdGain: 0
Specify the preamble.
pd.Preamble = preamble;
Capture ten consecutive signals with the specified preamble with a capture length of 5 ms and a timeout of 2 s.
[data,timestamp,droppedSamples,status] = capture(pd,milliseconds(5),seconds(2),"NumCaptures",10);
Capture Multiple Consecutive Signals with Energy Detector
Create and configure an energy detector object, specifying a radio setup configuration previously saved using the Radio Setup wizard. Set the data type of the captured data to double and the unit of the capture request timestamp to sample clock cycles.
ed = energyDetector("MyRadio",CaptureDataType="double",TimestampUnit="sample-clock-cycle")
ed = energyDetector with properties: Antennas: "RF0:RX2" CenterFrequency: 2.4000e+09 SampleRate: 250000000 RadioGain: 10 CaptureDataType: "double" WindowLength: 300 TriggerOffset: 0 DroppedSamplesAction: "error" ThresholdMethod: "adaptive" TimestampUnit: "sample-clock-cycle" MinimumEnergy: 1.0000e-04 EnergyDeltaThreshold: 1
Capture five consecutive signals that meet the default thresholding criteria with a capture length of 1 ms and a timeout of 1 s.
[data,timestamp,droppedSamples,status] = capture(ed,milliseconds(1),seconds(1),"NumCaptures",5);
Input Arguments
detector
— Preamble or energy detector
preambleDetector
object | energyDetector
object
Detector, specified as one of the following:
preambleDetector
objectenergyDetector
object (since R2023b)
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 detector
input
and captures ceil
(N) number of data
samples.
Specify the capture length relative to the onboard radio memory buffer size.
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
The onboard radio memory buffers capture and transmit data samples. Therefore, when specifying the capture length, you must also account for the length of the transmit waveform of any continuous transmission that you specify when calling the
transmit
object function with thedetector
input.If your host computer does not have enough free memory to receive the captured data from the radio buffer, the function call can hang or error out. To free up memory space on your host computer, try closing other software, reducing the capture length, or reducing the number of consecutive captures.
Example: seconds(5)
Data Types: double
| duration
timeout
— Signal detection timeout
duration
Signal detection timeout on the radio, specified as a duration
value in
time units.
When you set
NumCaptures
to greater than 1 to capture
consecutive signals from the air, the timeout
applies to the entire capture
operation. (since R2024a)
Note
If detector
is a preambleDetector
object, the
property specifies
a periodic signal. Set the detection timeout to a value that is
equal to or greater than the preamble signal period. If the number
of captures is set to a value greater than 1, set the detection
timeout to the preamble signal period multiplied by
Preamble
NumCaptures
. Setting the detection timeout
to a value less than this can end the detection operation
prematurely.
Example: milliseconds(100)
Data Types: duration
NumCaptures
— Number of consecutive signals to capture
1 (default) | positive integer
Since R2024a
Number of consecutive signals to capture, specified as a
positive integer. The capture
function
identifies the signal of interest with the
detector
input, captures N
samples of IQ data from the air based on the
length
input, and then waits until it
identifies the next signal of interest. The function repeats this
process until it captures NumCaptures
signals
or until it reaches the signal detection timeout,
timeout
.
Note
The minimum time between the end of a capture operation and the start of the next signal that can be detected is 33 ns.
Data Types: double
Output Arguments
data
— Captured signal
column vector of complex values | cell array of complex values
Captured signal, returned as one of these values, where
N is the integer number of samples defined by
length
.
An N-by-1 column vector of complex values if
NumCaptures
is 1 (default).An N-by-
NumCaptures
cell array of complex values ifNumCaptures
is greater than 1. (since R2024a)Note
If
timeout
is reached before the number of signals requested inNumCaptures
have been captured, the number of columns indata
is equal to the number of successfully captured signals.
Use the CaptureDataType
property of the
detector
input to specify the output data
type of the captured 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].
Data Types: int16
| single
| double
| cell
Complex Number Support: Yes
timestamp
— Capture request timestamp
datetime
value | column vector of datetime
values | sample clock cycles | column vector of sample clock cycles
Capture request timestamp, returned as a datetime
value, a column
vector of datetime
values, sample clock cycles, or a column vector of
sample clock cycles.
Use the TimestampUnit
property of the
detector
input to specify the output data
type of the capture request timestamp.
If the
TimestampUnit
property isdatetime
(default) andNumCaptures
is 1 (default), the function creates the initial timestamp just before requesting the first data capture from the hardware. The function returns this as adatetime
value to nanosecond precision.If the
TimestampUnit
property isdatetime
(default) andNumCaptures
is greater than 1, the function creates a timestamp just before it requests each data capture from the hardware. The function returns these as a column vector ofdatetime
values to nanosecond precision. (since R2024a)If the
TimestampUnit
property is set tosample-clock-cycle
and multiple consecutive captures are requested with theNumCaptures
name-value argument, the function first creates an initial timestamp of 0 just before requesting the first data capture from the hardware. For each subsequent capture, the function returns an integer number of clock cycles relative to the initial timestamp in a column vector. The sample clock rate is set by theSampleRate
property of thedetector
input. (since R2024a)Note
If
NumCaptures
is not set or set to 1, the capture request timestamp is returned as adatetime
value.
Data Types: datetime
| uint64
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 detector
input to specify the
behavior of the capture
function upon
dropped samples.
Data Types: logical
status
— Number of successful captures
positive integer
Number of successful captures, returned as a positive integer.
If NumCaptures
is 1 (default),
status
is returned as one of the following values:
1 — The capture operation was successful and the captured signal of interest is returned in
data
.0 — The detect and capture operation timed out.
If
NumCaptures
is set to a value greater than 1,
status
is returned as the number of
successful captures completed before the capture operation timed
out. (since R2024a)
Version History
Introduced in R2022aR2024a: Capture multiple consecutive signals
Specify the NumCaptures
name-value input argument to capture multiple
consecutive signals with detectors.
R2023b: Support for energy detector object
The function accepts an energyDetector
object as an input argument.
See Also
Objects
Functions
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)