Prerequisites

The Bluetooth Low Energy Host Stack library contains several external references that the application must define to enable full functionality.

Attention: Application developers must ensure to define these references to prevent linkage errors when trying to build the application binary.

Task and event queues

The task queues are declared in the ble_host_tasks.h as follows:

/*! App to Host message queue for the Host Task */
    extern messaging_t   gApp2Host_TaskQueue;
/*! HCI to Host message queue for the Host Task */
    extern messaging_t   gHci2Host_TaskQueue;
/*! Event for the Host Task Queue */
    extern OSA_EVENT_HANDLE_DEFINE(gHost_TaskEvent);

See Initialization for more details about the RTOS tasks required by the Bluetooth LE Host Stack.

Parent topic:Prerequisites

GATT database

The application must define and populate the database according to its requirements and constraints either statically, at application compile time, or dynamically.

Regardless of how the application creates the GATT database, the following two external references from gatt_database.h must be defined:

/*! The number of attributes in the GATT Database. */
extern uint16_t gGattDbAttributeCount_c;
/*! Reference to the GATT database */
extern gattDbAttribute_t* gattDatabase;

The attribute template is defined as shown here:

**typedef** **struct** {
    uint16_t handle ;
/*!< Attribute handle - cannot be 0x0000; attribute handles need not be consecutive, but must be strictly increasing. */
    uint16_t permissions ;
/*!< Attribute permissions as defined by ATT. */
    uint32_t uuid ;
/*!< The UUID should be read according to the gattDbAttribute_t.uuidType member: for 2-byte and 4-byte UUIDs, this contains the value of the UUID; for 16-byte UUIDs, this is a pointer to the allocated 16-byte array containing the UUID. */
    uint8_t * pValue ;
/*!< Pointer to allocated value array. */
    uint16_t valueLength ;
/*!< Size of the value array. */
    uint16_t uuidType : 2;
/*!< Identifies the length of the UUID; the 2-bit values are interpreted according to the bleUuidType_t enumeration. */
    uint16_t maxVariableValueLength : 10;
/*!< Maximum length of the attribute value array; if this is set to 0, then the attribute's length (valueLength) is fixed and cannot be changed. */
} gattDbAttribute_t ;

Parent topic:Prerequisites

Non-Volatile Memory (NVM) access

The Bluetooth LE Host Stack implements an internal module responsible for managing device information. This module relies on accessing a Non-Volatile Memory module for storing and loading bonded devices data.

The application developers determine the NVM access mechanism through the definition of three functions and one variable. The functions must first pre-process the information and then perform standard NVM operations (erase, write, read). The declarations are as follows:

** bleResult\_t App\_NvmErase**
(
    uint8_t mEntryIdx
);
bleResult_t **App\_NvmRead**
(
    uint8_t  mEntryIdx,
    void*    pBondHeader,
    void*    pBondDataDynamic,
    void*    pBondDataStatic,
    void*    pBondDataLegacy,
    void*    pBondDataDeviceInfo,
    void*    pBondDataDescriptor,
    uint8_t  mDescriptorIndex
);
bleResult_t **App\_NvmWrite**
(
    uint8_t  mEntryIdx,
    void*    pBondHeader,
    void*    pBondDataDynamic,
    void*    pBondDataStatic,
    void*    pBondDataLegacy,
    void*    pBondDataDeviceInfo,
    void*    pBondDataDescriptor,
    uint8_t  mDescriptorIndex
);

The device information is divided into several components to ensure that even software wear leveling mechanisms can be used optimally. The components sizes are fixed (defined in ble_constants.h) and have the following meaning:

API pointer to bond component

Component size (ble_constants.h)

Description

pBondHeader: points to a bleBondIdentityHeaderBlob_t element

gBleBondIdentityHeaderSize_c

Bonding information which is sufficient to identify a bonded device.

pBondDataDynamic: points to a bleBondDataDynamicBlob_t element

gBleBondDataDynamicSize_c

Bonding information that might change frequently.

pBondDataStatic: points to a bleBondDataStaticBlob_t element

gBleBondDataStaticSize_c

Bonding information that is unlikely to change frequently.

pBondDataLegacy: points to a bleBondDataLegacyBlob_t element

gBleBondDataLegacySize_c

Stores legacy pairing and Connection Signature Resolving Key (CSRK) bond information.

pBondDataDeviceInfo: points to a bleBondDataDeviceInfoBlob_t element

gBleBondDataDeviceInfoSize_c

Additional bonding information that can be accessed using the host stack API.

pBondDataDescriptor: points to a bleBondDataDescriptorBlob_t element

gBleBondDataDescriptorSize_c

Bonding information used to store one Client Characteristic Configuration Descriptor (CCCD).

The Bluetooth LE Host Stack handles the format of the bonding information. Therefore, application developers need not to take care of this aspect.

Each bonding data slot must contain one bonding header blob, one dynamic data blob, one static data blob, one data legacy blob, one device information blob, and an array of descriptor blobs equal to gcGapMaximumSavedCccds_c.

Note: The application must define the gcGapMaximumSavedCccds_c. macro according to its requirement. The default value can be found in the ble_constants.h file.)

A slot is uniquely identified by the mEntryIdx parameter.

A descriptor is uniquely identified by the pair mEntryIdx - mDescriptorIndex.

If one or more pointers passed as parameters are NULL, the read from or write to the corresponding blob of the bonding slot must be ignored. The erase function must clear the entire bonding data slot specified by the entry index.

Note: {#section_n4n_rtp_lvb .section}

When Advanced Secure Mode is chosen ( gAppSecureMode_d is defined as 1 in app_preinclude.h), two additional application NVM functions are defined to handle local keys encrypted blob storage. Their declaration is:

bleResult_t App_NvmWriteLocalKeys
(
    uint8_t mEntryIdx,
    void* pLocalKey
)
bleResult_t App_NvmReadLocalKeys
(
    uint8_t mEntryIdx,
    void* pLocalKey
)

The functions write/read a structure of type bleLocalKeysBlob_t into/from NVM using a dedicated data set. The parameter mEntryIdx can be 0 (local IRK is handled) or 1 (local CSRK is handled).

The format of the local keys blob nor about the generation and storage of the local keys is automatically handled in BLE Connection Manager (BleConnManager_GenericEvent). Therefore the application developer need not manage this aspect.

The current implementation of the aforementioned functions uses either the framework NVM module or a RAM buffer. Additional details about the NVM configuration and functionality can be found in the Connectivity Framework Reference Manual. See References.

To enable the NVM mechanism, ensure the following points:

  • gAppUseNvm_d (in app_preinclude.h) is set to 1 and

  • gUseNVMLink_d is set to 1 in the linker options of the toolchain.

Note:

  • If gAppUseNvm_d is set to 0, then all bonding data is stored in the RAM and is accessible until reset or power cycle.

  • If gAppUseNvm_d is set to 1, the default NVM module configurations are applied in the app_preinclude.h file.

Parent topic:Prerequisites