nRF51 SDK: Bonds Manager

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Bonds Manager

When using Bluetooth low energy, a central device and a peripheral device can exchange identification information which they are capable of storing in memory (for example, in non-volatile memory). This information can be used for identity verification between the devices when they reconnect in the future. This relationship is known as a 'bond'.

Bonding Information:

The S110 SoftDevice handles the BLE on-air transactions necessary to establish a new bond or to use a previous bond when it reconnects to a bonded central. It is however up to the application layer to memorize the identification information between connections and to provide them back to the S110 stack when it detects a re-connection from a previously bonded central. This identification information is referred to as Bonding Information in code and the SDK.

System Attributes:

If the application is a GATT server, it stores a set of persistent attributes related to a connection when bonding with a central. On reconnection with the known bonded central, the application restores the related persistent attributes in the last known state back to the S110 SoftDevice. These persistent attributes mainly include the Client Characteristic Configuration Descriptor (or CCCD, see the Bluetooth Core Specification for more information) states and could include other attributes in the future. Persistent attributes are referred to as System Attributes in code and in the SDK documentation.

An application can use the Bonds and Persistent Data Manager module (referred to as the bond manager) included in the nRF51 SDK to handle most of the operations related to the Bonding Information and System Attributes. The bond manager notifies the application when it's connected to a new bonded central or to a previously bonded central. The application can use the Bond Manager API to store or load (or restore) the Bonding Information and System Attributes. The bond manager identifies all the centrals the application is bonded to and restores their respective Bonding Information and System Attributes to the S110 stack.

In addition, you can use the bond manager to set up your application to advertise:

- To a given bonded central using directed advertisement.
- To a list of bonded centrals - i.e. using whitelist.

The bond manager automatically writes the Bonding Information to the flash memory when the bonding procedure to a new central is finished. Upon disconnection, the application should use the Bond Manager API ble_bondmngr_bonded_centrals_store to write the latest Bonding Information and System Attributes to flash.

The bond manager provides the API ble_bondmngr_sys_attr_store to allow the application to write the System Attributes to flash while in a connection. Your application should call this API when it considers that all CCCDs and other persistent attributes are in a stable state. This API call will safely fail if System Attributes data for the current connected central is already present in the flash. The API does so because a flash write in such a situation would require an erase of flash, which takes a long time (21 milliseconds) to complete. This may disrupt the radio.

Applications using the Bond Manager must have a configuration file named ble_bondmngr_cfg.h (see below for details).

Refer to Message Sequence Charts to see the flow of events when connecting to a central using the Bond Manager

# Configuration File

Applications using the Bond Manager must have a configuration file named ble_bondmngr_cfg.h. Here is an example of this file:

#ifndef BLE_BONDMNGR_CFG_H__
#define BLE_BONDMNGR_CFG_H__
#define BLE_BONDMNGR_CCCD_COUNT 1
#define BLE_BONDMNGR_MAX_BONDED_CENTRALS 4
#endif // BLE_BONDMNGR_CFG_H__

BLE_BONDMNGR_CCCD_COUNT is the number of CCCDs used in the application, and BLE_BONDMNGR_MAX_BONDED_CENTRALS is the maximum number of bonded centrals to be supported by the application.