preambleDetector
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
Description
creates a preamble detector configuration object for the specified
radio, pd
= preambleDetector(radio
)radio
.
Note
The object requires exclusive access to radio hardware resources. Before creating this object, clear any existing Wireless Testbench object associated with the specified radio from the workspace.
sets properties using one or more name-value arguments. For
example, pd
= preambleDetector(radio
,Name=Value
)CaptureDataType="double"
sets the data
type of the returned captured signal to
double
.
Input Arguments
radio
— Radio setup configuration
string scalar
Radio setup configuration, specified as a string scalar. To create a radio setup
configuration, set up your radio and save your radio setup configuration using the Radio Setup
wizard. To list all saved radio setup configurations, call the radioConfigurations
function.
For a list of supported radios, see Supported Radio Devices.
Example: "MyRadio"
indicates that you saved a radio setup
configuration under the name MyRadio in the Radio Setup wizard.
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 |
|
RFB channel: RX2 port |
| |
USRP X310 | RFA channel: RX2 port |
|
RFB channel: RX2 port |
| |
USRP X410 | DB0 RF0 channel: RX 1 port |
|
DB0 RF1 channel: RX 1 port |
| |
DB1 RF0 channel: RX 1 port |
| |
DB1 RF1 channel: RX 1 port |
|
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 |
|
USRP N310 | |
USRP N320 |
|
USRP N321 | |
USRP X300 |
|
USRP X310 | |
USRP X410 |
|
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 theAdaptiveThresholdGain
andAdaptiveThresholdOffset
properties."fixed"
— The threshold is a constant, specified by theFixedThreshold
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:
Write code to create a
preambleDetector
object with a saved radio setup configurationradio
and set the properties.Save the code to a script.
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:
Adjust the gain on the RF signal by using the
RadioGain
property.Adjust the threshold. You can specify an adaptive threshold or a fixed threshold.
For adaptive threshold, set the
ThresholdMethod
property to"adaptive"
, then use theAdaptiveThresholdGain
property to set the adaptive threshold gain value. To avoid false triggers, adjust theAdaptiveThresholdOffset
property.For fixed threshold, set the
ThresholdMethod
property to"fixed"
, then use theFixedThreshold
property to set the fixed threshold value.
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 R2022aR2024a: 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
.
See Also
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)