capture

Capture signal of interest from the air upon detection

Since R2022a

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

Syntax

[data,timestamp,droppedSamples,status] = capture(detector,length,timeout)

[data,timestamp,droppedSamples,status] = capture(___,NumCaptures=value)

Description

[data,timestamp,droppedSamples,status] = capture(detector,length,timeout) captures a signal of interest of length 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.

example

[data,timestamp,droppedSamples,status] = capture(___,NumCaptures=value) specifies the number of consecutive signals to capture, in addition to the input arguments in the previous syntax. (since R2024a)

example

Examples

collapse all

Configure Preamble Detector and Capture Data

Open Live Script

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

Open Live Script

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

Open Live Script

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

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

Open Live Script

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

collapse all

`detector` — Preamble or energy detector
`preambleDetector` object | `energyDetector` object

Detector, specified as one of the following:

preambleDetector object
energyDetector 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™ N300	2 GB	2²⁹
USRP N310	2 GB	2²⁹
USRP N320	2 GB	2²⁹
USRP N321	2 GB	2²⁹
USRP X300	1 GB	2²⁸
USRP X310	1 GB	2²⁸
USRP X410	4 GB	2³⁰

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 the detector 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 Preamble 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 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

collapse all

`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 if NumCaptures is greater than 1. (since R2024a)
Note
If timeout is reached before the number of signals requested in NumCaptures have been captured, the number of columns in data 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 is datetime (default) and NumCaptures is 1 (default), the function creates the initial timestamp just before requesting the first data capture from the hardware. The function returns this as a datetime value to nanosecond precision.
If the TimestampUnit property is datetime (default) and NumCaptures 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 of datetime values to nanosecond precision. (since R2024a)
If the TimestampUnit property is set to sample-clock-cycle and multiple consecutive captures are requested with the NumCaptures 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 the SampleRate property of the detector input. (since R2024a)

Note
If NumCaptures is not set or set to 1, the capture request timestamp is returned as a datetime 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 R2022a

expand all

R2024a: 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.

capture

Syntax

Description

Examples

Configure Preamble Detector and Capture Data

Configure Energy Detector and Capture Data

Capture Multiple Consecutive Signals with Preamble Detector

Capture Multiple Consecutive Signals with Energy Detector

Input Arguments

`detector` — Preamble or energy detector
`preambleDetector` object | `energyDetector` object

`length` — Capture length
integer number of samples | `duration`

`timeout` — Signal detection timeout
`duration`

`NumCaptures` — Number of consecutive signals to capture
1 (default) | positive integer

Output Arguments

`data` — Captured signal
column vector of complex values | cell array of complex values

`timestamp` — Capture request timestamp
`datetime` value | column vector of `datetime` values | sample clock cycles | column vector of sample clock cycles

`droppedSamples` — Status of dropped samples
`1` | `0`

`status` — Number of successful captures
positive integer

Version History

R2024a: Capture multiple consecutive signals

R2023b: Support for energy detector object

See Also

Objects

Functions

capture

Syntax

Description

Examples

Configure Preamble Detector and Capture Data

Configure Energy Detector and Capture Data

Capture Multiple Consecutive Signals with Preamble Detector

Capture Multiple Consecutive Signals with Energy Detector

Input Arguments

detector — Preamble or energy detector preambleDetector object | energyDetector object

length — Capture length integer number of samples | duration

timeout — Signal detection timeout duration

NumCaptures — Number of consecutive signals to capture 1 (default) | positive integer

Output Arguments

data — Captured signal column vector of complex values | cell array of complex values

timestamp — Capture request timestamp datetime value | column vector of datetime values | sample clock cycles | column vector of sample clock cycles

droppedSamples — Status of dropped samples 1 | 0

status — Number of successful captures positive integer

Version History

R2024a: Capture multiple consecutive signals

R2023b: Support for energy detector object

See Also

Objects

Functions

`detector` — Preamble or energy detector
`preambleDetector` object | `energyDetector` object

`length` — Capture length
integer number of samples | `duration`

`timeout` — Signal detection timeout
`duration`

`NumCaptures` — Number of consecutive signals to capture
1 (default) | positive integer

`data` — Captured signal
column vector of complex values | cell array of complex values

`timestamp` — Capture request timestamp
`datetime` value | column vector of `datetime` values | sample clock cycles | column vector of sample clock cycles

`droppedSamples` — Status of dropped samples
`1` | `0`

`status` — Number of successful captures
positive integer