BLE Low-Level Interfaces

There are two main BLE interfaces that can be used for low-level interaction: BLEScanner and BLEClient. They represent the advertising and connection phases of a BLE connection.

BLE Scanner

The BLEScanner interface is used to gather information about currently advertising devices and their advertised services. Scanning for devices is done via the BLEScanner.find_devices() function which returns a list of BLEAdvertisingDevice objects.

BLEScanner

Provides a scanner interface to the gateway's BLE stack.

find_devices(timeout=5.0, verbose=True, filter=None) async staticmethod

Find devices via a BLE scan. Timeout optionally provided. Note that this function is asynchronous via the built-in asyncio library. See the example project ble_device_scan for usage and testing examples.

Parameters:

Name	Type	Description	Default
timeout	float	Timeout limit of scan operation	5.0
verbose	bool	Verbosity flag	True
filter	Callable[[BLEAdvertisingDevice], bool]	Filter function called for every scanned device (return True to accept a device)	None

Returns:

Type	Description
list[BLEAdvertisingDevice]	List of found devices

BLE Client

The BLEClient class is used to represent a client during the connection phase. It has methods used for performing basic GATT operations.

BLEClient

Provides an interface to the gateway's BLE stack.

__init__(address_or_device)

Construct a new BLE Client object.

Parameters:

Name	Type	Description	Default
address_or_device		Client address to connect to, or BLEAdvertisingDevice object reference	required

_notification_callback(characteristic, value)

Private method to translate the backend's notify callback into a consistent interface that remains the same, even if the BLE backend changes.

connect(timeout=10, retry_count=5) async

Attempt to connect the client

Parameters:

Name	Type	Description	Default
timeout	float	Timeout limit of scan operation	10
retry_count	int	Number of times to attempt to connect in case of failure	5

Returns:

Type	Description
bool	True on success, false otherwise

disconnect() async

Attempt to disconnect the client

Returns:

Type	Description
bool	True on success, false otherwise

get_notified_uuids()

Return a list of the UUIDs that are currently subscribed for notifications

is_connected()

Return an is_connected future

Returns:

Type	Description
bool	True on connected, false otherwise

lookup_uuid_name(char_uuid)

Return the standard name for a given 16 bit UUID

Parameters:

Name	Type	Description	Default
char_uuid	str	16bit UUID of characteristic	required

read_gatt(char_uuid) async

Read a GATT characteristic value by UUID

Parameters:

Name	Type	Description	Default
char_uuid	str	Full UUID of characteristic	required

Returns:

Type	Description
bytearray	Characteristic value

start_notify(char_uuid, callback) async

Start listening for notifications on a given characteristic.

Parameters:

Name	Type	Description	Default
char_uuid	str	Full UUID of characteristic	required
callback		Callback that accepts two parameters: The first is the UUID of the characteristic, the second is the received data	required

write_gatt(char_uuid, data, response=False) async

Write to a GATT characteristic by UUID

Parameters:

Name	Type	Description	Default
char_uuid	str	Full UUID of characteristic	required
data		Data to be written	required
response		True if write-with-response is desired, False if write-without-response, None for autodetect	False

BLE Types

BLE type definitions and models used by BLEInterface.

BLEAdvertisingDevice

Represents a device that is advertising.

address = address instance-attribute

Address of device

name = name instance-attribute

Name of device

rssi = rssi instance-attribute

RSSI of device

service_uuids = service_uuids instance-attribute

List of advertised service UUIDs