read

Read and filter logged events

Since R2026a

Syntax

events = read(eventTracer)

loggedEvents = read(eventTracer,Name=Value)

Description

events = read(eventTracer) reads and filters logged events from either memory or a MAT file associated with the event tracer object, eventTracer. For post-simulation analysis, you can use a MAT file generated during a previous simulation. You do not have to run a new simulation to use this function.

loggedEvents = read(eventTracer,Name=Value) sets options using one or more name-value arguments. For example, EventName = "AppPacketGenerated" specifies to read only "AppPacketGenerated" events from the logged events. If you do not specify any name-value arguments, the object reads all 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

Input Arguments

eventTracer — Wireless network event tracer

wirelessNetworkEventTracer object

Wireless network event tracer, specified as a wirelessNetworkEventTracer object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: EventName = "AppPacketGenerated" specifies to read only "AppPacketGenerated" events from the logged events.

EventName — Name of event to read

'' (default) | "TransmissionStarted" | "ReceptionEnded" | "AppPacketGenerated" | "AppPacketGenerated" | character vector | string scalar | vector of strings | ...

Name of the event to read, specified as one of these options:

• "TransmissionStarted", "ReceptionEnded", "AppPacketGenerated", "AppPacketReceived", a character vector, a string scalar, or a vector of strings for the nodes such as nrGNB (5G Toolbox), nrUE (5G Toolbox), bluetoothNode (Bluetooth Toolbox), bluetoothLENode (Bluetooth Toolbox), or wlanNode (WLAN Toolbox).

• A character vector, a string scalar, or a vector of strings for subclasses of wnet.Node.

The read function reads only the events with the names specified to this argument from the event log. By default, the read function reads all events from the event log.

Data Types: string | char

NodeName — Name of node for which to read events

'' (default) | character vector | string scalar | vector of strings

Name of the node for which to read events, specified as a character vector, a string scalar, or a vector of strings. If you do not specify this argument, the read function reads all the logged events from the file.

Data Types: string | char

NodeID — ID of node

[] (default) | positive integer | vector of positive integers

ID of the node for which to read events, specified as a positive integer or a vector of positive integers. If you do not specify this argument, the read function reads all the logged events from the file.

Data Types: double

TimeRange — Time interval

[] (default) | two-element nonnegative vector

Time interval, specified as a two-element nonnegative vector. The units are in seconds. When you specify this argument, the event tracer retrieves only the events within the specified interval; otherwise, it retrieves events from all timestamps.

Data Types: double

TechnolgyType — Type of technology for which to fetch events from logged data

[] (default) | nonnegative integer

Type of technology for which to fetch events from the logged data, specified as a nonnegative integer. The value for the technology type is from wnet.TechnologyType. This argument specifies the events to fetch from the logged data based on the type of technology associated with them. If you do not specify this argument, the read function reads all the logged events from all the technology types.

Data Types: double

Output Arguments

events — Events retrieved from memory or MAT file

row vector of structures

Events retrieved from memory or a MAT file, returned as a row vector of structures. Each structure contains the information for a single event.

Data Types: struct

Version History

Introduced in R2026a