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)
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 *rsp_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

  • adv_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_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)

Start periodic advertising for specified advertising instance.

Return

0 on success, error code on failure.

Parameters

  • instance: Instance ID

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)

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.

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)

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.

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

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

  • conn_params: Additional arguments specifying the particulars of the connect procedure. Specify null for default values.

  • cb: The callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism.

  • cb_arg: The optional argument to pass to the callback function.

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

  • udiv: 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_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.

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

  • BLE_GAP_LE_PHY_1M_MASK

  • BLE_GAP_LE_PHY_2M_MASK

  • BLE_GAP_LE_PHY_CODED_MASK

  • BLE_GAP_LE_PHY_ANY_MASK @params rx_phys_mask Preferred RX PHY. Can be mask of following constants:

  • BLE_GAP_LE_PHY_1M_MASK

  • BLE_GAP_LE_PHY_2M_MASK

  • BLE_GAP_LE_PHY_CODED_MASK

  • BLE_GAP_LE_PHY_ANY_MASK

Return

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.

Return

0 on success; nonzero on failure.

Parameters

  • conn_handle: Connection handle @params tx_phys_mask Preferred TX PHY. Can be mask of following constants:

    • BLE_GAP_LE_PHY_1M_MASK

    • BLE_GAP_LE_PHY_2M_MASK

    • BLE_GAP_LE_PHY_CODED_MASK

    • BLE_GAP_LE_PHY_ANY_MASK @params rx_phys_mask Preferred RX PHY. Can be mask of following constants:

    • BLE_GAP_LE_PHY_1M_MASK

    • BLE_GAP_LE_PHY_2M_MASK

    • BLE_GAP_LE_PHY_CODED_MASK

    • BLE_GAP_LE_PHY_ANY_MASK

  • phy_opts: Additional PHY options. Valid values are:

    • BLE_GAP_LE_PHY_CODED_ANY

    • BLE_GAP_LE_PHY_CODED_S2

    • BLE_GAP_LE_PHY_CODED_S8

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

BLE_GAP_ADV_FAST_INTERVAL1_MIN

30 ms.

BLE_GAP_ADV_FAST_INTERVAL1_MAX

60 ms.

BLE_GAP_ADV_FAST_INTERVAL2_MIN

100 ms.

BLE_GAP_ADV_FAST_INTERVAL2_MAX

150 ms.

BLE_GAP_SCAN_FAST_INTERVAL_MIN

30 ms; active scanning.

BLE_GAP_SCAN_FAST_INTERVAL_MAX

60 ms; active scanning.

BLE_GAP_LIM_DISC_SCAN_INT

11.25 ms; limited discovery interval.

BLE_GAP_LIM_DISC_SCAN_WINDOW

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

BLE_GAP_SCAN_FAST_WINDOW

30 ms; active scanning.

BLE_GAP_SCAN_FAST_PERIOD
BLE_GAP_SCAN_SLOW_INTERVAL1

1.28 seconds; background scanning.

BLE_GAP_SCAN_SLOW_WINDOW1

11.25 ms; background scanning.

BLE_GAP_DISC_DUR_DFLT

10.24 seconds.

BLE_GAP_CONN_DUR_DFLT

30 seconds (not from the spec).

BLE_GAP_CONN_PAUSE_CENTRAL

1 second.

BLE_GAP_CONN_PAUSE_PERIPHERAL

5 seconds.

BLE_GAP_INITIAL_CONN_ITVL_MIN
BLE_GAP_INITIAL_CONN_ITVL_MAX
BLE_GAP_ADV_DFLT_CHANNEL_MAP

Default channels mask: all three channels are used.

BLE_GAP_INITIAL_CONN_LATENCY
BLE_GAP_INITIAL_SUPERVISION_TIMEOUT
BLE_GAP_INITIAL_CONN_MIN_CE_LEN
BLE_GAP_INITIAL_CONN_MAX_CE_LEN
BLE_GAP_ROLE_MASTER
BLE_GAP_ROLE_SLAVE
BLE_GAP_EVENT_CONNECT
BLE_GAP_EVENT_DISCONNECT
BLE_GAP_EVENT_CONN_UPDATE
BLE_GAP_EVENT_CONN_UPDATE_REQ
BLE_GAP_EVENT_L2CAP_UPDATE_REQ
BLE_GAP_EVENT_TERM_FAILURE
BLE_GAP_EVENT_DISC
BLE_GAP_EVENT_DISC_COMPLETE
BLE_GAP_EVENT_ADV_COMPLETE
BLE_GAP_EVENT_ENC_CHANGE
BLE_GAP_EVENT_PASSKEY_ACTION
BLE_GAP_EVENT_NOTIFY_RX
BLE_GAP_EVENT_NOTIFY_TX
BLE_GAP_EVENT_SUBSCRIBE
BLE_GAP_EVENT_MTU
BLE_GAP_EVENT_IDENTITY_RESOLVED
BLE_GAP_EVENT_REPEAT_PAIRING
BLE_GAP_EVENT_PHY_UPDATE_COMPLETE
BLE_GAP_EVENT_EXT_DISC
BLE_GAP_EVENT_PERIODIC_SYNC
BLE_GAP_EVENT_PERIODIC_REPORT
BLE_GAP_EVENT_PERIODIC_SYNC_LOST
BLE_GAP_EVENT_SCAN_REQ_RCVD
BLE_GAP_EVENT_PERIODIC_TRANSFER
BLE_GAP_SUBSCRIBE_REASON_WRITE

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

BLE_GAP_SUBSCRIBE_REASON_TERM

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

BLE_GAP_SUBSCRIBE_REASON_RESTORE

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

BLE_GAP_REPEAT_PAIRING_RETRY
BLE_GAP_REPEAT_PAIRING_IGNORE
BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE
BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE
BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED
BLE_GAP_CONN_MODE_NON
BLE_GAP_CONN_MODE_DIR
BLE_GAP_CONN_MODE_UND
BLE_GAP_DISC_MODE_NON
BLE_GAP_DISC_MODE_LTD
BLE_GAP_DISC_MODE_GEN
BLE_GAP_PRIVATE_MODE_NETWORK
BLE_GAP_PRIVATE_MODE_DEVICE
BLE_GAP_LE_PHY_1M
BLE_GAP_LE_PHY_2M
BLE_GAP_LE_PHY_CODED
BLE_GAP_LE_PHY_1M_MASK
BLE_GAP_LE_PHY_2M_MASK
BLE_GAP_LE_PHY_CODED_MASK
BLE_GAP_LE_PHY_ANY_MASK
BLE_GAP_LE_PHY_CODED_ANY
BLE_GAP_LE_PHY_CODED_S2
BLE_GAP_LE_PHY_CODED_S8
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>

Public Members

uint16_t conn_handle

The handle of the relevant connection.

uint8_t cur_key_size

Properties of the existing bond.

uint8_t new_key_size

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

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.

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 0.625ms units, if 0 stack use sane defaults.

uint16_t itvl_max

Maximum advertising interval in 0.625ms units, if 0 stack use sane defaults.

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.