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.
Description
returns the KPI value, specified by the name of the KPI kpiValue
= kpi(sourceNode
,destinationNode
,kpiString
,Layer=layerString
)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:
Create and configure two Bluetooth BR/EDR piconets.
Create, configure, and share connections between the Central and Peripheral nodes.
Add application traffic between the Central and Peripheral nodes.
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 0]); % 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 ... ] (1x79 double) PollInterval: 40 InstantOffset: 240 TransmitterPower: 20 SupervisionTimeout: 32000 CentralAddress: [1x0 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 ... ] (1x79 double) PollInterval: 40 InstantOffset: 240 TransmitterPower: 20 SupervisionTimeout: 32000 CentralAddress: [1x0 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
anddestinationNode
as singlebluetoothNode
objects.Vector — If you specify
sourceNode
ordestinationNode
as a vector ofbluetoothNode
objects.
Data Types: double
Version History
Introduced in R2024b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)