pcapngWriter

PCAPNG file writer of protocol packets

Description

The pcapngWriter object writes generated and recovered protocol packets to a packet capture next generation (PCAPNG) file (.pcapng).

Creation

Syntax

pcapngObj = pcapngWriter

pcapngObj = pcapngWriter(PropertyName=Value)

Description

pcapngObj = pcapngWriter creates a default PCAPNG file writer object.

pcapngObj = pcapngWriter(PropertyName=Value) sets properties using one or more name-value pair arguments. Enclose each property name in quotes. For example, 'ByteOrder','big-endian' specifies the byte order as big-endian.

Properties

Note

The pcapngWriter object does not overwrite the existing PCAP or PCAPNG file. Each time when you create this object, specify a unique PCAP or PCAPNG file name.

FileName — Name of the PCAPNG file

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

This property is read-only after object creation.

Name of the PCAPNG file, specified as a character row vector or a string scalar.

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

FileComment — Comment for PCAPNG file

'' (default) | character vector | string scalar

This property is read-only after object creation.

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

Data Types: char | string

PipeName — Name of FIFO pipe file

'' (default) | character vector | string scalar

Since R2026a

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
writeCustomBlock	Write custom block to PCAPNG file
writeInterfaceDescriptionBlock	Write interface description block to PCAPNG file

Examples

Write 5G NR Packet to PCAPNG File

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

pcapngObj = pcapngWriter('FileName','sample');

Write the interface block for 5G New Radio (NR). 5G NR packets do not have a valid link type. As per Tcpdump, if a valid link type is not present, specify the link type of SLL packet.

interface = '5GNR';                                       % Interface name
linkType = 113;                                           % Link type of SLL packet
timestamp = 300;                                          % Timestamp
interfaceID = writeInterfaceDescriptionBlock(pcapngObj,linkType,interface);

5G NR packets are not directly supported by Wireshark. To enable Wireshark to parse 5G NR packets, add encapsulation and metadata to the 5G NR packet.

payload = [59; 205];                                      % MAC subPDU (contains truncated buffer status report (BSR) control element)
radioType = 1;                                            % Frequency division duplexing
linkDir   = 0;                                            % Uplink packet
rntiType = 3;                                             % Cell-RNTI
startString = [109; 97; 99; 45; 110; 114];                % Tag to indicate start of NR MAC signature
payloadTag = 1;                                           % Payload tag for NR MAC packets
signature = [startString; radioType; linkDir; rntiType];
macNRInfoPacket = [signature; payloadTag; payload];

Construct a user datagram protocol (UDP) header.

udpPacketLength = 8 + length(macNRInfoPacket);            % Length of header (8 bytes) and payload
udpHeader = [163; 76;                                     % Source port number
    39; 15;                                               % Destination port number
    fix(udpPacketLength/256); mod(udpPacketLength,256);   % Total length of UDP packet
    0; 0];                                                % Checksum

Construct an IPv4 header.

ipPacketLength = 20 + udpPacketLength;                    % Length of header (20 bytes) and payload
ipHeader = [69;                                           % Version of IP protocol and priority or traffic class
    0;                                                    % Type of service
    fix(ipPacketLength/256);mod(ipPacketLength,256);      % Total length of the IPv4 packet
    0; 1;                                                 % Identification
    0; 0;                                                 % Flags and fragmentation offset
    64;                                                   % Time to live in seconds
    17;                                                   % Protocol number
    0; 0;                                                 % Header checksum
    127; 0; 0; 1;                                         % Source IP address
    127; 0; 0; 1];                                        % Destination IP address

Construct an SLL header.

sllHeader = [0; 0;                                        % Packet type
    3; 4;                                                 % Address resolution protocol hardware (ARPHRD) type
    0; 0;                                                 % Link layer address length
    0; 0; 0; 0; 0; 0; 0; 0;                               % Link layer address
    8; 0];                                                % Protocol type

Construct an 5G NR packet by adding encapsulation and metadata.

packet = [sllHeader; ipHeader; udpHeader; macNRInfoPacket];

Write the 5G NR packet to the PCAPNG file.

packetComment = 'This is NR MAC packet';                  % Packet comment
write(pcapngObj,packet,timestamp,interfaceID,'PacketComment',packetComment);

Write WLAN Packet to PCAPNG File

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

pcapngObj = pcapngWriter('FileName','writeWLANpacket');

Write the interface block for WLAN.

interfaceName = 'WLAN';
wlanLinkType = 105;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,wlanLinkType, ...
    interfaceName);

Specify a WLAN packet.

mpdu = 'B4000000FFFFFFFFFFFF00123456789BA79A5B28';

Specify the packet comment. Write the WLAN packet to the PCAPNG file, specifying the packet comment.

timestamp = 0; % Number of microseconds
packetComment = 'This is the first packet';
write(pcapngObj,mpdu,timestamp,interfaceId,'PacketComment', ...
    packetComment);

Write Packets from WLAN and BLE Interface to PCAPNG File

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

pcapngObj = pcapngWriter('FileName','writeWLANBLEpackets');

Write the interface block for WLAN.

interfaceName = 'WLAN';
wlanLinkType = 105;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,wlanLinkType, ...
    interfaceName);

Specify a WLAN packet.

mpdu = 'B4000000FFFFFFFFFFFF00123456789BA79A5B28';

Specify the packet comment. Write the WLAN packet to the PCAPNG file, specifying the packet comment.

timestamp = 0; % Number of microseconds
packetComment = 'This is a WLAN packet';
write(pcapngObj,mpdu,timestamp,interfaceId,'PacketComment', ...
    packetComment);

Write the interface block for Bluetooth low energy (BLE).

interfaceName = 'BLE';
bleLinkType = 251;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,bleLinkType, ...
    interfaceName);

Specify a BLE packet.

llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

Specify the packet comment. Write the BLE packet to the PCAPNG file, specifying the packet comment.

timestamp = 0; % Number of microseconds
packetComment = 'This is a BLE packet';
write(pcapngObj,llpacket,timestamp,interfaceId,'PacketComment', ...
    packetComment);

Write Bluetooth LE Link Layer Packet to PCAPNG File

Create a PCAPNG file writer object, specifying the name of the PCAPNG file. Specify the Bluetooth LE link type.

pcapngObj = pcapngWriter('FileName','BLELLCapture');

Write an interface description block for Bluetooth LE.

interfaceName = 'Bluetooth LE interface';
bleLinkType = 251;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,bleLinkType, ...
    interfaceName);

Specify a Bluetooth LE LL packet.

llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

Write the Bluetooth LE LL packet to the PCAPNG format file.

timestamp = 0;                                 % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
packetComment = 'This is a Bluetooth LE packet';
write(pcapngObj,llpacket,timestamp,interfaceId,'PacketComment', ...
    packetComment);

References

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

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

[3] “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™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2020b

R2026a: pcapngWriter moves to Wireless Network Toolbox from WLAN Toolbox and Bluetooth Toolbox

In R2026a, the pcapngWriter object and associated object functions move to the Wireless Network Toolbox™ product from the WLAN Toolbox™ and Bluetooth^® Toolbox products. Starting in R2026a, writing WLAN or Bluetooth packets to a PCAPNG file requires Wireless Network Toolbox. In releases R2025b and before, these functionalities require the WLAN Toolbox or Bluetooth Toolbox products, respectively.

R2026a: pcapngWriter adds support for pipe interface

The pcapngWriter object now enables you to specify a FIFO pipe file through the PipeName property.