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: ClassVar[CSSPathType | None] = 'app.css'#

File paths to load CSS from.

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]#

Use a dark theme if True, otherwise use a light theme.

Modify this attribute to switch between light and dark themes.

Example

`python self.app.dark = not self.app.dark  # Toggle dark mode `

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 for sub_title will be set to the SUB_TITLE class variable if it exists, or an empty string if it doesn’t.

Sub-titles are typically used to show the high-level state of the app, such as the current mode, or path to the file being worker on.

Assign a new value to this attribute to change the sub-title. The new value is always converted to string.

title: Reactive[str]#

The title for the application.

The initial value for title will be set to the TITLE class variable if it exists, or the name of the app if it doesn’t.

Assign a new value to this attribute to change the title. The new value is always converted to string.

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.

suggester: Suggester | None#

The suggester used to provide completions as the user types.

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() → ComposeResult[source]#

Show switches.

on_blur() → None[source]#

Automatically hide widget on losing focus.