wirelessNetworkEventTracer

R2026b

Log, read, and filter events from wireless nodes

Since R2026a

Description

Use the wirelessNetworkEventTracer object to log, read, and filter events from wireless nodes in a wireless network simulation.

Creation

Syntax

eventTracer = wirelessNetworkEventTracer

eventTracer = wirelessNetworkEventTracer(PropertyName=Value)

eventTracer = wirelessNetworkEventTracer(matfile)

eventTracer = wirelessNetworkEventTracer(matfile,PropertyName=Value)

Description

eventTracer = wirelessNetworkEventTracer creates a default wireless network event tracer object to log the events from wireless nodes in a wireless network simulation.

eventTracer = wirelessNetworkEventTracer(PropertyName=Value) sets properties using optional name-value arguments. For example, FileName = "eventlogs" sets the name of the file to "eventlogs".

eventTracer = wirelessNetworkEventTracer(matfile) creates an event tracer object to read logged events from a MAT file, folder, or list of MAT files. The function returns the events as a vector of structures by default.

eventTracer = wirelessNetworkEventTracer(matfile,PropertyName=Value) additionally specifies the optional name-value argument OutputFormat (since R2026b).

Input Arguments

matfile — MAT file, folder, or list of MAT files from which event tracer reads logged events

character vector | string scalar | vector of strings | cell array of character vectors

MAT file, folder, or list of MAT files from which the event tracer reads logged events, specified as one of these options.

• character vector or string scalar — Single MAT file or folder

• string array or cell array of character vectors — File list

You can provide the file name, folder name or the full path. When loading from multiple files (folder or file list), all files must belong to the same simulation run.

Each MAT file contains:

• LoggedEvents — Event records with fields: EventName, NodeName, NodeID, TechnologyType, Timestamp, and EventData

• Metadata — Structure that stores metadata about the events in the MAT file. It contains these fields:

  • EventTimeRange — Time range of events in the file, specified as [startTime endTime] where startTime is the timestamp of the first event and endTime is the timestamp of the last event in the file.

  • SimulationInitTimestamp — Timestamp when you initialized the simulation, specified as a datetime object with format yyyy-MMM-dd HH:mm:ss and local timezone. This value is identical across all MAT files belonging to the same simulation run. The wirelessNetworkEventTracer object uses this value to validate that multiple files belong together.

Note

Starting in R2026b, matfile supports loading from multiple sources including a single MAT file, a folder containing MAT files, or a list of MAT files. Additionally, each MAT file includes a Metadata structure to support multi-file event traces. In R2026a, matfile accepts only a single MAT file specified as a character vector or string scalar, and MAT files contain only the LoggedEvents field without metadata.

Data Types: char | string

Properties

FileName — Name of MAT file or folder

character vector | string scalar

This property is read-only after object creation.

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

If a file with the specified name exists, the function returns an error. If you do not specify a value for this property, the object saves the log as a MAT file with the name format eventlog_yyyyMMdd_HHmmss, where yyyyMMdd_HHmmss is the time at which you create the log file.

If the simulation generates more than one million events, the object automatically creates a folder to store multiple MAT files. The folder name matches the base file name, and each file holds up to one million events.

For example, FileName="mylogs" creates a folder mylogs/ containing mylogs.mat, mylogs_1.mat, mylogs_2.mat, and so on. If you do not provide a file name, the object creates a folder eventTrace_yyyyMMdd_HHmmss/ with correspondingly named files.

Note

Starting in R2026b, FileName can represent either a single MAT file or a folder containing multiple MAT files. When the simulation generates more than one million events, the object automatically creates a folder to store event files. In R2026a, FileName represents only a single MAT file, and logging is limited to the first one million events.

Data Types: string | char

OutputFormat — Format of returned event data

"struct" | "table"

Since R2026b

This property is read-only after object creation.

Format for event data returned by the read function, specified as one of these options.

• "struct" — Returns events as a structure array

• "table" — Returns events as a table

This property is only applicable in read mode when loading events from files.

Data Types: string | char

Object Functions

addNodes	Add wireless nodes to wireless network event tracer
read	Read and filter logged events

Examples

Trace Events in 5G Network Simulation

Configure event tracing in a 5G NR wireless network simulation. Log network events to a MAT file using an event tracer, and then extract specific event information, such as the timestamps of application packet generation events at the gNB, for further analysis.

Initialize the wireless network simulator.

networkSimulator = wirelessNetworkSimulator.init;

Create a gNB node with default settings.

gnb = nrGNB(Name="nrgnb",PHYModel="full-phy");

Create a UE node with default settings.

ue = nrUE(Name="nrue",PHYModel="full-phy");

Establish a connection between the UE and gNB nodes.

connectUE(gnb,ue)

Create a voice over Internet protocol (VoIP) application traffic pattern object.

