Scanning module

The Scanning Module handles the BLE scanning for your application. You can use it to find an advertising device and establish a connection with it. The scan can be narrowed down to the device of a specific type by using filters.

The Scanning Module can work in one of the following modes:

  • simple mode without using filters, or

  • advanced mode that allows you to use advanced filters.

The module can automatically establish a connection after a filter match.

Usage

Action

Description

Initialization

The module must be initialized with bt_scan_init() that can be called without initialization structure. When initialization structure is passed as NULL, the default static configuration is used. This configuration is also used when you use an initialization structure with NULL pointers to scan parameters and connection parameters.

Starting scanning

When initialization completes, you can start scanning with bt_scan_start(). In the simplest mode when you do not using event handler, the connection can be established when scanner found device.

Changing parameters

Call the function bt_scan_params_set() to change parameters.

Stopping scanning

Call the function bt_scan_stop() to stop scanning.

Resuming scanning

Scanning stops if the module established the connection automatically, or if the application calls bt_scan_stop(). To resume scanning use bt_scan_start().

Filters

The module can set scanning filters of different type and mode.

Filters types

Filter tupe

Details

Name

Filter set to the target name.

Short name

Filter set to the short target name.

Address

Filter set to the target address.

UUID

Filter set to the target UUID.

Appearance

Filter set to the target appearance.

Filter modes

Filter mode | Behavior

Normal

Only one of the filters you set, regardless of the type, must be matched to call filter match callback

Multifilter

In this mode, at least one filter from each filter type you set must be matched to call filter match callback, with UUID as an exception: all specified UUIDs must match in this mode.

Example: Several filters are set for name, address, UUID, and appearance. To call filter match callback, the following types must match:

  • one of the address filters,

  • one of the name filters,

  • one of the appearance filters,

  • all of the UUID filters.

Otherwise, the not found callback is called.

Directed Advertising

To support receiving Directed Advertising packets with the Scanning Module, enable one of the following options in Zephyr:

It is recommended to use the privacy option. When privacy is enabled directed advertising is only supported from bonded peers. Use scanning with identity only when scanning with privacy is not possible.

When Filters are set, you can use the proprietary filter_no_match event to handle Directed Advertising. This event checks whether the Directed Advertising packets do not match any filters. In case of a positive verification, you can establish connection without the need to disable or reconfigure the existing filters.

The following code sample demonstrates the filter_no_match event:

static void scan_filter_no_match(struct bt_scan_device_info *device_info,
				 bool connectable)
{
	struct bt_conn *conn;
	char addr[BT_ADDR_LE_STR_LEN];

	if (device_info->adv_info.adv_type == BT_LE_ADV_DIRECT_IND) {
		bt_addr_le_to_str(device_info->addr, addr, sizeof(addr));
		printk("Direct advertising received from %s\n", addr);
		bt_scan_stop();

		conn = bt_conn_create_le(device_info->addr,
					 device_info->conn_param);

		if (conn) {
			default_conn = bt_conn_ref(conn);
			bt_conn_unref(conn);
		}
	}
}

API documentation

Header file: include/bluetooth/scan.h
Source file: subsys/bluetooth/scan.c
group nrf_bt_scan

BT Scanning module.

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. The module can also be configured to automatically connect after it matches a filter.

Note

The Scanning Module also supports applications with a multicentral link.

Defines

BT_SCAN_CB_INIT(_name, match_fun, no_match_fun, error_fun, connecting_fun)

Initializing macro for scanning module.

This is macro initializing necessary structures for bt_scan_cb type.

Parameters
  • [in] _name: Unique name for bt_scan_cb structure.

  • [in] match_fun: Scan filter matched function pointer.

  • [in] no_match_fun: Scan filter unmatched (the device was not found) function pointer.

  • [in] error_fun: Error when connecting function pointer.

  • [in] connecting_fun: Connecting data function pointer.

Enums

enum bt_scan_type

Scan types.

Values:

BT_SCAN_TYPE_SCAN_PASSIVE

Active scanning.

BT_SCAN_TYPE_SCAN_ACTIVE

Passive scanning.

enum bt_scan_filter_type

Types of filters.

Values:

BT_SCAN_FILTER_TYPE_NAME

Filter for names.

BT_SCAN_FILTER_TYPE_SHORT_NAME

Filter for short names.

BT_SCAN_FILTER_TYPE_ADDR

Filter for addresses.

