Features

This section describes all features that are shipped with this package.

Scenario Features

class balderhub.ble.lib.scenario_features.AdvertisementObserverFeature(**kwargs)

Bases: Feature

Base scenario-level feature that manage an Advertisement observing device. It saves all received advertisements within the AdvertisementMessage and provides them over the method AdvertisementObserverFeature.filter_advertisements().

filter_advertisements(by_mac: str | None = None, from_start_time: float | None = None, till_end_time: float | None = None) → list[balderhub.ble.lib.utils.advertisement_message.AdvertisementMessage]

This method returns all stored AdvertisementMessage that were stored over all sessions made with this feature as long as it was active.

Parameters:

by_mac – if given, this filters the messages for the given mac address
from_start_time – if given, this filters the messages for the start time - all messages that occurred after the provided timestamp will be returned (use time.perf_counter())
till_end_time – if given, this filters the messages for the end time - all messages that occurred BEFORE the provided timestamp will be returned (use time.perf_counter())

Returns:

a list with all relevant advertisement messages

is_alive() → bool

This method returns True if the observer is currently alive and False otherwise. This could be a thread or a remote device.

Returns:: True if the observer is alive, False otherwise

shutdown_observer() → None: stops and shuts down the observer

start_observer() → None: starts the observer

wait_for_new_advertisement(with_mac: str | None = None, timeout_sec=10) → AdvertisementMessage

THis message wait for a new advertisement that occurs AFTER the message call was made. If with_mac is given, it will wait explicitly for a message from the specified mac address. If no message is received within timeout_sec the method will raise a TimeoutError.

Note

Make sure to store these messages in internal buffers too, so it still is returned by AdvertisementObserverFeature.filter_advertisements() too.

Parameters:

with_mac – if given, the method will wait for a new message explicity from this mac address
timeout_sec – maximum time to wait in seconds before raising an TimeoutError

Returns:

the new advertisement message

class balderhub.ble.lib.scenario_features.BleDeviceConfig(**kwargs)

Bases: Feature

general scenario level feature for a BLE device

property mac_address: str: the device’s MAC address

class balderhub.ble.lib.scenario_features.DeviceInformationConfig(**kwargs)

Bases: BleDeviceConfig

configuration feature for testing the GattDeviceInformationServiceFeature

property firmware_revision_string: bytes | None: expected firmware revision that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property hardware_revision_string: bytes | None: expected hardware revision that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property iee11073_20601_regulatory_cert_data_list: bytes | None: expected IEE11073-20601 Regulatory Certification Data List that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property manufacturer_name_string: bytes | None: expected manufacturer name that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property model_number_string: bytes | None: expected model number that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property pnp_id: PnpIdData | None: expected PNP ID that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property serial_number_string: bytes | None: expected serial number that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property software_revision_string: bytes | None: expected software revision that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property system_id: bytes | None: expected system ID that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

property udi_for_medical: bytes | None: expected UDI for medical devices that should be transmitted within the DeviceInformation-Service (None, if this value is not expected to exist as a characteristic within the DUT)

GATT Features

class balderhub.ble.lib.scenario_features.gatt.BaseGattProfileFeature(**kwargs)

Bases: Feature

Base GATT profile feature that is used as base class for all GATT profiles within this project

class balderhub.ble.lib.scenario_features.gatt.BaseGattServiceFeature(**kwargs)

Bases: Feature

Base abstract GATT service feature which is used as base class for every GATT service feature within this project

classmethod get_expected_characteristics() → list[type[balderhub.ble.lib.utils.characteristic.Characteristic]]

Determines the expected characteristics of the GATT service

Note

This is a helper method to auto determine the characteristics based on inner classes that inherit from Characteristic.

Returns:: returns a list of expected characteristics this service feature should handle

class balderhub.ble.lib.scenario_features.gatt.GattBatteryServiceFeature(**kwargs)

Bases: BaseGattServiceFeature

GATT Service Feature for Heart-Rate-Service

