src.bluetooth_sig.advertising.registry¶

Registry for advertising data interpreter routing.

Attributes¶

Name	Description
`logger`
`payload_interpreter_registry`

Classes¶

Name	Description
`PayloadContext`	Context information for payload interpretation.
`PayloadInterpreterRegistry`	Routes advertisements to PayloadInterpreter classes.

Functions¶

Name	Description
`parse_advertising_payloads`(→ list[Any])	Auto-discover and parse all payloads in an advertisement.

Module Contents¶

class src.bluetooth_sig.advertising.registry.PayloadContext¶

Bases: msgspec.Struct

Context information for payload interpretation.

mac_address: str¶

rssi: int | None = None¶

timestamp: float | None = None¶

class src.bluetooth_sig.advertising.registry.PayloadInterpreterRegistry¶

Routes advertisements to PayloadInterpreter classes.

Does NOT manage interpreter instances or state - caller owns those. Only handles class registration and lookup.

_by_service_uuid¶: Interpreters indexed by service UUID.

_by_company_id¶: Interpreters indexed by company ID.

_fallback¶: Interpreters that match by custom logic only.

clear() → None¶: Clear all registered interpreters.

find_all_interpreter_classes(advertising_data: bluetooth_sig.advertising.base.AdvertisingData) → list[type[bluetooth_sig.advertising.base.PayloadInterpreter[Any]]]¶

Find all interpreter classes that handle this advertisement.

Useful when multiple protocols coexist in one advertisement (e.g., BTHome + Xiaomi UUIDs).

Parameters:: advertising_data – Complete advertising data from BLE packet.
Returns:: List of all matching interpreter classes.

find_interpreter_class(advertising_data: bluetooth_sig.advertising.base.AdvertisingData) → type[bluetooth_sig.advertising.base.PayloadInterpreter[Any]] | None¶

Find first interpreter class that handles this advertisement.

Parameters:: advertising_data – Complete advertising data from BLE packet.
Returns:: First matching interpreter class, or None if no match.

get_registered_interpreters() → list[type[bluetooth_sig.advertising.base.PayloadInterpreter[Any]]]¶

Get all registered interpreter classes.

Returns:: List of all registered interpreter classes (deduplicated).

register(interpreter_class: type[bluetooth_sig.advertising.base.PayloadInterpreter[Any]]) → None¶

Called automatically by PayloadInterpreter.__init_subclass__.

Parameters:: interpreter_class – The interpreter class to register.

unregister(interpreter_class: type[bluetooth_sig.advertising.base.PayloadInterpreter[Any]]) → None¶

Unregister an interpreter class.

Parameters:: interpreter_class – The interpreter class to unregister.

src.bluetooth_sig.advertising.registry.parse_advertising_payloads(manufacturer_data: dict[int, bytes], service_data: dict[bluetooth_sig.types.uuid.BluetoothUUID, bytes], context: PayloadContext, state: bluetooth_sig.advertising.state.DeviceAdvertisingState | None = None, *, registry: PayloadInterpreterRegistry | None = None) → list[Any]¶

Auto-discover and parse all payloads in an advertisement.

This is the high-level “just parse everything” API. Finds all matching interpreters and parses their payloads.

Parameters:

manufacturer_data – Company ID → payload bytes mapping.
service_data – Service UUID → payload bytes mapping.
context – Advertisement context (MAC address, RSSI, timestamp).
state – Current device advertising state (optional, created if None).
registry – Interpreter registry to use (defaults to global registry).

Returns:

List of parsed data from all matching interpreters. Failed interpretations are silently skipped (exceptions logged).

Example::

from bluetooth_sig.advertising import parse_advertising_payloads, PayloadContext

context = PayloadContext(mac_address=”AA:BB:CC:DD:EE:FF”, rssi=-60) results = parse_advertising_payloads(

manufacturer_data={0x038F: xiaomi_bytes}, service_data={BTHOME_UUID: bthome_bytes}, context=context,

)

for data in results:: print(f”Parsed {data}”)

src.bluetooth_sig.advertising.registry.logger¶

src.bluetooth_sig.advertising.registry.payload_interpreter_registry¶