traffic = networkTrafficVoIP;

Add the data traffic source to the gNB node. Specify the UE node as the destination node.

addTrafficSource(gnb,traffic,DestinationNode=ue)

Add the gNB and UE nodes to the wireless network simulator.

addNodes(networkSimulator,gnb)
addNodes(networkSimulator,ue)

If an event log files exists, delete it.

if exist("nreventLog.mat","file")
    delete("nreventLog.mat");
end

Create an event tracer object to log events to a MAT file during simulation runtime.

eventTracer = wirelessNetworkEventTracer(FileName="nreventLog.mat");

Add the gNB and UE nodes to the event tracer.

addNodes(eventTracer,gnb) % Logs the events "TransmissionStarted", "ReceptionEnded", "AppPacketGenerated", and "AppPacketReceived"
addNodes(eventTracer,ue)  % Logs the events "TransmissionStarted", "ReceptionEnded", "AppPacketGenerated", and "AppPacketReceived"

Specify the simulation time, in seconds.

simulationTime = 0.5;

Run the simulation for the specified simulation time.

run(networkSimulator,simulationTime)

Read only the "AppPacketGenerated" events from node "nrgnb" from the event tracer.

events = read(eventTracer,EventName="AppPacketGenerated",NodeName="nrgnb");
disp(events);

  1×4 struct array with fields:

    EventName
    NodeName
    NodeID
    Timestamp
    TechnologyType
    EventData

Extract the timestamps for "AppPacketGenerated" events of the gNB node from the event log.

generationTimes = [events.Timestamp]

generationTimes = 1×4

         0    0.1690    0.3320    0.4990

Trace Events in Bluetooth Network Simulation

Configure event tracing in a Bluetooth® network simulation. Log network events to a MAT file using an event tracer, and then extract specific event information, such as the timestamps of packet transmission events at a Bluetooth node, for further analysis.

Initialize the wireless network simulator.

networkSimulator = wirelessNetworkSimulator.init;

Create Bluetooth Central and Peripheral nodes.

centralNode = bluetoothLENode("central",Name="Central1");
peripheralNode = bluetoothLENode("Peripheral",Name="Peripheral1",Position=[1 0 0]);

Create and configure the connection.

cfgConnection = bluetoothLEConnectionConfig;
configureConnection(cfgConnection,centralNode,peripheralNode)

ans = 
  bluetoothLEConnectionConfig with properties:

    ConnectionInterval: 0.0200
         AccessAddress: "5DA44270"
          UsedChannels: [0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36]
             Algorithm: 1
          HopIncrement: 5
     CRCInitialization: "012345"
    SupervisionTimeout: 1
               PHYMode: "LE1M"
         InstantOffset: 6
      ConnectionOffset: 0
          ActivePeriod: 0.0200
                MaxPDU: 251
                  TIFS: 1.5000e-04
                 TMCES: 1.5000e-04

Configure On-Off traffic.

traffic = networkTrafficOnOff(DataRate=200,PacketSize=27, ...
    OnTime=inf);

Add traffic from the Central to Peripheral node.

addTrafficSource(centralNode,traffic,DestinationNode=peripheralNode)

Add the Bluetooth nodes to the simulator.

addNodes(networkSimulator,[centralNode peripheralNode]);

If an event log files exists, delete it.

if exist("btEventLog.mat","file")
    delete("btEventLog.mat");
end

Create an event tracer object to log events to a MAT file during simulation runtime.

eventTracer = wirelessNetworkEventTracer(FileName="btEventLog.mat");

Add the Central and Peripheral nodes to the event tracer.

addNodes(eventTracer,centralNode,eventName=["TransmissionStarted" "ReceptionEnded"])
addNodes(eventTracer,peripheralNode,eventName=["TransmissionStarted" "ReceptionEnded"])

Set the simulation time, and run the simulation.

simulationTime = 0.3;
run(networkSimulator,simulationTime)

Read all the events from the event tracer.

events = read(eventTracer);

Extract the timestamps for "TransmissionStarted" events of the Central node from the event log.

event1 = read(eventTracer,NodeName="Central1",EventName="TransmissionStarted");
transmissionTimes1 = [event1.Timestamp]

transmissionTimes1 = 1×268

         0    0.0200    0.0207    0.0214    0.0220    0.0227    0.0234    0.0241    0.0247    0.0254    0.0261    0.0268    0.0275    0.0281    0.0288    0.0295    0.0302    0.0308    0.0315    0.0322    0.0329    0.0336    0.0342    0.0349    0.0400    0.0407    0.0414    0.0420    0.0427    0.0434    0.0441    0.0447    0.0454    0.0461    0.0468    0.0475    0.0481    0.0488    0.0495    0.0502    0.0508    0.0515    0.0522    0.0529    0.0536    0.0542    0.0549    0.0600    0.0607    0.0614

