General Description

This section contains the connection related defines and structures used in LE link management.

API Reference
	Connection and Filter Accept List
	This section provides functions for LE connection related and Filter Accept List operations.

	Phy
	This section provides functionality to read and update PHY.

Data Structures
struct	wiced_bt_ble_phy_preferences_t
	Host PHY preferences. More...

struct	wiced_bt_ble_conn_params_t
	LE connection parameteres. More...

struct	wiced_bt_ble_pref_conn_params_t
	LE preferred connection parameters. More...

struct	wiced_bt_ble_key_material_t
	Encryption Data Key Material structure. More...

Macros
#define	BTM_BLE_CONN_INTERVAL_MIN_DEF 24
	default connection interval min recommended min: 30ms = 24 * 1.25

#define	BTM_BLE_CONN_INTERVAL_MAX_DEF 40
	default connection interval max recommended max: 50 ms = 56 * 1.25

#define	BTM_BLE_CONN_PERIPHERAL_LATENCY_DEF 0
	default Peripheral latency

#define	BTM_BLE_CONN_TIMEOUT_DEF 2000
	default supervision timeout

#define	BTM_BLE_AUTH_SIGNATURE_SIZE 12
	LE Signature LE data signature length 8 Bytes + 4 bytes counter.

#define	BTM_BLE_PREFER_1M_PHY 0x01
	LE 1M PHY preference.

#define	BTM_BLE_PREFER_2M_PHY 0x02
	LE 2M PHY preference.

#define	BTM_BLE_PREFER_LELR_PHY 0x04
	LE LELR PHY preference.

#define	BTM_BLE_PREFER_NO_LELR 0x0000
	No preferred coding.

#define	BTM_BLE_PREFER_LELR_S2 0x0001
	Preferred coding is S=2, 500 kb/s.

#define	BTM_BLE_PREFER_LELR_S8 0x0002
	Preferred coding is S=8, 125 kb/s.

#define	BTM_AFH_CHNL_MAP_SIZE HCI_AFH_CHANNEL_MAP_LEN
	AFH channel map size.

#define	BLE_CHANNEL_MAP_LEN 5
	AFH Channel Map len.

Typedefs
typedef uint8_t	wiced_dev_ble_signature_t[BTM_BLE_AUTH_SIGNATURE_SIZE]
	Device address (see BTM_BLE_AUTH_SIGNATURE_SIZE)

typedef uint8_t	wiced_bt_ble_sec_action_type_t
	LE security type. More...

typedef uint8_t	wiced_bt_ble_host_phy_preferences_t
	Host preferences on PHY. More...

typedef uint16_t	wiced_bt_ble_lelr_phy_preferences_t
	The PHY_options parameter is a bit field that allows the Host to specify options for LE long range PHY. More...

typedef uint8_t	wiced_bt_ble_conn_type_t
	Connection type (see wiced_bt_ble_conn_type_e)

typedef uint8_t	wiced_bt_ble_privacy_mode_t
	LE Privacy mode. More...

typedef uint8_t	wiced_bt_ble_chnl_map_t[BLE_CHANNEL_MAP_LEN]
	LE Channel Map.

typedef void()	wiced_bt_ble_read_phy_complete_callback_t(wiced_bt_ble_phy_update_t *p_phy_result)
	Callback wiced_bt_ble_read_phy_complete_callback_t. More...

Enumerations
enum	wiced_bt_ble_sec_action_type_e { BTM_BLE_SEC_NONE, BTM_BLE_SEC_ENCRYPT, BTM_BLE_SEC_ENCRYPT_NO_MITM, BTM_BLE_SEC_ENCRYPT_MITM }
	LE encryption method. More...

enum	wiced_bt_ble_sec_flags_e { BTM_SEC_LE_LINK_ENCRYPTED = 0x01, BTM_SEC_LE_LINK_PAIRED_WITHOUT_MITM = 0x02, BTM_SEC_LE_LINK_PAIRED_WITH_MITM = 0x04 }
	security settings used with L2CAP LE COC More...

enum	wiced_bt_ble_conn_type_e { BTM_BLE_CONN_NONE, BTM_BLE_CONN_AUTO, BTM_BLE_CONN_SELECTIVE = BTM_BLE_CONN_AUTO }
	Background connection type. More...

enum	wiced_bt_ble_privacy_e { BTM_BLE_PRIVACY_MODE_NETWORK, BTM_BLE_PRIVACY_MODE_DEVICE }
	Privacy mode refer Spec version 5.0 Vol 3 Part C Section 10.7 privacy feature. More...

