bluetoothLECISConfig

Bluetooth LE CIS configuration parameters

Since R2023b

Description

Use the bluetoothLECISConfig object to specify the connected isochronous stream (CIS) configuration parameters of a Bluetooth^® low energy (LE) node. This object enables the bluetoothLENode object to support connected multistream audio.

Creation

Syntax

cfgCIS = bluetoothLECISConfig

cfgCIS = bluetoothLECISConfig(Name=Value)

Description

cfgCIS = bluetoothLECISConfig creates a default Bluetooth LE CIS configuration object.

cfgCIS = bluetoothLECISConfig(Name=Value) sets properties of the Bluetooth LE CIS configuration object by using one or more optional name-value arguments. For example, bluetoothLECISConfig(NumSubevents=2) sets the number of subevents in the CIS event to two.

Properties

ISOInterval — Time between successive anchor points of CIS

0.020 (default) | scalar in range [0.005, 4]

Time between successive anchor points of a CIS, specified as a scalar in the range [0.005, 4]. Units are in seconds. Set this property as a multiple of 1.25 milliseconds.

Because the connection events and CIS events in a Bluetooth LE network operate simultaneously at regular intervals, specify this property as $$\frac{ConnectionInterval}{NumPeripherals}$$. The ConnectionInterval value, specified by the ConnectionInterval property of the bluetoothLEConnectionConfig object, sets the interval between the start of two consecutive connection events. The NumPeripherals value specifies the total number of Peripheral nodes simulated in the network. For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.13.1.

Data Types: double

NumSubevents — Number of subevents in CIS event

1 (default) | integer in range [1, 31]

Number of subevents in the CIS event, specified as an integer in the range [1, 31]. For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.13.2.

Data Types: double

SubInterval — Time between start of two consecutive subevents in CIS

0 | scalar in range [0.0004, 4]

Time between the start of two consecutive subevents in CIS, specified as a scalar in the range [0.0004, 4]. Units are in seconds.

• If you set the NumSubevents property to 1, this value must be 0.

• If you set the NumSubevents property to a value other than 1, this value must be a scalar in the range [SubEventLength, ISOInterval]. To calculate the SubEventLength value, use the subeventLength object function.

• If you set the CISArrangement property to "sequential":

  • The object internally generates this value.

  • This value must be greater than or equal to the SubEventLength value of the CIS.

  • The default value of this property is SubEventLength.

• If you set the CISArrangement property to "interleaved":

  • Set this value greater than or equal to the SubEventLength value of all the CIS events in the connected isochronous group (CIG).

  • The default value of this property is the sum of all the subeventLength values of CIS events.

Data Types: double

BurstNumber — Number of unique payloads in CIS event

1 (default) | integer in range [0,15] | 1-by-2 vector

Number of unique payloads in a CIS event, specified as an integer in the range [0,15] or a 1-by-2 vector. This property specifies the number of unique payloads for the host to transmit through the link layer (LL) to other nodes using the CIS events.

• If you set this property as a vector, the first element specifies the burst number from the Central node to the Peripheral node, and the second element specifies the burst number from the Peripheral node to the Central node.

• If you set this property as a scalar, the object uses the same burst number value in both directions.

For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.13.3.

Data Types: double

MaxPDU — Maximum number of data octets that a CIS PDU can carry

251 (default) | decimal octets in range [0, 251] | 1-by-2 vector

Maximum number of data octets that a CIS protocol data unit (PDU) can carry, specified as decimal octets in the range [0, 251] or a 1-by-2 vector. If the data octets contain a message integrity check, this property excludes it.

• If you set this property as a vector, the first element specifies the maximum PDU size from the Central node to the Peripheral node, and the second element specifies the maximum PDU size from the Peripheral node to the Central node.

• If you set this property as a scalar, the object uses the same maximum PDU size in both directions.

For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.13.3.

Data Types: double

FlushTimeout — Maximum number of CIS events to use to transmit and retransmit payload

1 (default) | integer in range [1, 255] | 1-by-2 vector

Maximum number of CIS events to use to transmit and retransmit a payload, specified as an integer in the range [1, 255] or a 1-by-2 vector.

• If you set this property as a vector, the first element specifies the flush timeout from the Central node to the Peripheral node, and the second element specifies the flush timeout from the Peripheral node to the Central node.

