registerEventCallback

Register callback for event from Bluetooth LE node

Since R2026a

collapse all in page

    Syntax

    registerEventCallback(bluetoothLENodeObj,eventName,callback)

    Description

    registerEventCallback(bluetoothLENodeObj,eventName,callback) registers a function callback callback for the specified event eventName from the Bluetooth® low energy (LE) node bluetoothLENodeObj.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    Set the seed for the random number generator to ensure repeatability of results. The seed value controls the pattern of random number generation. For high-fidelity simulation results, change the seed value and average the results over multiple simulations.

    rng(1,"twister")

    Create a wireless network simulator object. Specify the simulation time, in seconds.

    networkSimulator = wirelessNetworkSimulator.init();
simulationTime = 0.01;

    Create a Bluetooth LE Central node and a Peripheral node, specifying their positions in 3-D Cartesian coordinates.

    centralNode = bluetoothLENode("central",Position=[1 1 1]);
peripheralNode = bluetoothLENode("peripheral",Position=[2 2 2]);

    Create a Bluetooth LE configuration object to share a connection between the Central and Peripheral nodes. Specify the LL connection interval and active communication period, in seconds, and the maximum number of octets that a data PDU can carry.

    cfgConnection = bluetoothLEConnectionConfig(ConnectionInterval=0.1,ActivePeriod=0.1,MaxPDU=32);

    Configure the LL connection between the Bluetooth LE Central and Peripheral nodes.

    configureConnection(cfgConnection,centralNode,peripheralNode)
    ans = 
  bluetoothLEConnectionConfig with properties:

    ConnectionInterval: 0.1000
         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.1000
                MaxPDU: 32
                  TIFS: 1.5000e-04
                 TMCES: 1.5000e-04

    Create an On-Off application traffic pattern generator object, specifying the On and Off state durations in seconds, the packet length in bytes, and the packet generation rate in Kbps. Add the application traffic source from the Central node to the Peripheral node.

    c2pTraffic = networkTrafficOnOff(DataRate=256,PacketSize=32,OnTime=inf,OffTime=0);
addTrafficSource(centralNode,c2pTraffic,DestinationNode=peripheralNode);

    Create an On-Off application traffic pattern generator object, specifying the On and Off state durations in seconds, the packet length in bytes, and the packet generation rate in Kbps. Add the application traffic source from the Peripheral node to the Central node.

    p2cTraffic = networkTrafficOnOff(DataRate=256,PacketSize=32,OnTime=inf,OffTime=0)
    p2cTraffic = 
  networkTrafficOnOff with properties:

             OnTime: Inf
            OffTime: 0
           DataRate: 256
         PacketSize: 32
    ApplicationData: [1500×1 double]


    addTrafficSource(peripheralNode,p2cTraffic,DestinationNode=centralNode);

    Add the Central node and Peripheral node to the wireless network simulator.

    nodes = [centralNode peripheralNode];
addNodes(networkSimulator,nodes)

    Register callbacks for events from the Central and Peripheral nodes.

    registerEventCallback(centralNode,"TransmissionStarted",@(eventStruct) disp(eventStruct))
registerEventCallback(peripheralNode,"ReceptionEnded",@(eventStruct) disp(eventStruct))
registerEventCallback(centralNode,"AppPacketGenerated",@(eventStruct) disp(eventStruct))
registerEventCallback(peripheralNode,"AppPacketReceived",@(eventStruct) disp(eventStruct))

    Run the simulation for the specified time.

    run(networkSimulator,simulationTime)
             EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "TransmissionStarted"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketReceived"
          NodeName: "Node2"
            NodeID: 2
         Timestamp: 3.3700e-04
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "ReceptionEnded"
          NodeName: "Node2"
            NodeID: 2
         Timestamp: 3.3700e-04
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 1.0000e-03
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0020
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0030
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0040
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0050
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0060
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0070
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0080
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0090
    TechnologyType: 3
         EventData: [1×1 struct]

         EventName: "AppPacketGenerated"
          NodeName: "Node1"
            NodeID: 1
         Timestamp: 0.0100
    TechnologyType: 3
         EventData: [1×1 struct]

    Retrieve APP, LL, and PHY statistics corresponding to the Central and Peripheral nodes.

    statsCentral = statistics(centralNode)
    statsCentral = struct with fields:
    Name: "Node1"
      ID: 1
     App: [1×1 struct]
      LL: [1×1 struct]
     PHY: [1×1 struct]


    statsPeripheral = statistics(peripheralNode)
    statsPeripheral = struct with fields:
    Name: "Node2"
      ID: 2
     App: [1×1 struct]
      LL: [1×1 struct]
     PHY: [1×1 struct]

    Input Arguments

    collapse all

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

    Name of the event, specified as a string scalar, character vector, vector of strings, or cell array of character vectors. Each element of the argument must be one of these values:

    • TransmissionStarted

    • ReceptionEnded

    • AppPacketGenerated

    • AppPacketReceived

    • ChangingState

    For more information about these events, see Events and Corresponding Event Notification Data Substructure.

    Data Types: string | char | cell

    Callback function to run when the Bluetooth LE node notifies occurrence of an event, specified as a scalar function handle. The callback function must use this syntax.

    @(eventStruct) callback(eventStruct)
    The Bluetooth LE node passes the event structure eventStruct with the notification data as a mandatory argument to the callback function. The structure contains these fields.

    Field ValueDescription

    EventName

    String scalar

    Name of the event.

    NodeName

    String scalar

    Name of the node.

    NodeID

    Double scalar

    Node identifier.

    Timestamp

    Double scalar

    Time at which the event is notified, in seconds.

    TechnologyType

    Double scalar

    Valid values are:

    • 0 — Invalid

    • 1 — WLAN

    • 2 — 5G

    • 3 — Bluetooth LE

    • 4 — Bluetooth basic rate/enhanced data rate ( BR/EDR)

    Type of technology.

    EventData

    Structure

    Event notification data.

    For more information about this structure, see Events and Corresponding Event Notification Data Substructure.

    Note

    Register a callback function for an event from bluetoothLENode only once. If you register the same callback function multiple times for the same event, the callback function executes repeatedly each time the node notifies the event.

    More About

    collapse all

    References

    [1] Bluetooth Technology Website. “Bluetooth Technology Website | The Official Website of Bluetooth Technology.” Accessed January 10, 2026. https://www.bluetooth.com/.

    [2] Bluetooth Core Specifications Working Group. "Bluetooth Core Specification" v6.1. https://www.bluetooth.com/specifications/specs/core-specification-6-1/.

    Version History

    Introduced in R2026a

    See Also

    Objects