nRF5 SDK v15.3.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Scanning Module

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

Detailed Description

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.

Note
The Scanning Module also supports applications with a multicentral link.

Macro Definition Documentation

#define NRF_BLE_SCAN_DEF (   _name)

Macro for defining a nrf_ble_scan instance.

Parameters
_nameName of the instance.

Enumeration Type Documentation

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_SCAN_REQ_REPORT 

Scan request report.

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.

Types of filters.

Enumerator
SCAN_NAME_FILTER 

Filter for names.

SCAN_SHORT_NAME_FILTER 

Filter for short names.

SCAN_ADDR_FILTER 

Filter for addresses.

SCAN_UUID_FILTER 

Filter for UUIDs.

SCAN_APPEARANCE_FILTER 

Filter for appearances.

Function Documentation

bool is_whitelist_used ( nrf_ble_scan_t const *const  p_scan_ctx)

Function for indicating that the Scanning Module is using the whitelist.

Parameters
[in]p_scan_ctxPointer to the Scanning Module instance.
Returns
Whether the whitelist is used.
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.

Note
After using this function the filters are still enabled.
Parameters
[in,out]p_scan_ctxPointer to the Scanning Module instance.
Return values
NRF_SUCCESSIf 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.

Parameters
[in]addrAddress to be converted to the SoftDevice address.
[out]p_gap_addrThe Bluetooth Low Energy address.
Return values
BLE_ERROR_GAP_INVALID_BLE_ADDRIf the BLE address type is invalid.
NRF_SUCCESSIf 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.

Parameters
[out]p_statusFilter status.
[in]p_scan_ctxPointer to the Scanning Module instance.
Return values
NRF_SUCCESSIf filter status is returned.
NRF_ERROR_NULLIf 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.

Parameters
[in,out]p_scan_ctxPointer to the Scanning Module instance.
[in]typeFilter type.
[in]p_dataThe filter data to add.
Return values
NRF_SUCCESSIf the filter is added successfully.
NRF_ERROR_NULLIf a NULL pointer is passed as input.
NRF_ERROR_DATA_SIZEIf the name filter length is too long. Maximum name filter length corresponds to NRF_BLE_SCAN_NAME_MAX_LEN.
NRF_ERROR_NO_MEMORYIf the number of available filters is exceeded.
NRF_ERROR_INVALID_PARAMIf the filter type is incorrect. Available filter types: nrf_ble_scan_filter_type_t.
BLE_ERROR_GAP_INVALID_BLE_ADDRIf 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.

Parameters
[in]p_scan_ctxPointer to the Scanning Module instance.
Return values
NRF_SUCCESSIf filters are disabled successfully.
NRF_ERROR_NULLIf 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.

Parameters
[in]modeFilter mode: Filter modes.
[in]match_allIf 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_ctxPointer to the Scanning Module instance.
Return values
NRF_SUCCESSIf the filters are enabled successfully.
NRF_ERROR_INVALID_PARAMIf the filter mode is incorrect. Available filter modes: Filter modes.
NRF_ERROR_NULLIf 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.

Parameters
[out]p_scan_ctxPointer 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_initCan 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_handlerHandler for the scanning events. Can be initialized as NULL if no handling is implemented in the main application.
Return values
NRF_SUCCESSIf initialization was successful.
NRF_ERROR_NULLWhen 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.

Parameters
[in]p_ble_evtPointer to the BLE event received.
[in,out]p_scanPointer 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.

Parameters
[in,out]p_scan_ctxPointer to the Scanning Module instance.
[in]p_scan_paramGAP scanning parameters. Can be initialized as NULL.
Return values
NRF_SUCCESSIf parameters are changed successfully.
NRF_ERROR_NULLIf 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.

Parameters
[in]p_scan_ctxPointer to the Scanning Module instance.
Return values
NRF_SUCCESSIf scanning started. Otherwise, an error code is returned.
NRF_ERROR_NULLIf NULL pointer is passed as input.
Returns
This API propagates the error code returned by the SoftDevice API sd_ble_gap_scan_start.

Documentation feedback | Developer Zone | Subscribe | Updated