nrPCAPWriter

PCAP or PCAPNG file writer of 5G NR MAC packets

Since R2021b

Description

The nrPCAPWriter object creates a packet capture (PCAP) or packet capture next generation (PCAPNG) file writer object to write generated and recovered 5G new radio (NR) medium access control (MAC) packets to a PCAP or PCAPNG file (.pcap or .pcapng, respectively). To write 5G NR MAC packets, no native link type is available for NR. The object writes the 5G NR MAC packets to the PCAP or PCAPNG file by encapsulating the packets into a pseudo protocol with a link type. The object prepends each MAC packet with socket address link layer (SLL), internet protocol (IP), and user datagram protocol (UDP) headers followed by per-packet information. The encapsulation of packets enables the object to write a MAC packet with a maximum size of 65,482 bytes at a time. If the size of the MAC packet is greater than 65,482 bytes, the object truncates the remaining bytes.

Creation

Syntax

nrPCAPW = nrPCAPWriter

nrPCAPW = nrPCAPWriter(Name=Value)

Description

nrPCAPW = nrPCAPWriter creates a default 5G NR PCAP or PCAPNG file writer object.

nrPCAPW = nrPCAPWriter(Name=Value) sets properties using one or more optional name-value arguments. For example, FileExtension='pcapng' sets the extension of the file as .pcapng.

Properties

Note

The nrPCAPWriter 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 PCAP or PCAPNG file

"nrcapture" (default) | character vector | string scalar

This property is read-only after object creation.

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

If you do not specify the Node property, the object uses "nrCapture" as the default file name. If you specify the Node property, the object sets the default file name to NodeName_NodeID_Timestamp, where:

• NodeName — Name of the node.

• NodeID — Unique identifier of the node.

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

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 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.

Dependencies

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

Data Types: char | string

Interface — Name of interface on which NR MAC packets are captured

'5GNR' (default) | character vector | string scalar

This property is read-only after object creation.

Name of the interface on which NR MAC packets are captured, specified as a character vector or a string scalar.

Dependencies

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

Data Types: char | string

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 a pcapWriter or pcapngWriter object.

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

Node — 5G node

nrGNB object | nrUE object

Since R2026a

This property is read-only after object creation.

5G node, specified as an nrGNB object, an nrUE object, or a vector of nrGNB or nrUE objects.

When you specify N nodes, the object returns a row vector of N nrPCAPWriter objects as output.

When you specify the Node property, nrPCAPWriter registers for the node events, namely the TransmissionStarted and ReceptionEnded events, and writes the PDUs contained in EventData.PDU, provided that SignalType is not "SRS" or "CSIRS". For more information about these events, see registerEventCallback.

TimestampResolution — Timestamp resolution

"microseconds" (default) | "nanoseconds"

Since R2026a

This property is read-only after object creation.

Timestamp resolution, specified as "microseconds" or "nanoseconds". When you specify Node and do not specify TimestampResolution, the default value of TimestampResolution is "nanoseconds".

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 5G NR MAC packet to PCAP or PCAPNG file

Examples

Write 5G NR MAC Packet to PCAP File

Create a 5G NR PCAP file writer object, specifying the name and extension of the file.

nrpcapw = nrPCAPWriter(FileName='nrPCAPExample',FileExtension='pcap');

Create a 5G NR MAC packet.

nrMACPDU = [6; 68; 64; 0; ones(66,1); 62; 4; 7; 74; 96; 102];

Set the timestamp for the packet.

timestamp = 1000000;                          % In microseconds

Create the packet information structure for the MAC packet by using the constants defined in the created 5G NR PCAP file writer object.

packetInfo = struct();
packetInfo.RadioType = nrpcapw.RadioFDD;      % Frequency division duplexing
packetInfo.LinkDir = nrpcapw.Uplink;          % Link direction
packetInfo.RNTIType = nrpcapw.CellRNTI;       % Type of radio network temporary identifier (RNTI)

Write the 5G NR MAC packet to the PCAP file.

write(nrpcapw,nrMACPDU,timestamp,PacketInfo=packetInfo);

Write SIB1 Packet with Comment to PCAPNG File

Create a 5G NR PCAPNG file writer object, specifying the name of the file, extension of the file, and file comment.

nrpcapw = nrPCAPWriter(FileName='nrPCAPExample2', ...
    FileExtension='pcapng', ...
    FileComment='SIB1 Packet');

Create a system information block 1 (SIB1) packet.

sib1Packet = [64; 0; 0; 36; 104; 21; 0; 10; 156; 1; 15; zeros(13,1)];

Set the timestamp for the packet.

timestamp = 1000000;                       % In microseconds

Create the packet information structure for the SIB1 packet by using the constants defined in the created 5G NR PCAPNG file writer object.

packetInfo = struct();
packetInfo.RadioType = nrpcapw.RadioFDD;         % Frequency division duplexing
packetInfo.LinkDir = nrpcapw.Downlink;           % Link direction
packetInfo.RNTIType = nrpcapw.SystemInfoRNTI;    % Type of radio network temporary identifier (RNTI)

Write the SIB1 packet to the PCAPNG file.

write(nrpcapw,sib1Packet,timestamp,PacketInfo=packetInfo);

Write 5G NR MAC BSR Packet to PCAPNG File

Create a 5G NR PCAPNG file writer object, specifying the name of the file, extension of the file, and packet comment.

nrpcapw = nrPCAPWriter(FileName='nrPCAPExample3', ...
    FileExtension='pcapng', ...
    FileComment='Sample file');

Create a 5G NR MAC packet containing short truncated buffer status report (BSR).

nrMACPDU = [59; 205];

Set the timestamp for the packet.

timestamp = 1000000;                        % In microseconds

Create the packet information structure for the MAC packet by using the constants defined in the created 5G NR PCAPNG file writer object.

packetInfo = struct();
packetInfo.RadioType = nrpcapw.RadioFDD;    % Frequency division duplexing
packetInfo.LinkDir = nrpcapw.Uplink;        % Link direction
packetInfo.RNTIType = nrpcapw.CellRNTI;     % Type of radio network temporary identifier (RNTI)
packetInfo.RNTI = 15;                       % RNTI value in the range [0, 65535]
packetInfo.UEID = 1022;                     % User equipment identifier in the range [0, 65535]
packetInfo.SystemFrameNumber = 10;          % System frame number in the range [0, 1023]

Write the 5G NR MAC packet to the PCAPNG file.

write(nrpcapw,nrMACPDU,timestamp,PacketInfo=packetInfo, ...
    PacketComment='This is a NR MAC BSR packet');

References

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

[2] “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 R2021b

R2026a: New properties in nrPCAPWriter

The nrPCAPWriter object supports these new properties: TimestampResolution, Node and PipeName.