NimBLEScan Class Reference

Perform and manage BLE scans. More...

#include <NimBLEScan.h>

Public Member Functions
bool	start (uint32_t duration, bool isContinue=false, bool restart=true)
	Start scanning.
bool	isScanning ()
	Get the status of the scanner.
void	setScanCallbacks (NimBLEScanCallbacks *pScanCallbacks, bool wantDuplicates=false)
	Set the call backs to be invoked.
void	setActiveScan (bool active)
	Should we perform an active or passive scan? The default is a passive scan. An active scan means that we will request a scan response.
void	setInterval (uint16_t intervalMs)
	Set the interval to scan.
void	setWindow (uint16_t windowMs)
	Set the window to actively scan.
void	setDuplicateFilter (uint8_t enabled)
	Set whether or not the BLE controller should only report results from devices it has not already seen.
void	setLimitedOnly (bool enabled)
	Set whether or not the BLE controller only reports scan results from devices advertising in limited discovery mode.
void	setFilterPolicy (uint8_t filter)
	Sets the scan filter policy.
bool	stop ()
	Stop an in progress scan.
void	clearResults ()
	Clear the stored results of the scan.
NimBLEScanResults	getResults ()
	Get the results of the scan.
NimBLEScanResults	getResults (uint32_t duration, bool is_continue=false)
	Start scanning and block until scanning has been completed.
void	setMaxResults (uint8_t maxResults)
	Sets the max number of results to store.
void	erase (const NimBLEAddress &address)
	Delete peer device from the scan results vector.
void	erase (const NimBLEAdvertisedDevice *device)
	Delete peer device from the scan results vector.
void	setPhy (Phy phyMask)
	Set the PHYs to scan.
void	setPeriod (uint32_t periodMs)
	Set the extended scanning period.

Detailed Description

Perform and manage BLE scans.

Scanning is associated with a BLE client that is attempting to locate BLE servers.

Member Function Documentation

erase() [1/2]

void NimBLEScan::erase

(

const NimBLEAddress &

address

)

Delete peer device from the scan results vector.

Parameters

[in]

address

The address of the device to delete from the results.

erase() [2/2]

void NimBLEScan::erase

(

const NimBLEAdvertisedDevice *

device

)

Delete peer device from the scan results vector.

Parameters

[in]

device

The device to delete from the results.

getResults() [1/2]

NimBLEScanResults NimBLEScan::getResults

(

)

Get the results of the scan.

Returns

NimBLEScanResults object.

getResults() [2/2]

NimBLEScanResults NimBLEScan::getResults	(	uint32_t	duration,
		bool	is_continue = false
	)

Start scanning and block until scanning has been completed.

Parameters

[in]	duration	The duration in milliseconds for which to scan.
[in]	is_continue	Set to true to save previous scan results, false to clear them.

Returns

The scan results.

isScanning()

bool NimBLEScan::isScanning

(

)

Get the status of the scanner.

Returns

true if scanning or scan starting.

setActiveScan()

void NimBLEScan::setActiveScan

(

bool

active

)

Should we perform an active or passive scan? The default is a passive scan. An active scan means that we will request a scan response.

Parameters

[in]

active

If true, we perform an active scan otherwise a passive scan.

setDuplicateFilter()

void NimBLEScan::setDuplicateFilter

(

uint8_t

enabled

)

Set whether or not the BLE controller should only report results from devices it has not already seen.

Parameters

[in]

enabled

If set to 1 (true), scanned devices will only be reported once. If set to 0 duplicates will be reported each time they are seen. If using extended scanning this can be set to 2 which will reset the duplicate filter at the end of each scan period if the scan period is set.

Note

The controller has a limited buffer and will start reporting duplicate devices once the limit is reached.

setFilterPolicy()

void NimBLEScan::setFilterPolicy

(

uint8_t

filter

)

Sets the scan filter policy.

Parameters

[in]

filter

Can be one of: BLE_HCI_SCAN_FILT_NO_WL (0) Scanner processes all advertising packets (white list not used) except directed, connectable advertising packets not sent to the scanner. BLE_HCI_SCAN_FILT_USE_WL (1) Scanner processes advertisements from white list only. A connectable, directed advertisement is ignored unless it contains scanners address. BLE_HCI_SCAN_FILT_NO_WL_INITA (2) Scanner process all advertising packets (white list not used). A connectable, directed advertisement shall not be ignored if the InitA is a resolvable private address. BLE_HCI_SCAN_FILT_USE_WL_INITA (3) Scanner process advertisements from white list only. A connectable, directed advertisement shall not be ignored if the InitA is a resolvable private address.

setInterval()

void NimBLEScan::setInterval

(

uint16_t

intervalMs

)

Set the interval to scan.

Parameters

[in]

intervalMs

The scan interval in milliseconds.

The interval is the time between the start of two consecutive scan windows. When a new interval starts the controller changes the channel it's scanning on.

setLimitedOnly()

void NimBLEScan::setLimitedOnly

(

bool

enabled

)

Set whether or not the BLE controller only reports scan results from devices advertising in limited discovery mode.

Parameters

[in]

enabled

If true, only limited discovery devices will be in scan results.

setMaxResults()

void NimBLEScan::setMaxResults

(

uint8_t

maxResults

)

Sets the max number of results to store.

Parameters

[in]

maxResults

The number of results to limit storage to 0 == none (callbacks only) 0xFF == unlimited, any other value is the limit.

setPeriod()

void NimBLEScan::setPeriod

(

uint32_t

periodMs

)

Set the extended scanning period.

Parameters

[in]

periodMs

The scan period in milliseconds

The period is the time between the start of two consecutive scan periods. This works as a timer to restart scanning at the specified amount of time in periodMs.

Note

The duration used when this is set must be less than period.

setPhy()

void NimBLEScan::setPhy

(

Phy

phyMask

)

Set the PHYs to scan.

Parameters

[in]

phyMask

The PHYs to scan, a bit mask of: NIMBLE_CPP_SCAN_1M NIMBLE_CPP_SCAN_CODED

setScanCallbacks()

void NimBLEScan::setScanCallbacks	(	NimBLEScanCallbacks *	pScanCallbacks,
		bool	wantDuplicates = false
	)

Set the call backs to be invoked.

Parameters

[in]	pScanCallbacks	Call backs to be invoked.
[in]	wantDuplicates	True if we wish to be called back with duplicates, default: false.

setWindow()

void NimBLEScan::setWindow

(

uint16_t

windowMs

)

Set the window to actively scan.

Parameters

[in]

windowMs

How long during the interval to actively scan in milliseconds.

start()

bool NimBLEScan::start	(	uint32_t	duration,
		bool	isContinue = false,
		bool	restart = true
	)

Start scanning.

Parameters

[in]	duration	The duration in milliseconds for which to scan. 0 == scan forever.
[in]	isContinue	Set to true to save previous scan results, false to clear them.
[in]	restart	Set to true to restart the scan if already in progress. this is useful to clear the duplicate filter so all devices are reported again.

Returns

True if scan started or false if there was an error.

stop()

bool NimBLEScan::stop

(

)

Stop an in progress scan.

Returns

True if successful.