NimBLE Host GAP Reference¶

Introduction¶

The Generic Access Profile (GAP) is responsible for all connecting, advertising, scanning, and connection updating operations.

API¶

typedef int ble_gap_event_fn(struct ble_gap_event *event, void *arg)¶: Callback function type for handling BLE GAP events.

typedef int ble_gap_conn_foreach_handle_fn(uint16_t conn_handle, void *arg)¶: Callback function type for iterating through BLE connection handles.

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.

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.

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.

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.

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.

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.

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.

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.

int ble_gap_adv_set_fields(const struct ble_hs_adv_fields *adv_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.

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:

rsp_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.

int ble_gap_ext_adv_configure(uint8_t instance, const struct ble_gap_ext_adv_params *params, int8_t *selected_tx_power, ble_gap_event_fn *cb, void *cb_arg)¶

Configure extended advertising instance.

Parameters:

instance – Instance ID
params – Additional arguments specifying the particulars of the advertising.
selected_tx_power – Selected advertising transmit power will be stored in that param if non-NULL.
cb – The callback to associate with this advertising procedure. Advertising complete event is reported through this callback
cb_arg – The optional argument to pass to the callback function.

Returns:

0 on success; nonzero on failure.

int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr)¶

Set random address for configured advertising instance.

Parameters:

instance – Instance ID
addr – Random address to be set

Returns:

0 on success; nonzero on failure.

int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events)¶

Start advertising instance.

Parameters:

instance – Instance ID
duration – The duration of the advertisement procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are 10 milliseconds. Specify 0 for no expiration. @params max_events Number of advertising events that should be sent before advertising ends and a BLE_GAP_EVENT_ADV_COMPLETE event is reported. Specify 0 for no limit.

Returns:

0 on success, error code on failure.

int ble_gap_ext_adv_stop(uint8_t instance)¶

Stops advertising procedure for specified instance.

Parameters:

instance – Instance ID

Returns:

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

int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data)¶

Configures the data to include in advertisements packets for specified advertising instance.

Parameters:

instance – Instance ID
data – Chain containing the advertising data.

Returns:

0 on success or error code on failure.

int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data)¶

Configures the data to include in subsequent scan responses for specified advertisign instance.

Parameters:

instance – Instance ID
data – Chain containing the scan response data.

Returns:

0 on success or error code on failure.

int ble_gap_ext_adv_remove(uint8_t instance)¶

Remove existing advertising instance.

Parameters:

instance – Instance ID

Returns:

0 on success, BLE_HS_EBUSY if advertising is in progress, other error code on failure.

int ble_gap_ext_adv_clear(void)¶

Clear all existing advertising instances.

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

int ble_gap_ext_adv_active(uint8_t instance)¶

Indicates whether an advertisement procedure is currently in progress on the specified Instance.

Parameters:

instance – Instance Id

Returns:

0 if there is no active advertising procedure for the instance, 1 otherwise

int ble_gap_adv_get_free_instance(uint8_t *out_adv_instance)¶

Finds first not configured advertising instance.

Parameters:

out_adv_instance – [out] Pointer to be filled with found advertising instance

Returns:

0 if free advertising instance was found, error code otherwise

int ble_gap_periodic_adv_configure(uint8_t instance, const struct ble_gap_periodic_adv_params *params)¶

Configure periodic advertising for specified advertising instance.

This is allowed only for instances configured as non-announymous, non-connectable and non-scannable.

Parameters:

instance – Instance ID
params – Additional arguments specifying the particulars of periodic advertising.

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_start(uint8_t instance, const struct ble_gap_periodic_adv_start_params *params)¶

Start periodic advertising for specified advertising instance.

Parameters:

instance – Instance ID
params – Additional arguments specifying the particulars of periodic advertising.

Returns:

0 on success, error code on failure.

int ble_gap_periodic_adv_stop(uint8_t instance)¶

Stop periodic advertising for specified advertising instance.

Parameters:

instance – Instance ID

Returns:

0 on success, error code on failure.

int ble_gap_periodic_adv_set_data(uint8_t instance, struct os_mbuf *data, const struct ble_gap_periodic_adv_set_data_params *params)¶

Configures the data to include in periodic advertisements for specified advertising instance.

Parameters:

