nRF5 SDK v17.1.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Peer Manager

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
 
 LESC module
 Module for handling LESC related events.
 
 Peer Manager Standard Event Handlers
 Standard event handlers implementing some best practices for BLE security.
 
 Peer Manager defined security errors
 
 All versions of Peer IDs.
 The data ID for each iteration of the data formats in flash.
 

Data Structures

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_conn_sec_status_t
 Security status of a connection. More...
 
struct  pm_conn_config_req_evt_t
 Parameters specific to the PM_EVT_CONN_CONFIG_REQ event. More...
 
struct  pm_conn_sec_start_evt_t
 Events parameters specific to the PM_EVT_CONN_SEC_START event. 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_conn_sec_params_req_evt_t
 Parameters specific to the PM_EVT_CONN_SEC_PARAMS_REQ 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...
 

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 uint16_t pm_peer_id_t
 Handle to uniquely identify a peer for which we have persistently stored data.
 
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...
 
typedef ble_gap_privacy_params_t pm_privacy_params_t
 Device Privacy. More...
 
typedef void(* pm_evt_handler_t )(pm_evt_t const *p_event)
 Event handler for events from the Peer Manager module. More...
 

Enumerations

enum  pm_peer_id_list_skip_t {
  PM_PEER_ID_LIST_ALL_ID,
  PM_PEER_ID_LIST_SKIP_NO_ID_ADDR = BIT_0,
  PM_PEER_ID_LIST_SKIP_NO_IRK = BIT_1,
  PM_PEER_ID_LIST_SKIP_NO_CAR = BIT_2,
  PM_PEER_ID_LIST_SKIP_ALL
}
 Peer list filtrations. They determine which peer ID will be added to list. 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_CENTRAL_ADDR_RES = 9,
  PM_PEER_DATA_ID_APPLICATION = 4,
  PM_PEER_DATA_ID_LAST = 10,
  PM_PEER_DATA_ID_INVALID = 0xFF
}
 The different types of data associated with a peer. More...
 
enum  pm_conn_sec_procedure_t {
  PM_CONN_SEC_PROCEDURE_ENCRYPTION,
  PM_CONN_SEC_PROCEDURE_BONDING,
  PM_CONN_SEC_PROCEDURE_PAIRING
}
 Different procedures that can lead to an encrypted link. More...
 
enum  pm_evt_id_t {
  PM_EVT_BONDED_PEER_CONNECTED,
  PM_EVT_CONN_CONFIG_REQ,
  PM_EVT_CONN_SEC_START,
  PM_EVT_CONN_SEC_SUCCEEDED,
  PM_EVT_CONN_SEC_FAILED,
  PM_EVT_CONN_SEC_CONFIG_REQ,
  PM_EVT_CONN_SEC_PARAMS_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,
  PM_EVT_SLAVE_SECURITY_REQ,
  PM_EVT_FLASH_GARBAGE_COLLECTED,
  PM_EVT_FLASH_GARBAGE_COLLECTION_FAILED
}
 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...
 

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...
 
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...
 
ret_code_t pm_conn_exclude (uint16_t conn_handle, void const *p_context)
 Function for excluding a connection from the BLE event flow that is handled inside the Peer Manager. 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...
 
ret_code_t pm_conn_sec_params_reply (uint16_t conn_handle, ble_gap_sec_params_t *p_sec_params, void const *p_context)
 Function for providing security parameters 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...
 
bool pm_sec_is_sufficient (uint16_t conn_handle, pm_conn_sec_status_t *p_sec_status_req)
 Function for comparing the security status of a connection against a baseline. 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...
 
bool pm_address_resolve (ble_gap_addr_t const *p_addr, ble_gap_irk_t const *p_irk)
 Function for resolving a resolvable address with an identity resolution key (IRK). 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...
 
ret_code_t pm_peer_id_list (pm_peer_id_t *p_peer_list, uint32_t *const p_list_size, pm_peer_id_t first_peer_id, pm_peer_id_list_skip_t skip_id)
 Function for retrieving a filtered list of peer IDs. 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, uint32_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, uint32_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, void *p_data, uint32_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, uint32_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, uint32_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, void const *p_data, uint32_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.

