Main Content

capture

Capture signal of interest from the air upon detection

Since R2022a

collapse all in page

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

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));
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));
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",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);
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, specified as one of the following:

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.

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 DeviceMemory Buffer SizeMaximum Data Samples

USRP™ N310

2 GB229

USRP N320

2 GB229

USRP N321

2 GB229

USRP X310

1 GB228

USRP X410

4 GB230

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

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

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

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

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

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

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

See Also

Objects

Functions