instance – Instance ID
data – Chain containing the periodic advertising data.
params – Additional arguments specifying the particulars of periodic advertising data.

Returns:

0 on success or error code on failure.

int ble_gap_periodic_adv_sync_create(const ble_addr_t *addr, uint8_t adv_sid, const struct ble_gap_periodic_sync_params *params, ble_gap_event_fn *cb, void *cb_arg)¶

Performs the Synchronization procedure with periodic advertiser.

Parameters:

addr – Peer address to synchronize with. If NULL than peers from periodic list are used.
adv_sid – Advertiser Set ID
params – Additional arguments specifying the particulars of the synchronization procedure.
cb – The callback to associate with this synchrnization procedure. BLE_GAP_EVENT_PERIODIC_REPORT events are reported only by this callback.
cb_arg – The optional argument to pass to the callback function.

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_create_cancel(void)¶

Cancel pending synchronization procedure.

Returns:: 0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_terminate(uint16_t sync_handle)¶

Terminate synchronization procedure.

Parameters:

sync_handle – Handle identifying synchronization to terminate.

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_reporting(uint16_t sync_handle, bool enable, const struct ble_gap_periodic_adv_sync_reporting_params *params)¶

Disable or enable periodic reports for specified sync.

Parameters:

sync_handle – Handle identifying synchronization.
enable – If reports should be enabled.
params – Additional arguments specifying the particulars of periodic reports.

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_transfer(uint16_t sync_handle, uint16_t conn_handle, uint16_t service_data)¶

Initialize sync transfer procedure for specified handles.

This allows to transfer periodic sync to which host is synchronized.

Parameters:

sync_handle – Handle identifying synchronization.
conn_handle – Handle identifying connection.
service_data – Sync transfer service data

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_set_info(uint8_t instance, uint16_t conn_handle, uint16_t service_data)¶

Initialize set info transfer procedure for specified handles.

This allows to transfer periodic sync which is being advertised by host.

Parameters:

instance – Advertising instance with periodic adv enabled.
conn_handle – Handle identifying connection.
service_data – Sync transfer service data

Returns:

0 on success; nonzero on failure.

int periodic_adv_set_default_sync_params(const struct ble_gap_periodic_sync_params *params)¶

Set the default periodic sync transfer params.

Parameters:

conn_handle – Handle identifying connection.
params – Default Parameters for periodic sync transfer.

Returns:

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_receive(uint16_t conn_handle, const struct ble_gap_periodic_sync_params *params, ble_gap_event_fn *cb, void *cb_arg)¶

Enables or disables sync transfer reception on specified connection.

When sync transfer arrives, BLE_GAP_EVENT_PERIODIC_TRANSFER is sent to the user. After that, sync transfer reception on that connection is terminated and user needs to call this API again when expect to receive next sync transfers.

Note: If ACL connection gets disconnected before sync transfer arrived, user will not receive BLE_GAP_EVENT_PERIODIC_TRANSFER. Instead, sync transfer reception is terminated by the host automatically.

Parameters:

conn_handle – Handle identifying connection.
params – Parameters for enabled sync transfer reception. Specify NULL to disable reception.
cb – The callback to associate with this synchronization procedure. BLE_GAP_EVENT_PERIODIC_REPORT events are reported only by this callback.
cb_arg – The optional argument to pass to the callback function.

Returns:

0 on success; nonzero on failure.

int ble_gap_add_dev_to_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid)¶

Add peer device to periodic synchronization list.

Parameters:

addr – Peer address to add to list.
adv_sid – Advertiser Set ID

Returns:

0 on success; nonzero on failure.

int ble_gap_rem_dev_from_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid)¶

Remove peer device from periodic synchronization list.

Parameters:

addr – Peer address to remove from list.
adv_sid – Advertiser Set ID

Returns:

0 on success; nonzero on failure.

int ble_gap_clear_periodic_adv_list(void)¶

Clear periodic synchrnization list.

Returns:: 0 on success; nonzero on failure.

int ble_gap_read_periodic_adv_list_size(uint8_t *per_adv_list_size)¶

Get periodic synchronization list size.

Parameters:

per_adv_list_size – On success list size is stored here.

Returns:

0 on success; nonzero on failure.

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.

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.

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.

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.

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.
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
ediv – 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.

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.

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.

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.

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.

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.

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.

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.

