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.

Return

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

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.

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.

Return

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

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.

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.

Return

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

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.

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.

Return

0 on success, error code on failure.

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.

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.

Return

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.

Return

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.

Return

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

Parameters

  • data: Buffer containing the advertising data.

  • data_len: The size of the advertising data, in bytes.

int ble_gap_adv_rsp_set_data(const uint8_t *data, int data_len)

Configures the data to include in subsequent scan responses.

Return

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

Parameters

  • data: Buffer containing the scan response data.

  • data_len: The size of the response data, in bytes.

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

Return

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.

Parameters

  • adv_fields: Specifies the advertisement data.

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

Return

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.

Parameters

  • rsp_fields: Specifies the scan response data.

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.

Return

0 on success; nonzero on failure.

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.

int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr)

Set random address for configured advertising instance.

Return

0 on success; nonzero on failure.

Parameters

  • instance: Instance ID

  • addr: Random address to be set

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

Start advertising instance.

Return

0 on success, error code on failure.

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.

int ble_gap_ext_adv_stop(uint8_t instance)

Stops advertising procedure for specified instance.

Return

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

Parameters

  • instance: Instance ID

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.

Return

0 on success or error code on failure.

Parameters

  • instance: Instance ID

  • data: Chain containing the advertising data.

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.

Return

0 on success or error code on failure.

Parameters

  • instance: Instance ID

  • data: Chain containing the scan response data.

int ble_gap_ext_adv_remove(uint8_t instance)

Remove existing advertising instance.

Return

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

Parameters

  • instance: Instance ID

int ble_gap_ext_adv_clear(void)

Clear all existing advertising instances.

Return

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.

Return

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

Parameters

  • instance: Instance Id

int ble_gap_adv_get_free_instance(uint8_t *out_adv_instance)

Finds first not configured advertising instance.

Return

0 if free advertising instance was found, error code otherwise

Parameters

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

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.

Return

0 on success; nonzero on failure.

Parameters

  • instance: Instance ID

  • params: Additional arguments specifying the particulars of periodic advertising.

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.

Return

0 on success, error code on failure.

Parameters

  • instance: Instance ID

  • params: Additional arguments specifying the particulars of periodic advertising.

int ble_gap_periodic_adv_stop(uint8_t instance)

Stop periodic advertising for specified advertising instance.

Return

0 on success, error code on failure.

Parameters

  • instance: Instance ID

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.

Return

0 on success or error code on failure.

Parameters

  • instance: Instance ID

  • data: Chain containing the periodic advertising data.

  • params: Additional arguments specifying the particulars of periodic advertising data.

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.

Return

0 on success; nonzero on failure.

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.

int ble_gap_periodic_adv_sync_create_cancel(void)

Cancel pending synchronization procedure.

Return

0 on success; nonzero on failure.

int ble_gap_periodic_adv_sync_terminate(uint16_t sync_handle)

Terminate synchronization procedure.

Return

0 on success; nonzero on failure.

Parameters

  • sync_handle: Handle identifying synchronization to terminate.

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.

Return

0 on success; nonzero on failure.

Parameters

  • sync_handle: Handle identifying synchronization.

  • enable: If reports should be enabled.

  • params: Additional arguments specifying the particulars of periodic reports.

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.

Return

0 on success; nonzero on failure.

Parameters

  • sync_handle: Handle identifying synchronization.

  • conn_handle: Handle identifying connection.

  • service_data: Sync transfer service data

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.

Return

0 on success; nonzero on failure.

Parameters

  • instance: Advertising instance with periodic adv enabled.

  • conn_handle: Handle identifying connection.

  • service_data: Sync transfer service data

int periodic_adv_set_default_sync_params(const struct ble_gap_periodic_sync_params *params)

Set the default periodic sync transfer params.

Return

0 on success; nonzero on failure.

Parameters

  • conn_handle: Handle identifying connection.

  • params: Default Parameters for periodic sync transfer.

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.

Return

0 on success; nonzero on failure.

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.

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.

Return

0 on success; nonzero on failure.

Parameters

  • addr: Peer address to add to list.

  • adv_sid: Advertiser Set ID

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.

Return

0 on success; nonzero on failure.

Parameters

  • addr: Peer address to remove from list.

  • adv_sid: Advertiser Set ID

int ble_gap_clear_periodic_adv_list(void)

Clear periodic synchrnization list.

Return

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.

Return

0 on success; nonzero on failure.

Parameters

  • per_adv_list_size: On success list size is stored here.

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.

Return

0 on success; nonzero on failure.

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.

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.

Return

0 on success; nonzero on failure.

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.

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.

Return

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.

Return

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.

Return

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.

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.

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.

Return

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.

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.

int ble_gap_conn_cancel(void)

Aborts a connect procedure in progress.

Return

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.

Return

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.

Return

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

Parameters

  • conn_handle: The handle corresponding to the connection to terminate.

  • hci_reason: The HCI error code to indicate as the reason for termination.

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.

Return

0 on success; nonzero on failure.

Parameters

  • addrs: The entries to write to the white list.

  • white_list_count: The number of entries in the white list.

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

Initiates a connection parameter update procedure.

Return

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.

Parameters

  • conn_handle: The handle corresponding to the connection to update.

  • params: The connection parameters to attempt to update to.

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

Return

0 on success, other error code on failure.

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

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

Return

0 on success, other error code on failure.

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

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

Return

0 on success, other error code on failure.

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

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

Return

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.

Parameters

  • conn_handle: The handle corresponding to the connection to secure.

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.

Return

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.

Parameters

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

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.

Return

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.

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.

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.

Return

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

Parameters

  • conn_handle: Specifies the connection to query.

  • out_rssi: On success, the retrieved RSSI is written here.

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.

Return

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

Parameters

  • peer_addr: Address of the device to be unpaired

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.

Return

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.

Return

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

Parameters

  • peer_addr: Address of the peer (not to be deleted)

int ble_gap_set_priv_mode(const ble_addr_t *peer_addr, uint8_t priv_mode)

Set privacy mode for specified peer device.

Return

0 on success; nonzero on failure.

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

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.

Return

0 on success; nonzero on failure.

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

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.

Return

0 on success; nonzero on failure.

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

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.

Return

0 on success; nonzero on failure.

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

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.

Return

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

Parameters

  • listener: Listener structure

  • fn: Callback function

  • arg: Callback argument

int ble_gap_event_listener_unregister(struct ble_gap_event_listener *listener)

Unregisters listener for GAP events.

Return

0 on success BLE_HS_ENOENT if listener was not registered

Parameters

  • listener: Listener structure

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.

Return

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

Parameters

  • addr: Address to look for

  • out_conn_handle: Pointer to the variable in which conn_handle will be saved if found

int ble_gap_set_path_loss_reporting_enable(uint16_t conn_handle, uint8_t enable)

Enable Set Path Loss Reporting.

Return

0 on success; nonzero on failure.

Parameters

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

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

Return

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

Parameters

  • 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

Return

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.

Return

0 on success; nonzero on failure.

Parameters

  • conn_handle: Connection handle @params phy Advertising Phy

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.

Return

0 on success; nonzero on failure.

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

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.