Alternatively, you can read events from the MAT file "btEventLog.mat" by following these steps.

eventLog= wirelessNetworkEventTracer("btEventLog.mat");
event2 = read(eventLog,NodeName="Central1",EventName="TransmissionStarted");
transmissionTimes2 = [event2.Timestamp]

transmissionTimes2 = 1×268

         0    0.0200    0.0207    0.0214    0.0220    0.0227    0.0234    0.0241    0.0247    0.0254    0.0261    0.0268    0.0275    0.0281    0.0288    0.0295    0.0302    0.0308    0.0315    0.0322    0.0329    0.0336    0.0342    0.0349    0.0400    0.0407    0.0414    0.0420    0.0427    0.0434    0.0441    0.0447    0.0454    0.0461    0.0468    0.0475    0.0481    0.0488    0.0495    0.0502    0.0508    0.0515    0.0522    0.0529    0.0536    0.0542    0.0549    0.0600    0.0607    0.0614

Trace Events in WLAN Simulation

Configure event tracing in a wireless local area network (WLAN) simulation. Log network events to a MAT file using an event tracer, and then extract specific event information, such as the timestamps of packet transmission events at the access point, for further analysis.

Initialize the wireless network simulator.

networkSimulator = wirelessNetworkSimulator.init;

Create and configure the AP node.

deviceCfg = wlanDeviceConfig(Mode="AP");
apNode = wlanNode(Name="AP",Position=[0 10 0],DeviceConfig=deviceCfg);

Create the STA node with a default device configuration.

staNode = wlanNode(Name="STA",Position=[5 0 0]);

Associate the STA node with the AP node.

associateStations(apNode,staNode)

Create On-Off application traffic.

traffic = networkTrafficOnOff(DataRate=10e6,PacketSize=1500);

Add application traffic from the AP to the STA.

addTrafficSource(apNode,traffic,DestinationNode=staNode)

Add the AP and STA nodes to the simulator.

addNodes(networkSimulator,[apNode staNode])

If an event log files exists, delete it.

if exist("wlanEventLog.mat","file")
    delete("wlanEventLog.mat");
end

Create an event tracer object to log events to a MAT file during simulation runtime.

eventTracer = wirelessNetworkEventTracer(FileName="wlanEventLog.mat");

Add the AP and STA nodes to the event tracer.

addNodes(eventTracer,apNode)
addNodes(eventTracer,staNode)

Set the simulation time, and run the simulation.

simulationTime = 0.3;
run(networkSimulator,simulationTime);

Read the events from the event tracer.

events=read(eventTracer);

Read the "TransmissionStarted" events of the AP node from the event tracer.

event1 = read(eventTracer,EventName="TransmissionStarted",NodeName="AP");

Obtain the timestamps for all "TransmissionStarted" events of the AP node from the event log.

generationTimes = [event1.Timestamp]

generationTimes = 1×112

    0.0001    0.0002    0.0054    0.0056    0.0109    0.0110    0.0164    0.0165    0.0219    0.0220    0.0273    0.0274    0.0327    0.0328    0.0381    0.0383    0.0436    0.0437    0.0490    0.0491    0.0543    0.0545    0.0597    0.0598    0.0652    0.0653    0.0706    0.0707    0.0760    0.0761    0.0814    0.0815    0.0868    0.0869    0.0922    0.0924    0.0977    0.0978    0.1031    0.1032    0.1085    0.1086    0.1138    0.1140    0.1193    0.1194    0.1247    0.1248    0.1301    0.1302

Limitations

• The object expects each logged event to be approximately 2–3 KB in size.

• The object does not log protocol data units (PDU) from the "TransmissionStarted" and "ReceptionEnded" events. The object also does not log packet octets or bytes from the "AppPacketGenerated" and "AppPacketReceived" events.

Version History

Introduced in R2026a

R2026b: Use OutputFormat to specify event data format

Use the OutputFormat property to specify the format of event data. Specify OutputFormat as one of these options.

• "struct" — Returns events as a structure array

• "table" — Returns events as a table

This property is only applicable in read mode when loading events from files.

R2026b: Load Events from Multiple MAT Files or Folder

Starting in R2026b, matfile supports loading from multiple sources including a single MAT file, a folder containing MAT files, or a list of MAT files. In R2026a, matfile accepts only a single MAT file specified as a character vector or string scalar, and MAT files contain only the LoggedEvents field without metadata.

R2026b: Log More Than One Million Events with Multi-File Support

Starting in R2026b, the wirelessNetworkEventTracer object logs events beyond the one-million-event limit. When the simulation generates more than one million events, the object automatically creates a folder and stores events across multiple MAT files. FileName represents either a single MAT file or a folder containing multiple MAT files. In R2026a, the object logs only the first one million events to a single MAT file and stops logging thereafter.