Functions
wiced_result_t	wiced_bt_ble_get_connection_parameters (wiced_bt_device_address_t remote_bda, wiced_bt_ble_conn_params_t *p_conn_parameters)
	To read LE connection parameters based on connection address received in gatt connection up indication. More...

wiced_result_t	wiced_bt_ble_read_le_features (wiced_bt_device_address_t bda, wiced_bt_features_t features)
	Function wiced_bt_ble_read_le_features. More...

wiced_bt_dev_status_t	wiced_bt_ble_set_host_features (wiced_bt_ble_feature_bit_t feature, uint8_t bit_value)
	Function wiced_bt_ble_set_host_features. More...

wiced_result_t	wiced_bt_ble_encrypt_adv_packet (uint8_t p_key, uint8_t p_iv, uint8_t p_randomizer, const uint8_t p_plaintext, uint8_t p_encrypted, int payload_len, uint32_t p_mic)
	Function wiced_bt_ble_encrypt_adv_packet. More...

wiced_result_t	wiced_bt_ble_decrypt_adv_packet (uint8_t p_key, uint8_t p_iv, uint8_t p_randomizer, const uint8_t p_encrypted, uint8_t p_plaintext, int coded_len, uint32_t p_mic)
	Function wiced_bt_ble_decrypt_adv_packet. More...

wiced_bt_dev_status_t	wiced_bt_ble_set_data_packet_length (wiced_bt_device_address_t bd_addr, uint16_t tx_pdu_length, uint16_t tx_time)
	This API allows to set maximum transmission payload size and maximum packet transmission time to be used for LL DATA PDUs on a given connection. More...

wiced_bool_t	wiced_bt_smp_create_local_sc_oob_data (wiced_bt_device_address_t bd_addr, wiced_bt_ble_address_type_t bd_addr_type)
	Create local LE SC (secure connection) OOB data. More...

wiced_bool_t	wiced_bt_ble_data_signature (wiced_bt_device_address_t bd_addr, uint8_t *p_text, uint16_t len, wiced_dev_ble_signature_t signature)
	Sign the data using AES128 CMAC algorith. More...

wiced_bool_t	wiced_bt_ble_verify_signature (wiced_bt_device_address_t bd_addr, uint8_t p_orig, uint16_t len, uint32_t counter, uint8_t p_comp)
	Verify the data signature. More...

wiced_bool_t	wiced_bt_ble_get_security_state (wiced_bt_device_address_t bd_addr, uint8_t p_le_sec_flags, uint8_t p_le_key_size)
	Get security mode 1 flags and encryption key size for LE peer. More...

wiced_bt_dev_status_t	wiced_bt_ble_set_privacy_mode (wiced_bt_device_address_t remote_bda, wiced_bt_ble_address_type_t rem_bda_type, wiced_bt_ble_privacy_mode_t privacy_mode)
	Updates privacy mode if device is already available in controller resolving list. More...

wiced_bt_dev_status_t	wiced_bt_ble_read_device_random_address (wiced_bt_device_address_t random_bd_addr)
	Get the configured local random device address. More...

wiced_result_t	wiced_ble_private_device_address_resolution (wiced_bt_device_address_t rpa, BT_OCTET16 irk)
	Function wiced_ble_private_device_address_resolution. More...

wiced_result_t	wiced_bt_ble_address_resolution_list_clear_and_disable (void)
	Function wiced_bt_ble_address_resolution_list_clear_and_disable. More...

Typedef Documentation

◆ wiced_bt_ble_sec_action_type_t

typedef uint8_t wiced_bt_ble_sec_action_type_t

LE security type.

refer wiced_bt_ble_sec_action_type_e

◆ wiced_bt_ble_host_phy_preferences_t

typedef uint8_t wiced_bt_ble_host_phy_preferences_t

Host preferences on PHY.

bit field that indicates the transmitter PHYs that the Host prefers the Controller to use.Bit number 3 -7 reserved for future.

◆ wiced_bt_ble_lelr_phy_preferences_t

typedef uint16_t wiced_bt_ble_lelr_phy_preferences_t

The PHY_options parameter is a bit field that allows the Host to specify options for LE long range PHY.

Default connection is with no LE coded PHY.The Controller may override any preferred coding (S2 coded phy for 512k speed and s8 coded phy for 128K) for transmitting on the LE Coded PHY. The Host may specify a preferred coding even if it prefers not to use the LE Coded transmitter PHY since the Controller may override the PHY preference. Bit 2-15 reserved for future use.

