| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Peer Manager
BLE libraries

Module for managing BLE bonding, which includes controlling encryption and pairing procedures as well as persistently storing different pieces of data that must be stored when bonded. More...

## Modules
| Peer Manager configuration
| Peer Manager defined security errors
| All versions of Peer IDs.
| The data ID for each iteration of the data formats in flash.
| Privacy modes

## Data Structures
struct | pm_conn_sec_status_t
| Security status of a connection. More...
struct | pm_conn_secured_evt_t
| Parameters specific to the PM_EVT_CONN_SEC_SUCCEEDED event. More...
struct | pm_conn_secure_failed_evt_t
| Parameters specific to the PM_EVT_CONN_SEC_FAILED event. More...
struct | pm_peer_data_update_succeeded_evt_t
| Parameters specific to the PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event. More...
struct | pm_peer_data_update_failed_t
| Parameters specific to the PM_EVT_PEER_DATA_UPDATE_FAILED event. More...
struct | pm_failure_evt_t
| Standard parameters for failure events. More...
struct | pm_evt_t
| An event from the Peer Manager module. More...
struct | pm_conn_sec_config_t
| Configuration of a security procedure. More...
struct | pm_peer_data_bonding_t
| Data associated with a bond to a peer. More...
struct | pm_peer_data_local_gatt_db_t
| Data on a local GATT database. More...
struct | pm_privacy_params_t
| Device Privacy. More...

## Macros
#define | PM_PEER_ID_INVALID 0xFFFF
| Invalid value for pm_peer_id_t.
#define | PM_STORE_TOKEN_INVALID 0
| Invalid value for store token.
#define | PM_PEER_ID_N_AVAILABLE_IDS 256
| The number of available peer IDs.
#define | PM_LOCAL_DB_LEN_OVERHEAD_BYTES offsetof(pm_peer_data_local_gatt_db_t, data)
| The static-length part of the local GATT data struct.
#define | PM_CONN_SEC_ERROR_BASE 0x1000
| The base for Peer Manager defined errors. See Peer Manager defined security errors and pm_sec_error_code_t.

## Typedefs
typedef void(* | pm_evt_handler_t )(pm_evt_t const *p_event)
| Event handler for events from the Peer Manager module. More...
typedef uint16_t | pm_peer_id_t
| Handle to uniquely identify a peer for which we have persistently stored data.
typedef uint32_t | pm_prepare_token_t
| Type that is used for write prepares (used to reserve space in flash).
typedef uint32_t | pm_store_token_t
| Type that is used to hold a reference to a stored item in flash.
typedef uint16_t | pm_sec_error_code_t
| Errors from security procedures in Peer Manager. More...

## Enumerations
enum | pm_evt_id_t { PM_EVT_BONDED_PEER_CONNECTED, PM_EVT_CONN_SEC_START, PM_EVT_CONN_SEC_SUCCEEDED, PM_EVT_CONN_SEC_FAILED, PM_EVT_CONN_SEC_CONFIG_REQ, PM_EVT_STORAGE_FULL, PM_EVT_ERROR_UNEXPECTED, PM_EVT_PEER_DATA_UPDATE_SUCCEEDED, PM_EVT_PEER_DATA_UPDATE_FAILED, PM_EVT_PEER_DELETE_SUCCEEDED, PM_EVT_PEER_DELETE_FAILED, PM_EVT_PEERS_DELETE_SUCCEEDED, PM_EVT_PEERS_DELETE_FAILED, PM_EVT_LOCAL_DB_CACHE_APPLIED, PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED, PM_EVT_SERVICE_CHANGED_IND_SENT, PM_EVT_SERVICE_CHANGED_IND_CONFIRMED }
| Types of events that can come from the Peer Manager module. More...
enum | pm_peer_data_op_t { PM_PEER_DATA_OP_UPDATE, PM_PEER_DATA_OP_DELETE }
| Actions that can be performed to peer data in persistent storage. More...
enum | pm_peer_data_id_t { PM_PEER_DATA_ID_FIRST = 0, PM_PEER_DATA_ID_BONDING = 7, PM_PEER_DATA_ID_SERVICE_CHANGED_PENDING = 1, PM_PEER_DATA_ID_GATT_LOCAL = 8, PM_PEER_DATA_ID_GATT_REMOTE = 5, PM_PEER_DATA_ID_PEER_RANK = 6, PM_PEER_DATA_ID_APPLICATION = 4, PM_PEER_DATA_ID_LAST = 9, PM_PEER_DATA_ID_INVALID = 0xFF }
| The different types of data associated with a peer. More...
enum | pm_conn_sec_procedure_t { PM_LINK_SECURED_PROCEDURE_ENCRYPTION, PM_LINK_SECURED_PROCEDURE_BONDING, PM_LINK_SECURED_PROCEDURE_PAIRING }
| Different procedures that can lead to an encrypted link. More...

