Device Scanning

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

Bluetooth Low Energy Scanner connector

class whad.ble.connector.Scanner(device)

BLE Observer interface for compatible WHAD device.

clear()

Clear device database.

discover_devices(minimal_rssi=None, filter_address=None, timeout: float = None) → Iterator[AdvertisingDevice]

Parse incoming advertisements and yield discovered devices.

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

sniff() → Iterator[Packet]

Listen and yield incoming advertising PDUs.

start()

Start the BLE scanner.

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

BLE device tracking database

Devices are tracked by the BLE scanner connector by a dedicated database, each device is then wrapped into a whad.ble.scanning.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)

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.

property name: str

Device complete or short name.

property rssi: float

Device RSSI.

property scan_rsp_records: bytes

Scan response records.

property scanned: bool

Device scanned status

seen()

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

set_scan_rsp(scan_rsp)

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)

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

Bluetooth Low Energy devices database.

This class stores information about discovered devices.

find_device(address) → AdvertisingDevice

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=None)

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)

Register or update a device.

Parameters:

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

reset()

Remove database content.