read

Read next protocol packet from PCAP file

Since R2021b

Syntax

protocolPacket = read(pcap)

protocolPacket = read(pcap,packetFilter)

Description

protocolPacket = read(pcap) reads the next protocol packet from the packet capture (PCAP) file specified by the input PCAP file reader and returns the decoded packet.

protocolPacket = read(pcap,packetFilter) returns only the decoded packets that match the specified filter, packetFilter.

Examples

Read eCPRI Packets in Streaming Mode from PCAP File

Create a PCAP file reader object, specifying the name of a PCAP file.

pcapReaderObj = pcapReader('ethernetSamplePackets.pcap');

Create a filter for the message types of eCPRI packets.

filterString = ['ecpri.MessageType == IQData || ecpri.MessageType == BitSequence ' ...
    '|| ecpri.MessageType == RemoteReset'];

In streaming mode, read the eCPRI packets that match the specified filter to the MATLAB® workspace.

for packetCount = 1:3
    ecpriFilteredPackets = read(pcapReaderObj,filterString)
end

ecpriFilteredPackets = struct with fields:
             SNo: 21
       Timestamp: 1.6128e+15
        LinkType: 1
        Protocol: 'eth'
    PacketLength: 64
          Packet: [1×1 struct]
        RawBytes: [1×0 uint8]

ecpriFilteredPackets = struct with fields:
             SNo: 22
       Timestamp: 1.6128e+15
        LinkType: 1
        Protocol: 'eth'
    PacketLength: 64
          Packet: [1×1 struct]
        RawBytes: [1×0 uint8]

ecpriFilteredPackets = struct with fields:
             SNo: 31
       Timestamp: 1.6128e+15
        LinkType: 1
        Protocol: 'eth'
    PacketLength: 64
          Packet: [1×1 struct]
        RawBytes: [1×0 uint8]

Input Arguments

pcap — PCAP file reader

pcapReader object

PCAP file reader, specified as a pcapReader object.

packetFilter — Packet filter

character vector | string scalar

Packet filter, specified as a character vector or a string scalar. Ignoring the white spaces, this object function reads the protocol packets that match this value. If the next packet does not match this value, the object function continues to read the next packet until one of these actions occurs.

• The object function detects a packet that matches the specified filter.

• The object function reaches the end of the PCAP file.

You can specify this argument as a combination of one or more filters connected by logical AND (& or &&) or logical OR (| or ||). This syntax shows a typical packet filter.

protocolName.FieldName RELATIONALOPERATOR value

The valid values for protocolName are pcap, eth, and ecpri.

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is pcap.

FieldName Value	value Value
SNo	Integer
TimestampSec	Integer
PacketLength	Integer

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is eth.

FieldName Value	value Value
SourceAddress	Character vector or string scalar representing hexadecimal bytes
DestinationAddress	Character vector or string scalar representing hexadecimal bytes
Type	Integer

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is ecpri.

FieldName Value	value Value
ProtocolRevision	Integer
MessageType	Character vector or string scalar representing eCPRI message type
PC_ID	Integer
SEQ_ID	Integer

Note

For more information about the FieldName values, see the protocolPacket output.

The valid values for RELATIONALOPERATOR are <=, >=, >, <, ==, ~=, and ~.

Example: ‘pcap.PacketLength == 100’ filters the protocol packets of size 100 bytes.

Example: ‘eth.SourceAddress == 44FB5A9710AC & eth.Type == 2048’ filters the Ethernet packets with the specified source address and type of upper-layer protocol.

Example: ‘ecpri.MessageType == IQData || ecpri.MessageType == RemoteReset || ecpri.MessageType == EventIndication’ filters the eCPRI packets with message type IQ data, remote reset, or event indication.

Data Types: char | string

Output Arguments

protocolPacket — Decoded protocol packet

structure

Decoded protocol packet, returned as a structure containing these fields.

