%% 802.11 MAC Frame Generation
% This example shows how to generate IEEE(R) 802.11(TM) MAC frames.

% Copyright 2018-2019 The MathWorks, Inc.

%% Introduction
% This example shows how WLAN MAC frames specified in Section 9 of [ <#22
% 1> ] and [ <#22 2> ] can be generated and exported to a packet capture
% (PCAP) file for analysis with third party packet analysis tools. In this
% example Wireshark [ <#22 3> ] is used to verify the content of MAC frames
% is as expected.
%
% <<../MACFrameGeneration.png>>
%
% The general MAC frame format consists of a header, frame-body, and frame
% check sequence (FCS). The header holds information about the frame. The
% frame-body carries data that needs to be transmitted. The transmitter
% calculates the FCS over the header and frame-body. The receiver uses the
% FCS to confirm that the header and frame-body are properly received. The
% following diagram shows the structure of a general MAC frame.
%
% <<../MACFrameFormat.png>>
%
% The standard specifies four types of frames: Management, Data, Control,
% and Extension. There are multiple subtypes of each frame type. These are
% identified by the _Type_ and _Subtype_ fields of the frame control field
% in the MAC header.
%
% *Management Frames:*
%
% * Frames that are used for connection establishment and maintenance.
% * These frames carry the information fields and elements that indicate
% the capabilities and configuration of the device operating in the 802.11
% network. While establishing the connection, these information fields and
% elements are communicated between the devices to match capabilities of
% both devices.
% * The MAC layer adds header and FCS to the frame-body carrying the
% information to form a MAC protocol data unit (MPDU).
%
% *Data Frames:* 
%
% * Frames that are used to transmit the higher-layer data.
% * The payload given to the MAC layer is termed MAC service data unit
% (MSDU). The MAC layer adds header and FCS to the MSDU to form a MAC
% protocol data unit (MPDU).
% * To improve the throughput, WLAN supports aggregated MSDUs (A-MSDUs) and
% aggregated MPDUs (A-MPDUs) as specified in Sections 9.3.2.2, 9.7 of [
% <#22 1> ] and [ <#22 2> ].
% * If MSDU aggregation is enabled, multiple MSDUs are aggregated to form
% an A-MSDU and then the MAC header and FCS are added to an A-MSDU to form
% an MPDU.
% * If MPDU aggregation is enabled, multiple MPDUs are aggregated to form
% an A-MPDU.
%
% *Control Frames:* 
%
% * Frames that are used to support the delivery of data, management, and
% extension frames.
% * Each control frame has a specific functionality. For example, control
% frames like request-to-send (RTS) and clear-to-send (CTS) help in
% reserving the channel to avoid collisions, while Ack frames help in
% recognizing successful transmission.
%
% *Extension Frames:* 
%
% * This frame type is an extension to the three frame types defined above.
% * DMG Beacon is the only frame currently specified under this frame type
% in [ <#22 1> ].
%
% You can use the <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a
% wlanMACFrame> function to generate MAC frames. This function accepts a
% MAC frame configuration object
% <docid:wlan_ref#mw_a004c76e-748e-42b5-84b2-360a063ea1f9
% wlanMACFrameConfig> as an input. This object configures the fields in the
% MAC header. Set the |FrameType| property to the desired _Subtype
% description_ in Table 9-1 of [ <#22 1> ] to set the appropriate _Type_
% and _Subtype_ fields in the MAC header. The
% <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a wlanMACFrame>
% function supports the generation of following MPDUs.
%
% * *Management Frames:* Beacon
% * *Data Frames:* Data, Null, QoS Data, QoS Null
% * *Control Frames:* RTS, CTS, Ack, Block Ack
%
% In addition to the above MPDUs,
% <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a wlanMACFrame>
% also supports generation of A-MPDUs containing MPDUs of type |QoS Data|.

%% Control Frame Generation
% To generate an RTS frame, create a MAC frame configuration object with
% the |FrameType| set to |'RTS'|.

rtsCfg = wlanMACFrameConfig('FrameType', 'RTS');
disp(rtsCfg);

%%
% Configure the frame header fields.

% Duration
rtsCfg.Duration = 500;
% Receiver address 
rtsCfg.Address1 = 'FCF8B0102001';
% Transmitter address
rtsCfg.Address2 = 'FCF8B0102002';

%%
% Generate an RTS frame using the configuration.

% Generate octets for an RTS frame
rtsFrame = wlanMACFrame(rtsCfg);

%%
% By default, the output of
% <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a wlanMACFrame> is
% a sequence of hexadecimal octets. If you want to generate the MAC frame
% as a sequence of bits, set the |OutputFormat| parameter to |bits|.

% Generate bits for an RTS frame
rtsFrameBits = wlanMACFrame(rtsCfg, 'OutputFormat', 'bits');

%% Data Frame Generation
% To generate a QoS Data frame, create a MAC frame configuration object
% with the |FrameType| set to |'QoS Data'|.

qosDataCfg = wlanMACFrameConfig('FrameType', 'QoS Data');
disp(qosDataCfg);

%%
% Configure the frame header fields.

% From DS flag
qosDataCfg.FromDS = 1;
% To DS flag
qosDataCfg.ToDS = 0;
% Acknowledgment Policy
qosDataCfg.AckPolicy = 'Normal Ack';
% Receiver address 
qosDataCfg.Address1 = 'FCF8B0102001';
% Transmitter address
qosDataCfg.Address2 = 'FCF8B0102002';

%%
% The QoS Data frame is used to transmit a payload from higher-layer. A
% 20-byte payload containing a repeating sequence of hexadecimal value '11'
% is used in this example.

payload = repmat('11', 1, 20);

%%
% Generate a QoS Data frame using payload and configuration.

% Generate octets for a QoS Data frame
qosDataFrame = wlanMACFrame(payload, qosDataCfg);

%%
% By default, the output of
% <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a wlanMACFrame> is
% a sequence of hexadecimal octets. If you want to generate the MAC frame
% as a sequence of bits, set the |OutputFormat| parameter to |bits|.

% Generate bits for a QoS Data frame
qosDataFrameBits = wlanMACFrame(payload, qosDataCfg, 'OutputFormat', 'bits');

%%
% The output MAC frame is an MPDU with a single MSDU. Refer to the example
% <docid:wlan_examples#example-VHTWaveformGenerationExample 802.11ac Waveform Generation with MAC
% Frames> for A-MSDU and A-MPDU generation.

%% Management Frame Generation
% To generate a Beacon frame, create a MAC frame configuration object with
% the |FrameType| set to |'Beacon'|.

beaconCfg = wlanMACFrameConfig('FrameType', 'Beacon');
disp(beaconCfg);

%%  
% Beacon frame-body consists of information fields and information elements
% as explained in Section 9.3.3.3 of [ <#22 1> ]. You can configure these
% information fields and elements using
% <docid:wlan_ref#mw_083f69be-10d7-4935-9f2e-e487f2aa75a9
% wlanMACManagementConfig>.

% Create a management frame-body configuration object
frameBodyCfg = wlanMACManagementConfig;
disp(frameBodyCfg);

%%
% Configure the information fields and elements in the frame-body
% configuration. You can add information elements using |addIE(elementID,
% information)| method as shown below. Refer Section 9.4 in [ <#22 1> ] for
% the list of information fields and information elements.

% Beacon Interval
frameBodyCfg.BeaconInterval = 100;
% Timestamp
frameBodyCfg.Timestamp = 123456;
% SSID
frameBodyCfg.SSID = 'TEST_BEACON';
% Add DS Parameter IE (element ID - 3) with channel number 11 (0x0b)
frameBodyCfg = frameBodyCfg.addIE(3, '0b');

%%
% Assign the updated frame-body configuration object to the
% |ManagementConfig| property in the MAC frame configuration.

% Update management frame-body configuration
beaconCfg.ManagementConfig = frameBodyCfg;

%%
% Generate the Beacon frame with the updated frame configuration.

% Generate octets for a Beacon frame
beaconFrame = wlanMACFrame(beaconCfg);

%%
% By default, the output of
% <docid:wlan_ref#mw_9f2e549d-99ee-49ae-b9c3-3a78e29a6c1a wlanMACFrame> is
% a sequence of hexadecimal octets. If you want to generate the MAC frame
% as a sequence of bits, set the |OutputFormat| parameter to |bits|.

% Generate bits for a Beacon frame
beaconFrameBits = wlanMACFrame(beaconCfg, 'OutputFormat', 'bits');

%% Exporting to a PCAP File
% The generated frames are exported to a PCAP file, which can be analyzed
% and visualized with a third party packet analyzer such as Wireshark. The
% helper function <matlab:edit('helperWLANExportToPCAP')
% helperWLANExportToPCAP> generates a PCAP file containing WLAN MAC frames.

% Export the generated MAC frames to a PCAP file
helperWLANExportToPCAP({rtsFrame, qosDataFrame, beaconFrame}, 'macFrames.pcap');

%% Visualization of the Generated MAC Frames
% You can open the PCAP files containing the generated MAC frames in a
% packet analyzer. The frames decoded by the Wireshark match the standard
% compliant MAC frames generated using WLAN Toolbox. The captured analysis
% of the frames in Wireshark is shown below.
%
% * *RTS frame*
%
% <<../MACRTSFrame.png>>
%
% * *QoS Data frame*
%
% <<../MACQoSDataFrame.png>>
%
% * *Beacon frame*
%
% <<../MACBeaconFrame.png>> 

%% Conclusion and Further Exploration
% This example demonstrated generation of MAC frames for the IEEE 802.11
% standard. You can use a packet analyzer to view the generated MAC frames.
% Alternatively, the generated MAC frames can be used to transmit over air
% as demonstrated in the examples
% <docid:wlan_examples#example-BeaconFrameGenerationExample 802.11 OFDM
% Beacon Frame Generation> and
% <docid:wlan_examples#example-VHTWaveformGenerationExample 802.11ac
% Waveform Generation with MAC Frames>.

%% Appendix
% This example uses the following helper function:
%
% * <matlab:edit('helperWLANExportToPCAP') helperWLANExportToPCAP>

%% Selected Bibliography
% # IEEE Std 802.11(TM)-2016 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
% # IEEE P802.11ax(TM)/D4.1 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 6: Enhancements for High Efficiency WLAN
% # Wireshark software: https://www.wireshark.org/