Functions
void	ble_gap_pair_enable (bool enable)
	Decide whether to support the pair feature. More...

uint16_t	ble_gap_addr_set (gap_bdaddr_t const *p_addr)
	Set the device identity address (public or random static). More...

uint16_t	ble_gap_addr_get (gap_bdaddr_t *p_addr)
	Get the device identity address (public or random static). More...

uint16_t	ble_gap_tx_power_set (gap_activity_role_t role, uint8_t index, int8_t txpwr_dbm)
	Set the tx power. More...

uint16_t	ble_gap_tx_power_get (gap_activity_role_t role, uint8_t index, int8_t *txpwr_dbm)
	Get the tx power. More...

uint16_t	ble_gap_irk_set (gap_sec_key_t *p_irk)
	Set IRK used for resolvable random BD address generation (LSB first). More...

uint16_t	ble_gap_privacy_params_set (uint16_t renew_dur, bool enable_flag)
	Set privacy related parameters. More...

uint16_t	ble_gap_data_length_set (uint16_t sugg_max_tx_octet, uint16_t sugg_max_tx_time)
	Set suggested default LE data length. More...

uint16_t	ble_gap_l2cap_params_set (uint16_t max_mtu, uint16_t max_mps, uint8_t max_nb_lecb)
	Set L2CAP related parameters. More...

void	ble_gap_pref_phy_set (uint8_t tx_pref_phy, uint8_t rx_pref_phy)
	Set the preferred values for the transmitter PHY and receiver PHY. More...

uint16_t	ble_gap_path_compensation_set (int16_t tx_path_comp, int16_t rx_path_comp)
	Set the RF path gain or loss between the RF transceiver and the antenna contributed by intermediate components. More...

uint16_t	ble_gap_chnl_map_set (gap_chnl_map_t *p_chnl_map)
	Set advertising channel map before advertising starts. More...

uint16_t	ble_gap_bond_devs_get (bond_dev_list_t *p_bond_list)
	Get all bonded devices. More...

uint16_t	ble_gap_bond_dev_addr_get (uint8_t conn_idx, gap_bdaddr_t *p_peer_addr)
	Get BD address of the bonded device. More...

uint16_t	ble_gap_bond_devs_clear (void)
	Clear all bonded devices. More...

uint16_t	ble_gap_bond_dev_del (const gap_bdaddr_t *p_peer_addr)
	Delete a bond device with the specified BD address. More...

uint16_t	ble_gap_whitelist_get (white_list_t *p_whitelist)
	Get the content of the whole white list. More...

uint16_t	ble_gap_whitelist_add (const white_list_t *p_whitelist)
	Add the devices into current white list. If white list is full or there are duplicated entries, it will return error. More...

uint16_t	ble_gap_whitelist_del (const white_list_t *p_whitelist)
	Delete the devices out of current white list. If the entries do not exist in the current white list, it will return error. More...

uint16_t	ble_gap_whitelist_clear (void)
	Clear all the entries in the current white list. More...

uint16_t	ble_gap_per_adv_list_get (period_adv_list_t *p_pal_list)
	Get the content of the whole periodic advertising list. More...

uint16_t	ble_gap_per_adv_list_add (const period_adv_list_t *p_pal_list)
	Add the devices into current periodic advertising list. If periodic advertising list is full or there are duplicated entries, it will return error. More...

uint16_t	ble_gap_per_adv_list_del (const period_adv_list_t *p_pal_list)
	Delete the devices out of periodic advertising list. If the entries do not exist in the current list, an error will be returned. More...

uint16_t	ble_gap_per_adv_list_clear (void)
	Clear all the entries in the current periodic advertising list. More...

uint16_t	ble_gap_rpa_list_get (ral_dev_list_t *p_rpa_list)
	Get the RPA list info. More...

uint16_t	ble_gap_dev_info_get (gap_dev_info_get_type_t type)
	Get the device information according to param type. More...

uint16_t	ble_gap_adv_param_set (uint8_t adv_idx, gap_own_addr_t own_addr_type, gap_adv_param_t *p_adv_param)
	Set parameters for advertising. Note that this function must be called prior to advertising started. More...

uint16_t	ble_gap_ext_adv_param_set (uint8_t adv_idx, gap_own_addr_t own_addr_type, gap_ext_adv_param_t *p_adv_param)
	Set extended parameters for advertising. Note that this function must be called prior to advertising. More...

