Main Content

kpi

Returns key performance indicators (KPIs) for Bluetooth LE nodes

Since R2024b

collapse all in page

    Download Required: To use kpi, first download the Communications Toolbox Wireless Network Simulation Library add-on. For more information, see Get and Manage Add-Ons.

    Syntax

    kpiValue = kpi(sourceNode,destinationNode,kpiString,Layer=layerString)

    Description

    kpiValue = kpi(sourceNode,destinationNode,kpiString,Layer=layerString) returns the KPI value, specified by the name of the KPI kpiString, between the Bluetooth® low energy (LE) source node sourceNode and the destination node destinationNode. The layerString input specifies the protocol layer of interest.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    This example shows how to simulate a Bluetooth® low energy (LE) isochronous broadcast audio network by using Bluetooth® Toolbox and Communications Toolbox™ Wireless Network Simulation Library.

    Using this example, you can:

    1. Create and configure a Bluetooth LE piconet with an isochronous broadcaster and receivers.

    2. Add application traffic at the broadcaster.

    3. Simulate the broadcast isochronous network and retrieve the statistics and KPIs of the broadcaster and receivers.

    Check if the Communications Toolbox Wireless Network Simulation Library support package is installed. If the support package is not installed, MATLAB® returns an error with a link to download and install the support package.

    wirelessnetworkSupportPackageCheck;

    Create a wireless network simulator.

    networkSimulator = wirelessNetworkSimulator.init;

    Create a Bluetooth LE node, specifying the role as "isochronous-broadcaster". Specify the name and position of the node.

    broadcasterNode = bluetoothLENode("isochronous-broadcaster");
broadcasterNode.Name = "Broadcaster";
broadcasterNode.Position = [0 0 0];                            % In x-, y-, and z-coordinates, in meters

    Create two Bluetooth LE nodes, specifying the role as "synchronized-receiver". You can use this syntax to generate an array of Bluetooth LE node objects by specifying the value of the Position property.

    receiverNodes = bluetoothLENode("synchronized-receiver",Position=[2 0 0; 3 0 0],Name=["Receiver1" "Receiver2"]);

    Create a default Bluetooth LE broadcast isochronous group (BIG) configuration object.

    cfgBIG = bluetoothLEBIGConfig
    cfgBIG = 
  bluetoothLEBIGConfig with properties:

        SeedAccessAddress: "78E52493"
                  PHYMode: "LE1M"
                   NumBIS: 1
              ISOInterval: 0.0050
               BISSpacing: 0.0022
              SubInterval: 0.0022
                   MaxPDU: 251
              BurstNumber: 1
    PretransmissionOffset: 0
          RepetitionCount: 1
             NumSubevents: 1
           BISArrangement: "sequential"
                BIGOffset: 0
        ReceiveBISNumbers: 1
             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]
            InstantOffset: 6
    BaseCRCInitialization: "1234"

    Configure the broadcaster and receiver nodes.

    updatedCfgBIG = configureBIG(cfgBIG,broadcasterNode,receiverNodes)
    updatedCfgBIG = 
  bluetoothLEBIGConfig with properties:

        SeedAccessAddress: "78E52493"
                  PHYMode: "LE1M"
                   NumBIS: 1
              ISOInterval: 0.0050
               BISSpacing: 0.0022
              SubInterval: 0.0022
                   MaxPDU: 251
              BurstNumber: 1
    PretransmissionOffset: 0
          RepetitionCount: 1
             NumSubevents: 1
           BISArrangement: "sequential"
                BIGOffset: 0
        ReceiveBISNumbers: 1
             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]
            InstantOffset: 6
    BaseCRCInitialization: "1234"

    Create a networkTrafficOnOff object to generate an On-Off application traffic pattern. Specify the data rate in kb/s and the packet size in bytes. Enable packet generation to generate an application packet with a payload.

    traffic = networkTrafficOnOff(DataRate=500, ...
                              PacketSize=10, ...
                              GeneratePacket=true);

    Add application traffic at the broadcaster node by using the addTrafficSource object function.

    addTrafficSource(broadcasterNode,traffic);

    Create a broadcast isochronous network consisting of LE broadcast audio nodes.

    nodes = {broadcasterNode receiverNodes};

    Add the LE broadcast audio nodes to the wireless network simulator.

    addNodes(networkSimulator,[broadcasterNode receiverNodes]);

    Set the simulation time in seconds and run the simulation.

    simulationTime = 0.5;      
run(networkSimulator,simulationTime);

    Retrieve application, link layer (LL), and physical layer (PHY) statistics corresponding to the broadcaster and receiver nodes. For more information about the statistics, see Bluetooth LE Node Statistics.

    broadcasterStats = statistics(broadcasterNode)
    broadcasterStats = struct with fields:
    Name: "Broadcaster"
      ID: 1
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]


    receiver1Stats = statistics(receiverNodes(1))
    receiver1Stats = struct with fields:
    Name: "Receiver1"
      ID: 2
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]


    receiver2Stats = statistics(receiverNodes(2))
    receiver2Stats = struct with fields:
    Name: "Receiver2"
      ID: 3
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]

    Retrieve application layer (APP) KPIs such as latency, packet loss ratio (PLR), and packet delivery ratio (PDR) for the connection between the broadcaster node and Receiver1.

    kpi(broadcasterNode,receiverNodes(1),"latency",Layer="App")
    ans = 
0.2397

    kpi(broadcasterNode,receiverNodes(1),"PLR",Layer="App")
    ans = 
0.9471

    kpi(broadcasterNode,receiverNodes(1),"PDR",Layer="App")
    ans = 
0.0529

    Input Arguments

    collapse all

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

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

    Note

    You can specify either the sourceNode or destinationNode input as an array of bluetoothNode objects, but not both.

    Name of the KPI to measure, specified as one of these values.

    Value of kpiString Description
    "throughput"

    Measure the throughput by computing the number of higher-layer data payloads successfully transmitted by the protocol layer over a specific time frame. Units are in kbps.

    "latency"

    Measure the latency by computing the time from generating an application packet at the source node for it to reach the destination node. Units are in seconds.

    "PLR"

    Measure the PLR by computing the ratio of the total number of packets lost to the total number of packets sent between the source and destination nodes.

    "PDR"

    Measure the PDR by computing the ratio of the total number of packets received at the destination node to the total number of packets sent between the source and destination nodes.

    Data Types: char | string

    Name of the protocol layer, specified as one of these values.

    Value of layerString Description
    "APP"

    The APP is the direct user interface, which defines the profiles that afford interoperability between various applications.

    "LL"

    The LL interfaces with the Bluetooth LE PHY and manages the link state of the radio to define the role of a bluetoothLENode as "peripheral", "central", "broadcaster", "observer", "isochronous-broadcaster", "synchronized-receiver", or "broadcaster-observer".

    Data Types: char | string

    Output Arguments

    collapse all

    Value of the specified KPI, returned as one of these values.

    Data Types: double

    Version History

    Introduced in R2024b

    See Also

    Objects