This module uses Flash Data Storage (FDS) to interface with persistent storage. The Peer Manager needs exclusive use of certain FDS file IDs and record keys. See Restrictions on keys and IDs for more information.

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_eventThe event that has occurred.

Device Privacy.

   The privacy feature provides a way for the device to avoid being tracked over a period of
   time. The privacy feature, when enabled, hides the local device identity and replaces it
   with a private address that is automatically refreshed at a specified interval.

   If a device still wants to be recognized by other peers, it needs to share it's Identity
   Resolving Key (IRK). With this key, a device can generate a random private address that
   can only be recognized by peers in possession of that key, and devices can establish
   connections without revealing their real identities.
Note
If the device IRK is updated, the new IRK becomes the one to be distributed in all bonding procedures performed after sd_ble_gap_privacy_set returns. The IRK distributed during bonding procedure is the device IRK that is active when sd_ble_gap_sec_params_reply is called.
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

Different procedures that can lead to an encrypted link.

Enumerator
PM_CONN_SEC_PROCEDURE_ENCRYPTION 

Using an LTK that was shared during a previous bonding procedure to encrypt the link.

PM_CONN_SEC_PROCEDURE_BONDING 

A pairing procedure, followed by a bonding procedure.

PM_CONN_SEC_PROCEDURE_PAIRING 

A pairing procedure with no bonding.

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_CONFIG_REQ 

A new connection has been established. This event is a wrapper for BLE_GAP_EVT_CONNECTED event and contains its parameters. Reply with pm_conn_exclude before the event handler returns to exclude BLE events targeting this connection from being handled by the Peer Manager.

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_CONN_SEC_PARAMS_REQ 

Security parameters (ble_gap_sec_params_t) are needed for an ongoing security procedure. Reply with pm_conn_sec_params_reply before the event handler returns. If no reply is sent, the parameters given in pm_sec_params_set are used. If a peripheral connection, the central's sec_params will be available in the event.

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.

PM_EVT_SLAVE_SECURITY_REQ 

The peer (peripheral) has requested link encryption, which has been enabled.

PM_EVT_FLASH_GARBAGE_COLLECTED 

The flash has been garbage collected (By FDS), possibly freeing up space.

PM_EVT_FLASH_GARBAGE_COLLECTION_FAILED 

Garbage collection was attempted but failed.

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. Type: 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. Type: bool.

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). Type: 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. Type: uint8_t array.

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. Type: uint32_t.

PM_PEER_DATA_ID_CENTRAL_ADDR_RES 

The data ID of the first version of central address resolution.

The data ID for central address resolution. See pm_peer_id_list. Type: uint32_t.

PM_PEER_DATA_ID_APPLICATION 

The data ID of the first version of application data.

The data ID for application data. Type: uint8_t array.

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.

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.

Peer list filtrations. They determine which peer ID will be added to list.

Enumerator
PM_PEER_ID_LIST_ALL_ID 

Add all peers.

PM_PEER_ID_LIST_SKIP_NO_ID_ADDR 

Add only peers with an ID address (static address).

PM_PEER_ID_LIST_SKIP_NO_IRK 

Add only peers with a valid IRK. This implies PM_PEER_ID_LIST_SKIP_NO_ID_ADDR, since all peers with IRKs have ID addresses.

PM_PEER_ID_LIST_SKIP_NO_CAR 

Add only peers with Central Address Resolution characteristic set to 0.

PM_PEER_ID_LIST_SKIP_ALL 

All above filters applied.

Function Documentation

bool pm_address_resolve ( ble_gap_addr_t const *  p_addr,
ble_gap_irk_t const *  p_irk 
)

Function for resolving a resolvable address with an identity resolution key (IRK).

Parameters
[in]p_addrA private random resolvable address.
[in]p_irkAn identity resolution key (IRK).
Return values
trueThe IRK used matched the one used to create the address.
falseThe IRK used did not match the one used to create the address, or an argument was NULL or invalid.
ret_code_t pm_conn_exclude ( uint16_t  conn_handle,
void const *  p_context 
)

