kpi
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® low energy (LE) source node sourceNode
and the
destination node destinationNode
. The layerString
input specifies the protocol layer of interest.
Examples
Create, Configure, and Simulate Bluetooth LE Broadcast Audio Network
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:
Create and configure a Bluetooth LE piconet with an isochronous broadcaster and receivers.
Add application traffic at the broadcaster.
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
sourceNode
— Bluetooth LE source node
bluetoothLENode
object | vector of bluetoothLENode
objects
Bluetooth LE source node, specified as a bluetoothLENode
object or a vector of bluetoothLENode
objects.
destinationNode
— Bluetooth LE destination node
bluetoothLENode
object | 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.
kpiString
— Name of KPI to measure
"throughput"
| "latency"
| "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. |
"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
layerString
— Name of protocol layer
"App"
| "LL"
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 |
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 singlebluetoothLENode
objects.Vector — If you specify
sourceNode
ordestinationNode
as a vector ofbluetoothLENode
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)