Module for handling the BLE scanning. More...
Modules | |
Scanning Module configuration | |
Filter modes | |
Data Structures | |
struct | nrf_ble_scan_short_name_t |
struct | nrf_ble_scan_init_t |
Structure for Scanning Module initialization. More... | |
struct | nrf_ble_scan_filter_match |
Structure for setting the filter status. More... | |
struct | nrf_ble_scan_evt_filter_match_t |
Event structure for NRF_BLE_SCAN_EVT_FILTER_MATCH. More... | |
struct | nrf_ble_scan_evt_connecting_err_t |
Event structure for NRF_BLE_SCAN_EVT_CONNECTING_ERROR. More... | |
struct | nrf_ble_scan_evt_connected_t |
Event structure for NRF_BLE_SCAN_EVT_CONNECTED. More... | |
struct | scan_evt_t |
Structure for Scanning Module event data. More... | |
struct | nrf_ble_scan_name_filter_t |
struct | nrf_ble_scan_short_name_filter_t |
struct | nrf_ble_scan_addr_filter_t |
struct | nrf_ble_scan_uuid_filter_t |
struct | nrf_ble_scan_appearance_filter_t |
struct | nrf_ble_scan_filters_t |
Filters data. More... | |
struct | nrf_ble_scan_t |
Scan module instance. Options for the different scanning modes. More... | |
Macros | |
#define | NRF_BLE_SCAN_DEF(_name) |
Macro for defining a nrf_ble_scan instance. More... | |
Typedefs | |
typedef void(* | nrf_ble_scan_evt_handler_t )(scan_evt_t const *p_scan_evt) |
BLE scanning event handler type. | |
Enumerations | |
enum | nrf_ble_scan_evt_t { NRF_BLE_SCAN_EVT_FILTER_MATCH, NRF_BLE_SCAN_EVT_WHITELIST_REQUEST, NRF_BLE_SCAN_EVT_WHITELIST_ADV_REPORT, NRF_BLE_SCAN_EVT_NOT_FOUND, NRF_BLE_SCAN_EVT_SCAN_TIMEOUT, NRF_BLE_SCAN_EVT_CONNECTING_ERROR, NRF_BLE_SCAN_EVT_CONNECTED } |
Enumeration for scanning events. More... | |
enum | nrf_ble_scan_filter_type_t { SCAN_NAME_FILTER, SCAN_SHORT_NAME_FILTER, SCAN_ADDR_FILTER, SCAN_UUID_FILTER, SCAN_APPEARANCE_FILTER } |
Types of filters. More... | |
Functions | |
bool | is_whitelist_used (nrf_ble_scan_t const *const p_scan_ctx) |
Function for indicating that the Scanning Module is using the whitelist. More... | |
ret_code_t | nrf_ble_scan_init (nrf_ble_scan_t *const p_scan_ctx, nrf_ble_scan_init_t const *const p_init, nrf_ble_scan_evt_handler_t evt_handler) |
Function for initializing the Scanning Module. More... | |
ret_code_t | nrf_ble_scan_start (nrf_ble_scan_t const *const p_scan_ctx) |
Function for starting scanning. More... | |
void | nrf_ble_scan_stop (void) |
Function for stopping scanning. | |
ret_code_t | nrf_ble_scan_filters_enable (nrf_ble_scan_t *const p_scan_ctx, uint8_t mode, bool match_all) |
Function for enabling filtering. More... | |
ret_code_t | nrf_ble_scan_filters_disable (nrf_ble_scan_t *const p_scan_ctx) |
Function for disabling filtering. More... | |
ret_code_t | nrf_ble_scan_filter_get (nrf_ble_scan_t *const p_scan_ctx, nrf_ble_scan_filters_t *p_status) |
Function for getting filter status. More... | |
ret_code_t | nrf_ble_scan_filter_set (nrf_ble_scan_t *const p_scan_ctx, nrf_ble_scan_filter_type_t type, void const *p_data) |
Function for adding any type of filter to the scanning. More... | |
ret_code_t | nrf_ble_scan_all_filter_remove (nrf_ble_scan_t *const p_scan_ctx) |
Function for removing all set filters. More... | |
ret_code_t | nrf_ble_scan_params_set (nrf_ble_scan_t *const p_scan_ctx, ble_gap_scan_params_t const *p_scan_param) |
Function for changing the scanning parameters. More... | |
void | nrf_ble_scan_on_ble_evt (ble_evt_t const *p_ble_evt, void *p_scan) |
Function for handling the BLE stack events of the application. More... | |
ret_code_t | nrf_ble_scan_copy_addr_to_sd_gap_addr (ble_gap_addr_t *p_gap_addr, uint8_t const addr[BLE_GAP_ADDR_LEN]) |
Function for converting the raw address to the SoftDevice GAP address. More... | |
Module for handling the BLE scanning.
The Scanning Module handles the BLE scanning for your application. The module offers several criteria for filtering the devices available for connection, and it can also work in the simple mode without using the filtering. If an event handler is provided, your main application can react to a filter match or to the need of setting the whitelist. The module can also be configured to automatically connect after it matches a filter or a device from the whitelist.
#define NRF_BLE_SCAN_DEF | ( | _name | ) |
Macro for defining a nrf_ble_scan instance.
_name | Name of the instance. |
enum nrf_ble_scan_evt_t |
Enumeration for scanning events.
These events are propagated to the main application if a handler is provided during the initialization of the Scanning Module. NRF_BLE_SCAN_EVT_WHITELIST_REQUEST cannot be ignored if whitelist is used.
Enumerator | |
---|---|
NRF_BLE_SCAN_EVT_FILTER_MATCH |
A filter is matched or all filters are matched in the multifilter mode. |
NRF_BLE_SCAN_EVT_WHITELIST_REQUEST |
Request the whitelist from the main application. For whitelist scanning to work, the whitelist must be set when this event occurs. |
NRF_BLE_SCAN_EVT_WHITELIST_ADV_REPORT |
Send notification to the main application when a device from the whitelist is found. |
NRF_BLE_SCAN_EVT_NOT_FOUND |
The filter was not matched for the scan data. |
NRF_BLE_SCAN_EVT_SCAN_TIMEOUT |
Scan timeout. |
NRF_BLE_SCAN_EVT_CONNECTING_ERROR |
Error occurred when establishing the connection. In this event, an error is passed from the function call sd_ble_gap_connect. |
NRF_BLE_SCAN_EVT_CONNECTED |
Connected to device. |
bool is_whitelist_used | ( | nrf_ble_scan_t const *const | p_scan_ctx | ) |
Function for indicating that the Scanning Module is using the whitelist.
[in] | p_scan_ctx | Pointer to the Scanning Module instance. |
ret_code_t nrf_ble_scan_all_filter_remove | ( | nrf_ble_scan_t *const | p_scan_ctx | ) |
Function for removing all set filters.
The function removes all previously set filters.
[in,out] | p_scan_ctx | Pointer to the Scanning Module instance. |
NRF_SUCCESS | If all filters are removed successfully. |
ret_code_t nrf_ble_scan_copy_addr_to_sd_gap_addr | ( | ble_gap_addr_t * | p_gap_addr, |
uint8_t const | addr[BLE_GAP_ADDR_LEN] | ||
) |
Function for converting the raw address to the SoftDevice GAP address.
This function inverts the byte order in the address. If you enter the address as it is displayed (for example, on a phone screen from left to right), you must use this function to convert the address to the SoftDevice address type.
[out] | p_gap_addr | The Bluetooth Low Energy address. |
[in] | addr | Address to be converted to the SoftDevice address. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
NRF_SUCCESS | If the address is copied and converted successfully. |
ret_code_t nrf_ble_scan_filter_get | ( | nrf_ble_scan_t *const | p_scan_ctx, |
nrf_ble_scan_filters_t * | p_status | ||
) |
Function for getting filter status.
This function returns the filter setting and whether it is enabled or disabled.
[out] | p_status | Filter status. |
[in] | p_scan_ctx | Pointer to the Scanning Module instance. |
NRF_SUCCESS | If filter status is returned. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
ret_code_t nrf_ble_scan_filter_set | ( | nrf_ble_scan_t *const | p_scan_ctx, |
nrf_ble_scan_filter_type_t | type, | ||
void const * | p_data | ||
) |
Function for adding any type of filter to the scanning.
This function adds a new filter by type nrf_ble_scan_filter_type_t. The filter will be added if the number of filters of a given type does not exceed NRF_BLE_SCAN_UUID_CNT, NRF_BLE_SCAN_NAME_CNT, NRF_BLE_SCAN_ADDRESS_CNT, or NRF_BLE_SCAN_APPEARANCE_CNT, depending on the filter type, and if the same filter has not already been set.
[in,out] | p_scan_ctx | Pointer to the Scanning Module instance. |
[in] | type | Filter type. |
[in] | p_data | The filter data to add. |
NRF_SUCCESS | If the filter is added successfully. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
NRF_ERROR_DATA_SIZE | If the name filter length is too long. Maximum name filter length corresponds to NRF_BLE_SCAN_NAME_MAX_LEN. |
NRF_ERROR_NO_MEMORY | If the number of available filters is exceeded. |
NRF_ERROR_INVALID_PARAM | If the filter type is incorrect. Available filter types: nrf_ble_scan_filter_type_t. |
BLE_ERROR_GAP_INVALID_BLE_ADDR | If the BLE address type is invalid. |
ret_code_t nrf_ble_scan_filters_disable | ( | nrf_ble_scan_t *const | p_scan_ctx | ) |
Function for disabling filtering.
This function disables all filters. Even if the automatic connection establishing is enabled, the connection will not be established with the first device found after this function is called.
[in] | p_scan_ctx | Pointer to the Scanning Module instance. |
NRF_SUCCESS | If filters are disabled successfully. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
ret_code_t nrf_ble_scan_filters_enable | ( | nrf_ble_scan_t *const | p_scan_ctx, |
uint8_t | mode, | ||
bool | match_all | ||
) |
Function for enabling filtering.
The filters can be combined with each other. For example, you can enable one filter or several filters. For example, (NRF_BLE_SCAN_NAME_FILTER | NRF_BLE_SCAN_UUID_FILTER) enables UUID and name filters.
[in] | mode | Filter mode: Filter modes. |
[in] | match_all | If this flag is set, all types of enabled filters must be matched before generating NRF_BLE_SCAN_EVT_FILTER_MATCH to the main application. Otherwise, it is enough to match one filter to trigger the filter match event. |
[in] | p_scan_ctx | Pointer to the Scanning Module instance. |
NRF_SUCCESS | If the filters are enabled successfully. |
NRF_ERROR_INVALID_PARAM | If the filter mode is incorrect. Available filter modes: Filter modes. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
ret_code_t nrf_ble_scan_init | ( | nrf_ble_scan_t *const | p_scan_ctx, |
nrf_ble_scan_init_t const *const | p_init, | ||
nrf_ble_scan_evt_handler_t | evt_handler | ||
) |
Function for initializing the Scanning Module.
[out] | p_scan_ctx | Pointer to the Scanning Module instance. This structure must be supplied by the application. It is initialized by this function and is later used to identify this particular module instance. |
[in] | p_init | Can be initialized as NULL. If NULL, the parameters required to initialize the module are loaded from static configuration. If module is to establish the connection automatically, this must be initialized with the relevant data. |
[in] | evt_handler | Handler for the scanning events. Can be initialized as NULL if no handling is implemented in the main application. |
NRF_SUCCESS | If initialization was successful. |
NRF_ERROR_NULL | When the NULL pointer is passed as input. |
void nrf_ble_scan_on_ble_evt | ( | ble_evt_t const * | p_ble_evt, |
void * | p_scan | ||
) |
Function for handling the BLE stack events of the application.
[in] | p_ble_evt | Pointer to the BLE event received. |
[in,out] | p_scan | Pointer to the Scanning Module instance. |
ret_code_t nrf_ble_scan_params_set | ( | nrf_ble_scan_t *const | p_scan_ctx, |
ble_gap_scan_params_t const * | p_scan_param | ||
) |
Function for changing the scanning parameters.
Use this function to change scanning parameters. During the parameter change the scan is stopped. To resume scanning, use nrf_ble_scan_start. Scanning parameters can be set to NULL. If so, the default static configuration is used. For example, use this function when the NRF_BLE_SCAN_EVT_WHITELIST_ADV_REPORT event is generated. The generation of this event means that there is a risk that the whitelist is empty. In such case, this function can change the scanning parameters, so that the whitelist is not used, and you avoid the error caused by scanning with the whitelist when there are no devices on the whitelist.
[in,out] | p_scan_ctx | Pointer to the Scanning Module instance. |
[in] | p_scan_param | GAP scanning parameters. Can be initialized as NULL. |
NRF_SUCCESS | If parameters are changed successfully. |
NRF_ERROR_NULL | If a NULL pointer is passed as input. |
ret_code_t nrf_ble_scan_start | ( | nrf_ble_scan_t const *const | p_scan_ctx | ) |
Function for starting scanning.
This function starts the scanning according to the configuration set during the initialization.
[in] | p_scan_ctx | Pointer to the Scanning Module instance. |
NRF_SUCCESS | If scanning started. Otherwise, an error code is returned. |
NRF_ERROR_NULL | If NULL pointer is passed as input. |