## Functions
ret_code_t | pm_init (void)
| Function for initializing the Peer Manager. More...
ret_code_t | pm_register (pm_evt_handler_t event_handler)
| Function for registering an event handler with the Peer Manager. More...
ret_code_t | pm_sec_params_set (ble_gap_sec_params_t *p_sec_params)
| Function for providing pairing and bonding parameters to use for pairing procedures. More...
void | pm_on_ble_evt (ble_evt_t *p_ble_evt)
| Function for passing BLE events to the Peer Manager. More...
ret_code_t | pm_conn_secure (uint16_t conn_handle, bool force_repairing)
| Function for establishing encryption on a connection, and optionally establishing a bond. More...
void | pm_conn_sec_config_reply (uint16_t conn_handle, pm_conn_sec_config_t *p_conn_sec_config)
| Function for providing security configuration for a link. More...
void | pm_local_database_has_changed (void)
| Function for manually informing that the local database has changed. More...
ret_code_t | pm_conn_sec_status_get (uint16_t conn_handle, pm_conn_sec_status_t *p_conn_sec_status)
| Function for getting the security status of a connection. More...
ret_code_t | pm_lesc_public_key_set (ble_gap_lesc_p256_pk_t *p_public_key)
| Experimental function for specifying the public key to use for LESC operations. More...
ret_code_t | pm_whitelist_set (pm_peer_id_t const *p_peers, uint32_t peer_cnt)
| Function for setting or clearing the whitelist. More...
ret_code_t | pm_whitelist_get (ble_gap_addr_t *p_addrs, uint32_t *p_addr_cnt, ble_gap_irk_t *p_irks, uint32_t *p_irk_cnt)
| Function for retrieving the previously set whitelist. More...
ret_code_t | pm_device_identities_list_set (pm_peer_id_t const *p_peers, uint32_t peer_cnt)
| Function for setting and clearing the device identities list. More...
ret_code_t | pm_id_addr_set (ble_gap_addr_t const *p_addr)
| Function for setting the local Bluetooth identity address. More...
ret_code_t | pm_id_addr_get (ble_gap_addr_t *p_addr)
| Function for retrieving the local Bluetooth identity address. More...
ret_code_t | pm_privacy_set (pm_privacy_params_t const *p_privacy_params)
| Function for configuring privacy settings. More...
ret_code_t | pm_privacy_get (pm_privacy_params_t *p_privacy_params)
| Function for retrieving privacy settings. More...
ret_code_t | pm_conn_handle_get (pm_peer_id_t peer_id, uint16_t *p_conn_handle)
| Function for getting the connection handle of the connection with a bonded peer. More...
ret_code_t | pm_peer_id_get (uint16_t conn_handle, pm_peer_id_t *p_peer_id)
| Function for retrieving the ID of a peer, given its connection handle. More...
pm_peer_id_t | pm_next_peer_id_get (pm_peer_id_t prev_peer_id)
| Function for getting the next peer ID in the sequence of all used peer IDs. More...
uint32_t | pm_peer_count (void)
| Function for querying the number of valid peer IDs that are available. More...

