addTrafficSource

Add data traffic source to Bluetooth LE node

Since R2022a

Syntax

addTrafficSource(bluetoothLENodeObj,trafficSource)

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationNode=destinationNode)

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationNode=destinationNode,CISConfig=cisConfig)

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

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

Description

This feature also requires the Wireless Network Toolbox™ product.

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

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

addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationNode=destinationNode,CISConfig=cisConfig) adds a data traffic source to send data to the connected isochronous stream (CIS) connection cisConfig of the specified destination node destinationNode. The Role property of bluetoothLENodeObj 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 bluetoothLENodeObj 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 bluetoothLENodeObj object must be set to "broadcaster-observer".

Note

• Each time you call this object function, you add a traffic generator (source) to a Bluetooth LE node. You can add multiple traffic sources to a node, directing them to the same or different destination nodes.

• Reusing the same traffic source object in another addTrafficSource object function call results in an error.

Examples

Create, Configure, and Simulate Bluetooth LE Network with Custom Channel

This example enables you to:

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. Create a custom channel, and plug it into the wireless network simulator.

5. Simulate Bluetooth LE network and retrieve the statistics of the Central and Peripheral nodes.

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",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",Name="PeripheralNode");
peripheralNode.Position = [10 0 10]              % In x-, y-, and z-coordinates in meters

peripheralNode = 
  bluetoothLENode with properties:

        TransmitterPower: 20
         TransmitterGain: 0
            ReceiverGain: 0
     ReceiverSensitivity: -100
             NoiseFigure: 0
    InterferenceModeling: "overlapping-adjacent-channel"
                    Role: "peripheral"
        ConnectionConfig: [0×0 bluetoothLEConnectionConfig]
               CISConfig: [0×0 bluetoothLECISConfig]
                Position: [10 0 10]
                    Name: "PeripheralNode"
                Mobility: []

   Read-only properties:
                      ID: 2
                Velocity: [0 0 0]

Add a random waypoint mobility model to the Bluetooth peripheral node. Set the shape of the node's mobility area to "circle".

addMobility(peripheralNode,BoundaryShape="circle",RefreshInterval=0.1)

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
                MaxPDU: 251
                  TIFS: 1.5000e-04
                 TMCES: 1.5000e-04

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 (Wireless Network Toolbox) 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);

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

addTrafficSource(centralNode,traffic,DestinationNode=peripheralNode);

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)

Add the custom channel to the wireless network simulator.

addChannelModel(networkSimulator,@addImpairment);

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 Central and Peripheral nodes. For more information about the statistics, see Bluetooth LE Node Statistics.

centralStats = statistics(centralNode)

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

peripheralStats = statistics(peripheralNode)

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

Follow these steps to create a custom channel that models Bluetooth path loss for an industrial scenario.

• Create a custom function with this syntax: rxData = customFcnName(rxInfo,txData). The rxInfo input specifies the receiver node information as a structure, and the txData input specifies the transmitted packets as a structure. The simulator automatically passes information about the receiver node and the packets transmitted by a transmitter node as inputs to the custom function. For more information about creating custom channel, see the addChannelModel (Wireless Network Toolbox) object function.

• Use the bluetoothPathLossConfig object to set path loss configuration parameters for an industrial scenario.

• Calculate path loss between the Central and Peripheral nodes using the bluetoothPathLoss function. Specify the transmitter and receiver positions.

• Apply path loss to the transmitted packets.

function rxData = addImpairment(rxInfo,txData)

    pathlossCfg = bluetoothPathLossConfig(Environment="Industrial");

    % Apply path loss and update output signal
    rxData = txData;

    % Calculate the distance between transmitter and receiver in meters
    distance = norm(rxData.TransmitterPosition - rxInfo.Position);
    pathloss = bluetoothPathLoss(distance,pathlossCfg);
    rxData.Power = rxData.Power-pathloss;                           % In dBm
    scale = 10.^(-pathloss/20);
    [numSamples,~] = size(rxData.Data);
    rxData.Data(1:numSamples,:) = rxData.Data(1:numSamples,:)*scale;
end

Simulate Bluetooth LE Mesh Network by Adding Traffic Between Single Source and Multiple Destinations

Create a wireless network simulator.

networkSimulator = wirelessNetworkSimulator.init;

Create three mesh profile configuration objects, specifying the unicast element address for each object.

cfgMeshNode1 = bluetoothMeshProfileConfig(ElementAddress="0001");
cfgMeshNode2 = bluetoothMeshProfileConfig(ElementAddress="0002");
cfgMeshNode3 = bluetoothMeshProfileConfig(ElementAddress="0003");

Create three Bluetooth LE mesh nodes by using the specified configurations, and set their role to "broadcaster-observer". Specify the position (in meters) of each node in 3-D Cartesian coordinates.

