Main Content

Recover and Analyze Packets in 802.11 Waveform

This example uses:

Open Live Script

This example blindly detects, decodes, and analyzes multiple IEEE 802.11a™, IEEE 802.11n™ (Wi-Fi 4), IEEE 802.11ac™ (Wi-Fi 5), IEEE 802.11ax™ (Wi-Fi 6), and IEEE 802.11be™ (Wi-Fi 7) packets in a waveform. The example provides a summary of the detected packets and displays the MAC contents, error vector magnitude (EVM), power, and signaling information for a selected packet.

Introduction

In this example, you detect, decode, and analyze multiple packets within a waveform. This example can decode OFDM non-HT, non-HT duplicate, HT, VHT [ 1 ], HE MU, HE SU, HE ER SU [ 2 ], and EHT MU [ 3 ] packet formats. The receiver does not know any transmission parameters, except for the channel bandwidth. It retrieves these parameters by decoding the preamble fields of the packet.

  • The spectrum and time domain samples.

  • The signaling field contents.

  • The resource unit and user information for an EHT or HE waveform.

  • The constellation of the equalized data symbols.

  • The EVM of the signaling fields.

  • The EVM per data subcarrier averaged over spatial streams and symbols.

  • The EVM per data symbol averaged over spatial streams and subcarriers.

  • The spectral flatness for non-OFDMA packets.

  • The MAC frame contents: A-MPDU deaggregation status, Address1, Address2, Frame Check Sequence (FCS) and Frame Type.

Setup Waveform Recovery Parameters

This example analyzes I/Q data containing non-HT, HT-MF, VHT, HE, and EHT packets. The useSDR variable controls the data source for this example:

  • When you select useSDR, an SDR captures an off-the-air waveform.

  • When you clear useSDR, comm.BasebandFileReader reads a synthetic waveform stored in a binary file format.

useSDR = false;

Reception with an SDR Device

This example uses SDRs supported by Wireless Testbench™ and SDRs supported by Communication Toolbox™ support packages. This list provides information on which radios can be used by this example along with the required products.

  • USRP™ N3xx series or X series (requires Wireless Testbench™ and Wireless Testbench Support Package for NI™ USRP Radios). For more information, see Supported Radio Devices (Wireless Testbench).

  • ADALM-PLUTO (requires Communications Toolbox Support Package for Analog Devices® ADALM-Pluto Radio). For more information, see ADALM-Pluto Radio.

  • USRP™ E310/E312 (requires Communications Toolbox Support Package for USRP™ Embedded Series Radio). For more information, see USRP Embedded Series Radio.

  • USRP™ 200 series (requires Communications Toolbox Support Package for USRP™ Radio). For more information, see USRP Radio and Supported Hardware and Required Software.

See the relevant documentation for the chosen product and SDR on set up and installation.

Select SDR Device and Capture Antenna(s)

When you select an SDR as the data source, specify the device name from the dropdown along with the capture antenna configuration.

If using an NI USRP hardware with Wireless Testbench, click Update to see your saved radio setup configuration name appear at the top of the dropdown list.

if useSDR %#ok<*UNRCH>
    deviceOptions    = getDeviceOptions;
    deviceName       = deviceOptions(1) ;
    antennaOptions   = getAntennaOptions(deviceName);
    antennaSelection = antennaOptions(1);
end

Specify Capture Parameters and Initiate Capture

After configuring deviceName and antennaSelection, specify the frequency band, channel number, capture duration, expected channel bandwidth of packets, radio sample rate, and radio gain.

To determine which channels in the 5 GHz band contain traffic from commercial 802.11 hardware, use the WLAN Beacon Receiver Using Software-Defined Radio example for Communication Toolbox Support Package radios or the OFDM Wi-Fi Scanner Using SDR Preamble Detection example for Wireless Testbench radios. 

if useSDR
    frequencyBand = 5; % Frequency band
    channelNumber = 102; % WLAN channel number
    captureTime   = milliseconds(100); % Signal capture duration, to be specified as a duration type (e.g. seconds(1))
    chanBW        = 'CBW20'; % Channel bandwidth of all packets within the waveform
    sr            = 20000000; % Radio sample rate
    gain          = 50; % Radio gain

    % Set the center frequency to the corresponding channel number. The
    % center frequency should be centered on the channel bandwidth.
    fc = wlanChannelFrequency(channelNumber,frequencyBand);

    % Create SDR variable (if one does not exist already) and initiate waveform capture
    if ~exist('rx','var')
        rx = [];
    end
    rx = getSDRObject(deviceName,antennaSelection,fc,sr,gain,rx);
    rxWaveform = capture(rx,captureTime);
end

Import a Captured Waveform from a File

