addTrafficSource

Add data traffic source to Bluetooth LE node

Since R2022a

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

Syntax

addTrafficSource(bluetoothLENodeObj,trafficSource)

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationNode=destinationNode)

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationAddress=destinationElementAddress,SourceAddress=sourceElementAddress,varargin)

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationAddress=destinationElementAddress,SourceAddress=sourceElementAddress,TTL=ttl)

Description

addTrafficSource(bluetoothLENodeObj,trafficSource) adds a data traffic source, trafficSource, to the Bluetooth^® low energy (LE) node object bluetoothLENodeObj. The Role property of the bluetoothLENode object must be set to "isochronous-broadcaster".

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationNode=destinationNode) adds a data traffic source to send data to the specified destination node destinationNode. The Role property of bluetoothLENode object must be set to "central" or "peripheral".

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationAddress=destinationElementAddress,SourceAddress=sourceElementAddress,varargin) adds a data traffic source to send data from the specified element of the source mesh node sourceElementAddress to the specified element of the destination mesh node destinationElementAddress. The Role property of the bluetoothLENode object must be set to "broadcaster-observer". varargin specifies one or more name-value arguments of the upper layer metadata.

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationAddress=destinationElementAddress,SourceAddress=sourceElementAddress,TTL=ttl) additionally specifies the time to live (TTL) for the data communication between the specified source and destination mesh nodes. The Role property of the bluetoothLENode object must be set to "broadcaster-observer".

Examples

Create, Configure, and Simulate Bluetooth LE Network

This example shows you how to simulate a Bluetooth® low energy (LE) 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 Central and Peripheral nodes.

2. Create and configure a link layer (LL) connection between Central and Peripheral nodes.

3. Add application traffic from the Central to Peripheral nodes.

4. Simulate Bluetooth LE network and retrieve the statistics of 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 a Bluetooth LE node, specifying the role as "central". Specify the name and position of the node.

centralNode = bluetoothLENode("central");
centralNode.Name = "CentralNode";
centralNode.Position = [0 0 0];                 % In x-, y-, and z-coordinates in meters

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

peripheralNode = bluetoothLENode("peripheral");
peripheralNode.Name = "PeripheralNode";
peripheralNode.Position = [10 0 0]              % In x-, y-, and z-coordinates in meters

peripheralNode = 
  bluetoothLENode with properties:

        TransmitterPower: 20
         TransmitterGain: 0
           ReceiverRange: 100
            ReceiverGain: 0
     ReceiverSensitivity: -100
             NoiseFigure: 0
    InterferenceFidelity: 0
                    Name: "PeripheralNode"
                Position: [10 0 0]

   Read-only properties:
                    Role: "peripheral"
        ConnectionConfig: [1x1 bluetoothLEConnectionConfig]
          TransmitBuffer: [1x1 struct]
                      ID: 2

Create a default Bluetooth LE configuration object to share the LL connection between the Central and Peripheral nodes.

cfgConnection = bluetoothLEConnectionConfig;

Specify the connection interval and connection offset. Throughout the simulation, the object establishes LL connection events for the duration of each connection interval. The connection offset is from the beginning of the connection interval.

cfgConnection.ConnectionInterval = 0.01; % In seconds
cfgConnection.ConnectionOffset = 0;      % In seconds

Specify the active communication period after the connection event is established between the Central and Peripheral nodes.

cfgConnection.ActivePeriod = 0.01 % In seconds

cfgConnection = 
  bluetoothLEConnectionConfig with properties:

    ConnectionInterval: 0.0100
         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.0100

Configure the connection between Central and Peripheral nodes by using the configureConnection object function of the bluetoothLEConnectionConfig object.

configureConnection(cfgConnection,centralNode,peripheralNode);

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=100, ...
                              PacketSize=10, ...
                              GeneratePacket=true);

Add application traffic from the Central to the Peripheral node by using the addTrafficSource object function.

addTrafficSource(centralNode,traffic,"DestinationNode",peripheralNode.Name);

Create a Bluetooth LE network consisting of a Central and a Peripheral node.

nodes = {centralNode peripheralNode};

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

addNodes(networkSimulator,nodes)

Set the simulation time in seconds and run the simulation.

simulationTime = 0.5;
run(networkSimulator,simulationTime);

Custom channel model is not added. Using free space path loss (fspl) model as the default channel model.

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.

centralStats = statistics(centralNode)

centralStats = struct with fields:
    Name: "CentralNode"
      ID: 1
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]

peripheralStats = statistics(peripheralNode)

peripheralStats = struct with fields:
    Name: "PeripheralNode"
      ID: 2
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]

Input Arguments

bluetoothLENodeObj — Bluetooth LE node object

bluetoothLENode object

Bluetooth LE node object, specified as a bluetoothLENode object.

trafficSource — On-Off application traffic pattern object

networkTrafficOnOff object

On-Off application traffic pattern object, specified as a networkTrafficOnOff object.

destinationNode — Name of the destination node

character vector | string scalar | bluetoothLENode object

Name of the destination node, specified as a character vector, a string scalar, or a bluetoothLENode object. If you set the Role property of the bluetoothLENodeObj object to "central" or "peripheral", this input is mandatory. This value specifies the Name property of the specified Bluetooth LE node object bluetoothLENodeObj for sending data to the specified destination node.

Data Types: char | string

destinationElementAddress — Destination address

4-element character vector | string scalar denoting a 2-octet hexadecimal address

Destination address, specified as a 4-element character vector or string scalar denoting a 2-octet hexadecimal address. If you set the Role property of the bluetoothLENodeObj object to "broadcaster-observer", this input is mandatory. This value specifies the destination address of the Bluetooth mesh node.

Data Types: char | string

sourceElementAddress — Source address

4-element character vector | string scalar denoting a 2-octet hexadecimal address

Source address, specified as a 4-element character vector or string scalar denoting a 2-octet hexadecimal address. If you set the Role property of the bluetoothLENodeObj object to "broadcaster-observer", this input is mandatory. This value specifies the element address of the Bluetooth mesh source node. The element address specifies the ElementAddress property of the specified Bluetooth mesh profile configuration object bluetoothMeshProfileConfig.

Data Types: char | string

ttl — Time to live for message

127 (default) | integer in the range [0, 127], excluding 1

Time to live for the message, specified as an integer in the range [0, 127], excluding 1. If you set the Role property of the bluetoothLENode object to "broadcaster-observer", this value is optional. If the value is not set, the function uses the default TTL property value 127 of the bluetoothMeshProfileConfig object. This value specifies the maximum number of hops that the transmitted message can traverse between the source and destination elements. For more information about the TTL value, see Bluetooth mesh profile v1.0.1, section 4.2.7.

Data Types: double

References

[1] Bluetooth Technology Website. “Bluetooth Technology Website | The Official Website of Bluetooth Technology.” Accessed November 12, 2021. https://www.bluetooth.com/.

[2] Bluetooth Core Specifications Working Group. "Bluetooth Core Specification" v5.3. https://www.bluetooth.com/.

Version History

Introduced in R2022a