Note: These preferences applicable only when BTM_BLE_PREFER_LELR_PHY flag is set

◆ wiced_bt_ble_privacy_mode_t

typedef uint8_t wiced_bt_ble_privacy_mode_t

LE Privacy mode.

See wiced_bt_ble_privacy_e

◆ wiced_bt_ble_read_phy_complete_callback_t

typedef void() wiced_bt_ble_read_phy_complete_callback_t(wiced_bt_ble_phy_update_t *p_phy_result)

Callback wiced_bt_ble_read_phy_complete_callback_t.

read phy complete callback (from calling wiced_bt_ble_read_phy)

Parameters

p_phy_result : read phys result

Returns: Nothing

Enumeration Type Documentation

◆ wiced_bt_ble_sec_action_type_e

enum wiced_bt_ble_sec_action_type_e

LE encryption method.

Enumerator
BTM_BLE_SEC_NONE	No encryption.
BTM_BLE_SEC_ENCRYPT	encrypt the link using current key
BTM_BLE_SEC_ENCRYPT_NO_MITM	encryption without MITM
BTM_BLE_SEC_ENCRYPT_MITM	encryption with MITM

◆ wiced_bt_ble_sec_flags_e

enum wiced_bt_ble_sec_flags_e

security settings used with L2CAP LE COC

Enumerator
BTM_SEC_LE_LINK_ENCRYPTED	Link encrypted.
BTM_SEC_LE_LINK_PAIRED_WITHOUT_MITM	Paired without man-in-the-middle protection.
BTM_SEC_LE_LINK_PAIRED_WITH_MITM	Link with man-in-the-middle protection.

◆ wiced_bt_ble_conn_type_e

enum wiced_bt_ble_conn_type_e

Background connection type.

Enumerator
BTM_BLE_CONN_NONE	No background connection.
BTM_BLE_CONN_AUTO	Auto connection based on filter list.
BTM_BLE_CONN_SELECTIVE	Selective not used.

◆ wiced_bt_ble_privacy_e

enum wiced_bt_ble_privacy_e

Privacy mode refer Spec version 5.0 Vol 3 Part C Section 10.7 privacy feature.

Enumerator
BTM_BLE_PRIVACY_MODE_NETWORK	network privacy mode
BTM_BLE_PRIVACY_MODE_DEVICE	device privacy mode

Function Documentation

◆ wiced_bt_ble_get_connection_parameters()

wiced_result_t wiced_bt_ble_get_connection_parameters	(	wiced_bt_device_address_t	remote_bda,
		wiced_bt_ble_conn_params_t *	p_conn_parameters
	)

To read LE connection parameters based on connection address received in gatt connection up indication.

Parameters

[in]	remote_bda	: remote device address.
[in]	p_conn_parameters	: Connection Parameters

Returns: wiced_result_t
WICED_BT_ILLEGAL_VALUE : if p_conn_parameters is NULL.
WICED_BT_UNKNOWN_ADDR : if device address is bad.
WICED_BT_SUCCESS otherwise.

◆ wiced_bt_ble_data_signature()

wiced_bool_t wiced_bt_ble_data_signature	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_text,
		uint16_t	len,
		wiced_dev_ble_signature_t	signature
	)

Sign the data using AES128 CMAC algorith.

Parameters

[in]	bd_addr	target device the data to be signed for.
[in]	p_text	signing data
[in]	len	length of the signing data
[in]	signature	output parameter where data signature is going to be stored

Returns: TRUE if signing successful, otherwise FALSE.

◆ wiced_bt_ble_verify_signature()

wiced_bool_t wiced_bt_ble_verify_signature	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_orig,
		uint16_t	len,
		uint32_t	counter,
		uint8_t *	p_comp
	)

Verify the data signature.

Parameters

[in]	bd_addr	target device the data to be signed for.
[in]	p_orig	original data before signature.
[in]	len	length of the signing data
[in]	counter	counter used when doing data signing
[in]	p_comp	signature to be compared against.

Returns: TRUE if signature verified correctly; otherwise FALSE.

◆ wiced_bt_ble_get_security_state()

wiced_bool_t wiced_bt_ble_get_security_state	(	wiced_bt_device_address_t	bd_addr,
		uint8_t *	p_le_sec_flags,
		uint8_t *	p_le_key_size
	)

