preambleDetector

Configure SDR as preamble detector

Since R2022a

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

Description

Use the preambleDetector object to configure the specified software-defined radio (SDR) as a preamble detector. You can use the preamble detector to detect and capture a signal of interest from the air using a correlation with a known preamble sequence. The object specifies the preamble sequence and the thresholding and triggering parameters. For more details on the internal architecture of the preamble detector, see Algorithms.

This diagram shows a conceptual overview of detecting and capturing radio signals in Wireless Testbench™ using a radio that you configure with this object. The object also enables you to send a test waveform for detection and capture. The onboard data buffering ensures contiguous data capture and transmit.

Creation

Syntax

pd = preambleDetector(radio)

pd = preambleDetector(radio,PropertyName=Value)

Description

pd = preambleDetector(radio) creates a preamble detector application object for the specified radio, radio.

Note

The object requires exclusive access to radio hardware resources. Before creating this object, clear any existing Wireless Testbench application object associated with the specified radio from the workspace.

pd = preambleDetector(radio,PropertyName=Value) sets properties using one or more name-value arguments. For example, CaptureDataType="double" sets the data type of the returned captured signal to double.

Input Arguments

radio — Radio setup configuration

string scalar | radio object

Radio setup configuration, specified as one of these options.

• String scalar — The name of a radio setup configuration you saved using the Radio Setup wizard. To list all saved radio setup configurations, call the radioConfigurations function with no input arguments. For example, "MyRadio".

• Radio object — A radio object that corresponds to a radio setup configuration you saved using the Radio Setup wizard. For example, to create a radio object for a radio setup configuration with the name "MyRadio", call radio = radioConfigurations("MyRadio").

  Use this option when you want to use synchronization features. You can refer to radio object properties to get information about the radio setup configuration that the object corresponds to, such as the model number of the radio, the radio IP address, and the synchronization options. Additionally, you can:

  • Check the lock status of the reference clock, local oscillators, or GPS disciplined oscillator (GPSDO) on the radio using the referenceLockedStatus, loLockedStatus, and gpsLockedStatus functions respectively.

  • Get the current radio time using the getRadioTime function.

  • Synchronize multiple devices by setting the radio time using the getTimeLastPPS and setTimeNextPPS functions.

  • Get time and GPS information from the radio using the getGPSTime and getGPSNMEA functions.

  • Schedule synchronized property updates on your preambleDetector object using the setCommandTime, getCommandTime, and clearCommandTime functions.

  For more information, see Time Synchronize Operations on NI USRP Radios.

For a list of supported radios, see Supported Radio Devices.

Properties

CenterFrequency — Capture center frequency in Hz

2.4e9 (default) | positive numeric scalar

Capture center frequency in Hz, specified as a positive numeric scalar. The valid center frequency range depends on the radio device.

Radio Device	Center Frequency
USRP™ N300	1 MHz to 6 GHz
USRP N310	1 MHz to 6 GHz
USRP N320	1 MHz to 6 GHz
USRP N321	1 MHz to 6 GHz
USRP X300	10 MHz to 6 GHz
USRP X310	10 MHz to 6 GHz
USRP X410	1 MHz to 8 GHz

Data Types: double

RadioGain — Capture radio gain in dB

10 (default) | positive numeric scalar

Capture radio gain in dB, specified as a positive numeric scalar. The valid gain range depends on the radio device.

Radio Device	Capture Radio Gain
USRP N300	0 dB to 75 dB
USRP N310	0 dB to 75 dB
USRP N320	0 dB to 60 dB
USRP N321	0 dB to 60 dB
USRP X300	0 dB to 31.5 dB
USRP X310	0 dB to 31.5 dB
USRP X410	0 dB to 60 dB

Data Types: double

Antennas — Capture radio antenna

string scalar

Capture radio antenna, specified as a string scalar. Use this table to identify a supported radio antenna port on the radio device and the corresponding string constant that you can specify for this property. The default value depends on the radio.

Radio Device	Supported Antenna Port	String Scalar
USRP N300	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
USRP N310	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
	RF2 channel: RX2 port	"RF2:RX2"
	RF3 channel: RX2 port	"RF3:RX2"
USRP N320	RF0 channel: RX2 port	"RF0:RX2" (default)
	RF1 channel: RX2 port	"RF1:RX2"
