wlanPCAPWriter

PCAP or PCAPNG file writer of WLAN MAC packets

Description

The wlanPCAPWriter object writes generated and recovered WLAN medium access control (MAC) packets to a packet capture (PCAP) or packet capture next generation (PCAPNG) file (.pcap or .pcapng, respectively). The object captures packets at the MAC layer as you send them to the PHY for transmission or receive them at the MAC layer after recovery from the PHY. Note that, this object also requires the Wireless Network Toolbox™ product.

Creation

Syntax

obj = wlanPCAPWriter

obj = wlanPCAPWriter(PropertyName=Value)

Description

obj = wlanPCAPWriter creates a default WLAN PCAP or PCAPNG file writer object that writes WLAN MAC packets to a PCAP or PCAPNG file, respectively.

obj = wlanPCAPWriter(PropertyName=Value) sets Properties using one or more name-value pairs. Enclose each property name in quotes. For example, ('FileExtension','pcapng') sets the extension of the file as .pcapng.

Properties

Note

The wlanPCAPWriter object does not overwrite the existing PCAP or PCAPNG file. During each call of this object, specify a unique PCAP or PCAPNG file name.

FileName — Name of the PCAP or PCAPNG file

"wlanCapture" (default) | character row vector | string scalar | string vector

This property is read-only after object creation.

Name of the PCAP or PCAPNG file, specified as a character row vector, a string scalar, or a string vector. If you do not specify the value of the Node property, the default file name is "wlanCapture". If you specify the value of Node property, the object formats the default file name as NodeName_NodeID_Band_ChannelNumber_Timestamp, where:

• NodeName — Name of the node.

• NodeID — Unique identifier of the node.

• Band — Band reflects the configured band of the WLAN node, and can be either 2G4 (2.4 GHz), 5G (5 GHz), or 6G (6 GHz).

• ChannelNumber — Channel number follows the format CHX, where X is the configured channel number of the WLAN node.

• Timestamp — Timestamp follows the format yyyyMMdd_HHmmss, where yyyyMMdd represents year, month, and day and HHmmss represents hour, minute, and second.

If the DeviceConfig property of a node has multiple wlanDeviceConfig objects configured, or a wlanMultilinkDeviceConfig object with multiple links configured, the object returns the default file name as a vector of strings. Each element in the vector specifies the file name for a particular device or link.

When you specify the Node input and set FileExtension to"pcapng", the object formats the default file name as NodeName_NodeID_Timestamp.

When you specify the Node property as a vector, you can assign a packet capture file name to each node in the vector at once by specifying this property as a string vector or a cell array of character vectors, and by setting the value of FileExtension property to"pcapng". If the length of this vector is greater than the number of nodes, the object does not use the extra names. If the length of this vector is less than the number of nodes, the remaining nodes receive default names.

Data Types: char | string

ByteOrder — Byte order

'little-endian' (default) | 'big-endian'

This property is read-only after object creation.

Byte order, specified as 'little-endian' or 'big-endian'.

Data Types: char | string

FileExtension — Type of file

'pcap' (default) | 'pcapng'

This property is read-only after object creation.

Type of file, specified as 'pcap' or 'pcapng'.

Data Types: char | string

FileComment — Comment for PCAPNG file

'' (default) | character row vector | string scalar

This property is read-only after object creation.

Comment for the PCAPNG file, specified as a character row vector or a string scalar.

Dependencies

To enable this property, set the FileExtension property to 'pcapng'.

Data Types: char | string

Interface — Name of device that captures WLAN packets

'WLAN' (default) | character row vector | string scalar

This property is read-only after object creation.

Name of device that captures WLAN packets, specified as a character vector or a string scalar in UTF-8 format.

This property is not applicable if you specify the value of the Node property. In this case, the object generates interface names internally for each node in the format Band_ChannelNumber, where:

• Band — Band reflects the configured band of the WLAN node, and can be either 2G4 (2.4 GHz), 5G (5 GHz), or 6G (6 GHz).

• ChannelNumber — Channel number follows the format CHX, where X is the configured channel number of the WLAN node.

Dependencies

To enable this property, set the FileExtension property to 'pcapng'.

Data Types: char | string

RadiotapPresent — Flag to indicate presence of radiotap

false or 0 (default) | true or 1

This property is read-only after object creation.

Flag to indicate the presence of radiotap, specified as a logical 1 (true) or 0 (false).

The object fills these radiotap fields for transmitted and received packets:

• Flags — Bitmap that indicates specific properties of transmitted and received frames. The size of this field is one byte.

• Rate — Data rate. Each unit represents 500 Kbps. The size of this field is one byte.

• Channel — This field describes the radio channel used to capture the wireless packet. It specifies the band, the center frequency of the packet, and indicates whether the packet uses OFDM. The size of this field is four bytes.

• dBm TX power — Transmit power expressed as dBm (decibels from a 1 milliwatt reference). This is the absolute power level measured at the antenna port. The size of this field is one byte.

• MCS — Modulation and coding scheme (MCS) rate index as in IEEE_802.11n-2009. The size of this field is three bytes.

• VHT — Very high throughput (VHT) packet information. The size of this field is 10 bytes.

• Timestamp — Time reference for the captured frame, along with information about its accuracy, units, and sampling position. The size of this field is 12 bytes.