BT_SCAN_FILTER_TYPE_UUID

Filter for UUIDs.

BT_SCAN_FILTER_TYPE_APPEARANCE

Filter for appearances.

BT_SCAN_FILTER_TYPE_MANUFACTURER_DATA

Filter for manufacturer data.

Functions

void bt_scan_cb_register(struct bt_scan_cb *cb)

Register scanning callbacks.

Register callbacks to monitor the state of scanning.

Parameters
  • cb: Callback struct.

void bt_scan_init(const struct bt_scan_init_param *init)

Function for initializing the Scanning Module.

Parameters
  • [in] init: Pointer to scanning module initialization structure. 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.

int bt_scan_start(enum bt_scan_type scan_type)

Function for starting scanning.

This function starts the scanning according to the configuration set during the initialization.

Return

0 If the operation was successful. Otherwise, a (negative) error code is returned.

Parameters
  • [in] scan_type: The choice between active and passive scanning.

int bt_scan_stop(void)

Function for stopping scanning.

void bt_scan_update_init_conn_params(struct bt_le_conn_param *new_conn_param)

Function to update initial connection parameters.

Note

The function should not be used when scanning is active.

Parameters
  • [in] new_conn_param: New initial connection parameters.

int bt_scan_filter_enable(u8_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, (BT_SCAN_NAME_FILTER | BT_SCAN_UUID_FILTER) enables UUID and name filters.

Return

0 If the operation was successful. Otherwise, a (negative) error code is returned.

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 BT_SCAN_EVT_FILTER_MATCH to the main application. Otherwise, it is enough to match one filter to trigger the filter match event.

void bt_scan_filter_disable(void)

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.

int bt_scan_filter_status(struct bt_filter_status *status)

Function for getting filter status.

This function returns the filter setting and whether it is enabled or disabled.

Return

0 If the operation was successful. Otherwise, a (negative) error code is returned.

Parameters
  • [out] status: Pointer to Filter Status structure.

int bt_scan_filter_add(enum bt_scan_filter_type type, const void *data)

Function for adding any type of filter to the scanning.

This function adds a new filter by type. The filter will be added if there is available space in this filter type array, and if the same filter has not already been set.

Return

0 If the operation was successful. Otherwise, a (negative) error code is returned.

Parameters
  • [in] type: Filter type.

  • [in] data: Pointer to The filter data to add.

void bt_scan_filter_remove_all(void)

Function for removing all set filters.

The function removes all previously set filters.

Note

After using this function the filters are still enabled.

int bt_scan_params_set(struct bt_le_scan_param *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 bt_scan_start. Scanning parameters can be set to NULL. If so, the default static configuration is used.

Return

0 If the operation was successful. Otherwise, a (negative) error code is returned.

Parameters
  • [in] scan_param: Pointer to Scanning parameters. Can be initialized as NULL.

struct bt_scan_filter_info
#include <scan.h>

Filter information structure.

It contains information about the number of filters of a given type and whether they are enabled

Public Members

bool enabled

Filter enabled.

u8_t cnt

Filter count.

struct bt_filter_status
#include <scan.h>

Filter status structure.

Public Members

bool all_mode

Filter mode.

struct bt_scan_filter_info name

Name filters info.

struct bt_scan_filter_info short_name

Short name filters info.

struct bt_scan_filter_info addr

Address filters info.

struct bt_scan_filter_info uuid

UUID filters info.

struct bt_scan_filter_info appearance

Appearance filter info.

struct bt_scan_filter_info manufacturer_data

Appearance filter info.

struct bt_scan_adv_info
#include <scan.h>

Advertising info structure.

Public Members

u8_t adv_type

BLE advertising type. According to Bluetooth Specification 7.8.5

s8_t rssi

Received Signal Strength Indication in dBm.

struct bt_scan_short_name
#include <scan.h>

A helper structure to set filters for the name.

Public Members

const char *name

Pointer to the short name.

u8_t min_len

Minimum length of the short name.

struct bt_scan_manufacturer_data
#include <scan.h>

A helper structure to set filters for the manufacturer data.

Public Members

u8_t *data

Pointer to the manufacturer data.

u8_t data_len

Manufacturer data length.

struct bt_scan_init_param
#include <scan.h>

Structure for Scanning Module initialization.

Public Members

const struct bt_le_scan_param *scan_param

Scan parameters required to initialize the module. Can be initialized as NULL. If NULL, the parameters required to initialize the module are loaded from the static configuration.

bool connect_if_match

If set to true, the module automatically connects after a filter match.

const struct bt_le_conn_param *conn_param

Connection parameters. Can be initialized as NULL. If NULL, the default static configuration is used.

struct bt_scan_name_filter_status
#include <scan.h>

Name filter status structure, used to inform the application which name filter is matched.

Public Members

bool match

Set to true if this type of filter is matched.

const char *name

Pointer to the matched filter name.

u8_t len

Length of the matched name.

struct bt_scan_addr_filter_status
#include <scan.h>

Address filter status structure, used to inform the application which address filter is matched.

Public Members

bool match

Set to true if this type of filter is matched.

const bt_addr_le_t *addr

Pointer to the matched filter address.

struct bt_scan_uuid_filter_status
#include <scan.h>

UUID filter status structure, used to inform the application which UUID filters are matched.

Public Members

bool match

Set to true if this type of filter is matched.

const struct bt_uuid *uuid[1]

Array of pointers to the matched UUID filters.

u8_t count

Matched UUID count.

struct bt_scan_appearance_filter_status
#include <scan.h>

Appearance filter status structure, used to inform the application which appearance filter is matched.

Public Members

bool match

Set to true if this type of filter is matched.

const u16_t *appearance

Pointer to the matched filter appearance.

struct bt_scan_manufacturer_data_filter_status
#include <scan.h>

Manufacturer data filter status structure, used to inform the application which manufacturer data filter is matched.

Public Members

bool match

Set to true if this type of filter is matched.

const u8_t *data

Pointer to the matched filter manufacturer data.

u8_t len

Length of the matched manufacturer data.

struct bt_scan_filter_match
#include <scan.h>

Structure for setting the filter status.

This structure is used for sending filter status to the main application. Filter status contains information about which kind of filter is matched and also appropriate filter data.

Public Members

struct bt_scan_name_filter_status name

Name filter status data.

struct bt_scan_name_filter_status short_name

Short name filter status data.

struct bt_scan_addr_filter_status addr

Address filter status data.

struct bt_scan_uuid_filter_status uuid

UUIDs filter status data.

struct bt_scan_appearance_filter_status appearance

Appearance filter status data.

struct bt_scan_manufacturer_data_filter_status manufacturer_data

Manufacturer data filter status data.

struct bt_scan_device_info
#include <scan.h>

Structure containing device data needed to establish connection and advertising information.

Public Members

struct bt_scan_adv_info adv_info

Information about advertising.

const bt_addr_le_t *addr

Pointer to device BLE address.

const struct bt_le_conn_param *conn_param

Connection parameters for LE connection.

struct net_buf_simple *adv_data

Received advertising data. If further data proccesing is needed, you should use bt_data_parse to get specific advertising data type.

struct cb_data
#include <scan.h>

Data for scanning callback structure.

This structure is used for storing callback functions pointers. It is used by bt_scan_cb structure.

Public Members

void (*filter_match)(struct bt_scan_device_info *device_info, struct bt_scan_filter_match *filter_match, bool connectable)

Scan filter matched.

Parameters
  • [in] device_info: Data needed to establish connection and advertising information.

  • [in] filter_match: Filter match status.

  • [in] connectable: Inform that device is connectable.

void (*filter_no_match)(struct bt_scan_device_info *device_info, bool connectable)

Scan filter unmatched. The device was not found.

Note

Even if the filters are disable and not set, then all devices will be reported by this callback. It can be useful if the scan is used without filters.

Parameters
  • [in] device_info: Data needed to establish connection and advertising information.

  • [in] connectable: Inform that device is connectable.

void (*connecting_error)(struct bt_scan_device_info *device_info)

Error when connecting.

Parameters
  • [in] device_info: Data needed to establish connection and advertising information.

void (*connecting)(struct bt_scan_device_info *device_info, struct bt_conn *conn)

Connecting data.

Parameters
  • [in] device_info: Data needed to establish connection and advertising information.

  • [in] conn: Connection object.

struct bt_scan_cb
#include <scan.h>

Scanning callback structure.

This structure is used for tracking the state of a scanning. It is registered with the help of the bt_scan_cb_register() API. It’s permissible to register multiple instances of this bt_scan_cb type, in case different modules of an application are interested in tracking the scanning state. If a callback is not of interest for an instance, it may be set to NULL and will as a consequence not be used for that instance.