class BatteryLevel(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Battery Level

message_type: alias of BatteryLevelMessage

class balderhub.ble.lib.scenario_features.gatt.GattControllerFeature(**kwargs)

Bases: Feature

Universal GATT controller feature for interacting with BLE devices that implement one or more GATT services/profiles.

exception CharacteristicNotFoundError

Bases: Exception

used when the provided characteristic was not found at the connected device

cancel_notify(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → None

This method cancels the nofify for a specific characteristic.

Parameters:: characteristic – the characteristic the notification should be canceled for

connect(mac_address: str, pair_on_connect: bool = False, timeout_discover=20, timeout_connect=60) → None

This method connects the controller to the device with the given mac address.

As soon as a connection is established, this feature is bound to the connected device. You can reconnect with another device after running the method GattControllerFeature.disconnect().

Parameters:

mac_address – the mac address of the device to connect with
pair_on_connect – True if the device should be paired directly while connecting
timeout_discover – timeout to discover the device
timeout_connect – timeout till the connection should be established

property connected_address: str | None

Returns:: returns the current connected device’s mac address or None if this feature is not connected with a device yet

disconnect(timeout=10) → None

Executed the disconnect procedure with the connected device.

Parameters:: timeout – max time till the device needs to be disconnected

discover(limit_to_address: str | None = None, timeout_discover: float = 20) → list[balderhub.ble.lib.utils.ble_device_information.BLEDeviceInformation]

Discover available devices that are in Advertising mode at the moment

Parameters:

limit_to_address – if given, the discover procedure is limited to the provided address
timeout_discover – the maximum time to discover devices (timeout, if limit_to_address is given)

Returns:

the discovered devices

fixt_make_sure_to_be_connected_to(with_address: str, restore_entry_state: bool = True) → Generator[None, None, None]

Fixture that makes sure that the BLE connection is established with the given address. If there is another connection established, the method will disconnect it and reconnect with the given address.

Note

You can use this fixture directly by using:

@balder.fixture(...)
def my_fixture(...):
    yield from feat.fixt_make_sure_to_be_connected_to(...)

Parameters:

with_address – the address to connect with
restore_entry_state – True if the previous state (either connected or disconnected) should be reestablished in the teardown part of this fixture

Returns:

the ready to use fixture generator, but without any values

fixt_make_sure_to_be_disconnected_from(with_address: str, restore_entry_state: bool = True) → Generator[None, None, None]

Fixture that makes sure that the BLE connection is disconnected before finishing the construction part of this fixture. If there is another connection established to another device like the given address, the fixture will do nothing. If it is connected to the device with the given address it will disconnect before finishing the construction part. If restore_entry_state is True, the method will reestablish the state that was given before entering this fixture.

Note

You can use this fixture directly by using:

@balder.fixture(...)
def my_fixture(...):
    yield from feat.fixt_make_sure_to_be_disconnected_from(...)

Parameters:

with_address – the address the connection should be disconnected from
restore_entry_state – True if the previous state (either connected or disconnected) should be reestablished in the teardown part of this fixture

Returns:

the ready to use fixture generator, but without any values

get_all_notify_messages_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → list[BaseGattMessageTypeT]: This method returns all received notification messages for a given characteristic. :param characteristic: the characteristic the notification needs to be from :return: a collection with all messages ordered by timestamp

property is_connected: bool

Returns:: returns True if the feature is connected with a device, otherwise False

is_notification_active(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → bool

Checks if the notification is active for the given characteristic.

Parameters:: characteristic – the characteristic that should be checked
Returns:: True if there was a nofification registered, False otherwise

read(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → BaseGattMessageTypeT

This method reads the value of a specific characteristic. It returns the related message.

Parameters:: characteristic – the characteristic to read
Returns:: the response for the given characteristic

start_notify(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → None

This method starts the notification for a specific characteristic.

Parameters:: characteristic – the characteristic the notification should be started for

unpair() → None: Unpairs the current connected device.

wait_for_a_new_message_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], timeout: float = 10) → BaseGattMessageTypeT

This method waits for a specific notification and returns as soon as it detects a new one. All buffered notification that were received before entering this method are ignored.

If there is no notification received within the given timeout, the method raises a TimeoutError.

Parameters:

characteristic – the characterisitic the notification needs to be from
timeout – the maximum time in seconds to block, if this timeout is reached the method raises a TimeoutError

Returns:

the newly received GATT message

wait_for_first_notification_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], timeout: float = 10) → BaseGattMessageTypeT

This method waits for the first notification of the given characteristic and returns it. If a message was already received before this method was called, it will be returned.

If there is no notification received within the given timeout, the method raises a TimeoutError.

Parameters:

characteristic – the characteristic the notification needs to be from
timeout – the maximum time in seconds to block, if this timeout is reached the method raises a TimeoutError

Returns:

the newly received GATT message

write(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], value: bytearray) → BaseGattMessageTypeT