meshNode1 = bluetoothLENode("broadcaster-observer",MeshConfig=cfgMeshNode1,Position=[0 0 1]);
meshNode2 = bluetoothLENode("broadcaster-observer",MeshConfig=cfgMeshNode2,Position=[0 1 0]);
meshNode3 = bluetoothLENode("broadcaster-observer",MeshConfig=cfgMeshNode3,Position=[1 1 0]);

Create an On-Off application traffic pattern generator object, specifying the length (in bytes) of the packet to be generated.

trafficSource = networkTrafficOnOff(PacketSize=10);

Add application traffic from the source node meshNode1 to the destination nodes meshNode2 and meshNode3.

addTrafficSource(meshNode1,trafficSource,SourceAddress="0001",DestinationAddress=["0002" "0003"])

Create a Bluetooth LE mesh network consisting of three mesh nodes.

nodes = {meshNode1 meshNode2 meshNode3};

Add all the mesh nodes to the wireless network simulator.

addNodes(networkSimulator,nodes)

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

simulationTime = 1;
run(networkSimulator,simulationTime)

Retrieve application, LL, and PHY statistics for each of the mesh nodes.

meshNodeStats1 = statistics(meshNode1)

meshNodeStats1 = struct with fields:
         Name: "Node1"
           ID: 1
          App: [1×2 struct]
    Transport: [1×1 struct]
      Network: [1×1 struct]
           LL: [1×1 struct]
          PHY: [1×1 struct]

meshNodeStats2 = statistics(meshNode2)

meshNodeStats2 = struct with fields:
         Name: "Node2"
           ID: 2
          App: [1×1 struct]
    Transport: [1×1 struct]
      Network: [1×1 struct]
           LL: [1×1 struct]
          PHY: [1×1 struct]

meshNodeStats3 = statistics(meshNode3)

meshNodeStats3 = struct with fields:
         Name: "Node3"
           ID: 3
          App: [1×1 struct]
    Transport: [1×1 struct]
      Network: [1×1 struct]
           LL: [1×1 struct]
          PHY: [1×1 struct]

Input Arguments

bluetoothLENodeObj — Bluetooth LE node object

bluetoothLENode object | vector of bluetoothLENode objects

Bluetooth LE node object, specified as a bluetoothLENode object or a vector of bluetoothLENode objects. If you specify the Role property of this input as:

• "central" or "peripheral"

  • The destinationNode name-value argument is mandatory and its Role property must be set to "central" or "peripheral".

  • If you add traffic between a CIS connection, the cisConfig name-value argument is mandatory and this input must be a bluetoothLENode object.

• "broadcaster-observer"

  • The sourceElementAddress and destinationElementAddress name-value arguments are applicable, and the destinationNode name-value argument is not applicable.

  • If this input is a vector of bluetoothLENode objects, the sourceElementAddress and destinationElementAddress name-value arguments must each be a bluetoothLENode object.

• "broadcaster" or "isochronous-broadcaster"

  • The Name-Value Arguments are not applicable.

trafficSource — On-Off application traffic pattern class

networkTrafficOnOff object | object of subclass of wnet.Traffic

On-Off application traffic pattern class, specified as a networkTrafficOnOff (Wireless Network Toolbox) object or an object of a subclass of the wnet.Traffic (Wireless Network Toolbox) class. To add an On-Off application traffic pattern, configure the networkTrafficOnOff object of the wnet.traffic class.

If you specify this input, the generatePacket property of the networkTrafficOnOff object is not applicable because the Bluetooth LE node always generates the packets.

When you add application traffic to a Bluetooth LE node by using this object function, the bluetoothLENodeObj automatically calls the generate (Wireless Network Toolbox) object function associated with the trafficSource object to generate the corresponding application traffic packet. This object function creates a copy of this input and adds it to the node, irrespective of whether you pass a scalar or a vector.

You can configure a custom traffic source by using the wnet.traffic class. The addTrafficSource object function creates a copy of that traffic source and adds it to the node, so changes you make to the original traffic source after adding it do not take effect in the node.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addTrafficSource(bluetoothLENodeObj,trafficSource,DestinationAddress="0005")

destinationNode — Destination node of traffic

character vector | string scalar | bluetoothLENode object | vector of bluetoothLENode objects

Destination node of traffic, specified as a character vector, a string scalar, a bluetoothLENode object or a vector of bluetoothLENode objects. If you set the Role property of the bluetoothLENodeObj input object to "central" or "peripheral", this name-value argument is mandatory. The value of this name-value argument depend on these conditions:

• bluetoothLENodeObj is a scalar and cisConfig is not specified — Specify this input as a bluetoothLENode object or a vector of bluetoothLENode objects. This object function copies the object specified to the trafficSource argument and sends it to all the specified destination nodes.