• HE — When a capture includes this field, it means the device either received or transmitted the frame using the high efficiency (HE) physical layer (PHY. The size of this field is 12 bytes.

• LSIG — Information about the contents of the Legacy Signal (L-SIG). The size of this field is four bytes.

Data Types: logical

PCAPWriter — PCAP or PCAPNG file writer object

pcapWriter object | pcapngWriter object

This property is read-only after object creation.

PCAP or PCAPNG file writer object, specified as pcapWriter (Wireless Network Toolbox) or pcapngWriter (Wireless Network Toolbox) object.

When you set this property, wlanPCAPWriter derives the FileName, FileExtension, FileComment, and ByteOrder properties based on the specified PCAP or PCAPNG file writer object.

Node — WLAN node

wlanNode object | vector of wlanNode objects

Since R2026a

This property is read-only after object creation.

WLAN node, specified as a wlanNode object, or a vector of wlanNode objects.

By specifying a vector, you create a vector of wlanPCAPWriter objects, with each object corresponding to a node.

When you specify the Node property, wlanPCAPWriter registers for the node events, namely the TransmissionStarted and ReceptionEnded events, and writes the PDUs contained in EventData.PDU. For more information about these events, see registerEventCallback.

PipeName — Name of FIFO pipe file

'' (default) | character vector | string scalar

Since R2026a

This property is read-only after object creation.

Name of the first-in first-out (FIFO) pipe file (also known as a named pipe), specified as a character row vector or string scalar. This value is an absolute or relative path to a pipe that you create outside MATLAB.

Dependencies

To enable this property, do not specify FileName.

Data Types: char | string

Object Functions

Specific to This Object

write

Write protocol packet data to PCAP or PCAPNG file

Examples

Write WLAN MAC Packet to PCAP File

Create a WLAN PCAP file writer object, specifying the name of the PCAP file.

pcapObj = wlanPCAPWriter('FileName','wlanExample', ...
    'FileExtension','pcap');

Generate a WLAN MAC packet of type QoS Data.

macConfig = wlanMACFrameConfig('FrameType','QoS Data');
payload ='00576000103afffe80';
mpdu = wlanMACFrame(payload,macConfig);

Write the WLAN MAC packet to the PCAP file.

timestamp = 0; % Number of microseconds
write(pcapObj,mpdu,timestamp);

Write WLAN MAC Packet to PCAPNG File

Create a WLAN PCAP file writer object, specifying the name of the PCAPNG file.

pcapObj = wlanPCAPWriter('FileName','wlanExample2', ...
    'FileExtension','pcapng');

Generate a WLAN MAC packet of type QoS Data.

macConfig = wlanMACFrameConfig('FrameType','QoS Data');
payload = '00576000103afffe80';
mpdu = wlanMACFrame(payload,macConfig,'OutputFormat','bits');

Write the WLAN MAC packet to the PCAPNG format file.

timestamp = 12800000; % Number of microseconds
write(pcapObj,mpdu,timestamp,'PacketFormat','bits');

Write WLAN MAC Packet to PCAPNG File Using PCAP File Writer

Create a PCAPNG file writer object, specifying the name of the PCAPNG file.

pcapObj = pcapngWriter('FileName','wlanExample3', ...
    'FileComment','This is a sample file');

Create a WLAN PCAP file writer object, specifying the PCAP file writer and the presence of radiotap header.

wlanPCAP = wlanPCAPWriter('PCAPWriter',pcapObj,'RadiotapPresent', ...
    true);

Generate a WLAN MAC packet of type QoS Data.

macConfig = wlanMACFrameConfig('FrameType','QoS Data');
payload = '00576000103afffe80';
mpdu = hex2dec(wlanMACFrame(payload,macConfig));

Write the WLAN MAC packet to the PCAPNG file.

radiotapBytes = [0 0 24 0 2 0 40 0 16 3 0 0 2 192 0 0 0 0 63 1 19 0 0 0];
timestamp = 18912345; % Number of microseconds
write(wlanPCAP,mpdu,timestamp,'Radiotap',radiotapBytes, ...
    'PacketComment','This is the first packet');

References

[1] Tuexen, M. “PCAP Next Generation (Pcapng) Capture File Format.” 2020. https://www.ietf.org/.

[2] “Radiotap - Introduction.” Accessed May 20, 2020. https://www.radiotap.org/.

[3] Group, The Tcpdump. “Tcpdump/Libpcap Public Repository.” Accessed May 20, 2020. https://www.tcpdump.org.

[4] “Development/LibpcapFileFormat - The Wireshark Wiki.” Accessed May 20, 2020. https://www.wireshark.org.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2021a

R2026a: Wireless Network Toolbox product required

Starting in R2026a, the wlanPCAPWriter object also requires the Wireless Network Toolbox product.

R2026a: Specify node and pipe interface

The wlanPCAPWriter object now enables you to specify a node and a pipe interface through the Node and PipeName object properties, respectively.

R2026a: Expanded options for FileName and Interface properties

The wlanPCAPWriter object now enables you to:

• Specify the value of the FileName property as a string vector. The default file name now adapts based on the presence of Node and FileExtension properties.

• Specify the value of the Interface property as a character vector or a string scalar in UTF-8 format. The Interface property is not applicable if you specify the value of the Node property.