This method writes the value of a specific characteristic. It returns the related response.

Parameters:

characteristic – the characteristic to write
value – the value to write

Returns:

the response from the device

write_without_response(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], value: bytearray) → None

This method writes the value of a specific characteristic. It does not return anything, because the method uses the write-without-response method.

Parameters:

characteristic – the characteristic to write
value – the value to write

class balderhub.ble.lib.scenario_features.gatt.GattDeviceInformationServiceFeature(**kwargs)

Bases: BaseGattServiceFeature

GATT Service Feature for Device-Information-Service

class FirmwareRevisionCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Firmware Revision

class HardwareRevisionCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Hardware Revision

class IeeeRegulatoryCertDataListCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the IEEE 11073-20601 Regulatory Certification Data List

class ManufacturerCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Manufacturer Name

class ModelNumberCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Model Number String

class PnpIdCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the PNP ID

class SerialNumberCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Serial Number

class SoftwareRevisionCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Software Revision

class SystemId(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the System ID

class UdiForMedicalDevicesCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the UDI for medical devices

class balderhub.ble.lib.scenario_features.gatt.GattHeartRateProfileFeature(**kwargs)

Bases: BaseGattProfileFeature

Base GATT heart rate profile feature

class balderhub.ble.lib.scenario_features.gatt.GattHeartRateServiceFeature(**kwargs)

Bases: BaseGattServiceFeature

GATT Service Feature for Heart-Rate-Service

class BodySensorLocation(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the body sensor location

message_type: alias of HeartRateServiceMessage

class MeasurementCharacteristic(uuid: ~uuid.UUID, name: str, optional: bool = False, mandatory_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, optional_properties: list[balderhub.ble.lib.utils.characteristic_property.CharacteristicProperty] = <factory>, security: list[balderhub.ble.lib.utils.characteristic_security.CharacteristicSecurity] = CharacteristicSecurity.NONE, message_type: type[balderhub.ble.lib.utils.base_gatt_message.BaseGattMessage] = <class 'balderhub.ble.lib.utils.raw_gatt_message.RawGattMessage'>)

Bases: Characteristic

characteristic representing the Heart Rate Measurement

message_type: alias of HeartRateServiceMessage

Setup Features

class balderhub.ble.lib.setup_features.BleakGattControllerFeature(**kwargs)

Bases: GattControllerFeature

bleak implementation of the feature GattControllerFeature

property adapter: str | None

Returns:: the BLE adapter to use, or None if no specific adapter should be selected (auto use)

cancel_notify(characteristic: Characteristic)

This method cancels the nofify for a specific characteristic.

Parameters:: characteristic – the characteristic the notification should be canceled for

connect(mac_address: str, pair_on_connect: bool = False, timeout_discover=20, timeout_connect=60)

This method connects the controller to the device with the given mac address.

As soon as a connection is established, this feature is bound to the connected device. You can reconnect with another device after running the method GattControllerFeature.disconnect().

Parameters:

mac_address – the mac address of the device to connect with
pair_on_connect – True if the device should be paired directly while connecting
timeout_discover – timeout to discover the device
timeout_connect – timeout till the connection should be established

property connected_address: str | None

Returns:: returns the current connected device’s mac address or None if this feature is not connected with a device yet

create_and_start_thread() → None: This method creates and starts the internal connection management thread. This method needs to be called before doing anything with this feature.

disconnect(timeout=10)

Executed the disconnect procedure with the connected device.

Parameters:: timeout – max time till the device needs to be disconnected

discover(limit_to_address: str | None = None, timeout_discover: float = 20) → list[balderhub.ble.lib.utils.ble_device_information.BLEDeviceInformation]

Discover available devices that are in Advertising mode at the moment

Parameters:

limit_to_address – if given, the discover procedure is limited to the provided address
timeout_discover – the maximum time to discover devices (timeout, if limit_to_address is given)

Returns:

the discovered devices

get_all_notify_messages_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → list[BaseGattMessageTypeT]: This method returns all received notification messages for a given characteristic. :param characteristic: the characteristic the notification needs to be from :return: a collection with all messages ordered by timestamp

is_notification_active(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → bool

Checks if the notification is active for the given characteristic.

Parameters:: characteristic – the characteristic that should be checked
Returns:: True if there was a nofification registered, False otherwise

read(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic]) → BaseGattMessageTypeT

This method reads the value of a specific characteristic. It returns the related message.

Parameters:: characteristic – the characteristic to read
Returns:: the response for the given characteristic

start_notify(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic])

This method starts the notification for a specific characteristic.

Parameters:: characteristic – the characteristic the notification should be started for

stop_and_wait_for_thread(timeout: float = 10): This method stops and cleans up the internal connection management thread. This method needs to be called to clean up all internal resources.

unpair(): Unpairs the current connected device.

wait_for_a_new_message_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], timeout: float = 10) → BaseGattMessageTypeT