• If you set this property as a scalar, the object uses the same flush timeout in both directions.

This property enables you to specify the appropriate CIS event and subevent numbers at which the LL discards the payload associated with the CIS data PDU to prevent continuous retransmissions. For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.13.3.

Data Types: double

CISArrangement — Arrangement of CIS events

"sequential" (default) | "interleaved"

Arrangement of CIS events, specified as "sequential" or "interleaved". If you set this property to "sequential", all the subevents of a CIS event occur simultaneously. If you set this property to "interleaved", the subevents corresponding to each CIS event are adjacent to each other. For more information about this property, see Bluetooth Core Specification v5.3 [2], Volume 6, Part B, Section 4.5.14.2.

Data Types: double

Object Functions

subeventLength

Compute subevent length of CIS

Examples

Create, Configure, and Simulate Multistream Audio in Bluetooth LE Piconet

Simulate multistream audio in a Bluetooth LE piconet consisting of a Central node and two Peripheral nodes by using Bluetooth Toolbox and the Communications Toolbox™ Wireless Network Simulation Library.

Using this example, you can:

1. Create and configure a Bluetooth LE piconet consisting of a Central node and two Peripheral nodes.

2. Establish asynchronous connection-oriented logical transport (ACL) and CIS connections between the Central node and the Peripheral nodes.

3. Generate, configure, and add On-Off application traffic from the Central node to the Peripheral nodes.

4. Simulate the scenario and visualize the statistics.

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

Initialize the wireless network simulator.

networkSimulator = wirelessNetworkSimulator.init;

Create a Bluetooth LE Central node and two Peripheral nodes, specifying their respective positions in meters.

central = bluetoothLENode("central",Position=[1 0 1]);
rightPeripheral = bluetoothLENode("peripheral",Position=[0 1 1]);
leftPeripheral = bluetoothLENode("peripheral",Position=[1 1 0]);

Create a Bluetooth LE CIS configuration object, specifying the isochronous interval and number of subevents of a CIS connection between the Central node and right Peripheral node.

cfgRightPeripheralCIS = bluetoothLECISConfig(ISOInterval=0.03,NumSubevents=2)

cfgRightPeripheralCIS = 
  bluetoothLECISConfig with properties:

       ISOInterval: 0.0300
      NumSubevents: 2
       SubInterval: []
       BurstNumber: 1
            MaxPDU: 251
      FlushTimeout: 1
    CISArrangement: "sequential"

   Read-only properties:
     AccessAddress: []
             CISID: []
         CISOffset: []

Create a Bluetooth LE connection configuration object, specifying the connection interval, active communication period, and access address of a connection event between the Central and right Peripheral nodes. Configure the CIS connection between the Central and right Peripheral nodes.

cfgConnectionRightPeripheral = bluetoothLEConnectionConfig(ConnectionInterval=0.06, ...
    ActivePeriod=10e-3,AccessAddress="5DA44270");

[connectionConfigRightPeripheral,cisConfigRightPeripheral] = configureConnection(cfgConnectionRightPeripheral, ...
    central,rightPeripheral,CISConfig=cfgRightPeripheralCIS);

Create a Bluetooth LE CIS configuration object, specifying the isochronous interval and number of subevents of a CIS connection between the Central and left Peripheral nodes.

cfgLeftPeripheralCIS = bluetoothLECISConfig(ISOInterval=30e-3,NumSubevents=1);

Create a Bluetooth LE connection configuration object, specifying the connection interval, offset for starting connection event, active communication period, and access address of a connection event between the Central and left Peripheral nodes. Configure the CIS connection between the Central and left Peripheral nodes.

cfgConnectionLeftPeripheral = bluetoothLEConnectionConfig(ConnectionInterval=60e-3, ...
    ConnectionOffset=30e-3,ActivePeriod=10e-3,AccessAddress="5DA44271");

[connectionConfigLeftPeripheral,cisConfigLeftPeripheral] = configureConnection(cfgConnectionLeftPeripheral, ...
    central,leftPeripheral,CISConfig=cfgLeftPeripheralCIS)

connectionConfigLeftPeripheral = 
  bluetoothLEConnectionConfig with properties:

    ConnectionInterval: 0.0600
         AccessAddress: "5DA44271"
          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.0300
          ActivePeriod: 0.0100