USRP N321	RF0 channel: RX2 port	RF0 channel: RX2 port
	RF0 channel: RX2 port	RF0 channel: RX2 port
USRP X300	RFA channel: RX2 port	"RFA:RX2" (default)
	RFB channel: RX2 port	"RFB:RX2"
USRP X310	RFA channel: RX2 port	"RFA:RX2" (default)
	RFB channel: RX2 port	"RFB:RX2"
USRP X410	DB0 RF0 channel: RX 1 port	"DB0:RF0:RX1" (default)
	DB0 RF1 channel: RX 1 port	"DB0:RF1:RX1"
	DB1 RF0 channel: RX 1 port	"DB1:RF0:RX1"
	DB1 RF1 channel: RX 1 port	"DB1:RF1:RX1"

Note

When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: string

SampleRate — Baseband sample rate in Hz

highest device sample rate (default) | positive numeric scalar

Baseband sample rate in Hz, specified as a positive numeric scalar. For more information on how the radio achieves the specified sample rate, see Baseband Sample Rate in NI USRP Radios.

The sample rate depends on the radio device.

Radio Device	Sample Rate
USRP N300	120,945 Hz to 76.8 MHz 122.88 MHz 125.00 MHz 153.60 MHz (default)
USRP N310
USRP N320	196,851 Hz to 125 MHz 200.00 MHz 245.76 MHz 250.00 MHz (default)
USRP N321
USRP X300	181,418 Hz to 100 MHz 184.32 MHz 200.00 MHz (default)
USRP X310
USRP X410	241,890 Hz to 125 MHz 245.76 MHz 250.00 MHz (default)

Note

To update this property, you must stop any ongoing transmission by calling the stopTransmission function on the object. When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: double

CaptureDataType — Data type of captured data

"int16" (default) | "double" | "single"

Data type of the captured data, specified as "int16", "double", or "single". Use this property to set the data type of the captured data that the capture object function returns.

Note

When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: string

TimestampUnit — Unit of capture request timestamp

"datetime" (default) | "sample-clock-cycle"

Since R2024a

Unit of capture request timestamp, specified as "datetime" or "sample-clock-cycle". Use this property to set the data type of the timestamp that the capture object function returns.

Data Types: string

DroppedSamplesAction — Behavior upon dropped samples

"error" (default) | "warning" | "none"

Behavior of the capture or plotThreshold object functions upon dropped samples, specified as one of these values.

• "error" — The object function stops with an error message.

• "warning" — The object function displays a warning message.

• "none" — The object function ignores dropped samples.

Data Types: string

Preamble — Preamble sequence

16-by-1 vector of all zeros (default) | numeric column vector

Preamble sequence, specified as a numeric column vector of length between 4 and 1024 and vector elements in the range [–1, 1]. The first object function call validates the preamble length against the maximum preamble length.

You can assign a double, single, or fi (requires Fixed-Point Designer™) data type to this property. To assign a fixed-point data type, use the fi (Fixed-Point Designer) object. The fixed-point data type must be signed with the WordLength property set to 16 and FractionLength property set to 15.

Note

To update this property, you must stop any ongoing transmission by calling the stopTransmission function on the object. When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: double | single | fi

ThresholdMethod — Threshold calculation method

"adaptive" (default) | "fixed"

Threshold calculation method to trigger data capture, specified as one of these values.

• "adaptive" — The threshold is the scaled signal power. To configure the scaled signal power, set the AdaptiveThresholdGain and AdaptiveThresholdOffset properties.

• "fixed" — The threshold is a constant, specified by the FixedThreshold property.

For more details, see Internal Architecture of Preamble Detection.

Note

To update this property, you must stop any ongoing transmission by calling the stopTransmission function on the object. When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: string

FixedThreshold — Fixed threshold value

0 (default) | numeric scalar in the range [0, 4095]

Fixed threshold value, specified as a numeric scalar in the range [0, 4095]. For more details, see Internal Architecture of Preamble Detection.

Dependencies

This property applies only when you set ThresholdMethod to "fixed".

Data Types: double

AdaptiveThresholdOffset — Adaptive threshold offset

0 (default) | numeric scalar in the range [0, 2]

Adaptive threshold offset to avoid false trigger points, specified as a numeric scalar in the range [0, 2]. For more details, see Internal Architecture of Preamble Detection.

Dependencies

This property applies only when you set ThresholdMethod to "adaptive".