Function for excluding a connection from the BLE event flow that is handled inside the Peer Manager.

This function is optional, and must be called in reply to a PM_EVT_CONN_CONFIG_REQ event, before the Peer Manager event handler returns. If it is not called in time, BLE events for a connection handle passed in the PM_EVT_CONN_CONFIG_REQ event will be normally handled by the Peer Manager.

Parameters
[in]conn_handleThe connection to be excluded.
[in]p_contextThe context found in the request event that this function replies to.
Return values
NRF_SUCCESSSuccessful reply.
NRF_ERROR_NULLp_context was null.
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_idThe peer ID of the bonded peer.
[out]p_conn_handleConnection handle, or BLE_CONN_HANDLE_INVALID if none could be resolved. The conn_handle can refer to a recently disconnected connection.
Return values
NRF_SUCCESSIf the connection handle was retrieved successfully.
NRF_ERROR_NULLIf p_conn_handle was NULL.
NRF_ERROR_INVALID_STATEIf 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_handleThe connection to set the configuration for.
[in]p_conn_sec_configThe configuration.
ret_code_t pm_conn_sec_params_reply ( uint16_t  conn_handle,
ble_gap_sec_params_t p_sec_params,
void const *  p_context 
)

Function for providing security parameters for a link.

This function is optional, and must be called in reply to a PM_EVT_CONN_SEC_PARAMS_REQ event, before the Peer Manager event handler returns. If it is not called in time, the parameters given in pm_sec_params_set are used.

Parameters
[in]conn_handleThe connection to set the parameters for.
[in]p_sec_paramsThe parameters. If NULL, the security procedure is rejected.
[in]p_contextThe context found in the request event that this function replies to.
Return values
NRF_SUCCESSSuccessful reply.
NRF_ERROR_NULLp_sec_params or p_context was null.
NRF_ERROR_INVALID_PARAMValue of p_sec_params was invalid.
NRF_ERROR_INVALID_STATEThis module is not initialized.
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_handleConnection handle of the link as provided by the SoftDevice.
[out]p_conn_sec_statusSecurity status of the link.
Return values
NRF_SUCCESSIf pairing was initiated successfully.
BLE_ERROR_INVALID_CONN_HANDLEIf the connection handle is invalid.
NRF_ERROR_NULLIf p_conn_sec_status was NULL.
NRF_ERROR_INVALID_STATEIf 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 security parameters, the function attempts to establish encryption with the existing keys. If no key exists, the function attempts to perform pairing and bonding according to the currently active security parameters.

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_AUTH_STATUS event occurs with the status BLE_GAP_SEC_STATUS_TIMEOUT. 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_handleConnection handle of the link as provided by the SoftDevice.
[in]force_repairingWhether 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_SUCCESSIf the operation completed successfully.
NRF_ERROR_BUSYIf a security procedure is already in progress on the link, or if the link is disconnecting or disconnected.
NRF_ERROR_TIMEOUTIf there was an SMP time-out, so that no more security operations can be performed on this link.
BLE_ERROR_INVALID_CONN_HANDLEIf the connection handle is invalid.
NRF_ERROR_NOT_FOUNDIf the security parameters have not been set, either by pm_sec_params_set or by pm_conn_sec_params_reply.
NRF_ERROR_INVALID_DATAIf the peer is bonded, but no LTK was found in the stored bonding data. Repairing was not requested.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf 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.

Note
When entering directed advertising, make sure the active identities list does not contain peers that have no Central Address Resolution. See pm_peer_id_list with skip_id PM_PEER_ID_LIST_SKIP_NO_CAR.
Parameters
[in]p_peersThe peers to add to the device identities list. Pass NULL to clear the device identities list.
[in]peer_cntThe number of peers. Pass zero to clear the device identities list.
Return values
NRF_SUCCESSIf the device identities list was successfully set or cleared.
NRF_ERROR_NOT_FOUNDIf a peer is invalid or its data could not be found in flash.
BLE_ERROR_GAP_INVALID_BLE_ADDRIf a peer has an address that cannot be used for whitelisting.
BLE_ERROR_GAP_DEVICE_IDENTITIES_IN_USEIf the device identities list is in use and cannot be set.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_NOT_SUPPORTEDIf 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_addrPointer to the address structure to be filled in.
Return values
NRF_SUCCESSIf the address was retrieved successfully.
NRF_ERROR_NULLIf p_addr is NULL.
NRF_ERROR_INVALID_STATEIf 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 use this function to assign a different identity address.