cisConfigLeftPeripheral = 
  bluetoothLECISConfig with properties:

       ISOInterval: 0.0300
      NumSubevents: 1
       SubInterval: 0.0045
       BurstNumber: 1
            MaxPDU: 251
      FlushTimeout: 1
    CISArrangement: "sequential"

   Read-only properties:
     AccessAddress: '1A31D8AB'
             CISID: 2
         CISOffset: 0.0190

Generate an On-Off application traffic pattern by using the networkTrafficOnOff object. Configure the On-Off application traffic by specifying the application data rate and packet size. Add application traffic from the Central node to the right and left Peripheral nodes.

trafficSourceToRightPeripheral = networkTrafficOnOff(DataRate=200,PacketSize=100,GeneratePacket=true);
addTrafficSource(central,trafficSourceToRightPeripheral,DestinationNode=rightPeripheral,CISConfig=cisConfigRightPeripheral)

trafficSourceToLeftPeripheral = networkTrafficOnOff(DataRate=100,PacketSize=100,GeneratePacket=true);
addTrafficSource(central,trafficSourceToLeftPeripheral,DestinationNode=leftPeripheral,CISConfig=cisConfigLeftPeripheral)

Add the Source node and right and left Peripheral nodes to the wireless network simulator.

addNodes(networkSimulator,[central rightPeripheral leftPeripheral])

Set the simulation time, in seconds and run the simulation

run(networkSimulator,0.5)

Retrieve the statistics of all the nodes. For information about these statistics, see Bluetooth LE Node Statistics.

sourceStats = statistics(central)

sourceStats = struct with fields:
    Name: "Node1"
      ID: 1
     App: [1x2 struct]
      LL: [1x2 struct]
     PHY: [1x1 struct]

rightPeripheralStats = statistics(rightPeripheral)

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

leftPeripheralStats = statistics(leftPeripheral)

leftPeripheralStats = struct with fields:
    Name: "Node3"
      ID: 3
     App: [1x1 struct]
      LL: [1x1 struct]
     PHY: [1x1 struct]

More About

CIS and ACL Connections Between Central and Peripheral Nodes

This figure shows a CIS and an ACL connection between a Central node and a Peripheral node created by using the default configuration of the bluetoothLECISConfig and bluetoothLEConnectionConfig objects.

In the figure, C and P represent a Central node and a Peripheral node, respectively. According to the Bluetooth Core Specifications v5.3 [2], to stream CIS events, C must establish an ACL link with P. C transmits the control data for audio streaming over the ACL link by using the connection events. C transmits the audio data by using the CIS link through the CIS events. The ACL connection events and CIS events occur at specific intervals. In the preceding figure, X represents the event number of the corresponding event.

The time interval between the start of two consecutive ACL connection events is called the connection interval. The time interval between the start of two consecutive CIS events is called the ISO interval. The ACL connection events between C and P nodes start communicating after the connection offset. The CIS events between C and P nodes start communicating after the active period of the ACL connection event between them.

Within a connection interval, when multiple connections exist between a C node and multiple P nodes, the connection offset value for each new connection is specified by performing these steps.

1. The object defines the connection offset value as $$\left(ConnectionOffsetOld+\left(\frac{ConnectionInterval}{NumPeripherals}\right)\right)$$.

2. For the first connection, the object sets the ConnectionOffsetOld value to 0.

3. For subsequent connections, the ConnectionOffset value of the previous connection determines the ConnectionOffsetOld value.

The ACL connection events for each C and P node pair start after their respective connection offset values expire.

Within an ISO interval, when multiple CIS connections exist between C and P nodes, the CIS events follow these steps.

1. Within a connection interval, the first connection event starts after the connection offset and occurs periodically.

2. The first CIS event starts after the completion of the active period of the connection event.

3. Each subsequent CIS event starts after the completion of the previous CIS event, and repeats in the same manner within the ISO interval.

4. Lastly, all CIS events occur periodically.

Note that the preceding timings and offsets are essential for efficient communication and synchronization between C and P nodes, ensuring smooth data transfer and coordinated operation.

References

[1] Bluetooth Technology Website. “Bluetooth Technology Website | The Official Website of Bluetooth Technology.” Accessed May 22, 2023. https://www.bluetooth.com/.

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

Version History

Introduced in R2023b