## Functions (Peer Data)
Functions for manipulating peer data.
ret_code_t | pm_peer_data_load (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void *p_data, uint16_t *p_len)
| Function for retrieving stored data of a peer. More...
ret_code_t | pm_peer_data_bonding_load (pm_peer_id_t peer_id, pm_peer_data_bonding_t *p_data)
| Function for reading a peer's bonding data (PM_PEER_DATA_ID_BONDING). More...
ret_code_t | pm_peer_data_remote_db_load (pm_peer_id_t peer_id, ble_gatt_db_srv_t *p_data, uint16_t *p_len)
| Function for reading a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE). More...
ret_code_t | pm_peer_data_app_data_load (pm_peer_id_t peer_id, uint8_t *p_data, uint16_t *p_len)
| Function for reading a peer's application data. (PM_PEER_DATA_ID_APPLICATION). More...
ret_code_t | pm_peer_data_store (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void const *p_data, uint16_t len, pm_store_token_t *p_token)
| Function for setting or updating stored data of a peer. More...
ret_code_t | pm_peer_data_bonding_store (pm_peer_id_t peer_id, pm_peer_data_bonding_t const *p_data, pm_store_token_t *p_token)
| Function for setting or updating a peer's bonding data (PM_PEER_DATA_ID_BONDING). More...
ret_code_t | pm_peer_data_remote_db_store (pm_peer_id_t peer_id, ble_gatt_db_srv_t const *p_data, uint16_t len, pm_store_token_t *p_token)
| Function for setting or updating a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE). More...
ret_code_t | pm_peer_data_app_data_store (pm_peer_id_t peer_id, uint8_t const *p_data, uint16_t len, pm_store_token_t *p_token)
| Function for setting or updating a peer's application data. (PM_PEER_DATA_ID_APPLICATION). More...
ret_code_t | pm_peer_data_delete (pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
| Function for deleting a peer's stored pieces of data. More...
ret_code_t | pm_peer_new (pm_peer_id_t *p_new_peer_id, pm_peer_data_bonding_t *p_bonding_data, pm_store_token_t *p_token)
| Function for manually adding a peer to the persistent storage. More...
ret_code_t | pm_peer_delete (pm_peer_id_t peer_id)
| Function for freeing persistent storage for a peer. More...
ret_code_t | pm_peers_delete (void)
| Function for deleting all data stored for all peers. More...
ret_code_t | pm_peer_ranks_get (pm_peer_id_t *p_highest_ranked_peer, uint32_t *p_highest_rank, pm_peer_id_t *p_lowest_ranked_peer, uint32_t *p_lowest_rank)
| Function for finding the highest and lowest ranked peers. More...
ret_code_t | pm_peer_rank_highest (pm_peer_id_t peer_id)
| Function for updating the rank of a peer to be highest among all stored peers. More...

## Detailed Description

Module for managing BLE bonding, which includes controlling encryption and pairing procedures as well as persistently storing different pieces of data that must be stored when bonded.

The API consists of functions for configuring the pairing and encryption behavior of the device and functions for manipulating the stored data.

## Typedef Documentation

typedef void(* pm_evt_handler_t)(pm_evt_t const *p_event)

Event handler for events from the Peer Manager module.

See Also
  pm_register

Parameters

  [in] | p_event | The event that has occurred.

typedef uint16_t pm_sec_error_code_t

Errors from security procedures in Peer Manager.

Possible values are defined in Peer Manager defined security errors and GAP Security status.

## Enumeration Type Documentation

enum pm_conn_sec_procedure_t

Different procedures that can lead to an encrypted link.

Enumerator
PM_LINK_SECURED_PROCEDURE_ENCRYPTION | Using an LTK that was shared during a previous bonding procedure to encrypt the link.
PM_LINK_SECURED_PROCEDURE_BONDING | A pairing procedure, followed by a bonding procedure.
PM_LINK_SECURED_PROCEDURE_PAIRING | A pairing procedure with no bonding.

enum pm_evt_id_t

Types of events that can come from the Peer Manager module.

Enumerator
PM_EVT_BONDED_PEER_CONNECTED | A connected peer has been identified as one with which we have a bond. When performing bonding with a peer for the first time, this event will not be sent until a new connection is established with the peer. When we are central, this event is always sent when the Peer Manager receives the BLE_GAP_EVT_CONNECTED event. When we are peripheral, this event might in rare cases arrive later.
PM_EVT_CONN_SEC_START | A security procedure has started on a link, initiated either locally or remotely. The security procedure is using the last parameters provided via pm_sec_params_set. This event is always followed by either a PM_EVT_CONN_SEC_SUCCEEDED or a PM_EVT_CONN_SEC_FAILED event. This is an informational event; no action is needed for the procedure to proceed.
PM_EVT_CONN_SEC_SUCCEEDED | A link has been encrypted, either as a result of a call to pm_conn_secure or a result of an action by the peer. The event structure contains more information about the circumstances. This event might contain a peer ID with the value PM_PEER_ID_INVALID, which means that the peer (central) used an address that could not be identified, but it used an encryption key (LTK) that is present in the database.
PM_EVT_CONN_SEC_FAILED | A pairing or encryption procedure has failed. In some cases, this means that security is not possible on this link (temporarily or permanently). How to handle this error depends on the application.
PM_EVT_CONN_SEC_CONFIG_REQ | The peer (central) has requested pairing, but a bond already exists with that peer. Reply by calling pm_conn_sec_config_reply before the event handler returns. If no reply is sent, a default is used.
PM_EVT_STORAGE_FULL | There is no more room for peer data in flash storage. To solve this problem, delete data that is not needed anymore and run a garbage collection procedure in FDS.
PM_EVT_ERROR_UNEXPECTED | An unrecoverable error happened inside Peer Manager. An operation failed with the provided error.
PM_EVT_PEER_DATA_UPDATE_SUCCEEDED | A piece of peer data was stored, updated, or cleared in flash storage. This event is sent for all successful changes to peer data, also those initiated internally in Peer Manager. To identify an operation, compare the store token in the event with the store token received during the initiating function call. Events from internally initiated changes might have invalid store tokens.
PM_EVT_PEER_DATA_UPDATE_FAILED | A piece of peer data could not be stored, updated, or cleared in flash storage. This event is sent instead of PM_EVT_PEER_DATA_UPDATE_SUCCEEDED for the failed operation.
PM_EVT_PEER_DELETE_SUCCEEDED | A peer was cleared from flash storage, for example because a call to pm_peer_delete succeeded. This event can also be sent as part of a call to pm_peers_delete or internal cleanup.
PM_EVT_PEER_DELETE_FAILED | A peer could not be cleared from flash storage. This event is sent instead of PM_EVT_PEER_DELETE_SUCCEEDED for the failed operation.
PM_EVT_PEERS_DELETE_SUCCEEDED | A call to pm_peers_delete has completed successfully. Flash storage now contains no peer data.
PM_EVT_PEERS_DELETE_FAILED | A call to pm_peers_delete has failed, which means that at least one of the peers could not be deleted. Other peers might have been deleted, or might still be queued to be deleted. No more PM_EVT_PEERS_DELETE_SUCCEEDED or PM_EVT_PEERS_DELETE_FAILED events are sent until the next time pm_peers_delete is called.
PM_EVT_LOCAL_DB_CACHE_APPLIED | Local database values for a peer (taken from flash storage) have been provided to the SoftDevice.
PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED | Local database values for a peer (taken from flash storage) were rejected by the SoftDevice, which means that either the database has changed or the user has manually set the local database to an invalid value (using pm_peer_data_store).
PM_EVT_SERVICE_CHANGED_IND_SENT | A service changed indication has been sent to a peer, as a result of a call to pm_local_database_has_changed. This event will be followed by a PM_EVT_SERVICE_CHANGED_IND_CONFIRMED event if the peer acknowledges the indication.
PM_EVT_SERVICE_CHANGED_IND_CONFIRMED | A service changed indication that was sent has been confirmed by a peer. The peer can now be considered aware that the local database has changed.

enum pm_peer_data_id_t

The different types of data associated with a peer.

Enumerator
PM_PEER_DATA_ID_FIRST | The smallest data ID.
PM_PEER_DATA_ID_BONDING | The data ID of the second version of bonding data. The data ID for bonding data. See pm_peer_data_bonding_t.
PM_PEER_DATA_ID_SERVICE_CHANGED_PENDING | The data ID of the first version of the service changed pending flag. The data ID for service changed state.
PM_PEER_DATA_ID_GATT_LOCAL | The data ID of the second version of local GATT data. The data ID for local GATT data (sys attributes). See pm_peer_data_local_gatt_db_t.
PM_PEER_DATA_ID_GATT_REMOTE | The data ID of the second version of remote GATT data. The data ID for remote GATT data.
PM_PEER_DATA_ID_PEER_RANK | The data ID of the first version of the rank. The data ID for peer rank. See pm_peer_rank_highest.
PM_PEER_DATA_ID_APPLICATION | The data ID of the first version of application data. The data ID for application data.
PM_PEER_DATA_ID_LAST | The data ID after the last valid one. One more than the highest data ID.
PM_PEER_DATA_ID_INVALID | A data ID guaranteed to be invalid.

enum pm_peer_data_op_t

Actions that can be performed to peer data in persistent storage.

Enumerator
PM_PEER_DATA_OP_UPDATE | Writing or overwriting the data.
PM_PEER_DATA_OP_DELETE | Removing the data.

## Function Documentation

ret_code_t pm_conn_handle_get | ( | pm_peer_id_t | peer_id,
|  | uint16_t * | p_conn_handle
| ) |  |

Function for getting the connection handle of the connection with a bonded peer.

Parameters

  [in] | peer_id | The peer ID of the bonded peer.
  [out] | p_conn_handle | Connection handle, or BLE_ERROR_INVALID_CONN_HANDLE if the peer is not connected.

Return values

  NRF_SUCCESS | If the connection handle was retrieved successfully.
  NRF_ERROR_NULL | If `p_conn_handle` was NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

void pm_conn_sec_config_reply | ( | uint16_t | conn_handle,
|  | pm_conn_sec_config_t * | p_conn_sec_config
| ) |  |

Function for providing security configuration for a link.

This function is optional, and must be called in reply to a PM_EVT_CONN_SEC_CONFIG_REQ event, before the Peer Manager event handler returns. If it is not called in time, a default configuration is used. See pm_conn_sec_config_t for the value of the default.

Parameters

  [in] | conn_handle | The connection to set the configuration for.
  [in] | p_conn_sec_config | The configuration.

ret_code_t pm_conn_sec_status_get | ( | uint16_t | conn_handle,
|  | pm_conn_sec_status_t * | p_conn_sec_status
| ) |  |

Function for getting the security status of a connection.

Parameters

  [in] | conn_handle | Connection handle of the link as provided by the SoftDevice.
  [out] | p_conn_sec_status | Security status of the link.

Return values

  NRF_SUCCESS | If pairing was initiated successfully.
  BLE_ERROR_INVALID_CONN_HANDLE | If the connection handle is invalid.
  NRF_ERROR_NULL | If `p_conn_sec_status` was NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_conn_secure | ( | uint16_t | conn_handle,
|  | bool | force_repairing
| ) |  |

Function for establishing encryption on a connection, and optionally establishing a bond.

This function attempts to secure the link that is specified by `conn_handle`. It uses the parameters that were previously provided in a call to pm_sec_params_set.

If the connection is a master connection, calling this function starts a security procedure on the link. If we have keys from a previous bonding procedure with this peer and the keys meet the security requirements in the currently active sec_params, the function attempts to establish encryption with the existing keys. If no key exists, the function attempts to pair and bond according to the currently active sec_params.

If the function completes successfully, a PM_EVT_CONN_SEC_START event is sent. The procedure might be queued, in which case the PM_EVT_CONN_SEC_START event is delayed until the procedure is initiated in the SoftDevice.

If the connection is a slave connection, the function sends a security request to the peer (master). It is up to the peer then to initiate pairing or encryption. If the peer ignores the request, a BLE_GAP_EVT_TIMEOUT event occurs with the source BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST. Otherwise, the peer initiates security, in which case things happen as if the peer had initiated security itself. See PM_EVT_CONN_SEC_START for information about peer-initiated security.

Parameters

  [in] | conn_handle | Connection handle of the link as provided by the SoftDevice.
  [in] | force_repairing | Whether to force a pairing procedure even if there is an existing encryption key. This argument is relevant only for the central role. Recommended value: false.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_ERROR_TIMEOUT | If there was an SMP time-out, so that no more SMP operations can be performed on this link.
  BLE_ERROR_INVALID_CONN_HANDLE | If the connection handle is invalid.
  NRF_ERROR_NOT_FOUND | If the security parameters have not been set.
  NRF_ERROR_NO_MEM | If there is no more space in flash.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized, or the peer is disconnected or in the process of disconnecting.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_device_identities_list_set | ( | pm_peer_id_t const * | p_peers,
|  | uint32_t | peer_cnt
| ) |  |

Function for setting and clearing the device identities list.

Parameters

  [in] | p_peers | The peers to add to the device identities list. Pass NULL to clear the device identities list.
  [in] | peer_cnt | The number of peers. Pass zero to clear the device identities list.

Return values

  NRF_SUCCESS | If the device identities list was successfully set or cleared.
  NRF_ERROR_NOT_FOUND | If a peer is invalid or its data could not be found in flash.
  BLE_ERROR_GAP_INVALID_BLE_ADDR | If a peer has an address that cannot be used for whitelisting.
  BLE_ERROR_GAP_DEVICE_IDENTITIES_IN_USE | If the device identities list is in use and cannot be set.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_NOT_SUPPORTED | If using a SoftDevice that does not support device identities, e.g. S130 v2.0.

ret_code_t pm_id_addr_get | ( | ble_gap_addr_t * | p_addr | ) |

Function for retrieving the local Bluetooth identity address.

This function always returns the identity address, irrespective of the privacy settings. This means that the address type will always be either BLE_GAP_ADDR_TYPE_PUBLIC or BLE_GAP_ADDR_TYPE_RANDOM_STATIC.

Parameters

  [out] | p_addr | Pointer to the address structure to be filled in.

Return values

  NRF_SUCCESS | If the address was retrieved successfully.
  NRF_ERROR_NULL | If `p_addr` is NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_id_addr_set | ( | ble_gap_addr_t const * | p_addr | ) |

Function for setting the local Bluetooth identity address.

The local Bluetooth identity address is the address that identifies the device to other peers. The address type must be either BLE_GAP_ADDR_TYPE_PUBLIC or BLE_GAP_ADDR_TYPE_RANDOM_STATIC. The identity address cannot be changed while roles are running.

The SoftDevice sets a default address of type BLE_GAP_ADDR_TYPE_RANDOM_STATIC when it is enabled. This default address is a random number that is populated during the IC manufacturing process. It remains unchanged for the lifetime of each IC, but the application can assign a different identity address.

The identity address is distributed to the peer during bonding. If the address changes, the address stored in the peer device will not be valid and the ability to reconnect using the old address will be lost.

Note
  The SoftDevice functions sd_ble_gap_address_set (S13x v2.x), sd_ble_gap_addr_set (S13x v3.x), and sd_ble_gap_privacy_set (S13x v3.x) must not be called when using the Peer Manager. Use this function instead.

Parameters

  [in] | p_addr | The GAP address to be set.

Return values

  NRF_SUCCESS | If the identity address was set successfully.
  NRF_ERROR_NULL | If `p_addr` is NULL.
  NRF_ERROR_INVALID_ADDR | If the `p_addr` pointer is invalid.
  BLE_ERROR_GAP_INVALID_BLE_ADDR | If the BLE address is invalid.
  NRF_ERROR_BUSY | If the SoftDevice was busy. Process SoftDevice events and retry.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized or if this function was called while advertising, scanning, or while connected.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_init | ( | void |  | ) |

Function for initializing the Peer Manager.

You must initialize the Peer Manager before you can call any other Peer Manager functions.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_lesc_public_key_set | ( | ble_gap_lesc_p256_pk_t * | p_public_key | ) |

Experimental function for specifying the public key to use for LESC operations.

This function can be called multiple times. The specified public key will be used for all subsequent LESC (LE Secure Connections) operations until the next time this function is called.

Note
  The key must continue to reside in application memory as it is not copied by Peer Manager.

Parameters

  [in] | p_public_key | The public key to use for all subsequent LESC operations.

Return values

  NRF_SUCCESS | If pairing was initiated successfully.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

void pm_local_database_has_changed | ( | void |  | ) |

Function for manually informing that the local database has changed.

This function sends a service changed indication to all bonded and/or connected peers that subscribe to this indication. If a bonded peer is not connected, the indication is sent when it reconnects. Every time an indication is sent, a PM_EVT_SERVICE_CHANGED_IND_SENT event occurs, followed by a PM_EVT_SERVICE_CHANGED_IND_CONFIRMED when the peer sends its confirmation. Peers that are not subscribed to the service changed indication when this function is called do not receive an indication, and no events are sent to the user. Likewise, if the service changed characteristic is not present in the local database, this no indications are sent peers, and no events are sent to the user.

pm_peer_id_t pm_next_peer_id_get | ( | pm_peer_id_t | prev_peer_id | ) |

Function for getting the next peer ID in the sequence of all used peer IDs.

This function can be used to loop through all used peer IDs. The order in which peer IDs are returned should be considered unpredictable. PM_PEER_ID_INVALID is considered to be before the first and after the last used peer ID.

To loop through all peer IDs exactly once, use the following constuct:

pm_peer_id_t current_peer_id = pm_next_peer_id_get(PM_PEER_ID_INVALID);
while (current_peer_id != PM_PEER_ID_INVALID)
{
// Do something with current_peer_id.
current_peer_id = pm_next_peer_id_get(current_peer_id)
}

Parameters

  [in] | prev_peer_id | The previous peer ID.

Returns
  The next peer ID. If `prev_peer_id` was PM_PEER_ID_INVALID, the next peer ID is the first used peer ID. If `prev_peer_id` was the last used peer ID, the function returns PM_PEER_ID_INVALID.

void pm_on_ble_evt | ( | ble_evt_t * | p_ble_evt | ) |

Function for passing BLE events to the Peer Manager.

For the module to work as expected, this function must be called with each BLE event from the SoftDevice. It must be called after ble_conn_state_on_ble_evt, but before the application processes the event.

Calling this function before pm_init is safe, but without effect.

Parameters

  [in] | p_ble_evt | BLE stack event that is dispatched to the function.

uint32_t pm_peer_count | ( | void |  | ) |

Function for querying the number of valid peer IDs that are available.

This function returns the number of peers for which there is data in persistent storage.

Returns
  The number of valid peer IDs.

ret_code_t pm_peer_data_app_data_load | ( | pm_peer_id_t | peer_id,
|  | uint8_t * | p_data,
|  | uint16_t * | p_len
| ) |  |

Function for reading a peer's application data. (PM_PEER_DATA_ID_APPLICATION).

See pm_peer_data_load for parameters and return values.

ret_code_t pm_peer_data_app_data_store | ( | pm_peer_id_t | peer_id,
|  | uint8_t const * | p_data,
|  | uint16_t | len,
|  | pm_store_token_t * | p_token
| ) |  |

Function for setting or updating a peer's application data. (PM_PEER_DATA_ID_APPLICATION).

See pm_peer_data_store for parameters and return values.

ret_code_t pm_peer_data_bonding_load | ( | pm_peer_id_t | peer_id,
|  | pm_peer_data_bonding_t * | p_data
| ) |  |

Function for reading a peer's bonding data (PM_PEER_DATA_ID_BONDING).

See pm_peer_data_load for parameters and return values.

ret_code_t pm_peer_data_bonding_store | ( | pm_peer_id_t | peer_id,
|  | pm_peer_data_bonding_t const * | p_data,
|  | pm_store_token_t * | p_token
| ) |  |

Function for setting or updating a peer's bonding data (PM_PEER_DATA_ID_BONDING).

See pm_peer_data_store for parameters and return values.

ret_code_t pm_peer_data_delete | ( | pm_peer_id_t | peer_id,
|  | pm_peer_data_id_t | data_id
| ) |  |

Function for deleting a peer's stored pieces of data.

This function deletes specific data that is stored for a peer. Note that bonding data cannot be cleared separately.

To delete all data for a peer (including bonding data), use pm_peer_delete.

Note
  Clearing data in persistent storage happens asynchronously.

Parameters

  [in] | peer_id | Peer ID to clear data for.
  [in] | data_id | Which data to clear.

Return values

  NRF_SUCCESS | If the clear procedure was initiated successfully.
  NRF_ERROR_INVALID_PARAM | If `data_id` was PM_PEER_DATA_ID_BONDING or invalid, or `peer_id` was invalid.
  NRF_ERROR_NOT_FOUND | If there was no data to clear for this peer ID/data ID combination.
  NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_peer_data_load | ( | pm_peer_id_t | peer_id,
|  | pm_peer_data_id_t | data_id,
|  | void * | p_data,
|  | uint16_t * | p_len
| ) |  |

Function for retrieving stored data of a peer.

Note
  The length of the provided buffer must be a multiple of 4.

Parameters

  [in] | peer_id | Peer ID to get data for.
  [in] | data_id | Which type of data to read.
  [out] | p_data | Where to put the retrieved data.
  [in,out] | p_len | In: The length in bytes of `p_data`. Out: The length in bytes of the read data, if the read was successful.

Return values

  NRF_SUCCESS | If the data was read successfully.
  NRF_ERROR_INVALID_PARAM | If the the data type or the peer ID was invalid or unallocated, or if the length in `p_length` was not a multiple of 4.
  NRF_ERROR_NULL | If a pointer parameter was NULL.
  NRF_ERROR_NOT_FOUND | If no stored data was found for this peer ID/data ID combination.
  NRF_ERROR_DATA_SIZE | If the provided buffer was not large enough.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_peer_data_remote_db_load | ( | pm_peer_id_t | peer_id,
|  | ble_gatt_db_srv_t * | p_data,
|  | uint16_t * | p_len
| ) |  |

Function for reading a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).

