humble_explorer package#

HumBLE Explorer: Human-Friendly Bluetooth Low Energy Explorer.

This is a cross-platform (Windows, Linux, macOS) human-friendly program to scan for Bluetooth Low Energy (BLE) advertisements on the command line.

Submodules#

humble_explorer.app module#

Module with the Textual app that scans for Bluetooth Low Energy advertisements.

class humble_explorer.app.BLEScannerApp(cli_args: Namespace)[source]#

Bases: App[None]

A Textual app to scan for Bluetooth Low Energy advertisements.

BINDINGS: ClassVar[list[BindingType]] = [('q', 'quit', 'Quit'), ('f', 'toggle_filter', 'Filter'), ('s', 'toggle_settings', 'Settings'), ('t', 'toggle_scan', 'Toggle scan'), ('c', 'clear_advertisements', 'Clear')]#
CSS_PATH: CSSPathType | None = 'app.css'#
action_clear_advertisements() → None[source]#

Clear the list of received advertisements.

action_toggle_filter() → None[source]#

Enable or disable filter input widget.

async action_toggle_scan() → None[source]#

Start or stop BLE scanning.

action_toggle_settings() → None[source]#

Enable or disable settings widget.

add_advertisement_to_table(table: DataTable, now: RichTime, device_address: RichDeviceAddress, rich_advertisement: RichAdvertisement) → None[source]#

Add new row to table with time, address and advertisement.

Parameters:

  • table (textual.widgets.DataTable) – The table to add an advertisement to.

  • now (RichTime) – The time.

  • device_address (RichDeviceAddress) – The device address.

  • rich_advertisement (RichAdvertisement) – The advertisement.

compose() → Iterable[Widget][source]#

Create child widgets for the app.

Returns:

The child widgets for the app.

Return type:

textual.app.ComposeResult

dark: Reactive[bool]#
async on_advertisement(device: BLEDevice, advertisement_data: AdvertisementData) → None[source]#

Show advertisement data on detection of a BLE advertisement.

Parameters:
on_input_changed(message: Changed) → None[source]#

Filter advertisements with user-supplied filter.

Parameters:

message (textual.widgets.Input.Changed) – The message with the user’s changed input.

async on_mount() → None[source]#

Initialize interface and start BLE scan.

on_switch_changed(message: Changed) → None[source]#

React when the switch is ticked or unticked.

Show or hide advertisement data depending on the state of the switches.

Parameters:

message (textual.widgets.Switch.Changed) – The message with the changed switch.

recreate_table() → None[source]#

Recreate table with advertisements.

scroll_if_autoscroll() → None[source]#

Scroll to the end if autoscroll is enabled.

set_title() → None[source]#

Set the title of the app with a description of the scanning status.

show_data_config() → dict[str, bool][source]#

Return dictionary with which advertisement data to show.

Returns:

Each key has the value True if this advertisement

type should be shown and False if not.

Return type:

dict[str, bool]

async start_scan() → None[source]#

Start BLE scan.

async stop_scan() → None[source]#

Stop BLE scan.

sub_title: Reactive[str]#

The sub-title for the application.

The initial value in a running application will be that set in SUB_TITLE (if one is set). Assign new values to this instance attribute to change the sub-title.

title: Reactive[str]#

The title for the application.

The initial value in a running application will be that set in TITLE (if one is set). Assign new values to this instance attribute to change the title.

watch_address_filter(old_filter: str, new_filter: str) → None[source]#

React when the reactive attribute address_filter changes.

This recreates the table.

Parameters:

  • old_filter (str) – The old value of the filter.

  • new_filter (str) – The new value of the filter.

humble_explorer.renderables module#

Module with Rich renderables for HumBLE Explorer’s user interface.

class humble_explorer.renderables.RichAdvertisement(data: AdvertisementData, show_data: dict[str, bool])[source]#

Bases: object

Rich renderable that shows advertisement data.

height() → int[source]#

Return the number of lines this Rich renderable uses.

class humble_explorer.renderables.RichCompanyID(cic: int)[source]#

Bases: object

Rich renderable that shows company ID and name.

class humble_explorer.renderables.RichDeviceAddress(address: str)[source]#

Bases: object

Rich renderable that shows a Bluetooth device address aand OUI description.

Every address is rendered in its own color.

height() → int[source]#

Return the number of lines this Rich renderable uses.

class humble_explorer.renderables.RichHexData(data: bytes)[source]#

Bases: object

Rich renderable that shows hex data.

class humble_explorer.renderables.RichHexString(data: bytes)[source]#

Bases: object

Rich renderable that shows hex data as a string.

Non-printable characters are replaced by a dot.

class humble_explorer.renderables.RichRSSI(rssi: int)[source]#

Bases: object

Rich renderable that shows RSSI of a device.

class humble_explorer.renderables.RichTime(time: datetime)[source]#

Bases: object

Rich renderable that shows a time.

All times within the same second are rendered in the same color.

class humble_explorer.renderables.RichUUID(uuid128: str)[source]#

Bases: object

Rich renderable that shows a UUID with description and colors.

humble_explorer.utils module#

This module contains utility functions for HumBLE Explorer.

humble_explorer.utils.hash8(message: str) → int[source]#

Compute an 8-bit hash from the message with Pearson hashing.

Parameters:

message (str) – The message to hash.

Returns:

An 8-bit hash value for message.

Return type:

int

humble_explorer.widgets module#

This module contains Textual widgets for HumBLE Explorer’s user interface.

class humble_explorer.widgets.FilterWidget(placeholder: str = '')[source]#

Bases: Input

A Textual widget to filter Bluetooth Low Energy advertisements.

can_focus: bool = True#

Widget may receive focus.

can_focus_children: bool = True#

Widget’s children may receive focus.

max_size: reactive[int | None]#
on_blur() → None[source]#

Automatically hide widget on losing focus.

class humble_explorer.widgets.SettingsWidget(id: str | None)[source]#

Bases: Static

A Textual widget to let the user choose settings.

can_focus: bool = False#

Widget may receive focus.

can_focus_children: bool = True#

Widget’s children may receive focus.

compose() → Iterable[Widget][source]#

Show switches.

on_blur() → None[source]#

Automatically hide widget on losing focus.