Main Content

bluetoothLENode

Bluetooth LE node

Since R2022a

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

    Description

    Use the bluetoothLENode object to create and configure a Bluetooth® low energy (LE) node.

    Creation

    Description

    example

    LENode = bluetoothLENode(Role) creates a default Bluetooth LE node object for the specified role Role.

    LENode = bluetoothLENode(Role,Name=Value) sets properties of the Bluetooth LE node object by using one or more optional name-value arguments. For example, "central",TransmitterPower=0 sets the transmitter power of the Central node to 0 dBm.

    Properties

    expand all

    Node name, specified as a character vector or string scalar. The default format of this value is "NodeN", where N is the node identifier specified by the ID property.

    Data Types: char | string

    Position in 3-D Cartesian coordinates, specified as a numeric row vector of length three. Specify this value in meters. This value specifies the position of the node in Cartesian x-, y-, z-coordinates.

    Data Types: double

    Signal transmission power, specified as a scalar in the range [-20, 20]. Specify this value in dBm. This value specifies the average power that the transmitter applies to the Bluetooth LE signal before sending it to the antenna.

    Data Types: double

    Transmitter antenna gain, specified as a finite numeric scalar. Specify this value in dB.

    Data Types: double

    Packet reception range of node, specified as a finite positive scalar. Specify this value in meters. If a receiving node receives a signal from a sending node located beyond this value, the receiving node drops the received signal. To reduce the processing complexity of the simulation, set this property to a smaller value.

    Data Types: double

    Receiver antenna gain, specified as a finite numeric scalar. Specify this value in dB.

    Data Types: double

    Receiver sensitivity, specified as a finite numeric scalar. Specify this value in dBm. This property sets the minimum received power to detect the incoming signal. If the received power of an incoming signal is below this value, the node considers the signal invalid.

    Data Types: double

    Noise figure, specified as a finite nonnegative numeric scalar. Specify this value in dB. Use this value to add thermal noise to the received signal.

    Data Types: double

    Fidelity to model interference, specified as an integer in the range [0,1]. To consider packets overlapping in both time and frequency as interference, set this value to 0. To consider all the packets overlapping in time as interference, irrespective of frequency overlap, set this value to 1.

    Data Types: double

    Advertising interval, specified as a scalar in the range [0.02, 10485.759375]. Specify this value in seconds. You must set this value as an integer multiple of 0.625 milliseconds. This value specifies the interval of an advertising event during which the transmission of advertising packets occurs.

    Data Types: double

    Random advertising channel selection, specified as 0 (false) or 1 (true). To model the random selection of advertising channels, set this value to true.

    Data Types: logical

    Scan interval, specified as a scalar in the range [0.0025, 40.960]. Specify this value in seconds. You must set this value as an integer multiple of 0.625 milliseconds. This value specifies the interval in which the node listens for the advertising packets.

    Data Types: double

    Bluetooth mesh profile configuration parameters, specified as a bluetoothMeshProfileConfig object.

    Dependencies

    To enable this property, set the Role property to "broadcaster-observer".

    This property is read-only.

    Node identifier, returned as an integer. This value specifies a unique identifier for the node in the simulation.

    Note

    If you create and store the Bluetooth LE nodes in an uninitialized matrix, the IDs that this property allocates to the nodes can be nonsequential because of the memory allocation to the object in the matrix. For more information about MATLAB memory allocation, see How MATLAB Allocates Memory.

    Data Types: double

    This property is read-only.

    Role of the Bluetooth LE node, specified as one of these values.

    Role Value Description
    "central"Simulate Bluetooth LE node scenario
    "peripheral"Simulate Bluetooth LE node scenario
    "isochronous-broadcaster"Simulate Bluetooth LE broadcast audio network
    "synchronized-receiver"Simulate Bluetooth LE broadcast audio network
    "broadcaster-observer"Simulate Bluetooth LE mesh network

    Data Types: char | string

    This property is read-only.

    Bluetooth LE LL connection configuration parameters, returned as a bluetoothLEConnectionConfig object.

    Dependencies

    To enable this property, set the Role property to "central" or "peripheral".

    This property is read-only.

    Connected isochronous stream (CIS) connection configuration object, specified as a bluetoothLECISConfig object or an array of objects of type bluetoothLECISConfig. To configure multiple CIS connections, set this property as an array of objects of type bluetoothLECISConfig. Note that you can configure a maximum of 31 CIS connections.

    Dependencies

    To enable this property, set the Role property to "central" or "peripheral".

    This property is read-only.

    Number of Peripheral nodes associated with Central node, returned as an integer.

    Dependencies

    To enable this property, set the Role property to "central".

    Data Types: double

    This property is read-only.

    Bluetooth LE BIG configuration parameters, returned as a bluetoothLEBIGConfig object.

    Dependencies

    To enable this property, set the Role property to "isochronous-broadcaster" or "synchronized-receiver".

    This property is read-only.

    Friendship configuration object for Friend and LPN, returned as a bluetoothMeshFriendshipConfig object.

    Dependencies

    To enable this property, set the Role property to "broadcaster-observer".

    Object Functions

    expand all

    addMobilityAdd random waypoint mobility model to Bluetooth LE node
    addTrafficSourceAdd data traffic source to Bluetooth LE node
    channelInvokeDecision(Removed) Determine whether to apply channel to incoming signal
    pushChannelData(Removed) Push data from channel to reception buffer
    runNode(Removed) Run Bluetooth LE node
    updateChannelListProvide updated channel list to Bluetooth LE node
    statisticsGet statistics of Bluetooth LE node

    Examples

    collapse all

    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]
                   CISConfig: [1x1 bluetoothLECISConfig]
              TransmitBuffer: [1x1 struct]
                          ID: 2
    
    

    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");

    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);

    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]
    
    

    More About

    expand all

    References

    [1] Bluetooth Technology Website. “Bluetooth Technology Website | The Official Website of Bluetooth Technology.” Accessed November 22, 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

    expand all