uint16_t	ble_gap_adv_data_set (uint8_t adv_idx, gap_adv_data_type_t type, const uint8_t *p_data, uint16_t length)
	Set Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions. More...

uint16_t	ble_gap_update_adv_data (uint8_t adv_idx, gap_adv_data_type_t type, const uint8_t *p_data, uint16_t length)
	Update Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions. More...

uint16_t	ble_gap_adv_start (uint8_t adv_idx, gap_adv_time_param_t *p_timeout)
	Start advertising. More...

uint16_t	ble_gap_adv_stop (uint8_t adv_idx)
	Stop advertising. More...

uint16_t	ble_gap_scan_param_set (gap_own_addr_t own_addr_type, gap_scan_param_t *p_scan_param)
	Set parameters for scanning. Note that this function must be called prior to scanning started. More...

uint16_t	ble_gap_ext_scan_param_set (gap_own_addr_t own_addr_type, gap_ext_scan_param_t *p_scan_param)
	Set extended parameters for scanning. Note that this function must be called prior to scanning started. More...

uint16_t	ble_gap_scan_start (void)
	Start scanning. More...

uint16_t	ble_gap_scan_stop (void)
	Stop scanning. More...

uint16_t	ble_gap_per_sync_param_set (uint8_t per_sync_idx, gap_per_sync_param_t *p_per_sync_param)
	Set the parameters used for periodic sync. More...

uint16_t	ble_gap_per_sync_start (uint8_t per_sync_idx)
	Start to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. More...

uint16_t	ble_gap_per_sync_stop (uint8_t per_sync_idx)
	Stop periodic synchronization. More...

uint16_t	ble_gap_connect (gap_own_addr_t own_addr_type, gap_init_param_t *p_init_param)
	Start a legacy connection to a device. More...

uint16_t	ble_gap_ext_connect (gap_own_addr_t own_addr_type, gap_ext_init_param_t *p_init_param)
	Start an extended connection to a device. More...

uint16_t	ble_gap_connect_cancel (void)
	Cancel an initiated connection. More...

void	ble_gap_appearance_set (uint16_t appearance)
	Set GAP appearance value. More...

uint16_t	ble_gap_appearance_get (uint16_t *p_appearance)
	Get GAP appearance value. More...

void	ble_gap_ppcp_present_set (bool present_flag)
	Set GAP Peripheral Preferred Connection Parameters present flag. More...

uint16_t	ble_gap_ppcp_set (gap_conn_param_t const *p_conn_params)
	Set GAP Peripheral Preferred Connection Parameters. More...

uint16_t	ble_gap_ppcp_get (gap_conn_param_t *p_conn_params)
	Get GAP Peripheral Preferred Connection Parameters. More...

uint16_t	ble_gap_device_name_set (gap_dev_name_write_perm_t write_perm, uint8_t const *p_dev_name, uint16_t length)
	Set GAP device name. More...

uint16_t	ble_gap_device_name_get (uint8_t p_dev_name, uint16_t p_length)
	Get GAP device name. More...

uint16_t	ble_gap_lepsm_register (gap_lepsm_register_t *p_lepsm)
	Register a LE Protocol/Service Multiplexer. More...

uint16_t	ble_gap_lepsm_unregister (uint16_t le_psm)
	Unregister a LE Protocol/Service Multiplexer. More...

uint16_t	ble_gap_privacy_mode_set (gap_bdaddr_t peer_addr, privacy_mode_t mode)
	Set privacy mode for peer device. More...

uint16_t	ble_gap_rslv_addr_read (gap_rslv_addr_read_op_id_t op_code, gap_bdaddr_t peer_iden_addr)
	Read peer or local resolvable address. More...

uint16_t	ble_gap_reslv_rpa_addr (uint8_t *reslv_addr, uint8_t src_info, reslv_rpa_addr_callback_t cb)
	Resolve the rpa address. More...

uint16_t	ble_gap_update_conn_param_method_set (uint8_t conn_idx, bool use_l2cap_flag)
	Set the method for updating connection parameter. More...

void	ble_gap_rpa_addr_report_cb_register (rpa_addr_report_callback_t cb)
	Set the cb for rpa address report. More...

Detailed Description

Function Documentation

◆ ble_gap_addr_get()

uint16_t ble_gap_addr_get ( gap_bdaddr_t * p_addr )

Get the device identity address (public or random static).

Parameters

[in] p_addr The pointer for the returned identity address.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_addr_set()

uint16_t ble_gap_addr_set ( gap_bdaddr_t const * p_addr )

Set the device identity address (public or random static).

Parameters

[in] p_addr Provided public or static random address. If addr_type = 0, it means public address, If addr_type = 1, it means static random address.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

◆ ble_gap_adv_data_set()

uint16_t ble_gap_adv_data_set	(	uint8_t	adv_idx,
		gap_adv_data_type_t	type,
		const uint8_t *	p_data,
		uint16_t	length
	)

Set Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions.

Parameters

[in]	adv_idx	Advertising index, range is 0 to 4.
[in]	type	Data type.
[in]	p_data	The data pointer.
[in]	length	Data length.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_ADV_DATA_TYPE	Invalid advertising data type supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already.

◆ ble_gap_adv_param_set()

uint16_t ble_gap_adv_param_set	(	uint8_t	adv_idx,
		gap_own_addr_t	own_addr_type,
		gap_adv_param_t *	p_adv_param
	)

Set parameters for advertising. Note that this function must be called prior to advertising started.

Parameters

[in]	adv_idx	Advertising index, range is 0 to 4.
[in]	own_addr_type	Own BD address source of the local device.
[in]	p_adv_param	The advertising parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: Discovery mode param contains Flags AD type, setting adv data should not set the Flags AD type.; This API is for legacy advertsing (BT Core Spec version <= 4.2).

◆ ble_gap_adv_start()

uint16_t ble_gap_adv_start	(	uint8_t	adv_idx,
		gap_adv_time_param_t *	p_timeout
	)

Start advertising.

Parameters

[in]	adv_idx	Advertising index, range is 0 to 4.
[in]	p_timeout	Advertising timing parameter.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: If advertising mode is directed high duty cycle mode, duration should be set nonzero and not be greater than 1.28s.; This API is asynchronous.; If the field scan_req_ind_en in gap_adv_param_t is TRUE passed in ble_gap_adv_param_set function, or if the GAP_ADV_PROP_SCAN_REQ_NTF_EN_BIT is set in gap_adv_prop_t and passed in ble_gap_ext_adv_param_set function, gap_cb_fun_t::app_gap_scan_req_ind_cb will be called once a scan request has been received.; gap_cb_fun_t::app_gap_adv_start_cb will be called once the operation has completed.

◆ ble_gap_adv_stop()

uint16_t ble_gap_adv_stop ( uint8_t adv_idx )

Stop advertising.

Parameters

[in] adv_idx Advertising index, range is 0 to 4.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_adv_stop_cb will be called once the operation has completed or advertising has been stopped.

◆ ble_gap_appearance_get()

uint16_t ble_gap_appearance_get ( uint16_t * p_appearance )

Get GAP appearance value.

Parameters

[out] p_appearance The pointer to appearance value.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_appearance_set()

void ble_gap_appearance_set ( uint16_t appearance )

Set GAP appearance value.

Parameters

[in] appearance Appearance value.

◆ ble_gap_bond_dev_addr_get()

uint16_t ble_gap_bond_dev_addr_get	(	uint8_t	conn_idx,
		gap_bdaddr_t *	p_peer_addr
	)

Get BD address of the bonded device.

Parameters

[in]	conn_idx	The index of connection.
[in]	p_peer_addr	Pointer to the peer BD addrss

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	The parameter is invalid.

◆ ble_gap_bond_dev_del()

uint16_t ble_gap_bond_dev_del ( const gap_bdaddr_t * p_peer_addr )

Delete a bond device with the specified BD address.

Parameters

[in] p_peer_addr Pointer to the BD addrss.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_SDK_INTERNAL	SDK internal error.
SDK_ERR_NVDS_NOT_INIT	NVDS is not initiated.
SDK_ERR_LIST_ITEM_NOT_FOUND	Item not found in list.
SDK_ERR_LIST_FULL	List is full.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_bond_devs_clear()

uint16_t ble_gap_bond_devs_clear ( void )

Clear all bonded devices.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_SDK_INTERNAL	SDK internal error.
SDK_ERR_NVDS_NOT_INIT	NVDS is not initiated.
SDK_ERR_LIST_ITEM_NOT_FOUND	Item not found in list.
SDK_ERR_LIST_FULL	List is full.

◆ ble_gap_bond_devs_get()

uint16_t ble_gap_bond_devs_get ( bond_dev_list_t * p_bond_list )

Get all bonded devices.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_SDK_INTERNAL	SDK internal error.
SDK_ERR_NVDS_NOT_INIT	NVDS is not initiated.
SDK_ERR_LIST_ITEM_NOT_FOUND	Item not found in list.
SDK_ERR_LIST_FULL	List is full.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_chnl_map_set()

uint16_t ble_gap_chnl_map_set ( gap_chnl_map_t * p_chnl_map )

Set advertising channel map before advertising starts.

Parameters

[in] p_chnl_map Bitmask of LE channel map. See enum gap_chnl_map_t for BT Core Spec version <= 4.2.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_CHNL_MAP_SET will be called once the operation has completed.

◆ ble_gap_connect()

uint16_t ble_gap_connect	(	gap_own_addr_t	own_addr_type,
		gap_init_param_t *	p_init_param
	)

Start a legacy connection to a device.

Parameters

[in]	own_addr_type	Own BD address source of the local device.
[in]	p_init_param	Initiate parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is for legacy connection (BT Core Spec version <= 4.2).; This API is asynchronous.; gap_cb_fun_t::app_gap_connect_cb will be called once the operation has completed or the connection has been completed.; gap_cb_fun_t::app_gap_peer_name_ind_cb will be called once the peer name has been got for the Name Discovery Procedure. See enum GAP_INIT_TYPE_NAME_DISC of type gap_init_type_t.

◆ ble_gap_connect_cancel()

uint16_t ble_gap_connect_cancel ( void )

Cancel an initiated connection.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_connect_cancel_cb will be called once the operation has completed.

◆ ble_gap_data_length_set()

uint16_t ble_gap_data_length_set	(	uint16_t	sugg_max_tx_octet,
		uint16_t	sugg_max_tx_time
	)

Set suggested default LE data length.

Parameters

[in]	sugg_max_tx_octet	Suggested value for the Controller's maximum transmitted number of payload octets to be used, the range is 27~251.
[in]	sugg_max_tx_time	Suggested value for the Controller's maximum packet transmission time to be used, the range is 328~2120.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

◆ ble_gap_dev_info_get()

uint16_t ble_gap_dev_info_get ( gap_dev_info_get_type_t type )

Get the device information according to param type.

Parameters

[in] type Param type.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_dev_info_get_cb with the specified op_id (see gap_dev_info_get_type_t) will be called once the requested parameters has been got.

◆ ble_gap_device_name_get()

uint16_t ble_gap_device_name_get	(	uint8_t *	p_dev_name,
		uint16_t *	p_length
	)

Get GAP device name.

Parameters

[out]	p_dev_name	The pointer to device name value, set to NULL to obtain the complete device name length.
[in,out]	p_length	Length of the buffer pointed by p_dev_name, complete device name length on output.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_DATA_LENGTH	Invalid data size(s) supplied.

Note: If device name was not set, the default device name "GOODIX_BLE" will be available.; If the device name is longer than the size of the supplied buffer,p_len will return the complete device name length, and not the number of bytes actually returned in p_dev_name. The application may use this information to allocate a suitable buffer size.

◆ ble_gap_device_name_set()

uint16_t ble_gap_device_name_set	(	gap_dev_name_write_perm_t	write_perm,
		uint8_t const *	p_dev_name,
		uint16_t	length
	)

Set GAP device name.

Parameters

[in]	write_perm	Write permissions of the device name characteristic.
[in]	p_dev_name	The pointer to device name value. If p_dev_name is NULL, this function will only set write permissions of the device name.
[in]	length	Device name length.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

◆ ble_gap_ext_adv_param_set()

uint16_t ble_gap_ext_adv_param_set	(	uint8_t	adv_idx,
		gap_own_addr_t	own_addr_type,
		gap_ext_adv_param_t *	p_adv_param
	)

Set extended parameters for advertising. Note that this function must be called prior to advertising.

Parameters

[in]	adv_idx	Advertising index, range is 0 to 4.
[in]	own_addr_type	Own BD address source of the local device.
[in]	p_adv_param	The advertising parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is for extended and periodic advertising (BT Core Spec version >= 5.0).

◆ ble_gap_ext_connect()

uint16_t ble_gap_ext_connect	(	gap_own_addr_t	own_addr_type,
		gap_ext_init_param_t *	p_init_param
	)

Start an extended connection to a device.

Parameters

[in]	own_addr_type	Own BD address source of the local device.
[in]	p_init_param	Initiate parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is for extended connection (BT Core Spec version >= 5.0).; This API is asynchronous.; gap_cb_fun_t::app_gap_connect_cb will be called once the operation has completed or the connection has been completed.

◆ ble_gap_ext_scan_param_set()

uint16_t ble_gap_ext_scan_param_set	(	gap_own_addr_t	own_addr_type,
		gap_ext_scan_param_t *	p_scan_param
	)

Set extended parameters for scanning. Note that this function must be called prior to scanning started.

Parameters

[in]	own_addr_type	Own BD address source of the local device.
[in]	p_scan_param	The scanning parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is for extended scanning (BT Core Spec version >= 5.0). The Scan window in p_scan_param should be enough to recieve one packet. For example. If you want to recieve packects with 1270 bytes on coded phy(S8), the scan_wd should be greater than 82ms. If you want to recieve packects with 1270 bytes on coded phy(S2), the scan_wd should be greater than 21ms.

◆ ble_gap_irk_set()

uint16_t ble_gap_irk_set ( gap_sec_key_t * p_irk )

Set IRK used for resolvable random BD address generation (LSB first).

Parameters

[in] p_irk Device IRK (Identity Resolving Key).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_l2cap_params_set()

uint16_t ble_gap_l2cap_params_set	(	uint16_t	max_mtu,
		uint16_t	max_mps,
		uint8_t	max_nb_lecb
	)

Set L2CAP related parameters.

Parameters

[in]	max_mtu	Maximal MTU acceptable for device, the range is 65~512.
[in]	max_mps	Maximal MPS Packet size acceptable for device (for COC SDU), the range is 65~max_mtu.
[in]	max_nb_lecb	Maximum number of LE Credit based connection that can be established, this range is 0x00~0x20. The actual number is decided by resource available.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

Note: If these parameters are not set, the stack will config the default value as (max_mtu = 512, max_mps = 512 and max_nb_lecb = 10).

◆ ble_gap_lepsm_register()

uint16_t ble_gap_lepsm_register ( gap_lepsm_register_t * p_lepsm )

Register a LE Protocol/Service Multiplexer.

Parameters

[in] p_lepsm The lepsm information to be registerred.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PSM_NUM	Invalid psm number.
SDK_ERR_INVALID_PSM_EXCEEDED_MAX_PSM_NUM	The maximum psm number limit is exceeded.
SDK_ERR_INVALID_PSM_ALREADY_REGISTERED	The psm number has been registered.

Note: This API is asynchronous. gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: GAP_OPCODE_LEPSM_REGISTER will be called.

◆ ble_gap_lepsm_unregister()

uint16_t ble_gap_lepsm_unregister ( uint16_t le_psm )

Unregister a LE Protocol/Service Multiplexer.

Parameters

[in] le_psm LE Protocol/Service Multiplexer (1 to 255).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PSM_NUM	Invalid psm number.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; app_gap_psm_manager_cb will be called once the operation has completed, gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: GAP_OPCODE_LEPSM_UNREGISTER will be called.

◆ ble_gap_pair_enable()

void ble_gap_pair_enable ( bool enable )

Decide whether to support the pair feature.

Parameters

[in] enable Support flag.

◆ ble_gap_path_compensation_set()

uint16_t ble_gap_path_compensation_set	(	int16_t	tx_path_comp,
		int16_t	rx_path_comp
	)

Set the RF path gain or loss between the RF transceiver and the antenna contributed by intermediate components.

Parameters

[in]	tx_path_comp	RF TX Path Compensation value (from -128dB to 128dB, unit is 0.1dB).
[in]	rx_path_comp	RF RX Path Compensation value (from -128dB to 128dB, unit is 0.1dB).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	The parameter is invalid.

◆ ble_gap_per_adv_list_add()

uint16_t ble_gap_per_adv_list_add ( const period_adv_list_t * p_pal_list )

Add the devices into current periodic advertising list. If periodic advertising list is full or there are duplicated entries, it will return error.

Parameters

[in] p_pal_list Pointer to input periodic advertising list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_LIST_ITEM_ALREADY_EXISTED	Item already existed in list.
SDK_ERR_LIST_FULL	List is full.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

◆ ble_gap_per_adv_list_clear()

uint16_t ble_gap_per_adv_list_clear ( void )

Clear all the entries in the current periodic advertising list.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_DISALLOWED	Operation is disallowed.

◆ ble_gap_per_adv_list_del()

uint16_t ble_gap_per_adv_list_del ( const period_adv_list_t * p_pal_list )

Delete the devices out of periodic advertising list. If the entries do not exist in the current list, an error will be returned.

Parameters

[in] p_pal_list Pointer to input periodic advertising list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_LIST_ITEM_NOT_FOUND	Item not found in list.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_PER_ADV_LIST_SET will be called once the operation has completed.

◆ ble_gap_per_adv_list_get()

uint16_t ble_gap_per_adv_list_get ( period_adv_list_t * p_pal_list )

Get the content of the whole periodic advertising list.

Parameters

[in] p_pal_list Pointer to the output periodic advertising list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_per_sync_param_set()

uint16_t ble_gap_per_sync_param_set	(	uint8_t	per_sync_idx,
		gap_per_sync_param_t *	p_per_sync_param
	)

Set the parameters used for periodic sync.

Parameters

[in]	per_sync_idx	Periodic synchronization index (range is 0 to 4).
[in]	p_per_sync_param	Periodic synchronization parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PER_SYNC_IDX	Invalid periodic syncronization index supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

◆ ble_gap_per_sync_start()

uint16_t ble_gap_per_sync_start ( uint8_t per_sync_idx )

Start to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Parameters

[in] per_sync_idx Periodic synchronization index (range is 0 to 4).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PER_SYNC_IDX	Invalid periodic syncronization index supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_sync_establish_cb will be called once the periodic advertising synchronization has been established.

◆ ble_gap_per_sync_stop()

uint16_t ble_gap_per_sync_stop ( uint8_t per_sync_idx )

Stop periodic synchronization.

Parameters

[in] per_sync_idx Periodic synchronization index (range is 0 to 4).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PER_SYNC_IDX	Invalid periodic syncronization index supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_stop_sync_cb will be called once the operation has completed.

◆ ble_gap_ppcp_get()

uint16_t ble_gap_ppcp_get ( gap_conn_param_t * p_conn_params )

Get GAP Peripheral Preferred Connection Parameters.

Parameters

[out] p_conn_params The pointer to PPCP values.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_ppcp_present_set()

void ble_gap_ppcp_present_set ( bool present_flag )

Set GAP Peripheral Preferred Connection Parameters present flag.

Parameters

[in] present_flag Present or not.

◆ ble_gap_ppcp_set()

uint16_t ble_gap_ppcp_set ( gap_conn_param_t const * p_conn_params )

Set GAP Peripheral Preferred Connection Parameters.

Parameters

[in] p_conn_params The pointer to PPCP values.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_pref_phy_set()

void ble_gap_pref_phy_set	(	uint8_t	tx_pref_phy,
		uint8_t	rx_pref_phy
	)

Set the preferred values for the transmitter PHY and receiver PHY.

Parameters

[in]	tx_pref_phy	A bit field that indicates the transmitter PHYs that the Host prefers the Controller to use(see GAP PHYs (bitmask)).
[in]	rx_pref_phy	A bit field that indicates the receiver PHYs that the Host prefers the Controller to use(see GAP PHYs (bitmask)).

◆ ble_gap_privacy_mode_set()

uint16_t ble_gap_privacy_mode_set	(	gap_bdaddr_t	peer_addr,
		privacy_mode_t	mode
	)

Set privacy mode for peer device.

Parameters

[in]	peer_addr	The peer address.
[in]	mode	Privacy mode (see privacy_mode_t).

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

◆ ble_gap_privacy_params_set()

uint16_t ble_gap_privacy_params_set	(	uint16_t	renew_dur,
		bool	enable_flag
	)

Set privacy related parameters.

Parameters

[in]	renew_dur	Duration before regenerating a device address when privacy is enabled in seconds. Range: 0x0001 (1s) ~ 0xA1B8 (11.5 hr). The suggested time is 900s(15 minutes).
[in]	enable_flag	Indicate the controller privacy is enabled or disabled.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

◆ ble_gap_reslv_rpa_addr()

uint16_t ble_gap_reslv_rpa_addr	(	uint8_t *	reslv_addr,
		uint8_t	src_info,
		reslv_rpa_addr_callback_t	cb
	)

Resolve the rpa address.

Parameters

[in]	reslv_addr	rpa address.
[in]	src_info	Information used retrieve requester (src_info >= 10).
[in]	cb	Function that will handle the resolved result.

Return values

SDK_SUCCESS	Operation is Success.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

◆ ble_gap_rpa_addr_report_cb_register()

void ble_gap_rpa_addr_report_cb_register ( rpa_addr_report_callback_t cb )

Set the cb for rpa address report.

Parameters

[in] cb the cb for rpa address report.

◆ ble_gap_rpa_list_get()

uint16_t ble_gap_rpa_list_get ( ral_dev_list_t * p_rpa_list )

Get the RPA list info.

Parameters

[in] p_rpa_list Pointer to the output RPA list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

◆ ble_gap_rslv_addr_read()

uint16_t ble_gap_rslv_addr_read	(	gap_rslv_addr_read_op_id_t	op_code,
		gap_bdaddr_t	peer_iden_addr
	)

Read peer or local resolvable address.

Parameters

[in]	op_code	The operation code (see gap_rslv_addr_read_op_id_t).
[in]	peer_iden_addr	The peer identity address.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.

◆ ble_gap_scan_param_set()

uint16_t ble_gap_scan_param_set	(	gap_own_addr_t	own_addr_type,
		gap_scan_param_t *	p_scan_param
	)

Set parameters for scanning. Note that this function must be called prior to scanning started.

Parameters

[in]	own_addr_type	Own BD address source of the local device.
[in]	p_scan_param	The scanning parameters.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is for legacy scanning (BT Core Spec version <= 4.2).

◆ ble_gap_scan_start()

uint16_t ble_gap_scan_start ( void )

Start scanning.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_adv_report_ind_cb will be called once the advertising report has been received.; gap_cb_fun_t::app_gap_scan_stop_cb will be called once the scanning has been stopped.; gap_cb_fun_t::app_gap_scan_start_cb will be called once the operation has completed.

◆ ble_gap_scan_stop()

uint16_t ble_gap_scan_stop ( void )

Stop scanning.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_DISALLOWED	Operation is disallowed.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_scan_stop_cb will be called once the operation has completed or the scanning has been stopped.

◆ ble_gap_tx_power_get()

uint16_t ble_gap_tx_power_get	(	gap_activity_role_t	role,
		uint8_t	index,
		int8_t *	txpwr_dbm
	)

Get the tx power.

Parameters

[in]	role	Select the role to Get tx power. gap_activity_role_t for possible roles.
[in]	index	The idx parameter is interpreted on role. -If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. -If role is GAP_ACTIVITY_ROLE_CON, it's the index of connection. -For all other roles, it should be ignored.
[in]	txpwr_dbm	The value of the tx power, Range: -20dbm to 7dbm.

Return values

SDK_SUCCESS	Operation is Success.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_HANDLE	Invalid handle supplied.

◆ ble_gap_tx_power_set()

uint16_t ble_gap_tx_power_set	(	gap_activity_role_t	role,
		uint8_t	index,
		int8_t	txpwr_dbm
	)

Set the tx power.

Parameters

[in]	role	Select the role to set tx power. gap_activity_role_t for possible roles.
[in]	index	The idx parameter is interpreted on role. -If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising. -If role is GAP_ACTIVITY_ROLE_CON, it's the index of connection. -For all other roles, it should be ignored.
[in]	txpwr_dbm	The value of the tx power, Range: -20dbm to 7dbm.

Return values

SDK_SUCCESS	Operation is Success.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_HANDLE	Invalid handle supplied.

◆ ble_gap_update_adv_data()

uint16_t ble_gap_update_adv_data	(	uint8_t	adv_idx,
		gap_adv_data_type_t	type,
		const uint8_t *	p_data,
		uint16_t	length
	)

Update Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM gap_ad_type_t for ADV Type definitions. See ENUM gap_adv_flags_t for ADV flag definitions.

Parameters

[in]	adv_idx	Advertising index, range is 0 to 4.
[in]	type	Data type.
[in]	p_data	The data pointer.
[in]	length	Data length.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_ADV_IDX	Invalid advertising index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already.

◆ ble_gap_update_conn_param_method_set()

uint16_t ble_gap_update_conn_param_method_set	(	uint8_t	conn_idx,
		bool	use_l2cap_flag
	)

Set the method for updating connection parameter.

Parameters

[in]	conn_idx	Connection index.
[in]	use_l2cap_flag	Preferred to use l2cap to update connection parameter.

Return values

SDK_SUCCESS	Operation is Success.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.

◆ ble_gap_whitelist_add()

uint16_t ble_gap_whitelist_add ( const white_list_t * p_whitelist )

Add the devices into current white list. If white list is full or there are duplicated entries, it will return error.

Parameters

[in] p_whitelist Pointer to input white list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_LIST_ITEM_ALREADY_EXISTED	Item already existed in list.
SDK_ERR_LIST_FULL	List is full.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

◆ ble_gap_whitelist_clear()

uint16_t ble_gap_whitelist_clear ( void )

Clear all the entries in the current white list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

◆ ble_gap_whitelist_del()

uint16_t ble_gap_whitelist_del ( const white_list_t * p_whitelist )

Delete the devices out of current white list. If the entries do not exist in the current white list, it will return error.

Parameters

[in] p_whitelist Pointer to input white list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_LIST_ITEM_NOT_FOUND	Item not found in list.
SDK_ERR_DISALLOWED	Operation is disallowed.
SDK_ERR_INVALID_PARAM	Invalid parameter supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

Note: This API is asynchronous.; gap_cb_fun_t::app_gap_param_set_cb with op_id: GAP_OPCODE_WHITELIST_SET will be called once the operation has completed.

◆ ble_gap_whitelist_get()

uint16_t ble_gap_whitelist_get ( white_list_t * p_whitelist )

Get the content of the whole white list.

Parameters

[in] p_whitelist Pointer to the output white list.

Return values

SDK_SUCCESS	Operation is successful.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.

Functions

Detailed Description

Function Documentation

◆ ble_gap_addr_get()

◆ ble_gap_addr_set()

◆ ble_gap_adv_data_set()

◆ ble_gap_adv_param_set()

◆ ble_gap_adv_start()

◆ ble_gap_adv_stop()

◆ ble_gap_appearance_get()

◆ ble_gap_appearance_set()

◆ ble_gap_bond_dev_addr_get()

◆ ble_gap_bond_dev_del()

◆ ble_gap_bond_devs_clear()

◆ ble_gap_bond_devs_get()

◆ ble_gap_chnl_map_set()

◆ ble_gap_connect()

◆ ble_gap_connect_cancel()

◆ ble_gap_data_length_set()

◆ ble_gap_dev_info_get()

◆ ble_gap_device_name_get()

◆ ble_gap_device_name_set()

◆ ble_gap_ext_adv_param_set()

◆ ble_gap_ext_connect()

◆ ble_gap_ext_scan_param_set()

◆ ble_gap_irk_set()

◆ ble_gap_l2cap_params_set()

◆ ble_gap_lepsm_register()

◆ ble_gap_lepsm_unregister()

◆ ble_gap_pair_enable()

◆ ble_gap_path_compensation_set()

◆ ble_gap_per_adv_list_add()

◆ ble_gap_per_adv_list_clear()

◆ ble_gap_per_adv_list_del()

◆ ble_gap_per_adv_list_get()

◆ ble_gap_per_sync_param_set()

◆ ble_gap_per_sync_start()

◆ ble_gap_per_sync_stop()

◆ ble_gap_ppcp_get()

◆ ble_gap_ppcp_present_set()

◆ ble_gap_ppcp_set()

◆ ble_gap_pref_phy_set()

◆ ble_gap_privacy_mode_set()

◆ ble_gap_privacy_params_set()

◆ ble_gap_reslv_rpa_addr()

◆ ble_gap_rpa_addr_report_cb_register()

◆ ble_gap_rpa_list_get()

◆ ble_gap_rslv_addr_read()

◆ ble_gap_scan_param_set()

◆ ble_gap_scan_start()

◆ ble_gap_scan_stop()

◆ ble_gap_tx_power_get()

◆ ble_gap_tx_power_set()

◆ ble_gap_update_adv_data()

◆ ble_gap_update_conn_param_method_set()

◆ ble_gap_whitelist_add()

◆ ble_gap_whitelist_clear()

◆ ble_gap_whitelist_del()

◆ ble_gap_whitelist_get()