kpi

Returns key performance indicators (KPIs) for Bluetooth BR/EDR nodes

Since R2024b

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^® basic rate/enhanced data rate (BR/EDR) source node sourceNode and the destination node destinationNode. The layerString input specifies the protocol layer of interest.

Examples

Simulate Multiple Bluetooth BR/EDR Piconets with ACL Traffic

This example shows how to create, configure, and simulate multiple Bluetooth® basic rate/enhanced data rate (BR/EDR) piconets with asynchronous connection-oriented logical (ACL) transport.

Using this example, you can:

1. Create and configure two Bluetooth BR/EDR piconets.

2. Create, configure, and share connections between the Central and Peripheral nodes.

3. Add application traffic between the Central and Peripheral nodes.

4. Simulate a Bluetooth BR/EDR piconet with ACL traffic, and retrieve the statistics of and KPIs between the Central and Peripheral nodes.

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 two Bluetooth BR/EDR Central nodes and specify their positions in Cartesian x-, y-, and z-coordinates.

centralNode = bluetoothNode("central",Position=[0 0 0; 1 1 1]); % In meters

Create three Bluetooth BR/EDR Peripheral nodes and specify their positions in Cartesian x-, y-, and z-coordinates.

peripheralNode = bluetoothNode("peripheral",Position=[0 1 0; 1 1 0; 2 2 2]); % In meters

Create a default Bluetooth BR/EDR connection configuration object to configure and share a connection between Central node 1 and Peripheral node 1.

cfgConnection1 = bluetoothConnectionConfig

cfgConnection1 = 
  bluetoothConnectionConfig with properties:

    CentralToPeripheralACLPacketType: "DH1"
    PeripheralToCentralACLPacketType: "DH1"
                       SCOPacketType: "None"
                 HoppingSequenceType: "Connection adaptive"
                        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 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 … ] (1×79 double)
                        PollInterval: 40
                       InstantOffset: 240
                    TransmitterPower: 20
                  SupervisionTimeout: 32000
                      CentralAddress: [1×0 char]
                    PrimaryLTAddress: []

Create a default Bluetooth BR/EDR connection configuration object to configure and share a connection between Central node 2 and Peripheral nodes 2 and 3. Specify the ACL packet type to be transmitted.

cfgConnection2 = bluetoothConnectionConfig;
cfgConnection2.CentralToPeripheralACLPacketType = "DH3";
cfgConnection2.PeripheralToCentralACLPacketType = "DH3"

cfgConnection2 = 
  bluetoothConnectionConfig with properties:

    CentralToPeripheralACLPacketType: "DH3"
    PeripheralToCentralACLPacketType: "DH3"
                       SCOPacketType: "None"
                 HoppingSequenceType: "Connection adaptive"
                        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 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 … ] (1×79 double)
                        PollInterval: 40
                       InstantOffset: 240
                    TransmitterPower: 20
                  SupervisionTimeout: 32000
                      CentralAddress: [1×0 char]
                    PrimaryLTAddress: []

Configure these connections between the Central and Peripheral nodes.

• Central node 1 and Peripheral node 1

• Central node 2 and Peripheral node 2

• Central node 2 and Peripheral node 3

Note that, you must configure each Peripheral node to only one Central node.

connection1 = configureConnection(cfgConnection1,centralNode(1),peripheralNode(1));
connection2 = configureConnection(cfgConnection2,centralNode(2),[peripheralNode(2) peripheralNode(3)]);

Create and configure a networkTrafficOnOff object for each connection, to generate an On-Off application traffic pattern between the corresponding Central and Peripheral nodes.

traffic1 = networkTrafficOnOff(DataRate=200,PacketSize=27, ...
    GeneratePacket=true,OnTime=inf);
traffic2 = networkTrafficOnOff(DataRate=200,PacketSize=27, ...
    GeneratePacket=true,OnTime=inf);
traffic3 = networkTrafficOnOff(DataRate=200,PacketSize=27, ...
    GeneratePacket=true,OnTime=inf);
traffic4 = networkTrafficOnOff(DataRate=400,PacketSize=80, ...
    GeneratePacket=true,OnTime=inf);

Add application traffic from the Central to the Peripheral nodes and vice versa. To transmit packets on an ACL transport, you must add application traffic between the nodes.

addTrafficSource(centralNode(1),traffic1,DestinationNode=peripheralNode(1));
addTrafficSource(peripheralNode(1),traffic2,DestinationNode=centralNode(1));
addTrafficSource(centralNode(2),traffic3,DestinationNode=peripheralNode(2));
addTrafficSource(centralNode(2),traffic4,DestinationNode=peripheralNode(3));

Create a Bluetooth BR/EDR network consisting of two piconets. The first piconet includes Central node 1 and Peripheral node 1, and the second piconet consists of Central node 2, Peripheral node 2, and Peripheral node 3.

nodes = [centralNode peripheralNode];

Add the Bluetooth nodes to the simulator.

addNodes(networkSimulator,nodes);

Set the simulation time in seconds, and run the simulation.

simulationTime = 0.5;
run(networkSimulator,simulationTime);

Retrieve application, baseband, and physical layer (PHY) statistics corresponding to the Central and Peripheral nodes.

nodeStats = statistics(nodes)

nodeStats=1×5 struct array with fields:
    Name
    ID
    App
    Baseband
    PHY

Retrieve KPIs such as throughput, packet loss ratio (PLR), and packet delivery ratio (PDR) between the Central and Peripheral nodes.

kpi(centralNode,peripheralNode(1),"throughput",Layer="Baseband")

ans = 1×2

  173.2320         0

kpi(centralNode,peripheralNode(2),"PLR",Layer="Baseband")

ans = 1×2

     0     0

kpi(centralNode,peripheralNode(2),"PDR",Layer="Baseband")

ans = 1×2

     0     1

Input Arguments

sourceNode — Bluetooth BR/EDR source node

bluetoothNode object | vector of bluetoothNode objects

Bluetooth BR/EDR source node, specified as a bluetoothNode object or a vector of bluetoothNode objects.

destinationNode — Bluetooth BR/EDR destination node

bluetoothNode object | vector of bluetoothNode objects

Bluetooth BR/EDR destination node, specified as a bluetoothNode object or a vector of bluetoothNode objects.

Note

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

kpiString — Name of KPI to measure

"throughput" | "PLR" | "PDR"

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

layerString — Name of protocol layer

"Baseband"

Name of the protocol layer, specified as "Baseband". The baseband layer enables the PHY radio frequency (RF) link between different Bluetooth BR/EDR devices, creating a piconet.

Data Types: char | string

Output Arguments

kpiValue — Value of specified KPI

scalar | vector

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

• Scalar — If you specify sourceNode and destinationNode as single bluetoothNode objects.

• Vector — If you specify sourceNode or destinationNode as a vector of bluetoothNode objects.

Data Types: double

Version History

Introduced in R2024b