bleGAPDataBlockConfig

Configuration object for BLE GAP data block

expand all in page

Download Required: To use bleGAPDataBlockConfig, first download Communications Toolbox™ Library for the Bluetooth® Protocol. For more information, see Get and Manage Add-Ons. Alternatively, see Communications Toolbox Library for the Bluetooth Protocol File Exchange.

Description

The bleGAPDataBlockConfig creates a configuration object for a Bluetooth low energy (BLE) generic access profile (GAP) data block of the type advertising data (AD) or scan response data (SRD). You can configure a BLE GAP data block using the applicable properties of bleGAPDataBlockConfig.

Creation

Syntax

cfgGAP = bleGAPDataBlockConfig
cfgGAP = bleGAPDataBlockConfig(Name,Value)

Description

example

cfgGAP = bleGAPDataBlockConfig creates a configuration object, cfgGAP, for a BLE GAP data block of the type AD or SRD with default values.

example

cfgGAP = bleGAPDataBlockConfig(Name,Value) sets properties using one or more name-value pairs. Enclose each property name in quotes. For example, bleGAPDataBlockConfig('AdvertisingDataTypes','Tx power level') configures cfgGAP with block data advertising data type as 'Tx power level'.

Properties

expand all

Note

For more information about BLE GAP data block properties and their respective values, see vol 3, part C, section 4 of the Bluetooth Core Specification [2].

Block data advertising data types, specified as a character vector or a string scalar or a cell array, containing the list of advertising data types for BLE GAP data block. You can specify AdvertisingDataTypes as one of these values:

  • 'Flags'

  • 'UUIDs'

  • 'Local name'

  • 'Tx power level'

  • 'Connection interval range'

  • 'Advertising interval'

Data Types: char | string | cell

LE discoverable mode, specified as a character vector or a string scalar, describing the LE discoverable mode of the device. You can specify LEDiscoverability as one of these values:

  • 'None'

  • 'General'

  • 'Limited'

  • 'Limited and general'

Data Types: char | string

Basic rate (BR) or enhanced data rate (EDR ) support, specified as true or false. A true value indicates that BR or EDR is supported. This is used when AdvertisingDataTypes is set to 'Flags'.

Data Types: logical

Simultaneous LE and BR/EDR support, specified as a character vector or a string scalar. You can specify 'LE' as one of these values:

  • 'None'

  • 'Host'

  • 'Controller'

  • 'Host and controller'

This property is applicable only when BREDR is set to true. Set this property to 'Host' or 'Controller' to specify simultaneous LE and BR or EDR support at the host or the controller respectively. Set this property to 'Host and Controller' for simultaneous LE and BR or EDR support at the host and the controller.

Data Types: char | string

Local name shortened used, specified as a scalar logical value of false or true. Set this value to true value indicates that the name of the device is shortened.

Data Types: logical

UTF-8 encoded user-friendly descriptive name, specified as a character vector or a string scalar consisting of UTF-8 characters. This property specifies the local name assigned to the device.

Data Types: char | string

Type of 16-bit service or service class identifiers, specified as 'Incomplete' or 'Complete'. If this value is 'Incomplete', then the list of 16-bit service or service class identifiers list is incomplete.

Data Types: char | string

List of 16-bit service or service class identifiers, specified as an n-by-4 character array. The value of n must be in the range [0, 127]. Each row in the n-by-4 character array is represented as a four-element character vector or string scalar denoting a two-octet (16-bit) hexadecimal value of a service or service class universally unique identifier (UUID). These UUIDs are assigned by the Bluetooth Special Interest Group (SIG).

Data Types: char

Advertising interval, specified as an integer in the range [32, 65,535]. This property denotes the interval between the start of two consecutive advertising events. Incremental units are 0.625 ms steps, so the resultant range for [32, 65,535] is [20, 40.959375].

Data Types: double

Packet transmit power level, in dBm, specified as an integer in the range [–127, 127]. This property calculates the pathloss as pathloss = Tx Power Level – RSSI, where RSSI is the received signal strength indicator.

Data Types: double

Connection interval range, specified as a two-element numeric vector [MIN, MAX], where MIN and MAX must be in the range [6,3200]. MIN and MAX specify the minimum and maximum value for the connection interval respectively. MIN must be less than or equal to MAX. Incremental units are 1.25 ms steps, so that the resultant range for [6, 3200] is [7.5, 4.0].