Get security mode 1 flags and encryption key size for LE peer.

Parameters

[in]	bd_addr	: peer address
[out]	p_le_sec_flags	: security flags (see wiced_bt_ble_sec_flags_e)
[out]	p_le_key_size	: encryption key size

Returns: TRUE if successful

◆ wiced_bt_ble_set_privacy_mode()

wiced_bt_dev_status_t wiced_bt_ble_set_privacy_mode	(	wiced_bt_device_address_t	remote_bda,
		wiced_bt_ble_address_type_t	rem_bda_type,
		wiced_bt_ble_privacy_mode_t	privacy_mode
	)

Updates privacy mode if device is already available in controller resolving list.

Parameters

[in]	remote_bda	-remote device address received during connection up
[in]	rem_bda_type	-remote device address type received during connection up
[in]	privacy_mode	- privacy mode (see wiced_bt_ble_privacy_mode_t)

Returns: wiced_bt_dev_status_t
WICED_BT_ILLEGAL_VALUE : if paramer is wrong
WICED_BT_UNSUPPORTED : if command not supported
WICED_BT_UNKNOWN_ADDR : if bd_addr is wrong
WICED_BT_ILLEGAL_ACTION : if device not added to resolving list or peer irk is not valid
WICED_BT_ERROR : error while processing the command
WICED_BT_SUCCESS : if command started

◆ wiced_bt_ble_read_device_random_address()

wiced_bt_dev_status_t wiced_bt_ble_read_device_random_address ( wiced_bt_device_address_t random_bd_addr )

Get the configured local random device address.

Note : random address depends on below settings in that priority order. 1) Global privacy configuration using rpa_refresh_timeout (see wiced_bt_cfg_settings_t). 2) else configured for static random bd_address while downloading using BT_DEVICE_ADDRESS=random build setting.

Parameters

[out] random_bd_addr - device random bd address

Returns: wiced_bt_dev_status_t WICED_BT_SUCCESS : if random address is configured.
WICED_BT_WRONG_MODE : if random address not configured.

◆ wiced_ble_private_device_address_resolution()

wiced_result_t wiced_ble_private_device_address_resolution	(	wiced_bt_device_address_t	rpa,
		BT_OCTET16	irk
	)

Function wiced_ble_private_device_address_resolution.

             This API verifies whether given device address is Resolvable Private Address or not

Parameters

rpa	LE Resolvable Private Address
irk	LE IRK

Returns: wiced_result_t WICED_BT_SUCCESS the identity of device address has been resolved. WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_address_resolution_list_clear_and_disable()

wiced_result_t wiced_bt_ble_address_resolution_list_clear_and_disable ( void )

Function wiced_bt_ble_address_resolution_list_clear_and_disable.

             This API clears the address resolution list and disables the address resolution feature.

Returns: wiced_result_t WICED_BT_SUCCESS if address resolution list is cleared and adress resolution feature is disabled. WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_read_le_features()

wiced_result_t wiced_bt_ble_read_le_features	(	wiced_bt_device_address_t	bda,
		wiced_bt_features_t	features
	)

Function wiced_bt_ble_read_le_features.

             This API returns the features supported by the \p bda

Parameters

[in]	bda	Device address pointer, pass NULL for local device
[out]	features	Pointer to store the supported features

Returns: wiced_result_t WICED_BT_SUCCESS contents of features are valid WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_set_host_features()

wiced_bt_dev_status_t wiced_bt_ble_set_host_features	(	wiced_bt_ble_feature_bit_t	feature,
		uint8_t	bit_value
	)

Function wiced_bt_ble_set_host_features.

     This API is called to set the supported host features

Parameters

[in]	feature	bit position of required feature
[in]	bit_value	Value to enable or disable Advertising Coding Selection Host Support feature bit

Returns: wiced_result_t WICED_BT_SUCCESS Advertising Coding Selection Host Support feature bit is modified WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_encrypt_adv_packet()

wiced_result_t wiced_bt_ble_encrypt_adv_packet	(	uint8_t *	p_key,
		uint8_t *	p_iv,
		uint8_t *	p_randomizer,
		const uint8_t *	p_plaintext,
		uint8_t *	p_encrypted,
		int	payload_len,
		uint32_t *	p_mic
	)

Function wiced_bt_ble_encrypt_adv_packet.

This API is called to encrypt advertising data. Encrypts data at p_plaintext of length payload_len into p_encrypted of length payload_len

Parameters

[in]	p_key	session key
[in]	p_iv	initialization vector
[in]	p_randomizer	randomizer
[in]	p_plaintext	plaintext to be encoded
[in]	p_encrypted	encrypted output
[in]	payload_len	plaintext/encrypted data len
[out]	p_mic	pointer to MIC, Message Integrity Check, derived from the data

Returns: wiced_result_t WICED_BT_SUCCESS If adv_packet is encrypted successfully WICED_BT_ERROR otherwise

◆ wiced_bt_ble_decrypt_adv_packet()

wiced_result_t wiced_bt_ble_decrypt_adv_packet	(	uint8_t *	p_key,
		uint8_t *	p_iv,
		uint8_t *	p_randomizer,
		const uint8_t *	p_encrypted,
		uint8_t *	p_plaintext,
		int	coded_len,
		uint32_t *	p_mic
	)

Function wiced_bt_ble_decrypt_adv_packet.

This API is called to decrypt advertising data. Decrypts data at p_encrypted of length coded_len into p_plaintext of length coded_len

Parameters

[in]	p_key	session key
[in]	p_iv	initialization vector
[in]	p_randomizer	randomizer
[in]	p_encrypted	encrypted data input
[in]	p_plaintext	plaintext output
[in]	coded_len	encrypted data len
[in]	p_mic	pointer to MIC, Message Integrity Check, derived from the data

Returns: wiced_result_t WICED_BT_SUCCESS If adv_packet is decrypted successfully WICED_BT_ERROR otherwise

◆ wiced_bt_ble_set_data_packet_length()

wiced_bt_dev_status_t wiced_bt_ble_set_data_packet_length	(	wiced_bt_device_address_t	bd_addr,
		uint16_t	tx_pdu_length,
		uint16_t	tx_time
	)

This API allows to set maximum transmission payload size and maximum packet transmission time to be used for LL DATA PDUs on a given connection.

Parameters

[in]	bd_addr	- bd_Addr for which the LL Data PDU need to set
[in]	tx_pdu_length	- maximum LL Data PDU on this connection.
[in]	tx_time	- maximum number of microseconds taken to transmit a packet on this connection(Range 0x0148 to 0x4290).

Returns: wiced_bt_dev_status_t

WICED_BT_SUCCESS : If command sent successfully
WICED_BT_ERROR : If there is no connection exists
WICED_BT_WRONG_MODE : If command not supported

Note: if tx_time = 0, then a default value applies based on the max supported by the controller HCI version.

◆ wiced_bt_smp_create_local_sc_oob_data()

wiced_bool_t wiced_bt_smp_create_local_sc_oob_data	(	wiced_bt_device_address_t	bd_addr,
		wiced_bt_ble_address_type_t	bd_addr_type
	)

Create local LE SC (secure connection) OOB data.

When operation is completed, local OOB data will be provided via BTM_SMP_SC_LOCAL_OOB_DATA_NOTIFICATION_EVT.

Parameters

[in]	bd_addr	: remote device address for the OOB data
[in]	bd_addr_type	: device address type of address `bd_addr`

Returns: TRUE: creation of local SC OOB data set started.

General Description

API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ wiced_bt_ble_sec_action_type_t

◆ wiced_bt_ble_host_phy_preferences_t

◆ wiced_bt_ble_lelr_phy_preferences_t

◆ wiced_bt_ble_privacy_mode_t

◆ wiced_bt_ble_read_phy_complete_callback_t

Enumeration Type Documentation

◆ wiced_bt_ble_sec_action_type_e

◆ wiced_bt_ble_sec_flags_e

◆ wiced_bt_ble_conn_type_e

◆ wiced_bt_ble_privacy_e

Function Documentation

◆ wiced_bt_ble_get_connection_parameters()

◆ wiced_bt_ble_data_signature()

◆ wiced_bt_ble_verify_signature()

◆ wiced_bt_ble_get_security_state()

◆ wiced_bt_ble_set_privacy_mode()

◆ wiced_bt_ble_read_device_random_address()

◆ wiced_ble_private_device_address_resolution()

◆ wiced_bt_ble_address_resolution_list_clear_and_disable()

◆ wiced_bt_ble_read_le_features()

◆ wiced_bt_ble_set_host_features()

◆ wiced_bt_ble_encrypt_adv_packet()

◆ wiced_bt_ble_decrypt_adv_packet()

◆ wiced_bt_ble_set_data_packet_length()

◆ wiced_bt_smp_create_local_sc_oob_data()