Device Scanning

Bluetooth Low Energy scanning is provided by a dedicated connector, Scanner, that drives a BLE-enable WHAD device to detect any available BLE device. This connector relies on an internal database implemented in AdvertisingDevicesDB that keeps track of every detected device.

Discovering devices with this connector is pretty simple:

from whad.device import Device
from whad.ble import Scanner

# Access hardware interface hci0
dev = Device.create("hci0")

# Scan for devices for 30 seconds
with Scanner(dev) as scanner:
    for device in scanner.discover_devices(timeout=30.0):
        print(device)

Note

It is recommended to use the Scanner connector within a with statement for proper device initialization and cleanup.

By default, discover_devices yields a AdvertisingDevice object only once each time a new device is detected, to avoid a device to be reported multiple times. This behavior can be changed by setting its optional parameter updates to True, forcing this method to continuously yield updated AdvertisingDevice objects no matter if they are new devices detected or previously reported. Deduplication and processing is then left to the caller.

The following code shows a scanner that implements this feature and will continuously report all detected devices:

from whad.device import Device
from whad.ble import Scanner

# Access hardware interface hci0
dev = Device.create("hci0")

# Scan for devices for 30 seconds, asks for updated information
with Scanner(dev) as scanner:
    for device in scanner.discover_devices(timeout=30.0, updates=True):
        print(device)

Bluetooth Low Energy Scanner connector

class whad.ble.connector.Scanner(device)[source]

BLE Observer interface for compatible WHAD device.

clear()[source]

Clear device database.

discover_devices(minimal_rssi=None, filter_address=None, timeout: float | None = None, updates: bool = False) → Iterator[AdvertisingDevice][source]

Parse incoming advertisements and yield discovered devices. If updates is set to True, all discovered devices will be reported with updated information.

Parameters:

  • minimal_rssi (float, optional) – Minimal RSSI level

  • filter_address (whad.ble.bdaddr.BDAddress, optional) – BD address of a device to discover

  • timeout (float, optional) – Timeout in seconds

  • updates (bool) – Enable/disable reporting updated information about already discovered devices

sniff(messages: List | None = None, timeout: float | None = None) → Iterator[Packet][source]

Listen and yield incoming advertising PDUs.

start() → bool[source]

Start the BLE scanner.

Calling this method resets the discovered devices database and put the WHAD device into BLE scanning mode.

stop() → bool[source]

Stop scanning.

Stop scanning for devices, disable scan mode if used.

BLE device tracking database

Devices are tracked by the BLE scanner connector by a dedicated database, each device is then wrapped into a AdvertisingDevice instance that holds all the interesting information.

class whad.ble.scanning.AdvertisingDevice(rssi, address_type, bd_address, adv_data, rsp_data=None, undirected=True, connectable=True)[source]

Store information about a device:

  • Received Signal Strength Indicator (RSSI)

  • Address type (public or random)

  • Advertising data

  • Scan response data

  • Type of advertising PDU

  • Connectable information

property ad_records: AdvDataFieldList

Combined advertising and scan response records.

property address: str

Device BD address.

property address_type: int

Device address type.

property adv_records: bytes

Advertising records.

property connectable: bool

Connectable status.

property got_scan_rsp: bool

Received a scan response from device.

property last_seen: float

Device last seen timestamp.

mark_reported()[source]

Mark device as reported (avoid duplicates)

property name: str

Device complete or short name.

property reported: bool

Reported status

property rssi: float

Device RSSI.

property scan_rsp_records: bytes

Scan response records.

property scanned: bool

Device scanned status

seen()[source]

Mark device as seen (update last_seen value with current time).

set_scan_rsp(scan_rsp)[source]

Update device advertisement data.

Parameters:

scan_rsp (bytes) – Raw scan response.

property timestamp: float

Device discovery timestamp.

update(rssi: float = None, adv_data: bytes = None)[source]

Update device RSSI and advertising data and check for scan response timeout.

Parameters:

  • rssi (float) – New RSSI value.

  • adv_data (bytes) – New advertising data

class whad.ble.scanning.AdvertisingDevicesDB[source]

Bluetooth Low Energy devices database.

This class stores information about discovered devices.

find_device(address: str) → AdvertisingDevice[source]

Find a device based on its BD address.

Parameters:

address (str) – Device BD address

Returns:

Device if found, None otherwise.

Return type:

whad.ble.scanning.AdvertisingDevice

on_device_found(rssi, adv_packet, filter_addr: str | None = None, updates: bool = False)[source]

Device advertising packet or scan response received.

Parse the incoming packet and handle device appropriately.

Parameters:

  • rssi (float) – Received Signal Strength Indicator

  • adv_packet (scapy.packet.Packet) – Advertising packet

  • filter_addr (str) – BD address to filter

register_device(device, update: bool = False) → bool[source]

Register or update a device.

Parameters:

device (whad.ble.scanning.AdvertisingDevice) – Device to register.

reset()[source]

Remove database content.