The identity address is distributed to the peer during bonding. Changing the identity address means bonded devices might not recognize us.

Note
The SoftDevice functions sd_ble_gap_addr_set and sd_ble_gap_privacy_set must not be called when using the Peer Manager. Use the Peer Manager equivalents instead.
Parameters
[in]p_addrThe GAP address to be set.
Return values
NRF_SUCCESSIf the identity address was set successfully.
NRF_ERROR_NULLIf p_addr is NULL.
NRF_ERROR_INVALID_ADDRIf the p_addr pointer is invalid.
BLE_ERROR_GAP_INVALID_BLE_ADDRIf the BLE address is invalid.
NRF_ERROR_BUSYIf the SoftDevice was busy. Process SoftDevice events and retry.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized or if this function was called while advertising, scanning, or while connected.
NRF_ERROR_INTERNALIf 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_SUCCESSIf initialization was successful.
NRF_ERROR_INTERNALIf 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.
This function is deprecated. LESC keys are now handled internally if PM_LESC_ENABLED is true. If PM_LESC_ENABLED is false, this function works as before.
Parameters
[in]p_public_keyThe public key to use for all subsequent LESC operations.
Return values
NRF_SUCCESSIf pairing was initiated successfully.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_FORBIDDENIf LESC module support is enabled (see PM_LESC_ENABLED).
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, or if the PM_SERVICE_CHANGED_ENABLED is set to 0, 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:

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)
}
Note
This function does not report peer IDs that are pending deletion.
Parameters
[in]prev_peer_idThe 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.
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,
void *  p_data,
uint32_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,
void const *  p_data,
uint32_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_idPeer ID to clear data for.
[in]data_idWhich data to clear.
Return values
NRF_SUCCESSIf the clear procedure was initiated successfully.
NRF_ERROR_INVALID_PARAMIf data_id was PM_PEER_DATA_ID_BONDING or invalid, or peer_id was invalid.
NRF_ERROR_NOT_FOUNDIf there was no data to clear for this peer ID/data ID combination.
NRF_ERROR_BUSYIf the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf 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,
uint32_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_idPeer ID to get data for.
[in]data_idWhich type of data to read.
[out]p_dataWhere to put the retrieved data. The documentation for pm_peer_data_id_t specifies what data type each data ID is stored as.
[in,out]p_lenIn: The length in bytes of p_data. Out: The length in bytes of the read data, if the read was successful.
Return values
NRF_SUCCESSIf the data was read successfully.
NRF_ERROR_INVALID_PARAMIf the data type or the peer ID was invalid or unallocated.
NRF_ERROR_NULLIf a pointer parameter was NULL.
NRF_ERROR_NOT_FOUNDIf no stored data was found for this peer ID/data ID combination.
NRF_ERROR_DATA_SIZEIf the provided buffer was not large enough. The data is still copied, filling the provided buffer. Note that this error can occur even if loading the same size as was stored, because the underlying layers round the length up to the nearest word (4 bytes) when storing.
NRF_ERROR_INVALID_STATEIf 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,
uint32_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,
uint32_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,
uint32_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. Data with data_id PM_PEER_DATA_ID_GATT_REMOTE PM_PEER_DATA_ID_APPLICATION is never (over)written internally.
Parameters
[in]peer_idPeer ID to set data for.
[in]data_idWhich type of data to set.
[in]p_dataNew value to set. The documentation for pm_peer_data_id_t specifies what data type each data ID should be stored as.
[in]lenThe length in bytes of p_data.
[out]p_tokenA 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_SUCCESSIf the data is scheduled to be written to persistent storage.
NRF_ERROR_NULLIf p_data is NULL.
NRF_ERROR_NOT_FOUNDIf no peer was found for the peer ID.
NRF_ERROR_INVALID_ADDRIf p_data is not word-aligned (4 bytes).
NRF_ERROR_BUSYIf the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event.
NRF_ERROR_STORAGE_FULLIf there is not enough space in persistent storage.
NRF_ERROR_FORBIDDENIf data ID is PM_PEER_DATA_ID_BONDING and the new bonding data also corresponds to another bonded peer. No data is written so duplicate entries are avoided.
NRF_ERROR_INVALID_STATEIf 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_idPeer ID to be freed and have all associated data deleted.
Return values
NRF_SUCCESSIf the operation was initiated successfully.
NRF_ERROR_INVALID_PARAMIf the peer ID was not valid.
NRF_ERROR_INVALID_STATEIf 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_handleThe connection handle of the peer.
[out]p_peer_idThe 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_SUCCESSIf the peer ID was retrieved successfully.
NRF_ERROR_NULLIf p_peer_id was NULL.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
ret_code_t pm_peer_id_list ( pm_peer_id_t p_peer_list,
uint32_t *const  p_list_size,
pm_peer_id_t  first_peer_id,
pm_peer_id_list_skip_t  skip_id 
)

Function for retrieving a filtered list of peer IDs.

This function starts searching from first_peer_id. IDs ordering is the same as for pm_next_peer_id_get(). If the first_peer_id is PM_PEER_ID_INVALID, the function starts searching from the first ID. The function looks for the ID's number specified by p_list_size. Only those IDs that match skip_id are added to the list. The number of returned elements is determined by p_list_size.

Warning
The size of the p_peer_list buffer must be equal or greater than p_list_size.
Parameters
[out]p_peer_listPointer to peer IDs list buffer.
[in,out]p_list_sizeThe amount of IDs to return / The number of returned IDs.
[in]first_peer_idThe first ID from which the search begins. IDs ordering is the same as for pm_next_peer_id_get()
[in]skip_idIt determines which peer ID will be added to list.
Return values
NRF_SUCCESSIf the ID list has been filled out.
NRF_ERROR_INVALID_PARAMIf skip_id was invalid.
NRF_ERROR_NULLIf peer_list or list_size was NULL.
NRF_ERROR_INVALID_STATEIf 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_dataThe bonding data of the new peer (must contain a public/static address or a non-zero IRK).
[out]p_new_peer_idPeer ID for the new peer, or an existing peer if a match was found.
[out]p_tokenA 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_SUCCESSIf the store operation for bonding data was initiated successfully.
NRF_ERROR_NULLIf p_bonding_data or p_new_peer_id is NULL.
NRF_ERROR_INVALID_ADDRIf p_bonding_data is not word-aligned (4 bytes).
NRF_ERROR_STORAGE_FULLIf there is not enough space in persistent storage.
NRF_ERROR_NO_MEMIf there are no more available peer IDs.
NRF_ERROR_BUSYIf the underlying flash filesystem is busy with other flash operations. Try again after receiving a Peer Manager event.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf 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_idThe peer to rank highest.
Return values
NRF_SUCCESSIf the peer's rank is, or will be updated to be highest.
NRF_ERROR_INVALID_PARAMIf peer_id is invalid, or doesn't exist in flash.
NRF_ERROR_STORAGE_FULLIf there is not enough space in persistent storage.
NRF_ERROR_BUSYIf 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_STATEIf the Peer Manager is not initialized.
NRF_ERROR_RESOURCESIf the highest rank is UINT32_MAX, so the new rank would wrap around to 0. To fix this, manually update all ranks to smaller values, while still keeping their order.
NRF_ERROR_INTERNALIf an internal error occurred.
NRF_ERROR_NOT_SUPPORTEDIf peer rank functionality has been disabled via the PM_PEER_RANKS_ENABLED configuration option.
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
Peers with no stored rank are not considered.
Any argument that is NULL is ignored.
Parameters
[out]p_highest_ranked_peerThe peer ID with the highest rank of all peers, for example, the most recently used peer.
[out]p_highest_rankThe highest rank.
[out]p_lowest_ranked_peerThe peer ID with the lowest rank of all peers, for example, the least recently used peer.
[out]p_lowest_rankThe lowest rank.
Return values
NRF_SUCCESSIf the operation completed successfully.
NRF_ERROR_NOT_FOUNDIf no peer with stored peer rank was found.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf an internal error occurred.
NRF_ERROR_NOT_SUPPORTEDIf peer rank functionality has been disabled via the PM_PEER_RANKS_ENABLED configuration option.
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
When there is no peer data in flash the PM_EVT_PEER_DELETE_SUCCEEDED event is sent synchronously.
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_SUCCESSIf the deletion process was initiated successfully.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf 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_paramsPrivacy settings.
Return values
NRF_SUCCESSIf the privacy settings were retrieved successfully.
NRF_ERROR_NULLIf p_privacy_params or p_privacy_params->p_device_irk is NULL.
NRF_ERROR_INVALID_STATEIf 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_addr_set and sd_ble_gap_privacy_set must not be called when using the Peer Manager. Use this function instead.
Parameters
[in]p_privacy_paramsPrivacy settings.
Return values
NRF_SUCCESSIf the privacy settings were configured successfully.
NRF_ERROR_NULLIf p_privacy_params is NULL.
NRF_ERROR_BUSYIf the operation could not be performed at this time. Process SoftDevice events and retry.
NRF_ERROR_INVALID_PARAMIf the address type is invalid.
NRF_ERROR_INVALID_STATEIf this function is called while BLE roles using privacy are enabled.
NRF_ERROR_INVALID_STATEIf 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_handlerCallback 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_SUCCESSIf initialization was successful.
NRF_ERROR_NULLIf event_handler was NULL.
NRF_ERROR_NO_MEMIf no more registrations can happen.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
bool pm_sec_is_sufficient ( uint16_t  conn_handle,
pm_conn_sec_status_t p_sec_status_req 
)

