Usage

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_peer_delete_all();
 }

 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.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_periph.enc = 1;
 sec_param.kdist_periph.id = 1;
 sec_param.kdist_central.enc = 1;
 sec_param.kdist_central.id = 1;

 err_code = pm_sec_params_set(&sec_param);
 APP_ERROR_CHECK(err_code);

 err_code = pm_register(&peer_manager_event_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 the BLE Device Manager and 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:

• No pairing/bonding: NULL (or do not call pm_sec_params_set)
• Pairing, no bonding:

  sec_param.bond = false;
  sec_param.mitm = false;
  sec_param.io_caps = BLE_GAP_IO_CAPS_NONE;
  sec_param.oob = false;
  sec_param.min_key_size = 7;
  sec_param.max_key_size = 16;
  sec_param.kdist_periph.enc = 0;
  sec_param.kdist_periph.id = 0;
  sec_param.kdist_central.enc = 0;
  sec_param.kdist_central.id = 0;

• Just Works bonding:

  sec_param.bond = true;
  sec_param.mitm = false;
  sec_param.io_caps = BLE_GAP_IO_CAPS_NONE;
  sec_param.oob = false;
  sec_param.min_key_size = 7;
  sec_param.max_key_size = 16;
  sec_param.kdist_periph.enc = 1;
  sec_param.kdist_periph.id = 1;
  sec_param.kdist_central.enc = 1;
  sec_param.kdist_central.id = 1;

• Passkey bonding with keyboard capabilities:

  sec_param.bond = true;
  sec_param.mitm = true;
  sec_param.io_caps = BLE_GAP_IO_CAPS_KEYBOARD_ONLY;
  sec_param.oob = false;

  The rest of the parameters are the same as for Just Works bonding.
• OOB bonding:

  sec_param.bond = true;
  sec_param.mitm = true;
  sec_param.io_caps = BLE_GAP_IO_CAPS_NONE;
  sec_param.oob = true;

  The rest of the parameters are the same as for Just Works bonding.
• Disallow IRKs:

  sec_param.bond = true;
  /* Arbitrary parameters removed. */
  sec_param.kdist_periph.enc = 1;
  sec_param.kdist_periph.id = 0;
  sec_param.kdist_central.enc = 1;
  sec_param.kdist_central.id = 0;

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 from the Experimental: BLE Relay Example shows some best practices 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:
 break;

 case PM_EVT_LINK_SECURED:
 break;

 case PM_EVT_LINK_SECURE_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.
 if (p_evt->params.link_secure_failed_evt.error.error_type == PM_ERROR_TYPE_PM_SEC_ERROR)
 {
 switch (p_evt->params.link_secure_failed_evt.error.error.pm_sec_error)
 {
 case PM_SEC_ERROR_CODE_PIN_OR_KEY_MISSING:
 // Rebond if one party has lost its keys.
 pm_link_secure(p_evt->conn_handle, true);
 break;

 default:
 break;
 }
 }
 else
 {
 switch (p_evt->params.link_secure_failed_evt.error.error.sec_status)
 {
 default:
 break;
 }
 }
 break;

 case PM_EVT_STORAGE_FULL:
 // Run garbage collection on the flash.
 err_code = fds_gc();
 APP_ERROR_CHECK(err_code);
 break;

 case PM_EVT_ERROR_UNEXPECTED:
 // A likely fatal error occurred. Assert.
 APP_ERROR_CHECK(p_evt->params.error_unexpected_evt.error);
 break;

 case PM_EVT_PEER_DATA_UPDATED:
 break;

 case PM_EVT_PEER_DATA_UPDATE_FAILED:
 APP_ERROR_CHECK_BOOL(false);
 break;

 case PM_EVT_ERROR_LOCAL_DB_CACHE_APPLY:
 // The local database has likely changed, send service changed indications.
 pm_local_database_has_changed();
 break;

 case PM_EVT_LOCAL_DB_CACHE_APPLIED:
 break;

 case PM_EVT_SERVICE_CHANGED_INDICATION_SENT:
 break;
 }
}

Storing and retrieving 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 the remote_gatt_db variable, in addition to 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_UPDATED or PM_EVT_PEER_DATA_UPDATE_FAILED is received.

ret_code_t err_code;
pm_peer_data_const_t peer_data;
static pm_peer_data_remote_gatt_db_t remote_gatt_db;
pm_store_token_t store_token;

peer_data.data_type = PM_PEER_DATA_ID_GATT_REMOTE;
peer_data.data.p_remote_gatt_db = &remote_gatt_db;
remote_gatt_db.p_data = array_of_services;
remote_gatt_db.service_count = number_of_services;
peer_data.length_words = PM_REMOTE_DB_N_WORDS(number_of_services);

err_code = pm_peer_data_store(peer_id, &peer_data, &store_token);
if (err_code != NRF_ERROR_BUSY)
{
 APP_ERROR_CHECK(err_code);
}

Making a whitelist

The Peer Manager must be aware of any whitelist that is being used. Therefore, when a whitelist is needed, use the pm_wlist_create function in Peer Manager to construct a whitelist out of the stored peer bonding data. The following example shows how to use pm_wlist_create to construct a whitelist based on the first (up to 8) bonded peers, and how to apply it when using Advertising Module:

static void on_adv_evt(ble_adv_evt_t ble_adv_evt)
{
 switch (ble_adv_evt)
 {
 ...
 case BLE_ADV_EVT_WHITELIST_REQUEST:
 {
 ret_code_t err_code;

 // Storage for the whitelist.
 ble_gap_irk_t * irks[8];
 ble_gap_addr_t * addrs[8];
 ble_gap_whitelist_t whitelist = {.pp_irks = irks, .pp_addrs = addrs};

 // Construct a list of peer IDs.
 pm_peer_id_t peer_ids[8];
 pm_peer_id_t peer_id = pm_next_peer_id_get(PM_PEER_ID_INVALID);
 uint32_t n_peer_ids = 0;

 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);
 }

 // Create the whitelist.
 err_code = pm_wlist_create(peer_ids, n_peer_ids, &whitelist);
 APP_ERROR_CHECK(err_code);

 // Apply the whitelist.
 err_code = ble_advertising_whitelist_reply(&whitelist);
 APP_ERROR_CHECK(err_code);
 }
 ...
 }
}