Main Content

updateChannelList

Provide updated channel list to Bluetooth LE node

collapse all in page

    Syntax

    status = updateChannelList(bluetoothLENodeObj,newUsedChannelsList)
    status = updateChannelList(bluetoothLENodeObj,newUsedChannelsList,DestinationNode=destinationNode)

    Description

    status = updateChannelList(bluetoothLENodeObj,newUsedChannelsList) updates the channel map by providing a new list of used channels, newUsedChannelsList, to the Bluetooth® low energy (LE) node specified by the bluetoothLENodeObj object. The object function returns the status, status, indicating whether the node accepted the new channel list. To use this syntax, set the Role property of bluetoothLENode to "isochronous-broadcaster".

    example

    status = updateChannelList(bluetoothLENodeObj,newUsedChannelsList,DestinationNode=destinationNode) additionally specifies the destination node, DestinationNode, to which this object function provides a new list of used channels. To use this syntax, set the Role property of the bluetoothLENode object to "central" and the Role property of the destination node to "peripheral".

    Examples

    collapse all

    Open Live Script

    Create a wireless network simulator.

    networkSimulator = wirelessNetworkSimulator.init();

    Create a Bluetooth LE node, specifying the role as "central". Specify the position of the node.

    centralNode = bluetoothLENode("central");
centralNode.Position = [0 0 0]                  % In x-, y-, z-direction, in meters
    centralNode = 
  bluetoothLENode with properties:

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

   Read-only properties:
                    Role: "central"
        ConnectionConfig: [1×1 bluetoothLEConnectionConfig]
         PeripheralCount: 0
          TransmitBuffer: [1×1 struct]
                      ID: 1

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

    peripheralNode = bluetoothLENode("peripheral");
peripheralNode.Position = [10 0 0]              % In x-, y-, z-direction, in meters
    peripheralNode = 
  bluetoothLENode with properties:

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

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

    Create a Bluetooth LE configuration object, specifying the connection interval and active period for the connection.

    cfgConnection = bluetoothLEConnectionConfig (...
    ConnectionInterval=0.02, ...                  % In seconds
    ActivePeriod=0.02, ...                        % In seconds
    ConnectionOffset=0);                          % In seconds

    Configure the link layer (LL) connection between the Central and Peripheral nodes.

    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. Add application traffic from the Central to the Peripheral node by using the addTrafficSource object function.

    traffic = networkTrafficOnOff(DataRate=500, ...
    PacketSize=10, ...
    GeneratePacket=true);
addTrafficSource(centralNode,traffic,"DestinationNode",peripheralNode.Name);

    Create a WLAN node to introduce interference in the network by using the helperInterferingWLANNode helper object. Specify the position of the WLAN node. Specify the transmitter power and frequency of operation of the WLAN node. Specify the signal periodicity in which the WLAN node transmits the signal.

    wlanNode = helperInterferingWLANNode( ...
Position=[2 0 0], ...                      % In x-, y-, z-direction, in meters
TransmitterPower=30, ...                   % In dBm
CenterFrequency=2.472e9, ...               % In Hz
SignalPeriodicity=2e-3);                   % In seconds

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

    nodes = {centralNode peripheralNode wlanNode};

    Add a listener for an event by using the addlistener function. This function attaches the listener to the source of the event, which is a handle object. When an event is triggered, the addlistener function invokes the callback function.

    Assume that when the number of retransmitted packets in the Bluetooth LE network is greater than 100 and when the packet loss ratio is greater than 0.2, the used (good) channels list is updated to use only channels 1-10. This function is implemented in the callback function channelMapUpdateFcn. To check statistics and update the channels at the end of each connection event, create a listener at the Central node for the ConnectionEventEnded event. Because the Central node classifies and updates the channel map for all of the Peripheral nodes, a listener is created at the Central node.

    addlistener(centralNode,"ConnectionEventEnded",@(nodeobj,eventdata) channelMapUpdateFcn(nodeobj,peripheralNode.Name));

    Create a function handle to display the updated list of used channels for Bluetooth LE communication.

    channelMapDispFcnhandle = @(nodeobj,eventdata) disp(['Channel map is updated and the used channels are ' ...
    num2str(eventdata.Data.UpdatedChannelList) ' at ' num2str(eventdata.Data.CurrentTime) ' seconds']);

    To display the updated list of channels after the Central node updates the channel map, create a listener at the Central node for the ChannelMapUpdated event. The listener returns the source node object and the event data. The event data is a structure containing the event information that triggered the listener.

    addlistener(centralNode,"ChannelMapUpdated",channelMapDispFcnhandle);

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

    addNodes(networkSimulator,nodes)

    Set the simulation time and run the simulation.

    simulationTime = 0.3;                 % In seconds
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 related to the source, relay, and destination nodes by using the statistics object function. For more information about the statistics, see Bluetooth LE Node Statistics.

    centralStats = statistics(centralNode)
    centralStats = struct with fields:
    Name: "Node1"
      ID: 1
     App: [1×1 struct]
      LL: [1×1 struct]
     PHY: [1×1 struct]


    peripheralStats = statistics(peripheralNode)
    peripheralStats = struct with fields:
    Name: "Node2"
      ID: 2
     App: [1×1 struct]
      LL: [1×1 struct]
     PHY: [1×1 struct]

    The callback function of the ConnectionEventEnded event channelMapUpdateFcn retrieves the statistics corresponding to the Bluetooth LE node object. This function checks whether these conditions are true.

    • The number of retransmitted packets in the Bluetooth LE network is greater than 100.

    • The packet loss ratio is greater than 0.2.

    If the conditions are true, the function updates the channel map in the Bluetooth LE node object to use Bluetooth LE channels 1-10 by using the updateChannelList object function of the bluetoothLENode object.

    function channelMapUpdateFcn(nodeobj,peripheralName)
usedChannels = 1:10;
stats = statistics(nodeobj);
if stats.LL.RetransmittedDataPackets > 100 && stats.LL.PacketLossRatio > 0.2
    updateChannelList(nodeobj,usedChannels,"DestinationNode",peripheralName);
end
end

    Input Arguments

    collapse all

    Bluetooth LE node object, specified as a bluetoothLENode object.

    List of good channels, specified as an integer vector with element values in the range [0, 36]. This input specifies the new list of used channels to update the channel map for the specified Bluetooth LE node. To ensure that at least two channels are set as used (good) channels, specify a vector length greater than 1.

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

    Data Types: char | string

    Output Arguments

    collapse all

    Flag indicating whether LL of the specified Bluetooth LE node bluetoothLENodeObj accepts the new channel list, returned as 0 (false) or 1 (true).

    Data Types: logical

    References

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

    [2] Bluetooth Special Interest Group (SIG). "Bluetooth Core Specification". v5.3. https://www.bluetooth.com/.

    Version History

    Introduced in R2022a

    See Also

    Objects

    Functions