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 IDparams
: 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 callbackcb_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 IDaddr
: 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 IDduration
: The duration of the advertisement procedure. On expiration, the procedure ends and a BLE_HS_FOREVER event is reported. Units are 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 IDdata
: 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 IDdata
: 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 IDparams
: 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 IDdata
: Chain containing the periodic advertising data.
-
int
ble_gap_periodic_adv_create_sync
(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 IDparams
: 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_create_sync_cancel
(void)¶ Cancel pending synchronization procedure.
- Return
0 on success; nonzero on failure.
-
int
ble_gap_periodic_adv_terminate_sync
(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_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.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 donephy_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 sizeltk
: Long Term Key to be used for encryption.udiv
: Encryption Diversifier for LTKrand_val
: Random Value for EDIV and LTKauth
: 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 addresspriv_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 handletx_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 structurefn
: Callback functionarg
: 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_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.
-
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.
-
uint8_t
-
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_sec_state
-
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.
-
uint16_t
-
struct
ble_gap_ext_disc_params
¶ - #include <ble_gap.h>
Extended discovery parameters.
-
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.
-
uint16_t
-
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.
-
uint16_t
-
struct
ble_gap_passkey_params
¶ - #include <ble_gap.h>
Passkey query.
-
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.
-
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).
-
uint8_t
-
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)
-
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).
-
uint8_t
-
struct
ble_gap_repeat_pairing
¶ - #include <ble_gap.h>
-
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.
-
uint8_t
-
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.
-
unsigned int
-
struct
ble_gap_periodic_adv_params
¶ - #include <ble_gap.h>
Periodic advertising parameters
-
struct
ble_gap_periodic_sync_params
¶ - #include <ble_gap.h>
Periodic sync parameters
-
struct
ble_gap_event_listener
¶ - #include <ble_gap.h>
Event listener structure.
This should be used as an opaque structure and not modified manually.