Loading...
Searching...
No Matches

Helper module to simplify the usage of NimBLE in scanning mode. More...

Detailed Description

Helper module to simplify the usage of NimBLE in scanning mode.

Files

file  nimble_scanner.h
 Scanner abstraction for NimBLE.
 

Data Structures

struct  nimble_scanner_cfg_t
 Scanner configuration parameters. More...
 
struct  nimble_scanner_info_t
 Additional information about received advertising packets. More...
 

Macros

#define NIMBLE_SCANNER_EXT_ADV   0x80
 Flag to mark type for extended advertisements.
 

Typedefs

typedef void(* nimble_scanner_cb) (uint8_t type, const ble_addr_t *addr, const nimble_scanner_info_t *info, const uint8_t *ad, size_t ad_len)
 Callback signature triggered by this module for each discovered advertising packet.
 

Enumerations

enum  { NIMBLE_SCANNER_PASSIVE = 0x01 , NIMBLE_SCANNER_LIMITED = 0x02 , NIMBLE_SCANNER_FILTER_DUPS = 0x04 , NIMBLE_SCANNER_PHY_1M = 0x10 }
 Scan procedure configuration flags. More...
 
enum  { NIMBLE_SCANNER_COMPLETE = BLE_HCI_ADV_DATA_STATUS_COMPLETE , NIMBLE_SCANNER_INCOMPLETE = BLE_HCI_ADV_DATA_STATUS_INCOMPLETE , NIMBLE_SCANNER_TRUNCATED = BLE_HCI_ADV_DATA_STATUS_TRUNCATED }
 Status flags for received advertising packets. More...
 

Functions

int nimble_scanner_init (const nimble_scanner_cfg_t *params, nimble_scanner_cb disc_cb)
 Initialize the scanner module.
 
int nimble_scanner_start (void)
 Start scanning using timing parameters configured on initialization.
 
void nimble_scanner_stop (void)
 Stop scanning.
 
static bool nimble_scanner_is_active (void)
 Get the current scanning status.
 
void nimble_scanner_set_scan_duration (int32_t duration_ms)
 Set the duration for the scanning procedure.
 

Macro Definition Documentation

◆ NIMBLE_SCANNER_EXT_ADV

#define NIMBLE_SCANNER_EXT_ADV   0x80

Flag to mark type for extended advertisements.

Definition at line 37 of file nimble_scanner.h.

Typedef Documentation

◆ nimble_scanner_cb

typedef void(* nimble_scanner_cb) (uint8_t type, const ble_addr_t *addr, const nimble_scanner_info_t *info, const uint8_t *ad, size_t ad_len)

Callback signature triggered by this module for each discovered advertising packet.

Parameters
[in]typetype of advertising packet. For legacy advertisements on of the following:
  • BLE_HCI_ADV_RPT_EVTYPE_ADV_IND
  • BLE_HCI_ADV_RPT_EVTYPE_DIR_IND
  • BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND
  • BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND
  • BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP For extended advertisements NIMBLE_SCANNER_EXT_ADV ORed with any set out of the following:
  • BLE_HCI_ADV_CONN_MASK
  • BLE_HCI_ADV_SCAN_MASK
  • BLE_HCI_ADV_DIRECT_MASK
  • BLE_HCI_ADV_SCAN_RSP_MASK
[in]addradvertising address of the source node
[in]infoadditional information about the advertiser
[in]adadvertising data
[in]ad_lenlength of ad in bytes

Definition at line 117 of file nimble_scanner.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Scan procedure configuration flags.

Enumerator
NIMBLE_SCANNER_PASSIVE 

do a passive scan

NIMBLE_SCANNER_LIMITED 

do limited discovery

NIMBLE_SCANNER_FILTER_DUPS 

filter duplicates

NIMBLE_SCANNER_PHY_1M 

scan on 1Mbit PHY

Definition at line 42 of file nimble_scanner.h.

◆ anonymous enum

anonymous enum

Status flags for received advertising packets.

Enumerator
NIMBLE_SCANNER_COMPLETE 

All fragments of a advertising message were received.

NIMBLE_SCANNER_INCOMPLETE 

The advertising message is incomplete.

NIMBLE_SCANNER_TRUNCATED 

Advertising message is truncated.

Definition at line 55 of file nimble_scanner.h.

Function Documentation

◆ nimble_scanner_init()

int nimble_scanner_init ( const nimble_scanner_cfg_t params,
nimble_scanner_cb  disc_cb 
)

Initialize the scanner module.

Parameters
[in]paramsscan parameters to use
[in]disc_cbcallback triggered of each received advertising packet
Returns
0 on success

◆ nimble_scanner_is_active()

static bool nimble_scanner_is_active ( void  )
inlinestatic

Get the current scanning status.

Returns
true if currently scanning
false if the scanner is stopped

Definition at line 154 of file nimble_scanner.h.

◆ nimble_scanner_set_scan_duration()

void nimble_scanner_set_scan_duration ( int32_t  duration_ms)

Set the duration for the scanning procedure.

     If there is an active scanning process, it will be restarted.
Parameters
[in]duration_msduration of scanning procedure in ms, set to BLE_HS_FOREVER to scan without time limit

◆ nimble_scanner_start()

int nimble_scanner_start ( void  )

Start scanning using timing parameters configured on initialization.

Note
Scanning will run for ever unless stopped or unless a different scan duration is set with nimble_scanner_set_scan_duration
Returns
0 on success
-ECANCELED on error