Data Types: double

AdaptiveThresholdGain — Adaptive threshold gain

0 (default) | numeric scalar in the range [0, 64]

Adaptive threshold gain value applied to the average input signal power before adaptive threshold calculation, specified as a numeric scalar in the range [0, 64]. For more details, see Internal Architecture of Preamble Detection.

Dependencies

This property applies only when you set ThresholdMethod to "adaptive".

Data Types: double

TriggerOffset — Trigger point offset

0 (default) | integer in the range [–4095, 4096]

Trigger point offset, specified as an integer in the range [–4095, 4096]. This value specifies the start of data capture relative to the trigger point. For more details, see Thresholding and Triggering.

Note

To update this property, you must stop any ongoing transmission by calling the stopTransmission function on the object. When you update this property, the execution time of the next object function call increases by a few seconds.

Data Types: double

Object Functions

capture	Capture signal of interest from the air upon detection
plotThreshold	Plot preamble detection signals for triggering
transmit	Transmit waveform using preamble or energy detector
stopTransmission	Stop transmission from preamble or energy detector

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

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

Tips

You cannot use save and load to store and reload Wireless Testbench objects. Instead, you can re-create the object with these steps:

1. Write code to create a preambleDetector object with a saved radio setup configuration radio and set the properties.

2. Save the code to a script.

3. Run the script in a new MATLAB^® session with the same saved radio setup configuration.

Algorithms

Internal Architecture of Preamble Detection

This diagram shows a conceptual overview of triggered capture based on preamble detection. The input is an RF signal received from the RF board of the radio.

• The Programmable FIR filter correlates the input signal with a known preamble sequence. To specify the preamble sequence, use the Preamble property.

• The Threshold calculation component provides the threshold for the trigger point generation. For more information on how to adjust the threshold, see Thresholding and Triggering.

• The Capture controller component controls the triggered capture.

  • The Comparator component generates the trigger point, which is the first data sample for which the correlator output power is greater than the threshold.

  • The Data packaging component starts the data capture at the trigger point. To adjust the start of the data capture relative to the trigger point, use the TriggerOffset property.

Thresholding and Triggering

The trigger point is the first data sample for which the correlator output power is greater than the threshold. To calibrate the thresholding and triggering operation:

1. Adjust the gain on the RF signal by using the RadioGain property.

2. Adjust the threshold. You can specify an adaptive threshold or a fixed threshold.

   • For adaptive threshold, set the ThresholdMethod property to "adaptive", then use the AdaptiveThresholdGain property to set the adaptive threshold gain value. To avoid false triggers, adjust the AdaptiveThresholdOffset property.

   • For fixed threshold, set the ThresholdMethod property to "fixed", then use the FixedThreshold property to set the fixed threshold value.

3. Call the plotThreshold object function to display and analyze the correlator output power, threshold, and corresponding trigger points.

By default, data capture stars at the trigger point. To adjust the start of the data capture relative to the trigger point, use the TriggerOffset property.

For example, this figure shows a scenario in which the trigger offset is 0. Therefore, data capture starts at the trigger point.

In this second scenario, the trigger point is the same, but the trigger offset is –9. Therefore, data capture starts at the specified trigger offset.

For an example of how to calibrate the thresholding and triggering operation, see Triggered Capture Using Preamble Detection.

Version History

Introduced in R2022a

R2025a: Create preambleDetector object with radio object

You can now use a radio object as the radio input argument when you create a preambleDetector object.

R2024a: Specify the unit of the capture request timestamp with TimestampUnit

The capture object function can now capture multiple consecutive signals with a preambleDetector object. Set the TimestampUnit property to "sample-clock-cycle" to return the capture function output argument timestamp as an integer number of sample clock cycles.

R2024a: Updates to TriggerOffset property

The valid range of the TriggerOffset property has changed. The trigger offset can now be an integer in the range [–4095, 4096]. In previous releases, the valid range was [-3096,4096].

R2023a: Updates to Preamble property

• The valid length of the preamble sequence specified by the Preamble property has changed. The preamble sequence now must be a vector of length between 4 and 1024. In previous releases, the maximum sequence length depends on the master clock rate that the object automatically selects for the radio based on the sample rate.

• The vector elements of the preamble sequence are now in the range [–1, 1]. In previous releases, you cannot set the vector elements of the preamble sequence to 1.