See pm_peer_data_load for parameters and return values.

ret_code_t pm_peer_data_remote_db_store | ( | pm_peer_id_t | peer_id,
|  | ble_gatt_db_srv_t const * | p_data,
|  | uint16_t | len,
|  | pm_store_token_t * | p_token
| ) |  |

Function for setting or updating a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).

See pm_peer_data_store for parameters and return values.

ret_code_t pm_peer_data_store | ( | pm_peer_id_t | peer_id,
|  | pm_peer_data_id_t | data_id,
|  | void const * | p_data,
|  | uint16_t | len,
|  | pm_store_token_t * | p_token
| ) |  |

Function for setting or updating stored data of a peer.

Note
  Writing the data to persistent storage happens asynchronously. Therefore, the buffer that contains the data must be kept alive until the operation has completed.
  The data written using this function might later be overwritten as a result of internal operations in the Peer Manager. A Peer Manager event is sent each time data is updated, regardless of whether the operation originated internally or from action by the user.

Parameters

  [in] | peer_id | Peer ID to set data for.
  [in] | data_id | Which type of data to set.
  [in] | p_data | New value to set.
  [in] | len | The length in bytes of `p_data`.
  [out] | p_token | A token that identifies this particular store operation. The token can be used to identify events that pertain to this operation. This parameter can be NULL.

