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

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

_name Name of the instance.

Enumeration Type Documentation

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.

enum nrf_ble_scan_filter_type_t

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_ctx Pointer 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_ctx Pointer to the Scanning Module instance.

Return values

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.

Note: This function does not decode an address type.

Parameters

[out]	p_gap_addr	The Bluetooth Low Energy address.
[in]	addr	Address to be converted to the SoftDevice address.

Return values

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.

Parameters

[out]	p_status	Filter status.
[in]	p_scan_ctx	Pointer to the Scanning Module instance.

Return values

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.

Parameters

[in,out]	p_scan_ctx	Pointer to the Scanning Module instance.
[in]	type	Filter type.
[in]	p_data	The filter data to add.

Return values

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.

Parameters

[in] p_scan_ctx Pointer to the Scanning Module instance.

Return values

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.

Parameters

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

Return values

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.

Parameters

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

Return values

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.

Parameters

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

Parameters

[in,out]	p_scan_ctx	Pointer to the Scanning Module instance.
[in]	p_scan_param	GAP scanning parameters. Can be initialized as NULL.

Return values

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.

Parameters

[in] p_scan_ctx Pointer to the Scanning Module instance.

Return values

NRF_SUCCESS	If scanning started. Otherwise, an error code is returned.
NRF_ERROR_NULL	If NULL pointer is passed as input.

Returns: This API propagates the error code returned by the SoftDevice API sd_ble_gap_scan_start .

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation