BLE Device Manager

This section provides API to manage the bonded peers and API to get and set security and connection between the bonded peers in LE. More...

Overview

This section provides API to manage the bonded peers and API to get and set security and connection between the bonded peers in LE.

The bonded peer management includes the bookkeeping of contextual information, such as the security keys and any application specific information.

Terms and Acronyms

Terms	Details
GAP	Generic Access Profile. This profile defines the generic procedures related to discovery of Bluetooth enabled devices and link management aspects of connecting to the Bluetooth enabled devices. It also defines procedures related to the use of different security levels.

How to use this module

• Step 1. Initialize the LE Device Manager.
  • Sample Code:

    bt_device_manager_le_init();

• Step 2. Use LE Device Manager APIs to set security information, such as local key, pairing configuration.
  • Sample code:

    bt_gap_le_smp_pairing_config_t pairing_config = {// MITM, Bond, Out-of-Band
                        .maximum_encryption_key_size = 16,
                        .io_capability = BT_GAP_LE_SMP_NO_INPUT_NO_OUTPUT,
                        .auth_req = BT_GAP_LE_SMP_AUTH_REQ_BONDING,
                        .oob_data_flag = BT_GAP_LE_SMP_OOB_DATA_NOT_PRESENTED,
                        .initiator_key_distribution = BT_GAP_LE_SMP_KEY_DISTRIBUTE_ENCKEY | BT_GAP_LE_SMP_KEY_DISTRIBUTE_IDKEY | BT_GAP_LE_SMP_KEY_DISTRIBUTE_SIGN,
                        .responder_key_distribution = BT_GAP_LE_SMP_KEY_DISTRIBUTE_ENCKEY | BT_GAP_LE_SMP_KEY_DISTRIBUTE_IDKEY | BT_GAP_LE_SMP_KEY_DISTRIBUTE_SIGN,
                        };
    bt_gap_le_local_key_t local_key = {
                         .encryption_info.ltk = { 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc8, 0xc7, 0xc8, 0xc9, 0xca, 0xcb, 0xcc, 0xcd, 0xce, 0xcf },
                         .master_id.ediv = 0x1005,
                         .master_id.rand = { 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7 },
                         .identity_info.irk = { 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7, 0xc8, 0xc9, 0xca, 0xcb, 0xcc, 0xcd, 0xce, 0xcf },
                         .signing_info.csrk = { 0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7, 0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf }
                         };
    
    bool sc_only = false;
    bt_device_manager_le_gap_set_pairing_configuration(&pairing_config); 
    bt_device_manager_le_gap_set_local_configuration(&local_key, sc_only);

Functions
void	bt_device_manager_le_init (void)
	This function initializes the LE Device Manager service. More...
void	bt_device_manager_le_remove_bonded_device (bt_addr_t *peer_addr)
	This function removes the bonded device information specified by the peer_addr from this device. More...
void	bt_device_manager_le_clear_all_bonded_info (void)
	This function clears all bonded information stored in this device. More...
bt_device_manager_le_connection_param_t *	bt_device_manager_le_get_current_connection_param (bt_handle_t connection_handle)
	This function gets the connection parameter of the current link specified by the connection handle. More...
bt_status_t	bt_device_manager_le_gap_set_local_configuration (bt_gap_le_local_key_t *local_key, bool sc_only_mode)
	This function sets the local configuration of this device. More...
bt_status_t	bt_device_manager_le_gap_set_pairing_configuration (bt_gap_le_smp_pairing_config_t *pairing_config)
	This function sets the preferred pairing configuration of this device. More...
void	bt_device_manager_le_get_bonded_list (bt_bd_addr_t *list, uint32_t *count)
	This function gets the list of bonded LE devices. More...
bool	bt_device_manager_le_is_bonded (bt_addr_t *address)
	This function gets the bonded status of the LE device specified by the address. More...
uint8_t	bt_device_manager_le_get_bonded_number (void)
	This function gets the count of the bonded LE devices. More...
bt_bd_addr_ptr_t	bt_device_manager_le_get_public_address (void)
	This function gets the public address of the device. More...

Modules
	Struct
	This section defines structures for the LE Device Manager.

Function Documentation

void bt_device_manager_le_clear_all_bonded_info

(

void

)

This function clears all bonded information stored in this device.

Parameters

[in]

void.

Returns

void.

bt_status_t bt_device_manager_le_gap_set_local_configuration	(	bt_gap_le_local_key_t *	local_key,
		bool	sc_only_mode
	)

This function sets the local configuration of this device.

Parameters

[in]	local_key	is a pointer to the bt_gap_le_local_config_req_ind_t structure.
[in]	sc_only_mode	is a flag to enable or disable the secure connection pairing mode.

Returns

BT_STATUS_SUCCESS, the local configuration is successfully set. BT_STATUS_FAIL, the local configuration failed to set. Please call bt_device_manager_le_init() first.

bt_status_t bt_device_manager_le_gap_set_pairing_configuration

(

bt_gap_le_smp_pairing_config_t *

pairing_config

)

This function sets the preferred pairing configuration of this device.

Parameters

[in]

pairing_config

is a pointer to the bt_gap_le_smp_pairing_config_t structure.

Returns

BT_STATUS_SUCCESS, the pairing configuration is successfully set. BT_STATUS_FAIL, the pairing configuration failed to set. Please call bt_device_manager_le_init() first.

void bt_device_manager_le_get_bonded_list	(	bt_bd_addr_t *	list,
		uint32_t *	count
	)

This function gets the list of bonded LE devices.

Parameters

[out]	list	is the list of bonded LE devices.
[in,out]	count	is the input and output parameter. As an input parameter, it is the length of the list and the maximum number of bonded LE devices that the list can hold. As an output parameter, it is the actual number of the bonded LE devices stored in the list upon the return of this function, which cannot exceed the length of the list.

Returns

void.

uint8_t bt_device_manager_le_get_bonded_number

(

void

)

This function gets the count of the bonded LE devices.

Returns

The count of the bonded LE devices.

bt_device_manager_le_connection_param_t* bt_device_manager_le_get_current_connection_param

(

bt_handle_t

connection_handle

)

This function gets the connection parameter of the current link specified by the connection handle.

Parameters

[in]

connection_handle

is the connection handle.

Returns

connection_param_t is a pointer to the current connection parameter.

bt_bd_addr_ptr_t bt_device_manager_le_get_public_address

(

void

)

This function gets the public address of the device.

Returns

The public address of the device.

void bt_device_manager_le_init

(

void

)

This function initializes the LE Device Manager service.

It is recommended to call this API once during the bootup.

Parameters

[in]

void.

Returns

void.

bool bt_device_manager_le_is_bonded

(

bt_addr_t *

address

)

This function gets the bonded status of the LE device specified by the address.

Parameters

[in]

address

is the address of the LE device to check.

Returns

True, bonded. False, unbonded.

void bt_device_manager_le_remove_bonded_device

(

bt_addr_t *

peer_addr

)

This function removes the bonded device information specified by the peer_addr from this device.

Parameters

[in]

peer_addr

is the address of the bonded device.

Returns

void.