Return values

  NRF_SUCCESS | If the data is scheduled to be written to persistent storage.
  NRF_ERROR_NULL | If `p_data` is NULL.
  NRF_ERROR_NOT_FOUND | If no peer was found for the peer ID.
  NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_peer_delete | ( | pm_peer_id_t | peer_id | ) |

Function for freeing persistent storage for a peer.

This function deletes every piece of data that is associated with the specified peer and frees the peer ID to be used for another peer. The deletion happens asynchronously, and the peer ID is not freed until the data is deleted. When the operation finishes, a PM_EVT_PEER_DELETE_SUCCEEDED or PM_EVT_PEER_DELETE_FAILED event is sent.

Warning
  Use this function only when not connected to or connectable for the peer that is being deleted. If the peer is or becomes connected or data is manually written in flash during this procedure (until the success or failure event happens), the behavior is undefined.

Parameters

  [in] | peer_id | Peer ID to be freed and have all associated data deleted.

Return values

  NRF_SUCCESS | If the operation was initiated successfully.
  NRF_ERROR_INVALID_PARAM | If the peer ID was not valid.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_peer_id_get | ( | uint16_t | conn_handle,
|  | pm_peer_id_t * | p_peer_id
| ) |  |

Function for retrieving the ID of a peer, given its connection handle.

Parameters

  [in] | conn_handle | The connection handle of the peer.
  [out] | p_peer_id | The peer ID, or PM_PEER_ID_INVALID if the peer is not bonded or `conn_handle` does not refer to a valid connection.

Return values

  NRF_SUCCESS | If the peer ID was retrieved successfully.
  NRF_ERROR_NULL | If `p_peer_id` was NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_peer_new | ( | pm_peer_id_t * | p_new_peer_id,
|  | pm_peer_data_bonding_t * | p_bonding_data,
|  | pm_store_token_t * | p_token
| ) |  |

Function for manually adding a peer to the persistent storage.

This function allocates a new peer ID and stores bonding data for the new peer. The bonding data is necessary to prevent ambiguity/inconsistency in peer data.

Parameters

  [in] | p_bonding_data | The bonding data of the new peer (must contain a public/static address or a non-zero IRK).
  [out] | p_new_peer_id | Peer ID for the new peer, or an existing peer if a match was found.
  [out] | p_token | A token that identifies this particular store operation (storing the bonding data). The token can be used to identify events that pertain to this operation. This parameter can be NULL.

Return values

  NRF_SUCCESS | If the store operation for bonding data was initiated successfully.
  NRF_ERROR_NULL | If `p_bonding_data` or `p_new_peer_id` is NULL.
  NRF_ERROR_NO_MEM | If there is no more space in persistent storage, or peer IDs have been exhausted.
  NRF_ERROR_BUSY | If the underlying flash filesystem is busy with other flash operations. Try again after receiving a Peer Manager event.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_peer_rank_highest | ( | pm_peer_id_t | peer_id | ) |

Function for updating the rank of a peer to be highest among all stored peers.

If this function returns NRF_SUCCESS, either a PM_EVT_PEER_DATA_UPDATE_SUCCEEDED or a PM_EVT_PEER_DATA_UPDATE_FAILED event is sent with a PM_STORE_TOKEN_INVALID store token when the operation is complete. Until the operation is complete, this function returns NRF_ERROR_BUSY.

When the operation is complete, the peer is the highest ranked peer as reported by pm_peer_ranks_get.

Note
  The PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event can arrive before the function returns if the peer is already ranked highest. In this case, the pm_peer_data_update_succeeded_evt_t::flash_changed flag in the event will be false.

Parameters

  [in] | peer_id | The peer to rank highest.

Return values

  NRF_SUCCESS | If the peer's rank is, or will be updated to be highest.
  NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations, or if a previous call to this function has not completed. Try again after receiving a Peer Manager event.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_peer_ranks_get | ( | pm_peer_id_t * | p_highest_ranked_peer,
|  | uint32_t * | p_highest_rank,
|  | pm_peer_id_t * | p_lowest_ranked_peer,
|  | uint32_t * | p_lowest_rank
| ) |  |

Function for finding the highest and lowest ranked peers.

The rank is saved in persistent storage under the data ID PM_PEER_DATA_ID_PEER_RANK.

The interpretation of rank is up to the user, because the rank is only updated by calling pm_peer_rank_highest or by manipulating the value using a PM_PEER_DATA_FUNCTIONS function.

Note
  Any argument that is NULL is ignored.

Parameters

  [out] | p_highest_ranked_peer | The peer ID with the highest rank of all peers, for example, the most recently used peer.
  [out] | p_highest_rank | The highest rank.
  [out] | p_lowest_ranked_peer | The peer ID with the lowest rank of all peers, for example, the least recently used peer.
  [out] | p_lowest_rank | The lowest rank.

Return values

  NRF_SUCCESS | If the operation completed successfully.
  NRF_ERROR_NOT_FOUND | If no peers were found.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_peers_delete | ( | void |  | ) |

Function for deleting all data stored for all peers.

This function sends either a PM_EVT_PEERS_DELETE_SUCCEEDED or a PM_EVT_PEERS_DELETE_FAILED event. In addition, a PM_EVT_PEER_DELETE_SUCCEEDED or PM_EVT_PEER_DELETE_FAILED event is sent for each deleted peer.

Note
  No event is sent when there is no peer data in flash.

Warning
  Use this function only when not connected or connectable. If a peer is or becomes connected or a PM_PEER_DATA_FUNCTIONS function is used during this procedure (until the success or failure event happens), the behavior is undefined.

Return values

  NRF_SUCCESS | If the deletion process was initiated successfully.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_privacy_get | ( | pm_privacy_params_t * | p_privacy_params | ) |

Function for retrieving privacy settings.

The privacy settings that are returned include the current IRK as well.

Parameters

  [out] | p_privacy_params | Privacy settings.

