energyDetector

Configure SDR as energy detector

Since R2023b

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

Description

Use the energyDetector object to configure the specified software-defined radio (SDR) as an energy detector. You can use the energy detector to detect and capture a signal of interest from the air using an increase in signal energy as the trigger. The object specifies the energy threshold and triggering parameters. For details, see Internal Architecture of Energy Detection.

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

ed = energyDetector(radio)

ed = energyDetector(radio,Name=Value)

Description

ed = energyDetector(radio) creates an energy detector configuration 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 object associated with the specified radio from the workspace.

ed = energyDetector(radio,Name=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 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	"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 plotDetectionSignals 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

WindowLength — Energy integration window length

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

Energy integration window length, specified as a numeric scalar in the range [0, 4095]. The number of samples in the sliding window that is used to calculate the signal energy and the energy increase. For details, see Thresholding and Triggering.

Data Types: double

ThresholdMethod — Threshold calculation method

"adaptive" (default) | "fixed"

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

• "adaptive" — Two thresholds must be met to trigger a data capture. The energy increase in dB, which is the ratio between the signal energy in the current window and the signal energy in the previous window, is compared against a constant threshold specified by the EnergyDeltaThreshold property. The signal energy is also compared against a constant threshold, specified by the MinimumEnergy property. Together, these thresholds are adaptive to channel noise.

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

For details, see Algorithms.

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

1e-4 (default) | numeric scalar in the range [0, 8191]

Fixed threshold value, specified as a numeric scalar in the range [0, 8191]. For details, see Thresholding and Triggering.

Dependencies

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

Data Types: double

MinimumEnergy — Minimum energy threshold value

1e-4 (default) | numeric scalar in the range [0, 8191]

Minimum energy threshold value, specified as a numeric scalar in the range [0, 8191]. This value is the minimum energy at which the EnergyDeltaThreshold is applied in adaptive threshold mode. Set this threshold relative to the noise floor so that noise variations under this level do not cause false triggers. For details, see Thresholding and Triggering.

Dependencies

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

Data Types: double

EnergyDeltaThreshold — Energy increase threshold in dB

1 (default)

Energy delta threshold, specified as the energy increase threshold in dB. This value is the ratio between the signal energy in the current window and the signal energy in the previous window, expressed in decibels. Set this threshold relative to the WindowLength property. For example:

• An energy increase of 3 dB corresponds to a two-fold increase in signal energy between two adjacent windows.

• An energy increase of 20 dB corresponds to a one-hundred-fold increase in signal energy between two adjacent windows.

For details, see Thresholding and Triggering.

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 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
plotDetectionSignals	Plot energy detection signals for triggering
transmit	Transmit waveform using preamble or energy detector
stopTransmission	Stop transmission from preamble or energy detector

Examples

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

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 energyDetector 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 Energy Detection

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

• The Data integration component calculates the energy in the received signal by integrating the input data over the window length specified by the WindowLength property. This component also calculates the signal energy in the previous window, and the ratio between the signal energy in the current window and the signal energy in the previous window.

• The Threshold component provides two thresholds for the trigger point generation. The energy threshold is set by the MinimumEnergy property when the ThresholdMethod property is set to "adaptive", or the FixedThreshold property when the ThresholdMethod is set to "fixed". This component also calculates the ratio threshold by converting the EnergyDeltaThreshold property from a dB value to a ratio.

• The Capture controller component controls the triggered capture.

  • The Comparators generate the trigger point using the energy threshold and the ratio threshold when the ThresholdMethod property is set to "adaptive", or the energy threshold only when the ThresholdMethod property is set to "fixed". The trigger point is the first data sample for which thresholding conditions have been met.

  • The Data packaging component starts the data capture. 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 thresholding conditions are met. 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.

   • To trigger data capture on an increase in signal energy, set the ThresholdMethod property to "adaptive". The energy increase in dB is calculated by finding the ratio between the energy in the current window and the energy in the previous window, and converting to dB. Set the MinimumEnergy and EnergyDeltaThreshold properties. The figure shows an example of a signal energy measurement and the associated thresholds that leads to a detection.

   • To trigger data capture when the signal energy crosses a fixed threshold, set the ThresholdMethod property to "fixed", and then use the FixedThreshold property to set the fixed threshold value.

3. Call the plotDetectionSignals object function to display and analyze the signals, thresholds, and corresponding trigger points.

By default, data capture starts 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 first detection point.

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

Version History

Introduced in R2023b

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

The capture object function can now capture multiple consecutive signals with an energyDetector 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.