This method waits for a specific notification and returns as soon as it detects a new one. All buffered notification that were received before entering this method are ignored.

If there is no notification received within the given timeout, the method raises a TimeoutError.

Parameters:

characteristic – the characterisitic the notification needs to be from
timeout – the maximum time in seconds to block, if this timeout is reached the method raises a TimeoutError

Returns:

the newly received GATT message

wait_for_first_notification_of(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], timeout: float = 10) → BaseGattMessageTypeT

This method waits for the first notification of the given characteristic and returns it. If a message was already received before this method was called, it will be returned.

If there is no notification received within the given timeout, the method raises a TimeoutError.

Parameters:

characteristic – the characteristic the notification needs to be from
timeout – the maximum time in seconds to block, if this timeout is reached the method raises a TimeoutError

Returns:

the newly received GATT message

write(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], value: bytearray)

This method writes the value of a specific characteristic. It returns the related response.

Parameters:

characteristic – the characteristic to write
value – the value to write

Returns:

the response from the device

write_without_response(characteristic: type[balderhub.ble.lib.utils.characteristic.Characteristic], value: bytearray) → None

This method writes the value of a specific characteristic. It does not return anything, because the method uses the write-without-response method.

Parameters:

characteristic – the characteristic to write
value – the value to write

class balderhub.ble.lib.setup_features.BleakAdvertisementObserverFeature(**kwargs)

Bases: AdvertisementObserverFeature

Feature implementation with bleak for AdvertisementObserverFeature

Note

This feature uses bleak as backend. Bleak does not receive every Advertisement. Consider that in mind, when using this feature.

property adapter: str | None

Returns:: the BLE adapter to use, or None if no specific adapter should be selected (auto use)

filter_advertisements(by_mac: str | None = None, from_start_time: float | None = None, till_end_time: float | None = None) → list[balderhub.ble.lib.utils.advertisement_message.AdvertisementMessage]

This method returns all stored AdvertisementMessage that were stored over all sessions made with this feature as long as it was active.

Parameters:

by_mac – if given, this filters the messages for the given mac address
from_start_time – if given, this filters the messages for the start time - all messages that occurred after the provided timestamp will be returned (use time.perf_counter())
till_end_time – if given, this filters the messages for the end time - all messages that occurred BEFORE the provided timestamp will be returned (use time.perf_counter())

Returns:

a list with all relevant advertisement messages

is_alive()

This method returns True if the observer is currently alive and False otherwise. This could be a thread or a remote device.

Returns:: True if the observer is alive, False otherwise

shutdown_observer(timeout=10): stops and shuts down the observer

start_observer(): starts the observer

wait_for_new_advertisement(with_mac: str | None = None, timeout_sec=10)

THis message wait for a new advertisement that occurs AFTER the message call was made. If with_mac is given, it will wait explicitly for a message from the specified mac address. If no message is received within timeout_sec the method will raise a TimeoutError.

Note

Make sure to store these messages in internal buffers too, so it still is returned by AdvertisementObserverFeature.filter_advertisements() too.

Parameters:

with_mac – if given, the method will wait for a new message explicity from this mac address
timeout_sec – maximum time to wait in seconds before raising an TimeoutError

Returns:

the new advertisement message