Field	Description
SNo	Serial number of the protocol packet
Timestamp	Timestamp of the packet in the format specified by the OutputTimestampFormat property.
TimestampSec	Timestamp of the packet in seconds. To enable this field, set the OutputTimestampFormat property of the pcap input to 'datetime'.
Protocol	Name of the link type
LinkType	Link type specified in the PCAP global header
PacketLength	Original length of the packet transmitted in the network, in bytes If this value is greater than the SnapLength property of the pcapReader object, the length of the decoded protocol packet is truncated to contain SnapLength bytes.
Packet	Decoded packet structure or packet bytes If the PCAP file includes Ethernet packets or eCPRI packets encapsulated in Ethernet, this field contains a decoded packet structure. Otherwise, this field contains packet bytes.
RawBytes	Undecoded bytes because of padding or decode error. The data type of this field is uint8.

If the PCAP file includes Ethernet packets, the Packet field of this argument contains a structure, eth, containing these fields.

Field	Description
SourceAddress	Medium access control (MAC) address of the source host in decimal bytes, returned as a column vector. You can access the source address of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.SourceAddress.
DestinationAddress	MAC address of the destination host in decimal bytes, returned as a column vector. You can access the destination address of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.DestinationAddress.
Type	Field in the Ethernet header that identifies the upper-layer protocol. You can access the upper-layer protocol type of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.Type.
Payload	Upper-layer protocol packet, returned as a vector of octets where each element is in the range [0, 255]. You can access the upper-layer protocol payload of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.Payload.
RawBytes	Undecoded bytes returned by the Ethernet decoder because of padding or decode error. The data type of this field is uint8. If the Ethernet decoder does not return any undecoded bytes, this field is not present in the eth structure. You can access the raw bytes of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.RawBytes.

If the PCAP file includes eCPRI packets encapsulated in Ethernet, the Packet field of this argument contains a structure or a cell array of structures, ecpri, containing these fields.

Field	Description
ProtocolRevision	Protocol version of eCPRI, specified as a nonnegative integer.
Concatenation	Concatenation indicator of eCPRI messages, specified as 0 or 1. A value of 0 indicates the corresponding eCPRI message is the last one inside the eCPRI protocol data unit (PDU). A value of 1 indicates that another eCPRI message follows this one within the eCPRI PDU.
MessageType	Type of service supported by the eCPRI message, specified as a character vector or a string scalar.

The output of the eCPRI decoder varies according to the MessageType value. This table shows the MessageType values and the corresponding additional fields supported by the ecpri structure.

MessageType Value	MessageType Description	Additional Fields Supported by ecpri Structure
IQData	Transfer time domain or frequency domain in-phase and quadrature (IQ) samples	PC_ID, SEQ_ID, UserData, and Payload
BitSequence	Transfer user data in the form of bit sequence	PC_ID, SEQ_ID, UserData, and Payload
RealTimeControlData	Transfer vendor specific real-time control messages	PC_ID, SEQ_ID, UserData, and Payload
GenericDataTransfer	Transfer user plane data or related control	PC_ID, SEQ_ID, UserData, and Payload
RemoteMemoryAccess	Enable reading or writing from or to a specific memory address	RemoteMemoryAccessID, ReadWrite, RequestResponse, ElementID, Address, DataLength, UserData, and Payload
OnewayDelayMeasurement	Estimate the one-way delay between two eCPRI ports in one direction	MeasurementID, ActionType, TimestampSec, TimestampNanoSec, CompensationValue, UserData, and Payload
RemoteReset	Request to reset an eCPRI node	ResetID, ResetCodeOp, UserData, and Payload
EventIndication	Indicates an event has occurred	EventID, EventType, SequenceNumber, NumberOfFaultsOrNotifications, and Elements

Note

For more information on the message types and the corresponding additional fields supported in the ecpri structure, see Section 3.2.4 of the eCPRI Specification V1.2.

Data Types: struct

References

[1] “Common Public Radio Interface: eCPRI Interface Specification V1.2 ” Accessed June 22, 2021.

Version History

Introduced in R2021b

R2026a: read function is now available in both 5G Toolbox and Wireless Network Toolbox

Starting in R2026a, the read function is available in both 5G Toolbox™ and Wireless Network Toolbox™ products. In releases R2025b and before, the read function is only available in the 5G Toolbox product.