Parameters:

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
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.

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
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
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.

int ble_gap_set_default_subrate(uint16_t subrate_min, uint16_t subrate_max, uint16_t max_latency, uint16_t cont_num, uint16_t supervision_timeout)¶

Set default subrate.

Parameters:

subrate_min – Min subrate factor allowed in request by a peripheral
subrate_max – Max subrate factor allowed in request by a peripheral
max_latency – Max peripheral latency allowed in units of subrated conn interval.
cont_num – Min number of underlying conn event to remain active after a packet containing PDU with non-zero length field is sent or received in request by a peripheral.
supervision_timeout – Max supervision timeout allowed in request by a peripheral

int ble_gap_subrate_req(uint16_t conn_handle, uint16_t subrate_min, uint16_t subrate_max, uint16_t max_latency, uint16_t cont_num, uint16_t supervision_timeout)¶

Subrate Request.

Parameters:

conn_handle – Connection Handle of the ACL.
subrate_min – Min subrate factor to be applied
subrate_max – Max subrate factor to be applied
max_latency – Max peripheral latency allowed in units of subrated conn interval.
cont_num – Min number of underlying conn event to remain active after a packet containing PDU with non-zero length field is sent or received in request by a peripheral.
supervision_timeout – Max supervision timeout allowed for this connection

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

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

void ble_gap_conn_foreach_handle(ble_gap_conn_foreach_handle_fn *cb, void *arg)¶

Calls function defined by the user for every connection that is currently established.

Parameters:

cb – Callback function
arg – Callback argument

int ble_gap_conn_find_handle_by_addr(const ble_addr_t *addr, uint16_t *out_conn_handle)¶

Looks for the connection with specified address.

Parameters:

addr – Address to look for
out_conn_handle – Pointer to the variable in which conn_handle will be saved if found

Returns:

0 on success BLE_HS_ENOTCONN if connection with specified address was not found

int ble_gap_set_path_loss_reporting_enable(uint16_t conn_handle, uint8_t enable)¶

Enable Set Path Loss Reporting.

Parameters:

conn_handle – Connection handle @params enable 1: Enable 0: Disable

Returns:

0 on success; nonzero on failure.

int ble_gap_set_transmit_power_reporting_enable(uint16_t conn_handle, uint8_t local_enable, uint8_t remote_enable)¶

Enable Reporting of Transmit Power.

@params remote_enable 1: Enable remote transmit power reports 0: Disable remote transmit power reports

Parameters:

conn_handle – Connection handle @params local_enable 1: Enable local transmit power reports 0: Disable local transmit power reports

Returns:

0 on success; nonzero on failure.

int ble_gap_enh_read_transmit_power_level(uint16_t conn_handle, uint8_t phy, uint8_t *out_status, uint8_t *out_phy, uint8_t *out_curr_tx_power_level, uint8_t *out_max_tx_power_level)¶

LE Enhanced Read Transmit Power Level.

@params status 0 on success; nonzero on failure. @params conn_handle Connection handle @params phy Advertising Phy

@params curr_tx_power_level Current trasnmit Power Level

@params mx_tx_power_level Maximum transmit power level

Parameters:

conn_handle – Connection handle @params phy Advertising Phy

Returns:

0 on success; nonzero on failure.

int ble_gap_read_remote_transmit_power_level(uint16_t conn_handle, uint8_t phy)¶

Read Remote Transmit Power Level.

Parameters:

conn_handle – Connection handle @params phy Advertising Phy

Returns:

0 on success; nonzero on failure.

int ble_gap_set_path_loss_reporting_param(uint16_t conn_handle, uint8_t high_threshold, uint8_t high_hysteresis, uint8_t low_threshold, uint8_t low_hysteresis, uint16_t min_time_spent)¶

Set Path Loss Reproting Param.

Parameters:

conn_handle – Connection handle @params high_threshold High Threshold value for path loss @params high_hysteresis Hysteresis value for high threshold @params low_threshold Low Threshold value for path loss @params low_hysteresis Hysteresis value for low threshold @params min_time_spent Minimum time controller observes the path loss

Returns:

0 on success; nonzero on failure.

BLE_GAP_ADV_DFLT_CHANNEL_MAP¶: Default channels mask: all three channels are used.

BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE¶

BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE¶

BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED¶

struct ble_gap_sec_state¶

#include <ble_gap.h>

Connection security state.

Public Members

unsigned encrypted¶: If connection is encrypted.

unsigned authenticated¶: If connection is authenticated.

unsigned bonded¶: If connection is bonded (security information is stored)

unsigned key_size¶: Size of a key used for encryption.

struct ble_gap_adv_params¶

#include <ble_gap.h>

Advertising parameters.

Public Members

uint8_t conn_mode¶

Advertising mode.

Can be one of following constants:

BLE_GAP_CONN_MODE_NON (non-connectable; 3.C.9.3.2).
BLE_GAP_CONN_MODE_DIR (directed-connectable; 3.C.9.3.3).
BLE_GAP_CONN_MODE_UND (undirected-connectable; 3.C.9.3.4).

uint8_t disc_mode¶

Discoverable mode.

Can be one of following constants:

BLE_GAP_DISC_MODE_NON (non-discoverable; 3.C.9.2.2).
BLE_GAP_DISC_MODE_LTD (limited-discoverable; 3.C.9.2.3).
BLE_GAP_DISC_MODE_GEN (general-discoverable; 3.C.9.2.4).

uint16_t itvl_min¶: Minimum advertising interval, if 0 stack use sane defaults.

uint16_t itvl_max¶: Maximum advertising interval, if 0 stack use sane defaults.

uint8_t channel_map¶: Advertising channel map , if 0 stack use sane defaults.

uint8_t filter_policy¶: Advertising Filter policy.

uint8_t high_duty_cycle¶: If do High Duty cycle for Directed Advertising.

struct ble_gap_conn_desc¶

#include <ble_gap.h>

Connection descriptor.

Public Members

struct ble_gap_sec_state sec_state¶: Connection security state.

ble_addr_t our_id_addr¶: Local identity address.

ble_addr_t peer_id_addr¶: Peer identity address.

ble_addr_t our_ota_addr¶: Local over-the-air address.

ble_addr_t peer_ota_addr¶: Peer over-the-air address.

uint16_t conn_handle¶: Connection handle.

uint16_t conn_itvl¶: Connection interval.

uint16_t conn_latency¶: Connection latency.

uint16_t supervision_timeout¶: Connection supervision timeout.

uint8_t role¶: Connection Role Possible values BLE_GAP_ROLE_SLAVE or BLE_GAP_ROLE_MASTER.

uint8_t master_clock_accuracy¶: Master clock accuracy.

struct ble_gap_conn_params¶

#include <ble_gap.h>

Connection parameters

Public Members

uint16_t scan_itvl¶: Scan interval in 0.625ms units.

uint16_t scan_window¶: Scan window in 0.625ms units.

uint16_t itvl_min¶: Minimum value for connection interval in 1.25ms units.

uint16_t itvl_max¶: Maximum value for connection interval in 1.25ms units.

uint16_t latency¶: Connection latency.

uint16_t supervision_timeout¶: Supervision timeout in 10ms units.

uint16_t min_ce_len¶: Minimum length of connection event in 0.625ms units.

uint16_t max_ce_len¶: Maximum length of connection event in 0.625ms units.

struct ble_gap_ext_disc_params¶

#include <ble_gap.h>

Extended discovery parameters.

Public Members

uint16_t itvl¶: Scan interval in 0.625ms units.

uint16_t window¶: Scan window in 0.625ms units.

uint8_t passive¶: If passive scan should be used.

struct ble_gap_disc_params¶

#include <ble_gap.h>

Discovery parameters.

Public Members

uint16_t itvl¶: Scan interval in 0.625ms units.

uint16_t window¶: Scan window in 0.625ms units.

uint8_t filter_policy¶: Scan filter policy.

uint8_t limited¶: If limited discovery procedure should be used.

uint8_t passive¶: If passive scan should be used.

uint8_t filter_duplicates¶: If enable duplicates filtering.

struct ble_gap_upd_params¶

#include <ble_gap.h>

Connection parameters update parameters.

Public Members

uint16_t itvl_min¶: Minimum value for connection interval in 1.25ms units.

uint16_t itvl_max¶: Maximum value for connection interval in 1.25ms units.

uint16_t latency¶: Connection latency.

uint16_t supervision_timeout¶: Supervision timeout in 10ms units.

uint16_t min_ce_len¶: Minimum length of connection event in 0.625ms units.

uint16_t max_ce_len¶: Maximum length of connection event in 0.625ms units.

struct ble_gap_passkey_params¶

#include <ble_gap.h>

Passkey query.

Public Members

uint8_t action¶

Passkey action, can be one of following constants:

BLE_SM_IOACT_NONE
BLE_SM_IOACT_OOB
BLE_SM_IOACT_INPUT
BLE_SM_IOACT_DISP
BLE_SM_IOACT_NUMCMP

uint32_t numcmp¶: Passkey to compare, valid for BLE_SM_IOACT_NUMCMP action.

struct ble_gap_ext_disc_desc¶

#include <ble_gap.h>

Extended advertising report.

Public Members

uint8_t props¶

Report properties bitmask.

BLE_HCI_ADV_CONN_MASK
BLE_HCI_ADV_SCAN_MASK
BLE_HCI_ADV_DIRECT_MASK
BLE_HCI_ADV_SCAN_RSP_MASK
BLE_HCI_ADV_LEGACY_MASK

uint8_t data_status¶

Advertising data status, can be one of following constants:

BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE
BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE
BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED

uint8_t legacy_event_type¶

Legacy advertising PDU type.

Valid if BLE_HCI_ADV_LEGACY_MASK props is set. Can be one of following constants:

BLE_HCI_ADV_RPT_EVTYPE_ADV_IND
BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND
BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND
BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP

ble_addr_t addr¶: Advertiser address.

int8_t rssi¶: Received signal strength indication in dBm (127 if unavailable)

int8_t tx_power¶: Advertiser transmit power in dBm (127 if unavailable)

uint8_t sid¶: Advertising Set ID.

uint8_t prim_phy¶

Primary advertising PHY, can be one of following constants:

BLE_HCI_LE_PHY_1M
BLE_HCI_LE_PHY_CODED

uint8_t sec_phy¶

Secondary advertising PHY, can be one of following constants:

BLE_HCI_LE_PHY_1M
LE_HCI_LE_PHY_2M
BLE_HCI_LE_PHY_CODED

uint16_t periodic_adv_itvl¶

Periodic advertising interval.

0 if no periodic advertising.

uint8_t length_data¶: Advertising Data length.

const uint8_t *data¶: Advertising data.

ble_addr_t direct_addr¶

Directed advertising address.

Valid if BLE_HCI_ADV_DIRECT_MASK props is set (BLE_ADDR_ANY otherwise).

struct ble_gap_disc_desc¶

#include <ble_gap.h>

Advertising report.

Public Members

uint8_t event_type¶

Advertising PDU type.

Can be one of following constants:

BLE_HCI_ADV_RPT_EVTYPE_ADV_IND
BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND
BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND
BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP

uint8_t length_data¶: Advertising Data length.

ble_addr_t addr¶: Advertiser address.

int8_t rssi¶: Received signal strength indication in dBm (127 if unavailable)

const uint8_t *data¶: Advertising data.

ble_addr_t direct_addr¶

Directed advertising address.

Valid for BLE_HCI_ADV_RPT_EVTYPE_DIR_IND event type (BLE_ADDR_ANY otherwise).

struct ble_gap_repeat_pairing¶

#include <ble_gap.h>

Represents a repeat pairing operation between two devices.

This structure contains information about a repeat pairing operation between two devices. The host can use this information to determine whether it needs to initiate a pairing procedure with a remote device again.

Public Members

uint16_t conn_handle¶: The handle of the relevant connection.

uint8_t cur_key_size¶

Properties of the existing bond.

The size of the current encryption key in octets.

uint8_t cur_authenticated¶: A flag indicating whether the current connection is authenticated.

uint8_t cur_sc¶: A flag indicating whether the current connection is using secure connections.

uint8_t new_key_size¶

Properties of the imminent secure link if the pairing procedure is allowed to continue.

The size of the imminent encryption key in octets.

uint8_t new_authenticated¶: A flag indicating whether the imminent connection will be authenticated.

uint8_t new_sc¶: A flag indicating whether the imminent connection will use secure connections.

uint8_t new_bonding¶: A flag indicating whether the pairing procedure will result in a new bonding,.

struct ble_gap_event¶

#include <ble_gap.h>

Represents a GAP-related event.

When such an event occurs, the host notifies the application by passing an instance of this structure to an application-specified callback.

Public Members

uint8_t type¶

Indicates the type of GAP event that occurred.

This is one of the BLE_GAP_EVENT codes.

union ble_gap_event.[anonymous] [anonymous]¶

A discriminated union containing additional details concerning the GAP event.

The ‘type’ field indicates which member of the union is valid.

struct ble_gap_ext_adv_params¶

#include <ble_gap.h>

Extended advertising parameters

Public Members

unsigned int connectable¶: If perform connectable advertising.

unsigned int scannable¶: If perform scannable advertising.

unsigned int directed¶: If perform directed advertising.

unsigned int high_duty_directed¶: If perform high-duty directed advertising.

unsigned int legacy_pdu¶

If use legacy PDUs for advertising.

Valid combinations of the connectable, scannable, directed, high_duty_directed options with the legcy_pdu flag are:

IND -> legacy_pdu + connectable + scannable
LD_DIR -> legacy_pdu + connectable + directed
HD_DIR -> legacy_pdu + connectable + directed + high_duty_directed
SCAN -> legacy_pdu + scannable
NONCONN -> legacy_pdu

Any other combination of these options combined with the legacy_pdu flag are invalid.

unsigned int anonymous¶: If perform anonymous advertising.

unsigned int include_tx_power¶: If include TX power in advertising PDU.

unsigned int scan_req_notif¶: If enable scan request notification

uint32_t itvl_min¶: Minimum advertising interval in 0.625ms units, if 0 stack use sane defaults.

uint32_t itvl_max¶: Maximum advertising interval in 0.625ms units, if 0 stack use sane defaults.

uint8_t channel_map¶: Advertising channel map , if 0 stack use sane defaults.

uint8_t own_addr_type¶: Own address type to be used by advertising instance.

ble_addr_t peer¶: Peer address for directed advertising, valid only if directed is set.

uint8_t filter_policy¶: Advertising Filter policy.

uint8_t primary_phy¶

Primary advertising PHY to use , can be one of following constants:

BLE_HCI_LE_PHY_1M
BLE_HCI_LE_PHY_CODED

uint8_t secondary_phy¶

Secondary advertising PHY to use, can be one of following constants:

BLE_HCI_LE_PHY_1M
LE_HCI_LE_PHY_2M
BLE_HCI_LE_PHY_CODED

int8_t tx_power¶: Preferred advertiser transmit power.

uint8_t sid¶: Advertising Set ID.

struct ble_gap_periodic_adv_params¶

#include <ble_gap.h>

Periodic advertising parameters

Public Members

unsigned int include_tx_power¶: If include TX power in advertising PDU.

uint16_t itvl_min¶: Minimum advertising interval in 1.25ms units, if 0 stack use sane defaults.

uint16_t itvl_max¶: Maximum advertising interval in 1.25ms units, if 0 stack use sane defaults.

struct ble_gap_periodic_adv_start_params¶: #include <ble_gap.h>

Periodic advertising enable parameters

struct ble_gap_periodic_adv_sync_reporting_params¶: #include <ble_gap.h>

Periodic advertising sync reporting parameters

struct ble_gap_periodic_adv_set_data_params¶: #include <ble_gap.h>

Periodic adv set data parameters

struct ble_gap_periodic_sync_params¶

#include <ble_gap.h>

Periodic sync parameters

Public Members

uint16_t skip¶: The maximum number of periodic advertising events that controller can skip after a successful receive.

uint16_t sync_timeout¶: Synchronization timeout for the periodic advertising train in 10ms units.

unsigned int reports_disabled¶: If reports should be initially disabled when sync is created.

struct ble_gap_event_listener¶

#include <ble_gap.h>

Event listener structure.

This should be used as an opaque structure and not modified manually.

Public Functions

SLIST_ENTRY (ble_gap_event_listener) link: Singly-linked list entry.

Public Members

ble_gap_event_fn *fn¶: The function to call when a GAP event occurs.

void *arg¶: An optional argument to pass to the event handler function.

An OS to build, deploy and securely manage billions of devices

Latest News:

NimBLE Host GAP Reference¶

Introduction¶

API¶