bleGAPDataBlockDecode

Decode BLE GAP data block

collapse all in page

Download Required: To use bleGAPDataBlockDecode, 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.

Syntax

[status,cfgGAP] = bleGAPDataBlockDecode(dataBlock)

Description

example

[status,cfgGAP] = bleGAPDataBlockDecode(dataBlock) decodes a Bluetooth low energy (BLE) generic access profile (GAP) data block, dataBlock, of the type advertising data (AD) or scan response data (SRD), returning the decoding status, status, and the BLE GAP data block configuration object, cfgGAP.

Examples

collapse all

This example uses:

Open Live Script

Decode two unique BLE GAP AD blocks: one with AD types 'Flags' and 'Tx power level' and the other with AD types 'Advertising interval' and 'Local name'.

Create a configuration object for a BLE GAP AD block. Specify the AD types as 'Flags' and 'Tx power level'. Set the values of LE discoverability as 'Limited' and Tx power level to 45. View the properties of the configuration object 'cfgGAP'.

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

Generate a BLE GAP AD block from the corresponding configuration object.

dataBlock = bleGAPDataBlock(cfgGAP);

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

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

cfgGAP = 
  bleGAPDataBlockConfig with properties:

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

Create another BLE GAP AD block configuration object, this time specifying AD types 'Advertising interval' and 'Local name'. Set the values of advertising interval as 48, local name as 'MathWorks', and local name shortening as true. View the properties of the configuration object 'cfgGAP'.

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

Generate the BLE GAP AD block from the corresponding configuration object.

dataBlock = bleGAPDataBlock(cfgGAP);

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

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

cfgGAP = 
  bleGAPDataBlockConfig with properties:

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

This example uses:

Open Live Script

Specify a BLE GAP AD block containing corrupted data values.

dataBlock = ['010106010202']; % Sample BLE GAP AD block with corrupted data values

Decode the specified BLE GAP AD block. The returned status indicates that the decoding failed due to the corrupted input BLE GAP AD block. In this case, when decoding fails, the BLE GAP AD block configuration object, 'cfgGAP', displays no properties.

[status, cfgGAP] = bleGAPDataBlockDecode(dataBlock)
status = 
MismatchGAPADLength

cfgGAP = 
  bleGAPDataBlockConfig with properties:

Input Arguments

collapse all

BLE GAP data block, specified as one of these values:

  • Character vector — This vector represents octets in hexadecimal format.

  • String scalar — This scalar represents octets in hexadecimal format.

  • Numeric vector of elements in the range [0, 255] — This vector represents octets in decimal format.

  • n-by-2 character array — Each row represents an octet in hexadecimal format.

Data Types: char | string | double

Output Arguments

collapse all

BLE GAP data block decoding status, returned as a nonpositive integer of type blePacketDecodeStatus. This value represents the result of an BLE GAP data block decoding. Each value of status corresponds to a member of the blePacketDecodeStatus enumeration class, which indicates the packet decoding status according to this table.

Enumeration ValueMember of Enumeration ClassDecoding Status
0SuccessPacket decoding succeeded
-201 InvalidGAPADLengthGAP AD length is not valid
–202MismatchGAPADLengthReceived AD length does not match with actual length
–203UnsupportedGAPADTypeAdvertising data type is not valid or not supported
–204InvalidGAPAdvertisingIntervalAdvertising interval is not valid
–205InvalidGAPConnectionIntervalRangeInvalid connection interval
–206InvalidGAPConnectionIntervalMinimumInvalid interval minimum
–207InvalidGAPConnectionIntervalMaximumInvalid interval maximum

An enumeration value other than 0 means that the BLE GAP data block decoding failed. If the decoding fails, object cfgGAP displays no output.

BLE GAP data block configuration object, returned as a bleGAPDataBlockConfig object. This value defines the type of BLE GAP data block and its applicable properties.

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

Objects

Topics

Introduced in R2019b

Communications Toolbox Documentation

Support