src.bluetooth_sig.device.advertising

Advertising-related functionality for Device.

Manages advertising packet interpretation for a BLE device using the composition pattern. This class is accessed via device.advertising.

Based on patterns from bleak (BLEDevice + BleakClient) and real-world implementations (BTHome-BLE, Xiaomi-BLE).

Error Handling:

Methods raise exceptions instead of returning status codes. This is consistent with GATT characteristic parsing and Pythonic patterns.

Exceptions:

EncryptionRequiredError: Payload encrypted, no bindkey available DecryptionFailedError: Decryption failed (wrong key or corrupt data) AdvertisingParseError: General parse failure (includes “no interpreter found”)

Attributes

Name

Description

T

logger

Classes

Name

Description

DeviceAdvertising

Manages advertising packet interpretation for a device.

Module Contents

class src.bluetooth_sig.device.advertising.DeviceAdvertising(mac_address: str, connection_manager: bluetooth_sig.device.connection.ConnectionManagerProtocol)

Manages advertising packet interpretation for a device.

Accessed via device.advertising.

state

Current advertising state (caller-owned, mutable).

mac_address

Device MAC address.

Example

device = Device(mac_address=”AA:BB:CC:DD:EE:FF”, translator=translator)

# Set bindkey for encrypted advertisements device.advertising.set_bindkey(bytes.fromhex(“0102030405060708090a0b0c0d0e0f10”))

# Subscribe to continuous advertisement updates def on_advertisement(ad_data: AdvertisementData, data: Any) -> None:

if data is not None:

print(f”Sensor data: {data}”)

device.advertising.subscribe(on_advertisement)

# Later, unsubscribe device.advertising.unsubscribe(on_advertisement)

# Or process single advertisement manually ad_data = AdvertisingData(

manufacturer_data={}, service_data={BluetoothUUID(“0000fcd2-…”): payload}, rssi=-60,

) try:

data = device.advertising.process(ad_data) print(f”Sensor data: {data}”)

except EncryptionRequiredError:

print(“Need bindkey”)

except AdvertisingParseError as e:

print(f”Parse error: {e}”)

get_interpreter(name: str) → bluetooth_sig.advertising.base.PayloadInterpreter[object] | None

Get an interpreter by name.

Parameters:

name – Interpreter name.

Returns:

PayloadInterpreter instance if found, None otherwise.

parse_raw_pdu(raw_data: bytes, rssi: int = ..., *, interpreter: type[bluetooth_sig.advertising.base.PayloadInterpreter[T]]) → tuple[bluetooth_sig.types.advertising.result.AdvertisementData, T]
parse_raw_pdu(raw_data: bytes, rssi: int = ...) → tuple[bluetooth_sig.types.advertising.result.AdvertisementData, object | None]

Parse raw advertising PDU bytes directly.

Parameters:

  • raw_data – Raw BLE advertising PDU bytes

  • rssi – Received signal strength in dBm

  • interpreter – Interpreter class for type-safe parsing (optional).

Returns:

Tuple of (parsed AdvertisementData, interpreted data or None)

process(advertising_data: bluetooth_sig.advertising.base.AdvertisingData, *, interpreter: type[bluetooth_sig.advertising.base.PayloadInterpreter[T]]) → T
process(advertising_data: bluetooth_sig.advertising.base.AdvertisingData) → object

Process an advertising payload.

Type-safe path: Pass an interpreter class to get typed return.

Parameters:

  • advertising_data – Complete advertising data from BLE packet.

  • interpreter – Interpreter class for type-safe parsing (recommended).

Returns:

Parsed data from the interpreter. Return type is inferred when passing interpreter class, otherwise returns object.

Raises:

Example

# Type-safe: IDE knows return type is BTHomeData data = device.advertising.process(ad_data, interpreter=BTHomeInterpreter)

# Auto-detect: returns object data = device.advertising.process(ad_data)

process_from_connection_manager(advertisement: bluetooth_sig.types.advertising.result.AdvertisementData, *, interpreter: type[bluetooth_sig.advertising.base.PayloadInterpreter[T]]) → tuple[bluetooth_sig.types.advertising.result.AdvertisementData, T]
process_from_connection_manager(advertisement: bluetooth_sig.types.advertising.result.AdvertisementData) → tuple[bluetooth_sig.types.advertising.result.AdvertisementData, object | None]

Process advertisement from connection manager.

Parameters:

  • advertisement – AdvertisementData from connection manager

  • interpreter – Interpreter class for type-safe parsing (optional).

Returns:

Tuple of (processed AdvertisementData, interpreted data or None)

register_interpreter(name: str, interpreter: bluetooth_sig.advertising.base.PayloadInterpreter[object]) → None

Register a named interpreter.

Parameters:

  • name – Unique name for the interpreter.

  • interpreter – PayloadInterpreter instance.

set_bindkey(bindkey: bytes) → None

Set the encryption bindkey for decryption.

Parameters:

bindkey – 16-byte AES-CCM key.

set_registry(registry: bluetooth_sig.advertising.registry.PayloadInterpreterRegistry) → None

Set the interpreter registry for auto-detection.

Parameters:

registry – PayloadInterpreterRegistry to use for interpreter lookup.

subscribe(callback: Callable[[bluetooth_sig.types.advertising.result.AdvertisementData, object], None]) → None

Subscribe to continuous advertisement updates.

Registers a callback that will be invoked whenever new advertisements are received. Automatically enables backend monitoring when the first callback is registered.

Parameters:

callback – Function called with (AdvertisementData, interpreted_data) when advertisements are received. interpreted_data is None if parsing failed.

unsubscribe(callback: Callable[[bluetooth_sig.types.advertising.result.AdvertisementData, object], None] | None = None) → None

Unsubscribe from advertisement updates.

If callback is provided, removes only that specific callback. If no callback is provided, removes all callbacks. Automatically disables backend monitoring when no callbacks remain.

Parameters:

callback – Specific callback to remove, or None to remove all

property mac_address: str

Device MAC address.

state
src.bluetooth_sig.device.advertising.T
src.bluetooth_sig.device.advertising.logger