Data Types: double

Object Functions

expand all

bleGAPDataBlockGenerate BLE GAP data block
bleGAPDataBlockDecodeDecode BLE GAP data block

Examples

collapse all

This example uses:

Open Live Script

Create two unique BLE GAP AD configuration objects: one with AD types 'Flags' and 'Tx power level' and the other with AD type 'Flags' and simultaneous LE and BR or EDR support at the host.

Create a BLE GAP AD block configuration object using default settings. Set the values of AD types as 'Flags' and 'Tx power level', LE discoverability as 'Limited' and Tx power level as 45. View the properties of the corresponding configuration object.

cfgGAP = bleGAPDataBlockConfig;
cfgGAP.AdvertisingDataTypes = {'Flags';'Tx power level'};
cfgGAP.LEDiscoverability = 'Limited';
cfgGAP.TxPowerLevel = 45
cfgGAP = 
  bleGAPDataBlockConfig with properties:

    AdvertisingDataTypes: {2x1 cell}
       LEDiscoverability: 'Limited'
                   BREDR: 0
            TxPowerLevel: 45

Create another BLE GAP AD block configuration object using default settings, this time with AD type 'Flags' and having simultaneous support for LE and BR/EDR. Set the values of LE discoverability as 'Limited', enable BR or EDR support as true and enable simultaneous support for LE and BR or EDR as 'Host'. View the properties of the corresponding configuration object.

cfgGAP = bleGAPDataBlockConfig;
cfgGAP.LEDiscoverability = 'Limited and general';
cfgGAP.BREDR = true;
cfgGAP.LE = 'Host'
cfgGAP = 
  bleGAPDataBlockConfig with properties:

    AdvertisingDataTypes: {'Flags'}
       LEDiscoverability: 'Limited and general'
                   BREDR: 1
                      LE: 'Host'

This example uses:

Open Live Script

Create a configuration object for a BLE GAP AD block using name-value pairs. Set the values of AD types as 'Advertising interval' and 'Local name', advertising interval as 48, local name as 'MathWorks' and local name shortening as true. View the properties of the corresponding configuration object.

cfgGAP = bleGAPDataBlockConfig('AdvertisingDataTypes', ...
    {'Advertising interval', ...
    'Local name'});
cfgGAP.AdvertisingInterval = 48;
cfgGAP.LocalName = 'MathWorks';
cfgGAP.LocalNameShortening = true
cfgGAP = 
  bleGAPDataBlockConfig with properties:

    AdvertisingDataTypes: {2x1 cell}
               LocalName: 'MathWorks'
     LocalNameShortening: 1
     AdvertisingInterval: 48

This example uses:

Open Live Script

Create a configuration object for a BLE GAP AD block using name-value pairs. Set the values of AD types as 'Advertising interval' and 'Local name', advertising interval as 48, local name as 'MathWorks', and local name shortening as true. View the properties of the corresponding configuration object.

cfgTx = bleGAPDataBlockConfig('AdvertisingDataTypes',{'Advertising interval','Local name'});
cfgTx.AdvertisingInterval = 48;
cfgTx.LocalName = 'MathWorks';
cfgTx.LocalNameShortening = true
cfgTx = 
  bleGAPDataBlockConfig with properties:

    AdvertisingDataTypes: {2x1 cell}
               LocalName: 'MathWorks'
     LocalNameShortening: 1
     AdvertisingInterval: 48

Create a BLE GAP AD block using the configuration object 'cfgTx'.

dataBlock = bleGAPDataBlock(cfgTx);

Decode the generated BLE GAP AD block. The returned status indicates decoding was successful. View the output of 'status' and 'cfgRx'.

[status, cfgRx] = bleGAPDataBlockDecode(dataBlock)
status = 
Success

cfgRx = 
  bleGAPDataBlockConfig with properties:

    AdvertisingDataTypes: {2x1 cell}
               LocalName: 'MathWorks'
     LocalNameShortening: 1
     AdvertisingInterval: 48

References

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

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

[3] Bluetooth Special Interest Group (SIG). "Supplement to the Bluetooth Core Specification." CSS Version 7 (2016).

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

See Also

Functions

Topics

Introduced in R2019b

Communications Toolbox Documentation

Support