• bluetoothLENodeObj is a vector and cisConfig is not specified — Specify this input as a bluetoothLENode object. This object function copies the object specified to the trafficSource argument and sends it to the specified destination node.

• bluetoothLENodeObj is a scalar and cisConfig is specified — Specify this input as a bluetoothLENode object. This object function copies the object specified to the trafficSource argument and attaches to each specified CIS configuration between bluetoothLENodObj and destinationNode .

Data Types: char | string

cisConfig — CIS connection configuration of destination node

bluetoothLECISConfig object | vector of bluetoothLECISConfig objects

CIS connection configuration of the destination node, specified as a bluetoothLECISConfig object or a vector of bluetoothLECISConfig objects. When you establish a CIS connection between the Central and Peripheral nodes, the configureConnection object function returns this value.

When you specify this value as a scalar or a vector, this object function attaches a copy of the trafficSource to each specified CIS configuration between the bluetoothLENodeObj and destinationNode. You can specify this name-value argument only when these conditions are satisfied.

• The bluetoothLENodeObj and destinationNode input objects have a Role property set to "central" or "peripheral" and a CIS connection exists between them.

• bluetoothLENodeObj and destinationNode are scalar bluetoothLENode objects.

destinationElementAddress — Destination element address

four-element character vector | string scalar | vector of strings denoting a two-octet hexadecimal address

Destination element address, specified as a four-element character vector, string scalar, or a vector of strings denoting a two-octet hexadecimal address. If you set the Role property of the bluetoothLENodeObj input object to "broadcaster-observer", this input is mandatory. This value specifies the element address of the Bluetooth mesh destination node that you can configure using the ElementAddress property of the bluetoothMeshProfileConfig object.

Specify this input based on the sourceElementAddress value under these conditions.

• If sourceElementAddress is a scalar — Specify this input as a scalar or a vector to attach a copy of the traffic from the element addresses specified by sourceElementAddress to the element addresses specified by destinationElementAddress.

• If sourceElementAddress is a vector — Specify this input as a scalar to attach a copy of the traffic from all the element addresses specified by sourceElementAddress to the element address specified by destinationElementAddress.

• If sourceElementAddress is not specified — Specify this input as a scalar to attach a copy of the traffic from all the elements specified by bluetoothLENodeObj to the element address specified by destinationElementAddress.

Data Types: char | string

sourceElementAddress — Source element address

four-element character vector | string scalar | vector of strings denoting a two-octet hexadecimal address

Source element address, specified as a four-element character vector, string scalar, or a vector of strings denoting a two-octet hexadecimal address. This value specifies the element address of the Bluetooth mesh source node that you can configure using the ElementAddress property of the bluetoothMeshProfileConfig object.

Specify this input based on the bluetoothLENodeObj value under these conditions.

• If bluetoothLENodeObj is a scalar:

  • If you specify this input as a scalar, the object function attaches a copy of the traffic source from that source element to all the elements in destinationElementAddress.

  • If you specify this input as a vector, the object function attaches a copy of the traffic source from all the specified source element addresses to the destinationElementAddress. Note that the destinationElementAddress must be a scalar.

  • If you do not specify this input, the object function attaches a copy of the traffic source from all the elements of bluetoothLENodeObj to destinationElementAddress. Note that the destinationElementAddress must be a scalar.

• If bluetoothLENodeObj is a vector — The object function ignores this input and attaches a copy of the traffic source from all elements of each source node to the scalar destinationElementAddress.

Data Types: char | string

Note

Each node in the mesh network must have a unique element address. Two nodes cannot share the same source element address.

ttl — Time to live for message

127 (default) | 0 | integer in range [2, 127]

Time to live for the message, specified as 0 or an integer in the range [2, 127]. If you set the Role property of the bluetoothLENodeObj object to "broadcaster-observer", this value is optional. If you do not set this value, the object function uses the default value of the TTL property 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 [3].

Data Types: double

Note

In the connection establishment procedure, the traffic configuration that you set between the nodes is applicable only when the connection between the nodes is active.

References

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

[2] Bluetooth Core Specifications Working Group. "Bluetooth Core Specification" v6.1. https://www.bluetooth.com/specifications/specs/core-specification-6-1/.

[3] Bluetooth Special Interest Group (SIG). "Bluetooth Mesh Profile". v1.0.1. https://www.bluetooth.com/specifications/specs/mesh-model-1-0-1/.

Version History

Introduced in R2022a

R2026a: Moved to Bluetooth Toolbox and requires Wireless Network Toolbox

Starting in R2026a, this feature is available in Bluetooth Toolbox and also requires a Wireless Network Toolbox license. In prior releases, the feature is available through the Communications Toolbox™ Wireless Network Simulation Library add-on.

R2026a: Vectorization support to add traffic

The addTrafficSource object function now enables you to add a traffic source from a single source node to multiple destination nodes and from multiple source nodes to a single destination node in a single function call.