src.bluetooth_sig.advertising.exceptions¶

Advertising exceptions for the Bluetooth SIG library.

Provides exception types for advertising-related errors, following the same patterns as GATT exceptions for API consistency.

Exception Hierarchy:: AdvertisingError (base) ├── AdvertisingParseError - General parse failures │ ├── EncryptionRequiredError - Payload encrypted, no bindkey │ ├── DecryptionFailedError - Decryption failed │ └── UnsupportedVersionError - Unknown protocol version ├── ReplayDetectedError - Counter not increasing └── DuplicatePacketError - Same packet_id as previous

Exceptions¶

Name	Description
`AdvertisingError`	Base exception for all advertising-related errors.
`AdvertisingParseError`	Exception raised when advertising payload parsing fails.
`DecryptionFailedError`	Exception raised when decryption fails.
`DuplicatePacketError`	Exception raised when a duplicate packet is detected.
`EncryptionRequiredError`	Exception raised when payload is encrypted but no bindkey is available.
`ReplayDetectedError`	Exception raised when a replay attack is detected.
`UnsupportedVersionError`	Exception raised when protocol version is not supported.

Module Contents¶

exception src.bluetooth_sig.advertising.exceptions.AdvertisingError¶

Bases: bluetooth_sig.gatt.exceptions.BluetoothSIGError

Base exception for all advertising-related errors.

exception src.bluetooth_sig.advertising.exceptions.AdvertisingParseError(message: str, raw_data: bytes = b'', interpreter_name: str = '', field: str | None = None)¶

Bases: AdvertisingError

Exception raised when advertising payload parsing fails.

message¶: Human-readable error message.

raw_data¶: The raw advertising data that failed to parse.

interpreter_name¶: Name of the interpreter that raised the error.

field¶: Specific field that caused the error (if applicable).

field = None¶

interpreter_name = ''¶

raw_data = b''¶

exception src.bluetooth_sig.advertising.exceptions.DecryptionFailedError(mac_address: str, reason: str = 'decryption failed', raw_data: bytes = b'', interpreter_name: str = '')¶

Bases: AdvertisingParseError

Exception raised when decryption fails.

This typically indicates: - Wrong bindkey - Corrupted data - Incorrect nonce construction

mac_address¶: Device MAC address.

reason¶: Specific reason for decryption failure.

mac_address¶

reason = 'decryption failed'¶

exception src.bluetooth_sig.advertising.exceptions.DuplicatePacketError(mac_address: str, packet_id: int)¶

Bases: AdvertisingError

Exception raised when a duplicate packet is detected.

This occurs when the same packet_id is received twice, indicating the same advertisement was received multiple times. This is typically not an error but may be useful for deduplication.

mac_address¶: Device MAC address.

packet_id¶: The duplicate packet ID.

mac_address¶

packet_id¶

exception src.bluetooth_sig.advertising.exceptions.EncryptionRequiredError(mac_address: str, raw_data: bytes = b'', interpreter_name: str = '')¶

Bases: AdvertisingParseError

Exception raised when payload is encrypted but no bindkey is available.

This exception indicates the payload contains encrypted data that requires a bindkey for decryption. The caller should: 1. Prompt the user to provide a bindkey 2. Store the bindkey in DeviceAdvertisingState.encryption.bindkey 3. Retry interpretation

mac_address¶: Device MAC address needing a bindkey.

mac_address¶

exception src.bluetooth_sig.advertising.exceptions.ReplayDetectedError(mac_address: str, received_counter: int, expected_counter: int)¶

Bases: AdvertisingError

Exception raised when a replay attack is detected.

This occurs when the encryption counter is not increasing, indicating a potential replay attack.

Note: Per Bluetooth Core Specification, replay protection is typically handled at Controller/Link Layer level. This exception is provided for vendor protocols that implement their own replay detection.

mac_address¶: Device MAC address.

received_counter¶: Counter value received in the packet.

expected_counter¶: Minimum expected counter value.

expected_counter¶

mac_address¶

received_counter¶

exception src.bluetooth_sig.advertising.exceptions.UnsupportedVersionError(version: str | int, supported_versions: list[str | int] | None = None, raw_data: bytes = b'', interpreter_name: str = '')¶

Bases: AdvertisingParseError

Exception raised when protocol version is not supported.

version¶: The unsupported version identifier.

supported_versions¶: List of supported version identifiers.

supported_versions = []¶

version¶