If using a precaptured waveform as the data source, this section shows how to load I/Q data from an existing binary file using comm.BasebandFileReader. The baseband file format includes the sample rate and the number of channels in the captured waveform. Alternatively, you can load the waveform from a MAT file.

% Configure the analysis source
if ~useSDR
    BBR = comm.BasebandFileReader('wlanWaveform.bb'); % Create a baseband file reader object
    chanBW = 'CBW20'; % Channel bandwidth of all packets within the waveform
    bbrInfo = info(BBR);
    BBR.SamplesPerFrame = bbrInfo.NumSamplesInData; % Number of samples in the waveform
    rxWaveform = BBR();  % Load the I&Q sample from a binary file
    sr = BBR.SampleRate; % Sampling rate of the input signal
    release(BBR);
end

To recover beacon packets from a MAT-file, see the WLAN Beacon Receiver Using Software-Defined Radio example.

Signal Recovery and Analysis

This section detects, analyzes, and displays a summary of the detected packets. All packets in the waveform must have the specified channel bandwidth. Parse and analyze the packets within a waveform by using the WaveformAnalyzer object.

analyzer = WaveformAnalyzer;
process(analyzer,rxWaveform,chanBW,sr);

Display a summary of the detected packets.

detectionSummary(analyzer);
                                                                           Summary of the Detected Packets

detSummary=14×9 table
    Number     Format     PHY Status    Power (dBm)    CFO (Hz)    Offset (samples)    MAC Contents    RMS EVM (dB)    Max EVM (dB)
    ______    ________    __________    ___________    ________    ________________    ____________    ____________    ____________

       1      "Non-HT"    "Success"         12.7         61431             97          "Beacon"          -25.824         -17.272   
       2      "Non-HT"    "Success"        13.08        -39757           2577          "RTS"             -24.937         -17.737   
       3      "Non-HT"    "Success"        13.01         62250           4017          "CTS"             -26.181         -18.982   
       4      "EHT-MU"    "Success"        12.38         61932           5199          "A-MPDU"          -28.127         -18.167   
       5      "Non-HT"    "Success"        12.84         62015          14199          "RTS"             -29.565         -21.111   
       6      "Non-HT"    "Success"        12.82         61806          15639          "CTS"             -29.417         -21.095   
       7      "HE-MU"     "Success"        14.98        -39660          17118          "A-MPDU"          -25.353         -12.353   
       8      "Non-HT"    "Success"        13.04        -39437          30478          "Block Ack"       -25.564         -17.118   
       9      "Non-HT"    "Success"        13.07        -29899          32238          "RTS"             -25.082         -16.625   
      10      "Non-HT"    "Success"        13.01         52489          33678          "CTS"             -26.118         -18.372   
      11      "VHT"       "Success"        17.43         62290          34958          "A-MPDU"            -20.9         -10.957   
      12      "Non-HT"    "Success"        14.99        -38861          40158          "RTS"             -27.842         -20.114   
      13      "Non-HT"    "Success"        14.94         42363          41598          "CTS"             -27.409         -19.042   
      14      "HT-MF"     "Success"        15.03         22238          42879          "A-MPDU"           -26.55         -17.287

Use the pktNum variable to display the MAC and PHY analysis for a selected packet.

pktNum = 4 ;

Display the MAC information of the selected packet.

macSummary(analyzer,pktNum);
 
                                    Recovered MPDU Summary of Packet 4

    AMPDU/MPDU Number    STAID       Address1          Address2       AMPDU/MPDU Decode Status    MAC Frame Type
    _________________    _____    ______________    ______________    ________________________    ______________

     "AMPDU1_MPDU1"        0      "23AFABC2FA1F"    "00123456789B"           "Success"              "QoS Data"  
     "AMPDU2_MPDU1"        1      "1432ABC2BD1C"    "00123456789B"           "Success"              "QoS Data"  
     "AMPDU3_MPDU1"        2      "3142BAC2AB1F"    "00123456789B"           "Success"              "QoS Data"

Display the time samples and spectrum of the detected packet.

plotWaveform(analyzer,pktNum)

Figure contains an axes object. The axes object with title Power of time-domain samples (packet 4), xlabel Samples, ylabel Power (dBm) contains 9 objects of type line, area. This object represents EHT.

Figure contains an axes object. The axes object with title Power spectrum (packet 4), xlabel Frequency (MHz), ylabel Power (dBm) contains an object of type line.

Display the packet field information of the selected packet.

