Main Content

bleGAPDataBlockDecode

Decode Bluetooth LE GAP data block

    Description

    example

    [status,cfgGAP] = bleGAPDataBlockDecode(dataBlock) decodes a Bluetooth® low energy (LE) 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 Bluetooth LE GAP data block configuration object, cfgGAP.

    Examples

    collapse all

    Decode two unique Bluetooth LE 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 Bluetooth LE GAP AD block. Specify the AD types as 'Flags' and 'Tx power level'. Set the values of LE discoverability to 'Limited' and Tx power level to 45.

    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 Bluetooth LE GAP AD block by using the corresponding configuration object.

    dataBlock1 = bleGAPDataBlock(cfgGAP);

    Decode the generated Bluetooth LE GAP AD block. The returned status indicates decoding was successful.

    [status,cfgGAP] = bleGAPDataBlockDecode(dataBlock1)
    status = 
      blePacketDecodeStatus enumeration
    
        Success
    
    
    cfgGAP = 
      bleGAPDataBlockConfig with properties:
    
        AdvertisingDataTypes: {2x1 cell}
           LEDiscoverability: 'Limited'
                       BREDR: 0
                TxPowerLevel: 45
    
    

    Create another Bluetooth LE 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.

    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 Bluetooth LE GAP AD block by using the corresponding configuration object.

    dataBlock2 = 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(dataBlock2)
    status = 
      blePacketDecodeStatus enumeration
    
        Success
    
    
    cfgGAP = 
      bleGAPDataBlockConfig with properties:
    
        AdvertisingDataTypes: {2x1 cell}
                   LocalName: 'MathWorks'
         LocalNameShortening: 1
         AdvertisingInterval: 48
    
    

    Specify a Bluetooth LE GAP AD block containing corrupted data values.

    dataBlock = ['010106010202'];

    Decode the specified Bluetooth LE GAP AD block. The returned status indicates that the decoding failed because of the corrupted input Bluetooth LE GAP AD block. When decoding fails, the Bluetooth LE GAP AD block configuration object, 'cfgGAP', displays no properties.

    [status,cfgGAP] = bleGAPDataBlockDecode(dataBlock)
    status = 
      blePacketDecodeStatus enumeration
    
        MismatchGAPADLength
    
    
    cfgGAP = 
      bleGAPDataBlockConfig with properties:
    
    

    Input Arguments

    collapse all

    Bluetooth LE 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

    Bluetooth LE GAP data block decoding status, returned as a nonpositive integer of the type blePacketDecodeStatus. This value represents the result of a Bluetooth LE 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.

    Value of statusMember 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 implies failed Bluetooth LE GAP data block decoding. If the decoding fails, the cfgGAP configuration object displays no output.

    Bluetooth LE GAP data block configuration object, returned as a bleGAPDataBlockConfig object.

    References

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

    [2] Bluetooth Special Interest Group (SIG). "Bluetooth Core Specification." Version 5.3. 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™.

    Version History

    Introduced in R2019b