Return values

  NRF_SUCCESS | If the privacy settings were retrieved successfully.
  NRF_ERROR_NULL | If `p_privacy_params` or `p_privacy_params->p_device_irk` is NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_privacy_set | ( | pm_privacy_params_t const * | p_privacy_params | ) |

Function for configuring privacy settings.

The privacy settings cannot be configured while advertising, scanning, or while in a connection.

Note
  The SoftDevice functions sd_ble_gap_address_set (S13x v2.x), sd_ble_gap_addr_set (S13x v3.x), and sd_ble_gap_privacy_set (S13x v3.x) must not be called when using the Peer Manager. Use this function instead.

Parameters

  [in] | p_privacy_params | Privacy settings.

Return values

  NRF_SUCCESS | If the privacy settings were configured successfully.
  NRF_ERROR_NULL | If `p_privacy_params` is NULL.
  NRF_ERROR_BUSY | If the operation could not be performed at this time. Process SoftDevice events and retry.
  NRF_ERROR_INVALID_PARAM | If the address type is invalid.
  NRF_ERROR_INVALID_STATE | If this function is called while BLE roles using privacy are enabled.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_register | ( | pm_evt_handler_t | event_handler | ) |

Function for registering an event handler with the Peer Manager.

Parameters

  [in] | event_handler | Callback for events from the Peer Manager module. `event_handler` is called for every event that the Peer Manager sends after this function is called.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_NULL | If `event_handler` was NULL.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_sec_params_set | ( | ble_gap_sec_params_t * | p_sec_params | ) |

Function for providing pairing and bonding parameters to use for pairing procedures.

Until this function is called, all bonding procedures that are initiated by the peer are rejected.

This function can be called multiple times with different parameters, even with NULL as `p_sec_params`, in which case the Peer Manager starts rejecting all procedures again.

Parameters

  [in] | p_sec_params | Security parameters to be used for subsequent security procedures.

Return values

  NRF_SUCCESS | If the parameters were set successfully.
  NRF_ERROR_INVALID_PARAM | If the combination of parameters is invalid.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.
  NRF_ERROR_INTERNAL | If an internal error occurred.

ret_code_t pm_whitelist_get | ( | ble_gap_addr_t * | p_addrs,
|  | uint32_t * | p_addr_cnt,
|  | ble_gap_irk_t * | p_irks,
|  | uint32_t * | p_irk_cnt
| ) |  |

Function for retrieving the previously set whitelist.

The function retrieves the whitelist of GAP addresses and IRKs that was previously set by pm_whitelist_set.

To retrieve only GAP addresses or only IRKs, provide only one of the buffers. If a buffer is provided, its size must be specified.

Parameters

  [out] | p_addrs | The buffer where to store GAP addresses. Pass NULL to retrieve only IRKs (in that case, `p_irks` must not be NULL).
  [in,out] | p_addr_cnt | In: The size of the `p_addrs` buffer. May be NULL if and only if `p_addrs` is NULL. Out: The number of GAP addresses copied into the buffer. If `p_addrs` is NULL, this parameter remains unchanged.
  [out] | p_irks | The buffer where to store IRKs. Pass NULL to retrieve only GAP addresses (in that case, `p_addrs` must not NULL).
  [in,out] | p_irk_cnt | In: The size of the `p_irks` buffer. May be NULL if and only if `p_irks` is NULL. Out: The number of IRKs copied into the buffer. If `p_irks` is NULL, this paramater remains unchanged.

Return values

  NRF_SUCCESS | If the whitelist was successfully retrieved.
  BLE_ERROR_GAP_INVALID_BLE_ADDR | If a peer has an address that cannot be used for whitelisting (this error can occur only when using the S13x SoftDevice v2.x).
  NRF_ERROR_NULL | If a required parameter is NULL.
  NRF_ERROR_NO_MEM | If the provided buffers are too small.
  NRF_ERROR_NOT_FOUND | If the data for any of the cached whitelisted peers cannot be found. It might have been deleted.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.

ret_code_t pm_whitelist_set | ( | pm_peer_id_t const * | p_peers,
|  | uint32_t | peer_cnt
| ) |  |

Function for setting or clearing the whitelist.

When using the S13x SoftDevice v3.x, this function sets or clears the whitelist. When using the S13x SoftDevice v2.x, this function caches a list of peers that can be retrieved later by pm_whitelist_get to pass to the Advertising Module.

To clear the current whitelist, pass either NULL as `p_peers` or zero as `peer_cnt`.

Parameters

  [in] | p_peers | The peers to add to the whitelist. Pass NULL to clear the current whitelist.
  [in] | peer_cnt | The number of peers to add to the whitelist. The number must not be greater than BLE_GAP_WHITELIST_ADDR_MAX_COUNT. Pass zero to clear the current whitelist.

Return values

  NRF_SUCCESS | If the whitelist was successfully set or cleared.
  BLE_GAP_ERROR_WHITELIST_IN_USE | If a whitelist is already in use and cannot be set.
  BLE_ERROR_GAP_INVALID_BLE_ADDR | If a peer in `p_peers` has an address that cannot be used for whitelisting.
  NRF_ERROR_NOT_FOUND | If any of the peers in `p_peers` cannot be found.
  NRF_ERROR_DATA_SIZE | If `peer_cnt` is greater than BLE_GAP_WHITELIST_ADDR_MAX_COUNT.
  NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized.