The following code examples show the typical usage of the Peer Manager in an application.
Initializing the Peer Manager typically consists of three steps:
The following code example shows how the Peer Manager is initialized in the Experimental: BLE Relay Example:
The function pm_sec_params_set configures how the Peer Manager behaves when securing the link, thus it configures bonding, pairing, and encryption. The configuration is given by security parameters (ble_gap_sec_params_t). These security parameters are also used in directly in the SoftDevice security API and contain the parameters that are sent over-the-air during the bonding procedure. See the Bluetooth Core Specification (sections 3.H.3.5.1 and 3.H.3.5.2) for more information.
pm_sec_params_set rejects invalid security parameters. See the mentioned Bluetooth specification sections or the verification function in the Peer Manager source code for the constraints on the parameters.
The following list shows the required security parameters for common use cases:
NULL
(or do not call pm_sec_params_set)How to handle Peer Manager events depends on the application. The Peer Manager provides different kinds of events; some must be handled, while others can be disregarded.
The following code example provides a starting point for handling Peer Manager events:
The Peer Manager stores and retrieves data autonomously and does not require you to manually store any data. However, if you want to manually change, add, or remove data, the Peer Manager provides API functions to manipulate all data that is associated with its bonded peers.
The data is stored in chunks. For example, all bonding data (keys and identities) is stored together. A chunk cannot be partially stored or updated, but each chunk can be stored or updated independently of the other chunks. The only restrictions are that there must always be valid bonding data for a peer in flash and that there is only one instance of each chunk for each bonded peer. Two of the chunks, the remote GATT database and the application data, are not used internally by the Peer Manager. They are solely meant to be used through the Peer Manager API.
The following code example shows how to store a remote GATT database (in array_of_services
). Note that array_of_services
must be available for the duration of the (asynchronous) store operation. The store operation is finished when the event PM_EVT_PEER_DATA_UPDATE_SUCCEEDED or PM_EVT_PEER_DATA_UPDATE_FAILED is received.
pm_peer_data_remote_db_store, as well as pm_peer_data_bonding_store and pm_peer_data_app_data_store, call pm_peer_data_store. pm_peer_data_store can also be used directly, as in the following example:
The Peer Manager can be used to set and retrieve a whitelist that can be provided to the Advertising Module module and be used during advertising. When a whitelist is needed, call the pm_whitelist_set function to whitelist peers based on their peer IDs.
The following example shows how to use pm_whitelist_set to whitelist a number of peers and pm_whitelist_get to retrieve such a list and provide it to Advertising Module for use during advertising: