Bluetooth Host Generic Access Profile (GAP) More...

Modules
	for checking random address validity

Classes
struct	ble_gap_sec_state

struct	ble_gap_adv_params

struct	ble_gap_conn_desc
	Connection descriptor. More...

struct	ble_gap_conn_params
	Connection parameters More...

struct	ble_gap_ext_disc_params
	Extended discovery parameters. More...

struct	ble_gap_disc_params
	Discovery parameters. More...

struct	ble_gap_upd_params
	Connection parameters update parameters. More...

struct	ble_gap_passkey_params
	Passkey query. More...

struct	ble_gap_disc_desc
	Advertising report. More...

struct	ble_gap_event

struct	ble_gap_event_listener

Macros
#define	BLE_GAP_ADV_FAST_INTERVAL1_MIN BLE_GAP_ADV_ITVL_MS(30)

#define	BLE_GAP_ADV_FAST_INTERVAL1_MAX BLE_GAP_ADV_ITVL_MS(60)

#define	BLE_GAP_ADV_FAST_INTERVAL2_MIN BLE_GAP_ADV_ITVL_MS(100)

#define	BLE_GAP_ADV_FAST_INTERVAL2_MAX BLE_GAP_ADV_ITVL_MS(150)

#define	BLE_GAP_SCAN_FAST_INTERVAL_MIN BLE_GAP_SCAN_ITVL_MS(30)

#define	BLE_GAP_SCAN_FAST_INTERVAL_MAX BLE_GAP_SCAN_ITVL_MS(60)

#define	BLE_GAP_LIM_DISC_SCAN_INT BLE_GAP_SCAN_ITVL_MS(11.25)

#define	BLE_GAP_LIM_DISC_SCAN_WINDOW BLE_GAP_SCAN_WIN_MS(11.25)

#define	BLE_GAP_SCAN_FAST_WINDOW BLE_GAP_SCAN_WIN_MS(30)

#define	BLE_GAP_SCAN_SLOW_INTERVAL1 BLE_GAP_SCAN_ITVL_MS(1280)

#define	BLE_GAP_SCAN_SLOW_WINDOW1 BLE_GAP_SCAN_WIN_MS(11.25)

#define	BLE_GAP_DISC_DUR_DFLT (10.24 * 1000)

#define	BLE_GAP_CONN_DUR_DFLT (30 * 1000)

#define	BLE_GAP_CONN_PAUSE_CENTRAL (1 * 1000)

#define	BLE_GAP_CONN_PAUSE_PERIPHERAL (5 * 1000)

#define	BLE_GAP_ADV_DFLT_CHANNEL_MAP 0x07

#define	BLE_GAP_SUBSCRIBE_REASON_WRITE 1

#define	BLE_GAP_SUBSCRIBE_REASON_TERM 2

#define	BLE_GAP_SUBSCRIBE_REASON_RESTORE 3

Functions
int	ble_gap_conn_find (uint16_t handle, struct ble_gap_conn_desc *out_desc)

int	ble_gap_conn_find_by_addr (const ble_addr_t addr, struct ble_gap_conn_desc out_desc)

int	ble_gap_set_event_cb (uint16_t conn_handle, ble_gap_event_fn cb, void cb_arg)

int	ble_gap_adv_start (uint8_t own_addr_type, const ble_addr_t direct_addr, int32_t duration_ms, const struct ble_gap_adv_params adv_params, ble_gap_event_fn cb, void cb_arg)
	Start advertising.

int	ble_gap_adv_stop (void)

int	ble_gap_adv_active (void)

int	ble_gap_adv_set_data (const uint8_t *data, int data_len)

int	ble_gap_adv_rsp_set_data (const uint8_t *data, int data_len)

int	ble_gap_adv_set_fields (const struct ble_hs_adv_fields *rsp_fields)

int	ble_gap_adv_rsp_set_fields (const struct ble_hs_adv_fields *rsp_fields)

int	ble_gap_disc (uint8_t own_addr_type, int32_t duration_ms, const struct ble_gap_disc_params disc_params, ble_gap_event_fn cb, void *cb_arg)

int	ble_gap_ext_disc (uint8_t own_addr_type, uint16_t duration, uint16_t period, uint8_t filter_duplicates, uint8_t filter_policy, uint8_t limited, const struct ble_gap_ext_disc_params uncoded_params, const struct ble_gap_ext_disc_params coded_params, ble_gap_event_fn cb, void cb_arg)

int	ble_gap_disc_cancel (void)

int	ble_gap_disc_active (void)

int	ble_gap_connect (uint8_t own_addr_type, const ble_addr_t peer_addr, int32_t duration_ms, const struct ble_gap_conn_params params, ble_gap_event_fn cb, void cb_arg)

int	ble_gap_ext_connect (uint8_t own_addr_type, const ble_addr_t peer_addr, int32_t duration_ms, uint8_t phy_mask, const struct ble_gap_conn_params phy_1m_conn_params, const struct ble_gap_conn_params phy_2m_conn_params, const struct ble_gap_conn_params phy_coded_conn_params, ble_gap_event_fn cb, void cb_arg)

int	ble_gap_conn_cancel (void)

int	ble_gap_conn_active (void)

int	ble_gap_terminate (uint16_t conn_handle, uint8_t hci_reason)

int	ble_gap_wl_set (const ble_addr_t *addrs, uint8_t white_list_count)

int	ble_gap_update_params (uint16_t conn_handle, const struct ble_gap_upd_params *params)

int	ble_gap_set_data_len (uint16_t conn_handle, uint16_t tx_octets, uint16_t tx_time)

int	ble_gap_read_sugg_def_data_len (uint16_t out_sugg_max_tx_octets, uint16_t out_sugg_max_tx_time)

int	ble_gap_write_sugg_def_data_len (uint16_t sugg_max_tx_octets, uint16_t sugg_max_tx_time)

int	ble_gap_security_initiate (uint16_t conn_handle)

int	ble_gap_pair_initiate (uint16_t conn_handle)

int	ble_gap_encryption_initiate (uint16_t conn_handle, uint8_t key_size, const uint8_t *ltk, uint16_t ediv, uint64_t rand_val, int auth)

int	ble_gap_conn_rssi (uint16_t conn_handle, int8_t *out_rssi)

int	ble_gap_unpair (const ble_addr_t *peer_addr)

int	ble_gap_unpair_oldest_peer (void)

int	ble_gap_unpair_oldest_except (const ble_addr_t *peer_addr)

int	ble_gap_set_priv_mode (const ble_addr_t *peer_addr, uint8_t priv_mode)

int	ble_gap_read_le_phy (uint16_t conn_handle, uint8_t tx_phy, uint8_t rx_phy)

int	ble_gap_set_prefered_default_le_phy (uint8_t tx_phys_mask, uint8_t rx_phys_mask)

int	ble_gap_set_prefered_le_phy (uint16_t conn_handle, uint8_t tx_phys_mask, uint8_t rx_phys_mask, uint16_t phy_opts)

int	ble_gap_event_listener_register (struct ble_gap_event_listener listener, ble_gap_event_fn fn, void *arg)

int	ble_gap_event_listener_unregister (struct ble_gap_event_listener *listener)

int	ble_gap_set_data_related_addr_change_param (uint8_t adv_handle, uint8_t change_reason)

int	ble_gap_dtm_tx_start (uint8_t tx_chan, uint8_t test_data_len, uint8_t payload)

int	ble_gap_dtm_rx_start (uint8_t rx_chan)

int	ble_gap_dtm_stop (void)

int	ble_gap_dtm_enh_tx_start (uint8_t tx_chan, uint8_t test_data_len, uint8_t payload, uint8_t phy)

int	ble_gap_dtm_enh_rx_start (uint8_t rx_chan, uint8_t index, uint8_t phy)

Detailed Description

Bluetooth Host Generic Access Profile (GAP)

Macro Definition Documentation

◆ BLE_GAP_ADV_DFLT_CHANNEL_MAP

#define BLE_GAP_ADV_DFLT_CHANNEL_MAP 0x07

Default channels mask: all three channels are used.

◆ BLE_GAP_ADV_FAST_INTERVAL1_MAX

#define BLE_GAP_ADV_FAST_INTERVAL1_MAX BLE_GAP_ADV_ITVL_MS(60)

60 ms.

◆ BLE_GAP_ADV_FAST_INTERVAL1_MIN

#define BLE_GAP_ADV_FAST_INTERVAL1_MIN BLE_GAP_ADV_ITVL_MS(30)

30 ms.

◆ BLE_GAP_ADV_FAST_INTERVAL2_MAX

#define BLE_GAP_ADV_FAST_INTERVAL2_MAX BLE_GAP_ADV_ITVL_MS(150)

150 ms.

◆ BLE_GAP_ADV_FAST_INTERVAL2_MIN

#define BLE_GAP_ADV_FAST_INTERVAL2_MIN BLE_GAP_ADV_ITVL_MS(100)

100 ms.

◆ BLE_GAP_CONN_DUR_DFLT

#define BLE_GAP_CONN_DUR_DFLT (30 * 1000)

30 seconds (not from the spec).

◆ BLE_GAP_CONN_PAUSE_CENTRAL

#define BLE_GAP_CONN_PAUSE_CENTRAL (1 * 1000)

1 second.

◆ BLE_GAP_CONN_PAUSE_PERIPHERAL

#define BLE_GAP_CONN_PAUSE_PERIPHERAL (5 * 1000)

5 seconds.

◆ BLE_GAP_DISC_DUR_DFLT

#define BLE_GAP_DISC_DUR_DFLT (10.24 * 1000)

10.24 seconds.

◆ BLE_GAP_LIM_DISC_SCAN_INT

#define BLE_GAP_LIM_DISC_SCAN_INT BLE_GAP_SCAN_ITVL_MS(11.25)

11.25 ms; limited discovery interval.

◆ BLE_GAP_LIM_DISC_SCAN_WINDOW

#define BLE_GAP_LIM_DISC_SCAN_WINDOW BLE_GAP_SCAN_WIN_MS(11.25)

11.25 ms; limited discovery window (not from the spec).

◆ BLE_GAP_SCAN_FAST_INTERVAL_MAX

#define BLE_GAP_SCAN_FAST_INTERVAL_MAX BLE_GAP_SCAN_ITVL_MS(60)

60 ms; active scanning.

◆ BLE_GAP_SCAN_FAST_INTERVAL_MIN

#define BLE_GAP_SCAN_FAST_INTERVAL_MIN BLE_GAP_SCAN_ITVL_MS(30)

30 ms; active scanning.

◆ BLE_GAP_SCAN_FAST_WINDOW

#define BLE_GAP_SCAN_FAST_WINDOW BLE_GAP_SCAN_WIN_MS(30)

30 ms; active scanning.

◆ BLE_GAP_SCAN_SLOW_INTERVAL1

#define BLE_GAP_SCAN_SLOW_INTERVAL1 BLE_GAP_SCAN_ITVL_MS(1280)

1.28 seconds; background scanning.

◆ BLE_GAP_SCAN_SLOW_WINDOW1

#define BLE_GAP_SCAN_SLOW_WINDOW1 BLE_GAP_SCAN_WIN_MS(11.25)

11.25 ms; background scanning.

◆ BLE_GAP_SUBSCRIBE_REASON_RESTORE

#define BLE_GAP_SUBSCRIBE_REASON_RESTORE 3

Peer's CCCD subscription state changed due to restore from persistence (bonding restored).

◆ BLE_GAP_SUBSCRIBE_REASON_TERM

#define BLE_GAP_SUBSCRIBE_REASON_TERM 2

Peer's CCCD subscription state cleared due to connection termination.

◆ BLE_GAP_SUBSCRIBE_REASON_WRITE

#define BLE_GAP_SUBSCRIBE_REASON_WRITE 1

Peer's CCCD subscription state changed due to a descriptor write.

Function Documentation

◆ ble_gap_adv_active()

int ble_gap_adv_active ( void )

Indicates whether an advertisement procedure is currently in progress.

Returns: 0 if no advertisement procedure in progress, 1 otherwise.

◆ ble_gap_adv_rsp_set_data()

int ble_gap_adv_rsp_set_data	(	const uint8_t *	data,
		int	data_len
	)

Configures the data to include in subsequent scan responses.

Parameters

data	Buffer containing the scan response data.
data_len	The size of the response data, in bytes.

Returns: 0 on succes, BLE_HS_EBUSY if advertising is in progress, other error code on failure.

◆ ble_gap_adv_rsp_set_fields()

int ble_gap_adv_rsp_set_fields ( const struct ble_hs_adv_fields * rsp_fields )

Configures the fields to include in subsequent scan responses. This is a convenience wrapper for ble_gap_adv_rsp_set_data().

Parameters

adv_fields Specifies the scan response data.

Returns: 0 on success, BLE_HS_EBUSY if advertising is in progress, BLE_HS_EMSGSIZE if the specified data is too large to fit in a scan response, other error code on failure.

◆ ble_gap_adv_set_data()

int ble_gap_adv_set_data	(	const uint8_t *	data,
		int	data_len
	)

Configures the data to include in subsequent advertisements.

Parameters

data	Buffer containing the advertising data.
data_len	The size of the advertising data, in bytes.

Returns: 0 on succes, BLE_HS_EBUSY if advertising is in progress, other error code on failure.

◆ ble_gap_adv_set_fields()

int ble_gap_adv_set_fields ( const struct ble_hs_adv_fields * rsp_fields )

Configures the fields to include in subsequent advertisements. This is a convenience wrapper for ble_gap_adv_set_data().

Parameters

adv_fields Specifies the advertisement data.

Returns: 0 on success, BLE_HS_EBUSY if advertising is in progress, BLE_HS_EMSGSIZE if the specified data is too large to fit in an advertisement, other error code on failure.

◆ ble_gap_adv_start()

int ble_gap_adv_start	(	uint8_t	own_addr_type,
		const ble_addr_t *	direct_addr,
		int32_t	duration_ms,
		const struct ble_gap_adv_params *	adv_params,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Start advertising.

This function configures and start advertising procedure.

Parameters

own_addr_type	The type of address the stack should use for itself. Valid values are: BLE_OWN_ADDR_PUBLIC BLE_OWN_ADDR_RANDOM BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT BLE_OWN_ADDR_RPA_RANDOM_DEFAULT
direct_addr	The peer's address for directed advertising. This parameter shall be non-NULL if directed advertising is being used.
duration_ms	The duration of the advertisement procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration.
adv_params	Additional arguments specifying the particulars of the advertising procedure.
cb	The callback to associate with this advertising procedure. If advertising ends, the event is reported through this callback. If advertising results in a connection, the connection inherits this callback as its event-reporting mechanism.
cb_arg	The optional argument to pass to the callback function.

Returns: 0 on success, error code on failure.

◆ ble_gap_adv_stop()

int ble_gap_adv_stop ( void )

Stops the currently-active advertising procedure. A success return code indicates that advertising has been fully aborted and a new advertising procedure can be initiated immediately.

NOTE: If the caller is running in the same task as the NimBLE host, or if it is running in a higher priority task than that of the host, care must be taken when restarting advertising. Under these conditions, the following is not a reliable method to restart advertising: ble_gap_adv_stop() ble_gap_adv_start()

Instead, the call to ble_gap_adv_start() must be made in a separate event context. That is, ble_gap_adv_start() must be called asynchronously by enqueueing an event on the current task's event queue. See https://github.com/apache/mynewt-nimble/pull/211 for more information.

Returns: 0 on success, BLE_HS_EALREADY if there is no active advertising procedure, other error code on failure.

◆ ble_gap_conn_active()

int ble_gap_conn_active ( void )

Indicates whether a connect procedure is currently in progress.

Returns: 0: No connect procedure in progress; 1: Connect procedure in progress.

◆ ble_gap_conn_cancel()

int ble_gap_conn_cancel ( void )

Aborts a connect procedure in progress.

Returns: 0 on success; BLE_HS_EALREADY if there is no active connect procedure. Other nonzero on error.

◆ ble_gap_conn_find()

int ble_gap_conn_find	(	uint16_t	handle,
		struct ble_gap_conn_desc *	out_desc
	)

Searches for a connection with the specified handle. If a matching connection is found, the supplied connection descriptor is filled correspondingly.

Parameters

handle	The connection handle to search for.
out_desc	On success, this is populated with information relating to the matching connection. Pass NULL if you don't need this information.

Returns: 0 on success, BLE_HS_ENOTCONN if no matching connection was found.

◆ ble_gap_conn_find_by_addr()

int ble_gap_conn_find_by_addr	(	const ble_addr_t *	addr,
		struct ble_gap_conn_desc *	out_desc
	)

Searches for a connection with a peer with the specified address. If a matching connection is found, the supplied connection descriptor is filled correspondingly.

Parameters

addr	The ble address of a connected peer device to search for.
out_desc	On success, this is populated with information relating to the matching connection. Pass NULL if you don't need this information.

Returns: 0 on success, BLE_HS_ENOTCONN if no matching connection was found.

◆ ble_gap_conn_rssi()

int ble_gap_conn_rssi	(	uint16_t	conn_handle,
		int8_t *	out_rssi
	)

Retrieves the most-recently measured RSSI for the specified connection. A connection's RSSI is updated whenever a data channel PDU is received.

Parameters

conn_handle	Specifies the connection to query.
out_rssi	On success, the retrieved RSSI is written here.

Returns: 0 on success; A BLE host HCI return code if the controller rejected the request; A BLE host core return code on unexpected error.

◆ ble_gap_connect()

int ble_gap_connect	(	uint8_t	own_addr_type,
		const ble_addr_t *	peer_addr,
		int32_t	duration_ms,
		const struct ble_gap_conn_params *	params,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Initiates a connect procedure.

Parameters

own_addr_type	The type of address the stack should use for itself during connection establishment. BLE_OWN_ADDR_PUBLIC BLE_OWN_ADDR_RANDOM BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT BLE_OWN_ADDR_RPA_RANDOM_DEFAULT
peer_addr	The address of the peer to connect to. If this parameter is NULL, the white list is used.
duration_ms	The duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds.
conn_params	Additional arguments specifying the particulars of the connect procedure. Specify null for default values.
cb	The callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism.
cb_arg	The optional argument to pass to the callback function.

Returns: 0 on success; BLE_HS_EALREADY if a connection attempt is already in progress; BLE_HS_EBUSY if initiating a connection is not possible because scanning is in progress; BLE_HS_EDONE if the specified peer is already connected; Other nonzero on error.

◆ ble_gap_disc()

int ble_gap_disc	(	uint8_t	own_addr_type,
		int32_t	duration_ms,
		const struct ble_gap_disc_params *	disc_params,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Performs the Limited or General Discovery Procedures.

Parameters

own_addr_type	The type of address the stack should use for itself when sending scan requests. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM BLE_ADDR_TYPE_RPA_PUB_DEFAULT BLE_ADDR_TYPE_RPA_RND_DEFAULT This parameter is ignored unless active scanning is being used.
duration_ms	The duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration. Specify 0 to use stack defaults.
disc_params	Additional arguments specifying the particulars of the discovery procedure.
cb	The callback to associate with this discovery procedure. Advertising reports and discovery termination events are reported through this callback.
cb_arg	The optional argument to pass to the callback function.

Returns: 0 on success; nonzero on failure.

◆ ble_gap_disc_active()

int ble_gap_disc_active ( void )

Indicates whether a discovery procedure is currently in progress.

Returns: 0: No discovery procedure in progress; 1: Discovery procedure in progress.

◆ ble_gap_disc_cancel()

int ble_gap_disc_cancel ( void )

Cancels the discovery procedure currently in progress. A success return code indicates that scanning has been fully aborted; a new discovery or connect procedure can be initiated immediately.

Returns: 0 on success; BLE_HS_EALREADY if there is no discovery procedure to cancel; Other nonzero on unexpected error.

◆ ble_gap_dtm_enh_rx_start()

int ble_gap_dtm_enh_rx_start	(	uint8_t	rx_chan,
		uint8_t	index,
		uint8_t	phy
	)

Start a test where the DUT receives test reference packets at fixed interval

Parameters

rx_chan	Channel for test data reception, rx_channel = (Frequency -2402)/2, tx_channel range = 0x00-0x27, Frequency range: 2402 MHz to 2480 MHz
index	modulation index, 0x00:standard modulation index, 0x01:stable modulation index
phy	Phy type used by the receiver, 1M phy: 0x01, 2M phy:0x02, coded phy:0x03

Returns: 0 on success; nonzero on failure

◆ ble_gap_dtm_enh_tx_start()

int ble_gap_dtm_enh_tx_start	(	uint8_t	tx_chan,
		uint8_t	test_data_len,
		uint8_t	payload,
		uint8_t	phy
	)

Start a test where the DUT generates reference packets at a fixed interval.

Parameters

tx_chan	Channel for sending test data, tx_channel = (Frequency -2402)/2, tx_channel range = 0x00-0x27, Frequency range: 2402 MHz to 2480 MHz
test_data_len	Length in bytes of payload data in each packet
payload	Packet payload type. Valid range: 0x00 - 0x07
phy	Phy used by transmitter 1M phy: 0x01, 2M phy:0x02, coded phy:0x03.

Returns: 0 on sucess; nonzero on failure

◆ ble_gap_dtm_rx_start()

int ble_gap_dtm_rx_start ( uint8_t rx_chan )

Start a test where the DUT receives test reference packets at a fixed interval.

Parameters

rx_chan Channel for test data reception, rx_channel = (Frequency -2402)/2, tx_channel range = 0x00-0x27, Frequency range = 2402 MHz to 2480 MHz.

Returns: 0 on success; nonzero on failure

◆ ble_gap_dtm_stop()

int ble_gap_dtm_stop ( void )

Stop any test which is in progress

Returns: 0 on success; nonzero on failure

◆ ble_gap_dtm_tx_start()

int ble_gap_dtm_tx_start	(	uint8_t	tx_chan,
		uint8_t	test_data_len,
		uint8_t	payload
	)

Start a test where the DUT generates reference packets at a fixed interval.

Parameters

tx_chan	Channel for sending test data, tx_channel = (Frequency -2402)/2, tx_channel range = 0x00-0x27, Frequency range = 2402 MHz to 2480 MHz.
test_data_len	Length in bytes of payload data in each packet
payload	Packet Payload type. Valid range: 0x00 - 0x07

Returns: 0 on success; nonzero on failure

◆ ble_gap_encryption_initiate()

int ble_gap_encryption_initiate	(	uint16_t	conn_handle,
		uint8_t	key_size,
		const uint8_t *	ltk,
		uint16_t	ediv,
		uint64_t	rand_val,
		int	auth
	)

Initiates the GAP encryption procedure as a master. This is for testing only and should not be used by application. Use ble_gap_security_initiate() instead.

Parameters

conn_handle	The handle corresponding to the connection to start encryption.
key_size	Encryption key size
ltk	Long Term Key to be used for encryption.
udiv	Encryption Diversifier for LTK
rand_val	Random Value for EDIV and LTK
auth	If LTK provided is authenticated.

Returns: 0 on success; BLE_HS_ENOTCONN if the there is no connection with the specified handle; BLE_HS_EALREADY if an encryption procedure for this connection is already in progress; Other nonzero on error.

◆ ble_gap_event_listener_register()

int ble_gap_event_listener_register	(	struct ble_gap_event_listener *	listener,
		ble_gap_event_fn *	fn,
		void *	arg
	)

Registers listener for GAP events

On success listener structure will be initialized automatically and does not need to be initialized prior to calling this function. To change callback and/or argument unregister listener first and register it again.

Parameters

listener	Listener structure
fn	Callback function
arg	Callback argument

Returns: 0 on success BLE_HS_EINVAL if no callback is specified BLE_HS_EALREADY if listener is already registered

◆ ble_gap_event_listener_unregister()

int ble_gap_event_listener_unregister ( struct ble_gap_event_listener * listener )

Unregisters listener for GAP events

Parameters

listener Listener structure

Returns: 0 on success BLE_HS_ENOENT if listener was not registered

◆ ble_gap_ext_connect()

int ble_gap_ext_connect	(	uint8_t	own_addr_type,
		const ble_addr_t *	peer_addr,
		int32_t	duration_ms,
		uint8_t	phy_mask,
		const struct ble_gap_conn_params *	phy_1m_conn_params,
		const struct ble_gap_conn_params *	phy_2m_conn_params,
		const struct ble_gap_conn_params *	phy_coded_conn_params,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Initiates an extended connect procedure.

Parameters

own_addr_type	The type of address the stack should use for itself during connection establishment. BLE_OWN_ADDR_PUBLIC BLE_OWN_ADDR_RANDOM BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT BLE_OWN_ADDR_RPA_RANDOM_DEFAULT
peer_addr	The address of the peer to connect to. If this parameter is NULL, the white list is used.
duration_ms	The duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds.
phy_mask	Define on which PHYs connection attempt should be done
phy_1m_conn_params	Additional arguments specifying the particulars of the connect procedure. When BLE_GAP_LE_PHY_1M_MASK is set in phy_mask this parameter can be specify to null for default values.
phy_2m_conn_params	Additional arguments specifying the particulars of the connect procedure. When BLE_GAP_LE_PHY_2M_MASK is set in phy_mask this parameter can be specify to null for default values.
phy_coded_conn_params	Additional arguments specifying the particulars of the connect procedure. When BLE_GAP_LE_PHY_CODED_MASK is set in phy_mask this parameter can be specify to null for default values.
cb	The callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism.
cb_arg	The optional argument to pass to the callback function.

Returns: 0 on success; BLE_HS_EALREADY if a connection attempt is already in progress; BLE_HS_EBUSY if initiating a connection is not possible because scanning is in progress; BLE_HS_EDONE if the specified peer is already connected; Other nonzero on error.

◆ ble_gap_ext_disc()

int ble_gap_ext_disc	(	uint8_t	own_addr_type,
		uint16_t	duration,
		uint16_t	period,
		uint8_t	filter_duplicates,
		uint8_t	filter_policy,
		uint8_t	limited,
		const struct ble_gap_ext_disc_params *	uncoded_params,
		const struct ble_gap_ext_disc_params *	coded_params,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Performs the Limited or General Extended Discovery Procedures.

Parameters

own_addr_type	The type of address the stack should use for itself when sending scan requests. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM BLE_ADDR_TYPE_RPA_PUB_DEFAULT BLE_ADDR_TYPE_RPA_RND_DEFAULT This parameter is ignored unless active scanning is being used.
duration	The duration of the discovery procedure. On expiration, if period is set to 0, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are 10 milliseconds. Specify 0 for no expiration.
period	Time interval from when the Controller started its last Scan Duration until it begins the subsequent Scan Duration. Specify 0 to scan continuously. Units are 1.28 second.
filter_duplicates	Set to enable packet filtering in the controller
filter_policy	Set the used filter policy. Valid values are: BLE_HCI_SCAN_FILT_NO_WL BLE_HCI_SCAN_FILT_USE_WL BLE_HCI_SCAN_FILT_NO_WL_INITA BLE_HCI_SCAN_FILT_USE_WL_INITA BLE_HCI_SCAN_FILT_MAX This parameter is ignored unless `filter_duplicates` is set.
limited	If limited discovery procedure should be used.
uncoded_params	Additional arguments specifying the particulars of the discovery procedure for uncoded PHY. If NULL is provided no scan is performed for this PHY.
coded_params	Additional arguments specifying the particulars of the discovery procedure for coded PHY. If NULL is provided no scan is performed for this PHY.
cb	The callback to associate with this discovery procedure. Advertising reports and discovery termination events are reported through this callback.
cb_arg	The optional argument to pass to the callback function.

Returns: 0 on success; nonzero on failure.

◆ ble_gap_pair_initiate()

int ble_gap_pair_initiate ( uint16_t conn_handle )

Initiates the GAP pairing procedure as a master. This is for testing only and should not be used by application. Use ble_gap_security_initiate() instead.

Parameters

conn_handle The handle corresponding to the connection to start pairing on.

Returns: 0 on success; BLE_HS_ENOTCONN if the there is no connection with the specified handle; BLE_HS_EALREADY if an pairing procedure for this connection is already in progress; Other nonzero on error.

◆ ble_gap_read_le_phy()

int ble_gap_read_le_phy	(	uint16_t	conn_handle,
		uint8_t *	tx_phy,
		uint8_t *	rx_phy
	)

Read PHYs used for specified connection.

On success output parameters are filled with information about used PHY type.

Parameters

conn_handle	Connection handle
tx_phy	TX PHY used. Can be one of following constants: BLE_GAP_LE_PHY_1M BLE_GAP_LE_PHY_2M BLE_GAP_LE_PHY_CODED
rx_phy	RX PHY used. Can be one of following constants: BLE_GAP_LE_PHY_1M BLE_GAP_LE_PHY_2M BLE_GAP_LE_PHY_CODED

Returns: 0 on success; nonzero on failure.

◆ ble_gap_read_sugg_def_data_len()

int ble_gap_read_sugg_def_data_len	(	uint16_t *	out_sugg_max_tx_octets,
		uint16_t *	out_sugg_max_tx_time
	)

Read LE Suggested Default Data Length in controller (OGF = 0x08, OCF = 0x0024).

Parameters

out_sugg_max_tx_octets	The Host's suggested value for the Controller's maximum transmitted number of payload octets in LL Data PDUs to be used for new connections. (Range 0x001B-0x00FB).
out_sugg_max_tx_time	The Host's suggested value for the Controller's maximum packet transmission time for packets containing LL Data PDUs to be used for new connections. (Range 0x0148-0x4290).

Returns: 0 on success, other error code on failure.

◆ ble_gap_security_initiate()

int ble_gap_security_initiate ( uint16_t conn_handle )

Initiates the GAP security procedure.

Depending on connection role and stored security information this function will start appropriate security procedure (pairing or encryption).

Parameters

conn_handle The handle corresponding to the connection to secure.

Returns: 0 on success; BLE_HS_ENOTCONN if the there is no connection with the specified handle; BLE_HS_EALREADY if an security procedure for this connection is already in progress; Other nonzero on error.

◆ ble_gap_set_data_len()

int ble_gap_set_data_len	(	uint16_t	conn_handle,
		uint16_t	tx_octets,
		uint16_t	tx_time
	)

Configure LE Data Length in controller (OGF = 0x08, OCF = 0x0022).

Parameters

conn_handle	Connection handle.
tx_octets	The preferred value of payload octets that the Controller should use for a new connection (Range 0x001B-0x00FB).
tx_time	The preferred maximum number of microseconds that the local Controller should use to transmit a single link layer packet (Range 0x0148-0x4290).

Returns: 0 on success, other error code on failure.

◆ ble_gap_set_data_related_addr_change_param()

int ble_gap_set_data_related_addr_change_param	(	uint8_t	adv_handle,
		uint8_t	change_reason
	)

Set Data Related Address Changes Param

Parameters

adv_handle	Advertising handle
change_reason	Reasons for refreshing addresses

Returns: 0 on success; nonzero on failure.

◆ ble_gap_set_event_cb()

int ble_gap_set_event_cb	(	uint16_t	conn_handle,
		ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Configures a connection to use the specified GAP event callback. A connection's GAP event callback is first specified when the connection is created, either via advertising or initiation. This function replaces the callback that was last configured.

Parameters

conn_handle	The handle of the connection to configure.
cb	The callback to associate with the connection.
cb_arg	An optional argument that the callback receives.

Returns: 0 on success, BLE_HS_ENOTCONN if there is no connection with the specified handle.

◆ ble_gap_set_prefered_default_le_phy()

int ble_gap_set_prefered_default_le_phy	(	uint8_t	tx_phys_mask,
		uint8_t	rx_phys_mask
	)

Set preferred default PHYs to be used for connections.

@params tx_phys_mask Preferred TX PHY. Can be mask of following constants:

BLE_GAP_LE_PHY_1M_MASK
BLE_GAP_LE_PHY_2M_MASK
BLE_GAP_LE_PHY_CODED_MASK
BLE_GAP_LE_PHY_ANY_MASK @params rx_phys_mask Preferred RX PHY. Can be mask of following constants:
BLE_GAP_LE_PHY_1M_MASK
BLE_GAP_LE_PHY_2M_MASK
BLE_GAP_LE_PHY_CODED_MASK
BLE_GAP_LE_PHY_ANY_MASK

Returns: 0 on success; nonzero on failure.

◆ ble_gap_set_prefered_le_phy()

int ble_gap_set_prefered_le_phy	(	uint16_t	conn_handle,
		uint8_t	tx_phys_mask,
		uint8_t	rx_phys_mask,
		uint16_t	phy_opts
	)

Set preferred PHYs to be used for connection.

Parameters

conn_handle	Connection handle @params tx_phys_mask Preferred TX PHY. Can be mask of following constants: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK @params rx_phys_mask Preferred RX PHY. Can be mask of following constants: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
phy_opts	Additional PHY options. Valid values are: BLE_GAP_LE_PHY_CODED_ANY BLE_GAP_LE_PHY_CODED_S2 BLE_GAP_LE_PHY_CODED_S8

Returns: 0 on success; nonzero on failure.

◆ ble_gap_set_priv_mode()

int ble_gap_set_priv_mode	(	const ble_addr_t *	peer_addr,
		uint8_t	priv_mode
	)

Set privacy mode for specified peer device

Parameters

peer_addr	Peer device address
priv_mode	Privacy mode to be used. Can be one of following constants: BLE_GAP_PRIVATE_MODE_NETWORK BLE_GAP_PRIVATE_MODE_DEVICE

Returns: 0 on success; nonzero on failure.

◆ ble_gap_terminate()

int ble_gap_terminate	(	uint16_t	conn_handle,
		uint8_t	hci_reason
	)

Terminates an established connection.

Parameters

conn_handle	The handle corresponding to the connection to terminate.
hci_reason	The HCI error code to indicate as the reason for termination.

Returns: 0 on success; BLE_HS_ENOTCONN if there is no connection with the specified handle; Other nonzero on failure.

◆ ble_gap_unpair()

int ble_gap_unpair ( const ble_addr_t * peer_addr )

Unpairs a device with the specified address. The keys related to that peer device are removed from storage and peer address is removed from the resolve list from the controller. If a peer is connected, the connection is terminated.

Parameters

peer_addr Address of the device to be unpaired

Returns: 0 on success; A BLE host HCI return code if the controller rejected the request; A BLE host core return code on unexpected error.

◆ ble_gap_unpair_oldest_except()

int ble_gap_unpair_oldest_except ( const ble_addr_t * peer_addr )

Similar to ble_gap_unpair_oldest_peer(), except it makes sure that the peer received in input parameters is not deleted.

Parameters

peer_addr Address of the peer (not to be deleted)

Returns: 0 on success; A BLE host HCI return code if the controller rejected the request; A BLE host core return code on unexpected error.

◆ ble_gap_unpair_oldest_peer()

int ble_gap_unpair_oldest_peer ( void )

Unpairs the oldest bonded peer device. The keys related to that peer device are removed from storage and peer address is removed from the resolve list from the controller. If a peer is connected, the connection is terminated.

Returns: 0 on success; A BLE host HCI return code if the controller rejected the request; A BLE host core return code on unexpected error.

◆ ble_gap_update_params()

int ble_gap_update_params	(	uint16_t	conn_handle,
		const struct ble_gap_upd_params *	params
	)

Initiates a connection parameter update procedure.

Parameters

conn_handle	The handle corresponding to the connection to update.
params	The connection parameters to attempt to update to.

Returns: 0 on success; BLE_HS_ENOTCONN if the there is no connection with the specified handle; BLE_HS_EALREADY if a connection update procedure for this connection is already in progress; BLE_HS_EINVAL if requested parameters are invalid; Other nonzero on error.

◆ ble_gap_wl_set()

int ble_gap_wl_set	(	const ble_addr_t *	addrs,
		uint8_t	white_list_count
	)

Overwrites the controller's white list with the specified contents.

Parameters

addrs	The entries to write to the white list.
white_list_count	The number of entries in the white list.

Returns: 0 on success; nonzero on failure.

◆ ble_gap_write_sugg_def_data_len()

int ble_gap_write_sugg_def_data_len	(	uint16_t	sugg_max_tx_octets,
		uint16_t	sugg_max_tx_time
	)

Configure LE Suggested Default Data Length in controller (OGF = 0x08, OCF = 0x0024).

Parameters

sugg_max_tx_octets	The Host's suggested value for the Controller's maximum transmitted number of payload octets in LL Data PDUs to be used for new connections. (Range 0x001B-0x00FB).
sugg_max_tx_time	The Host's suggested value for the Controller's maximum packet transmission time for packets containing LL Data PDUs to be used for new connections. (Range 0x0148-0x4290).

Returns: 0 on success, other error code on failure.

Modules

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BLE_GAP_ADV_DFLT_CHANNEL_MAP

◆ BLE_GAP_ADV_FAST_INTERVAL1_MAX

◆ BLE_GAP_ADV_FAST_INTERVAL1_MIN

◆ BLE_GAP_ADV_FAST_INTERVAL2_MAX

◆ BLE_GAP_ADV_FAST_INTERVAL2_MIN

◆ BLE_GAP_CONN_DUR_DFLT

◆ BLE_GAP_CONN_PAUSE_CENTRAL

◆ BLE_GAP_CONN_PAUSE_PERIPHERAL

◆ BLE_GAP_DISC_DUR_DFLT

◆ BLE_GAP_LIM_DISC_SCAN_INT

◆ BLE_GAP_LIM_DISC_SCAN_WINDOW

◆ BLE_GAP_SCAN_FAST_INTERVAL_MAX

◆ BLE_GAP_SCAN_FAST_INTERVAL_MIN

◆ BLE_GAP_SCAN_FAST_WINDOW

◆ BLE_GAP_SCAN_SLOW_INTERVAL1

◆ BLE_GAP_SCAN_SLOW_WINDOW1

◆ BLE_GAP_SUBSCRIBE_REASON_RESTORE

◆ BLE_GAP_SUBSCRIBE_REASON_TERM

◆ BLE_GAP_SUBSCRIBE_REASON_WRITE

Function Documentation

◆ ble_gap_adv_active()

◆ ble_gap_adv_rsp_set_data()

◆ ble_gap_adv_rsp_set_fields()

◆ ble_gap_adv_set_data()

◆ ble_gap_adv_set_fields()

◆ ble_gap_adv_start()

◆ ble_gap_adv_stop()

◆ ble_gap_conn_active()

◆ ble_gap_conn_cancel()

◆ ble_gap_conn_find()

◆ ble_gap_conn_find_by_addr()

◆ ble_gap_conn_rssi()

◆ ble_gap_connect()

◆ ble_gap_disc()

◆ ble_gap_disc_active()

◆ ble_gap_disc_cancel()

◆ ble_gap_dtm_enh_rx_start()

◆ ble_gap_dtm_enh_tx_start()

◆ ble_gap_dtm_rx_start()

◆ ble_gap_dtm_stop()

◆ ble_gap_dtm_tx_start()

◆ ble_gap_encryption_initiate()

◆ ble_gap_event_listener_register()

◆ ble_gap_event_listener_unregister()

◆ ble_gap_ext_connect()

◆ ble_gap_ext_disc()

◆ ble_gap_pair_initiate()

◆ ble_gap_read_le_phy()

◆ ble_gap_read_sugg_def_data_len()

◆ ble_gap_security_initiate()

◆ ble_gap_set_data_len()

◆ ble_gap_set_data_related_addr_change_param()

◆ ble_gap_set_event_cb()

◆ ble_gap_set_prefered_default_le_phy()

◆ ble_gap_set_prefered_le_phy()

◆ ble_gap_set_priv_mode()

◆ ble_gap_terminate()

◆ ble_gap_unpair()

◆ ble_gap_unpair_oldest_except()

◆ ble_gap_unpair_oldest_peer()

◆ ble_gap_update_params()

◆ ble_gap_wl_set()

◆ ble_gap_write_sugg_def_data_len()