Function for comparing the security status of a connection against a baseline.

Parameters
[in]conn_handleConnection handle of the link as provided by the SoftDevice.
[out]p_sec_status_reqTarget baseline security status to compare against.
Return values
trueIf the security status of the connection matches or exceeds the baseline on all points.
falseIf the security status of the connection does not fulfil the baseline, or could not be retrieved.
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_paramsSecurity parameters to be used for subsequent security procedures.
Return values
NRF_SUCCESSIf the parameters were set successfully.
NRF_ERROR_INVALID_PARAMIf the combination of parameters is invalid.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.
NRF_ERROR_INTERNALIf 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_addrsThe 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_cntIn: 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_irksThe buffer where to store IRKs. Pass NULL to retrieve only GAP addresses (in that case, p_addrs must not NULL).
[in,out]p_irk_cntIn: 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_SUCCESSIf the whitelist was successfully retrieved.
BLE_ERROR_GAP_INVALID_BLE_ADDRIf 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_NULLIf a required parameter is NULL.
NRF_ERROR_NO_MEMIf the provided buffers are too small.
NRF_ERROR_NOT_FOUNDIf the data for any of the cached whitelisted peers cannot be found. It might have been deleted.
NRF_ERROR_INVALID_STATEIf 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_peersThe peers to add to the whitelist. Pass NULL to clear the current whitelist.
[in]peer_cntThe 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_SUCCESSIf the whitelist was successfully set or cleared.
BLE_GAP_ERROR_WHITELIST_IN_USEIf a whitelist is already in use and cannot be set.
BLE_ERROR_GAP_INVALID_BLE_ADDRIf a peer in p_peers has an address that cannot be used for whitelisting.
NRF_ERROR_NOT_FOUNDIf any of the peers in p_peers cannot be found.
NRF_ERROR_DATA_SIZEIf peer_cnt is greater than BLE_GAP_WHITELIST_ADDR_MAX_COUNT.
NRF_ERROR_INVALID_STATEIf the Peer Manager is not initialized.

Documentation feedback | Developer Zone | Subscribe | Updated