blePCAPWriter

PCAP or PCAPNG file writer of Bluetooth LE LL packets

Description

The blePCAPWriter object writes generated and recovered Bluetooth^® low energy (LE) link layer (LL) packets to a packet capture (PCAP) or packet capture next generation (PCAPNG) file (.pcap or .pcapng, respectively). Note that, this object requires the Wireless Network Toolbox™ product.

Creation

Syntax

obj = blePCAPWriter

obj = blePCAPWriter(PropertyName,Value)

Description

obj = blePCAPWriter creates a default Bluetooth LE PCAP or PCAPNG file writer object that writes Bluetooth LE LL packets to a PCAP or PCAPNG file, respectively.

obj = blePCAPWriter(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 blePCAPWriter 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 PCAP or PCAPNG file

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

This property is read-only after object creation.

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

If you do not specify the Node property, the object uses "bleCapture" 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 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 Bluetooth LE packets

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

This property is read-only after object creation.

Name of the device that captures Bluetooth LE packets, 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

PhyHeaderPresent — Flag to indicate presence of PHY header

false or 0 (default) | true or 1

This property is read-only after object creation.

Flag to indicate the presence of physical layer (PHY) header, specified as a logical 1 (true) or 0 (false).

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

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

Node — Bluetooth node

bluetoothLENode object | vector of bluetoothLENode objects

Since R2026a

This property is read-only after object creation.

Bluetooth node, specified as a bluetoothLENode object, or a vector of bluetoothLENode objects.

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

When you specify the Node property, blePCAPWriter 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 Bluetooth LE LL protocol packet data to PCAP or PCAPNG file

Examples

Use Bluetooth LE PCAP Writer to Write LL Packet to PCAP File

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

pcapObj = blePCAPWriter('FileName','writeblepacket');

Generate a Bluetooth LE LL packet.

cfgLLData = bleLLDataChannelPDUConfig('LLID', ...
    'Data (start fragment/complete)');
payload = '0E00050014010A001F004000170017000000';
llDataPDU = bleLLDataChannelPDU(cfgLLData,payload);
connAccessAddress = int2bit(hex2dec('E213BC42'),32,false);
llpacket = [connAccessAddress; llDataPDU];

Write the Bluetooth LE LL packet to the PCAP file.

timestamp = 0;                                           % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
write(pcapObj,llpacket,timestamp,'PacketFormat','bits');

Use Bluetooth LE PCAP Writer to Write LL Packet to PCAPNG File

Create a Bluetooth LE PCAPNG file writer object, specifying the name and extension of the PCAPNG file.

pcapObj = blePCAPWriter('FileName','sampleBLELL', ...
    'FileExtension','pcapng');

Generate a Bluetooth LE LL packet.

cfgLLData = bleLLDataChannelPDUConfig('LLID', ...
    'Data (start fragment/complete)');
payload = '0E00050014010A001F004000170017000000';
llDataPDU = bleLLDataChannelPDU(cfgLLData,payload);
connAccessAddress = int2bit(hex2dec('E213BC42'),32,false);
llpacket = [connAccessAddress; llDataPDU];

Write the Bluetooth LE LL packet to the PCAPNG file.

timestamp = 12800000;                                   % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
write(pcapObj,llpacket,timestamp,'PacketFormat','bits');

Write Bluetooth LE LL Packet to PCAPNG File from PCAPNG File Writer

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

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

Create a Bluetooth LE PCAP file writer object, specifying the PCAPNG file writer and the presence of PHY header.

blePCAP = blePCAPWriter('PCAPWriter',pcapObj,'PhyHeaderPresent',true);

Generate a Bluetooth LE LL packet.

cfgLLAdv = bleLLAdvertisingChannelPDUConfig;
cfgLLAdv.PDUType = 'Advertising indication';
cfgLLAdv.AdvertisingData = '020106';
llDataPDU = bleLLAdvertisingChannelPDU(cfgLLAdv);
connAccessAddress = int2bit(hex2dec('E213BC42'),32,false);
llpacket = [connAccessAddress;llDataPDU];

Write the Bluetooth LE LL packet to the PCAPNG file.

PhyHeaderBytes = [39 10 8 1 10 10 10 10 15 00];
timestamp = 18912345;                                       % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
write(blePCAP,llpacket,timestamp,'PacketFormat','bits', ...
    'PhyHeader',PhyHeaderBytes, ...
    'PacketComment','This is the first packet');

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

Version History

Introduced in R2020b

R2026a: Requires Wireless Network Toolbox

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

R2026a: Specify node and pipe interface

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