fieldSummary(analyzer,pktNum);
 
                                           Field Summary of Packet 4 (EHT-MU)

    Field Name    Modulation    Num Symbols    Parity Check/CRC    Power (dBm)    RMS EVM (dB)    Max EVM (dB)
    __________    __________    ___________    ________________    ___________    ____________    ____________

     L-STF        BPSK               2                                14.52                                   
     L-LTF        BPSK               2                                14.37                                   
     L-SIG        BPSK               1               Pass             14.23         -31.43          -25.23    
     RL-SIG       BPSK               1               Pass             14.19         -32.40          -27.57    
     U-SIG        BPSK               2               Pass             14.55         -32.24          -25.35    
     EHT-SIG      BPSK               5               Pass             14.84         -31.78          -20.02    
     EHT-STF      BPSK               1                                12.11                                   
     EHT-LTF      BPSK               1                                11.98                                   
     Data                           23                                11.98         -28.13          -18.17

Display the signaling field information of the selected packet.

signalingSummary(analyzer,pktNum);
 
                               Signaling Field Summary of Packet 4 (EHT-MU)

        Property           Value              Property           Value     Property        Value   
    ________________    ___________    ______________________    _____    ____________    ________

    L-SIG Length        312            Num EHT-SIG Symbols       5        PPDU Type       DL OFDMA
    L-SIG Rate          0xB            Spatial Reuse             0        EHT DUP Mode    False   
    Bandwidth           CBW20          Guard Interval            3.2                              
    UL/DL Indication    DL             EHT-LTF Type              4                                
    BSS Color           0              Num EHT-LTF Symbols       1                                
    TXOP                Unspecified    LDPC Extra Symbol         True                             
    Compression Mode    0              Pre-FEC Padding Factor    4                                
    EHT-SIG MCS         0              PE Disambiguity           False

Display the RU information.

ruSummary(analyzer,pktNum);
 
                                    Resource Unit (RU) Information of Packet 4 (EHT-MU)

    RU Number    RU/MRU Size    Subcarrier Index (Start)    Subcarrier Index (End)    Num Users    Num STS    Power (dBm)
    _________    ___________    ________________________    ______________________    _________    _______    ___________

      "RU1"        26                     -121                       -96                  1           1          2.36    
      "RU2"        52+26                   -95                       -17                  1           1          7.15    
      "RU3"        106+26                  -16                       122                  1           1          9.41

Display the user information.

userSummary(analyzer,pktNum);
 
                                      User Information of Packet 4 (EHT-MU)

    STAID    RU Number    MCS    Modulation    Code Rate    Channel Coding    Num STS    Transmit Beamforming
    _____    _________    ___    __________    _________    ______________    _______    ____________________

      0        "RU1"       2      "QPSK"         "3/4"          "LDPC"           1                0          
      1        "RU2"       4      "16QAM"        "3/4"          "LDPC"           1                0          
      2        "RU3"       6      "64QAM"        "3/4"          "LDPC"           1                0

Display EVM per spatial streams for all users.

userEVM(analyzer,pktNum);
 
          User EVM per Spatial Stream of Packet 4 (EHT-MU)

    STAID    Spatial Stream Index    RMS EVM (dB)    Max EVM (dB)
    _____    ____________________    ____________    ____________

      0               1                -27.928         -19.943   
      1               1                -28.229         -18.167   
      2               1                -28.228         -18.687

Plot the constellation for all users.

plotConstellation(analyzer,pktNum);

Figure contains an axes object. The axes object with title Equalized data symbols (packet 4), xlabel In-phase Amplitude, ylabel Quadrature Amplitude contains 6 objects of type line. One or more of the lines displays its values using only markers These objects represent STAID 0, STAID 1, STAID 2, Ref.

Plot the EVM.

plotEVM(analyzer,pktNum);

Figure contains an axes object. The axes object with title Average EVM (RMS) per data subcarrier (packet 4), xlabel Subcarrier index, ylabel EVM (dB) contains 3 objects of type line. These objects represent STAID 0, STAID 1, STAID 2.

Figure contains an axes object. The axes object with title Average EVM (RMS) per symbol (packet 4), xlabel Symbol number, ylabel EVM (dB) contains 3 objects of type line. These objects represent STAID 0, STAID 1, STAID 2.

Plot the spectral flatness of non-punctured, non-OFDMA packets.

plotSpectralFlatness(analyzer,chanBW,pktNum);

Further Exploration

The WaveformAnalyzer provides properties to control the pilot tracking, equalization, DC blocking, and packet detection algorithms that can be tweaked to improve packet detection and analysis performance.

False packet detections

False packet detections are detected packets that you do not believe are actual packets. Evaluating the time domain waveform of the packet is one way to determine if the detected packet is legitimate. If there is a significant number of false detections present these techniques may help reduce them:

  • Enable the EnergyDetection property and set the EnergyDetectionThreshold property to a suitable value given the noise floor of the capture device. When enabled, EnergyDetection only detects packets with a power exceeding EnergyDetectionThreshold during the preamble.

  • Increase the LLTFSNRDetectionThreshold and PacketDetectionThreshold properties to discard packets with a low measured SNR during detection.

Missed packet detections

Missed packet detections are packets that you believe are in the waveform but have not been detected.

  • One possible reason a packet detection may have been missed is if a false detection occurred earlier in the waveform, but the L-SIG check passed, causing samples to be skipped. To search for possible false detections, enable the SearchWithinUnsupportedPacket property.

  • Alternatively try decreasing the PacketDetectionThreshold property to detect packet with low SNR during detection.

For detail on 802.11be, 802.11ax, 802.11ac signal recovery and processing, see the Recovery Procedure for an 802.11be Packet, Recovery Procedure for an 802.11ax Packet and Recovery Procedure for an 802.11ac Packet examples.

References

  1. IEEE Std 802.11™ - 2020 IEEE Standard for Information technology - Telecommunications and information exchange between systems - Local and metropolitan area networks - Specific requirements - Part 11: Wireless LAN Medium Access Control (MAC) and Physical Layer (PHY) Specifications.

  2. IEEE 802.11ax™ - 2021 IEEE Standard for Information technology - Telecommunications and information exchange between systems - Local and metropolitan area networks - Specific requirements - Part 11: Wireless LAN Medium Access Control (MAC) and Physical Layer (PHY) Specifications - Amendment 1: Enhancements for High Efficiency WLAN.

  3. IEEE P802.11be™/D4.0 Draft Standard for Information technology - Telecommunications and information exchange between systems Local and metropolitan area networks - Specific requirements - Part 11: Wireless LAN Medium Access Control (MAC) and Physical Layer (PHY) Specifications - Amendment 8: Enhancements for extremely high throughput (EHT).

Local Functions

These functions assist in SDR set up.

function options = getDeviceOptions
% GETDEVICEOPTIONS returns a string array with all saved Wireless
% Testbench radio configurations and Communication toolbox support package
% SDRs
spkgSDRs = getSupportPackageSDRs;

% Check for WT configurations if user has WT installed and a valid license
if ~isempty(ver('wt')) && license('test','Wireless_Testbench')
    savedRadioConfigurations = radioConfigurations;
    savedRadioConfigurationNames = [string({savedRadioConfigurations.Name})];
else
    savedRadioConfigurationNames = [];
end

options = [savedRadioConfigurationNames spkgSDRs];
end

function options = getAntennaOptions(deviceName)
%GETANTENNAOPTIONS returns a string array of valid antenna configurations
%for a specified DEVICENAME
% Acquire valid antenna values based on radio
if ~matches(deviceName,getSupportPackageSDRs)
    antennas = hCaptureAntennas(deviceName);
elseif matches(deviceName,["X300","FMCOMMS5"])
    antennas = [1 2 3 4]';
elseif matches(deviceName,["Pluto", "B200", "N200/N210/USRP2"])
    antennas = 1;
else
    antennas = [1 2]';
end

% Generate a string array list of all valid antenna configurations
options = strings(0,1);
for a = 1:length(antennas)
    % Generate unique combinations
    AntennaCombinations = nchoosek(antennas,a);
    % Generate list of all unique combinations
    for i = 1:size(AntennaCombinations, 1)
        options = [options;string(mat2str(AntennaCombinations(i,:)))]; %#ok<AGROW>
    end
end
end

function spkgSDRs = getSupportPackageSDRs
%GETSUPPORTPACKAGESDRs returns a string array of Communication Toolbox
%support package SDRs that are supported for this example
spkgSDRs = ["Pluto" "E3xx" "B200" "B210" "N200/N210/USRP2" "N300" "X300"];
end

function rx = getSDRObject(deviceName,antennas,fc,sr,gain,rx)
%GETSDROBJECT returns a Wireless Testbench basebandReceiver object
%or an hSDRReceiver object with the properties of the object set according
%to the input parameters

% Create SDR object for waveform capture and set object's properties
if matches(deviceName,getSupportPackageSDRs)
    rx = hSDRReceiver(deviceName);
    rx.OutputDataType = 'double';
    rx.ChannelMapping = eval(antennas);
    rx.Gain = gain;
else % Wireless Testbench hardware
    % Keep existing basebandReceiver object for performance purposes
    if ~isa(rx,'basebandReceiver')
        rx = basebandReceiver(deviceName);
    end
    rx.CaptureDataType = 'double';
    rx.Antennas = eval(antennas);
    rx.RadioGain = gain;
end
rx.SampleRate = sr;
rx.CenterFrequency = fc;
end