Usage

nRF5 SDK v14.2.0

The following code examples show the typical usage of the Peer Manager in an application.

Initializing

Initializing the Peer Manager typically consists of three steps:

  1. Call pm_init once to initialize the module.
  2. Optionally, call pm_sec_params_set to set the security parameters. If you do not call this function, pairing and bonding is not supported. See Security parameters .
  3. Subscribe to the Peer Manager events by calling pm_register .

The following code example shows how the Peer Manager is initialized in the Experimental: BLE Relay Example :

static void peer_manager_init( bool erase_bonds)
{
ble_gap_sec_params_t sec_param;
ret_code_t err_code;
err_code = pm_init ();
APP_ERROR_CHECK (err_code);
if (erase_bonds)
{
pm_peers_delete ();
}
memset(&sec_param, 0, sizeof ( ble_gap_sec_params_t ));
// Security parameters to be used for all security procedures.
sec_param. bond = SEC_PARAM_BOND;
sec_param. mitm = SEC_PARAM_MITM;
sec_param. lesc = SEC_PARAM_LESC;
sec_param. keypress = SEC_PARAM_KEYPRESS;
sec_param. io_caps = SEC_PARAM_IO_CAPABILITIES;
sec_param. oob = SEC_PARAM_OOB;
sec_param. min_key_size = SEC_PARAM_MIN_KEY_SIZE;
sec_param. max_key_size = SEC_PARAM_MAX_KEY_SIZE;
sec_param. kdist_own . enc = 1;
sec_param. kdist_own . id = 1;
sec_param. kdist_peer . enc = 1;
sec_param. kdist_peer . id = 1;
err_code = pm_sec_params_set (&sec_param);
APP_ERROR_CHECK (err_code);
err_code = pm_register (pm_evt_handler);
APP_ERROR_CHECK (err_code);
}

Security parameters

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:

Event handling

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:

static void peer_manager_event_handler( pm_evt_t const * p_evt)
{
ret_code_t err_code;
switch (p_evt-> evt_id )
{
case PM_EVT_BONDED_PEER_CONNECTED :
// Update the rank of the peer.
err_code = pm_peer_rank_highest (p_evt-> peer_id );
break ;
case PM_EVT_CONN_SEC_START :
break ;
case PM_EVT_CONN_SEC_SUCCEEDED :
// Update the rank of the peer.
err_code = pm_peer_rank_highest (p_evt-> peer_id );
break ;
case PM_EVT_CONN_SEC_FAILED :
// In some cases, when securing fails, it can be restarted directly. Sometimes it can be
// restarted, but only after changing some Security Parameters. Sometimes, it cannot be
// restarted until the link is disconnected and reconnected. Sometimes it is impossible
// to secure the link, or the peer device does not support it. How to handle this error
// is highly application-dependent.
break ;
case PM_EVT_CONN_SEC_CONFIG_REQ :
{
// A connected peer (central) is trying to pair, but the Peer Manager already has a bond
// for that peer. Setting allow_repairing to false rejects the pairing request.
// If this event is ignored (pm_conn_sec_config_reply is not called in the event
// handler), the Peer Manager assumes allow_repairing to be false.
pm_conn_sec_config_t conn_sec_config = {.allow_repairing = false };
pm_conn_sec_config_reply (p_evt-> conn_handle , &conn_sec_config);
}
break ;
case PM_EVT_CONN_SEC_PARAMS_REQ :
{
// If you want to set different security parameters for particular peers, you can do
// so here. Pass the desired security parameters to pm_conn_sec_params_reply().
err_code = pm_conn_sec_params_reply (p_evt-> conn_handle ,
&sec_param,
p_evt->params. conn_sec_params_req . p_context );
APP_ERROR_CHECK (err_code);
} break ;
case PM_EVT_STORAGE_FULL :
// Run garbage collection on the flash.
err_code = fds_gc ();
if (err_code == FDS_ERR_BUSY || err_code == FDS_ERR_NO_SPACE_IN_QUEUES )
{
// Retry.
}
else
{
APP_ERROR_CHECK (err_code);
}
break ;
case PM_EVT_ERROR_UNEXPECTED :
// Assert.
APP_ERROR_CHECK (p_evt->params. error_unexpected . error );
break ;
case PM_EVT_PEER_DATA_UPDATE_SUCCEEDED :
break ;
case PM_EVT_PEER_DATA_UPDATE_FAILED :
// Assert.
APP_ERROR_CHECK_BOOL ( false );
break ;
case PM_EVT_PEER_DELETE_SUCCEEDED :
break ;
case PM_EVT_PEER_DELETE_FAILED :
// Assert.
APP_ERROR_CHECK (p_evt->params. peer_delete_failed . error );
break ;
case PM_EVT_PEERS_DELETE_SUCCEEDED :
// At this point it is safe to start advertising or scanning.
break ;
case PM_EVT_PEERS_DELETE_FAILED :
// Assert.
APP_ERROR_CHECK (p_evt->params. peers_delete_failed_evt . error );
break ;
case PM_EVT_LOCAL_DB_CACHE_APPLIED :
break ;
case PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED :
// The local database has likely changed, send service changed indications.
pm_local_database_has_changed ();
break ;
case PM_EVT_SERVICE_CHANGED_IND_SENT :
break ;
case PM_EVT_SERVICE_CHANGED_IND_CONFIRMED :
break ;
}
}

Storing data

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.

ret_code_t err_code;
pm_store_token_t store_token;
err_code = pm_peer_data_remote_db_store (peer_id, array_of_services, number_of_services, &store_token);
if (err_code != NRF_ERROR_BUSY)
{
APP_ERROR_CHECK (err_code);
}

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:

ret_code_t err_code;
pm_store_token_t store_token;
err_code = pm_peer_data_store (peer_id, PM_PEER_DATA_ID_GATT_REMOTE , array_of_services, number_of_services, &store_token);
if (err_code != NRF_ERROR_BUSY)
{
APP_ERROR_CHECK (err_code);
}

Using a whitelist

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:

{
// Fetch a list of peer IDs from Peer Manager and whitelist them.
pm_peer_id_t peer_ids[8] = { PM_PEER_ID_INVALID };
uint32_t n_peer_ids = 0;
pm_peer_id_t peer_id = pm_next_peer_id_get ( PM_PEER_ID_INVALID );
while ((peer_id != PM_PEER_ID_INVALID ) && (n_peer_ids < 8))
{
peer_ids[n_peer_ids++] = peer_id;
peer_id = pm_next_peer_id_get (peer_id);
}
// Whitelist peers.
err_code = pm_whitelist_set (peer_ids, n_peer_ids);
APP_ERROR_CHECK (err_code);
}
static void on_adv_evt( ble_adv_evt_t ble_adv_evt)
{
switch (ble_adv_evt)
{
...
case BLE_ADV_EVT_WHITELIST_REQUEST :
{
// When the Advertising module is about to advertise, an event
// will be received by the application. In this event, the application
// retrieves a whitelist from the Peer Manager, based on the peers
// previously whitelisted using pm_whitelist_set().
ret_code_t err_code;
// Storage for the whitelist.
ble_gap_irk_t irks[8] = {0};
ble_gap_addr_t addrs[8] = {0};
uint32_t irk_cnt = 8;
uint32_t addr_cnt = 8;
err_code = pm_whitelist_get (addrs, &addr_cnt, irks, &irk_cnt);
APP_ERROR_CHECK (err_code);
// Apply the whitelist.
err_code = ble_advertising_whitelist_reply (addrs, addr_cnt, irks, irk_cnt);
APP_ERROR_CHECK (err_code);
}
...
}
}