Main Content

Recover and Analyze Packets in 802.11 Waveform

This example blindly detects, decodes, and analyzes multiple IEEE 802.11a™, IEEE 802.11n™, IEEE 802.11ac™, and IEEE 802.11ax™ 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, and HE ER SU [ 2 ] 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 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, and HE 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™ N310/N320/N321/X310/X410 (requires Wireless Testbench™ and Wireless Testbench Support Package for NI™ USRP Radios)

  • ADALM-PLUTO (requires Communications Toolbox Support Package for Analog Devices® ADALM-Pluto Radio)

  • USRP™ E310/E312 (requires Communications Toolbox Support Package for USRP™ Embedded Series Radio)

  • AD9361/FMCOMMS2/3/4/5 (requires Communications Toolbox Support Package for Xilinx® Zynq®-Based Radio)

  • USRP™ N200/N210/USRP2/N300/B200/B210/X300 (requires Communications Toolbox Support Package for USRP™ Radio)

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 OFDM Beacon Receiver Using Software-Defined Radio (WLAN Toolbox) example for Communication Toolbox Support Package radios or the OFDM Wi-Fi Scanner Using SDR Preamble Detection (WLAN Toolbox) 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 OFDM Beacon Receiver Using Software-Defined Radio (WLAN Toolbox) 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=11×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      "HE-MU"     "Success"        14.98        -39660           5297          "A-MPDU"          -25.353         -12.353   
       5      "Non-HT"    "Success"        13.04        -39437          18657          "Block Ack"       -25.564         -17.118   
       6      "Non-HT"    "Success"        13.07        -29899          20417          "RTS"             -25.082         -16.625   
       7      "Non-HT"    "Success"        13.01         52489          21857          "CTS"             -26.118         -18.372   
       8      "VHT"       "Success"        17.43         62290          23137          "A-MPDU"            -20.9         -10.955   
       9      "Non-HT"    "Success"        14.99        -38861          28337          "RTS"             -27.842         -20.114   
      10      "Non-HT"    "Success"        14.94         42363          29777          "CTS"             -27.409         -19.042   
      11      "HT-MF"     "Success"        15.03         22238          31058          "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"        1      "1342ABC2FF1F"    "00123456789B"           "Success"              "QoS Data"  
     "AMPDU2_MPDU1"        2      "23FFAB1234AC"    "00123456789B"           "Success"              "QoS Data"  
     "AMPDU3_MPDU1"        3      "13EF35781356"    "00123456789B"           "Success"              "QoS Data"  
     "AMPDU4_MPDU1"        4      "159A123AFFFF"    "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 HE.

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 (HE-MU)

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

     L-STF        BPSK               2                                14.59                                   
     L-LTF        BPSK               2                                14.61                                   
     L-SIG        BPSK               1               Pass             14.96         -27.59          -22.62    
     RL-SIG       BPSK               1               Pass             14.86         -27.14          -19.87    
     HE-SIG-A     BPSK               2               Pass             15.37         -26.14          -19.54    
     HE-SIG-B     BPSK               5               Pass             14.98         -27.56          -20.08    
     HE-STF       BPSK               1                                14.95                                   
     HE-LTF       BPSK               2                                15.01                                   
     Data                           35                                14.99         -25.35          -12.35    

Display the signaling field information of the selected packet.

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

        Property        Value          Property          Value          Property            Value 
    ________________    _____    ____________________    _____    ______________________    _____

    L-SIG Length        467      Bandwidth               CBW20    Num HE-LTF Symbols        2    
    L-SIG Rate          0xB      Num HE-SIG-B Symbols    5        LDPC Extra Symbol         True 
    UL/DL Indication    DL       SIGB Compression        False    STBC                      False
    SIGB MCS            0        Guard Interval          3.2      Pre-FEC Padding Factor    1    
    SIGB DCM            False    HE-LTF Type             4        PE Disambiguity           False
    BSS Color           0        Doppler                 False                                   
    Spatial Reuse       0        TXOP                    127                                     

Display the RU information.

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

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

      "RU1"        52                 -121                       -70                  1           1          8.98    
      "RU2"        52                  -68                       -17                  1           1          8.96    
      "RU3"        52                   17                        68                  1           2          8.97    
      "RU4"        52                   70                       121                  1           1          8.97    

Display the user information.

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

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

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

Display EVM per spatial streams for all users.

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

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

      1               1                -26.391         -17.295   
      2               1                -27.401         -19.682   
      3               1                -23.564         -12.353   
      3               2                -23.122         -14.444   
      4               1                -27.278         -17.793   

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 8 objects of type line. One or more of the lines displays its values using only markers These objects represent STAID 1, STAID 2, STAID 3, STAID 4, 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 number, ylabel EVM (dB) contains 4 objects of type line. These objects represent STAID 1, STAID 2, STAID 3, STAID 4.

 

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

Plot the spectral flatness for 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 (WLAN Toolbox), Recovery Procedure for an 802.11ax Packet (WLAN Toolbox) and Recovery Procedure for an 802.11ac Packet (WLAN Toolbox) 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 6: Enhancements for High Efficiency WLAN.

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" "AD936x" "FMCOMMS5" "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

See Also

Functions

Objects

Related Topics