src.bluetooth_sig.types.advertising¶

BLE Advertising data types and parsing utilities.

Organization:

Core PDU Types and Enums - Low-level PDU structure definitions
Advertising Data Type Registry - AD Type metadata
Advertising Flags - Device discovery and capabilities flags
PDU and Header Structures - Structured PDU representations
Parsed Advertising Data - High-level parsed advertisement content

Classes¶

Name	Description
`AdvertisementData`	Complete parsed advertisement with PDU structures and interpreted data.
`AdvertisingData`	Complete BLE advertising data with device information and metadata.
`AdvertisingDataStructures`	Complete parsed advertising data structures organized by category.
`BLEAdvertisingFlags`	BLE Advertising Flags (Core Spec Supplement, Part A, Section 1.3).
`BLEAdvertisingPDU`	BLE Advertising PDU structure.
`BLEExtendedHeader`	Extended Advertising Header fields (BLE 5.0+).
`CoreAdvertisingData`	Core advertising data - device identification and services.
`DeviceProperties`	Device capability and appearance properties.
`DirectedAdvertisingData`	Directed advertising and timing parameters.
`ExtendedAdvertisingData`	Extended advertising PDU-level metadata (BLE 5.0+).
`ExtendedHeaderFlags`	Extended advertising header field presence flags (BLE 5.0+).
`LocationAndSensingData`	Location, positioning, and sensing related data.
`MeshAndBroadcastData`	Bluetooth Mesh and audio broadcast related data.
`OOBSecurityData`	Out-of-Band (OOB) security data advertised for pairing.
`PDUHeaderFlags`	BLE PDU header bit masks for parsing operations.
`PDULayout`	BLE PDU structure size and offset constants.
`PDUType`	BLE Advertising PDU Types (Core Spec Vol 6, Part B, Section 2.3).
`SecurityData`	Security and encryption related advertising data.

Module Contents¶

class src.bluetooth_sig.types.advertising.AdvertisementData¶

Bases: msgspec.Struct

Complete parsed advertisement with PDU structures and interpreted data.

This is the unified result from Device.update_advertisement(), containing both low-level AD structures and high-level vendor-specific interpretation.

The interpreted_data field is typed as Any to maintain msgspec.Struct compatibility while supporting generic vendor-specific result types at runtime.

ad_structures¶: Parsed AD structures (manufacturer_data, service_data, etc.)

interpreted_data¶: Vendor-specific typed result (e.g., sensor readings), or None

interpreter_name¶: Name of the interpreter used (e.g., “BTHome”, “Xiaomi”), or None

rssi¶: Received signal strength indicator in dBm

Example

# Using connection manager (recommended) ad_data = BleakConnectionManager.convert_advertisement(bleak_advertisement) result = device.update_advertisement(ad_data)

# Access low-level AD structures print(result.ad_structures.core.manufacturer_data) # {0x0499: b’…’} print(result.ad_structures.properties.flags)

# Access vendor-specific interpreted data if result.interpreted_data:

print(f”Interpreter: {result.interpreter_name}”) print(f”Temperature: {result.interpreted_data.temperature}”)

ad_structures: AdvertisingDataStructures¶

property has_interpretation: bool¶: Check if vendor-specific interpretation was applied.

interpreted_data: Any = None¶

interpreter_name: str | None = None¶

property local_name: str¶: Convenience accessor for device local name.

property manufacturer_data: dict[int, bytes]¶: Convenience accessor for manufacturer data (company_id → payload).

rssi: int | None = None¶

property service_data: dict[bluetooth_sig.types.uuid.BluetoothUUID, bytes]¶: Convenience accessor for service data (UUID → payload).

class src.bluetooth_sig.types.advertising.AdvertisingData¶

Bases: msgspec.Struct

Complete BLE advertising data with device information and metadata.

raw_data¶: Raw bytes from the advertising packet

ad_structures¶: Parsed AD structures organized by category

extended¶: Extended advertising data (BLE 5.0+)

rssi¶: Received signal strength indicator in dBm

ad_structures: AdvertisingDataStructures¶

extended: ExtendedAdvertisingData¶

property is_extended_advertising: bool¶: Check if this advertisement uses extended advertising.

raw_data: bytes¶

rssi: int | None = None¶

property total_payload_size: int¶: Get total payload size including extended data.

class src.bluetooth_sig.types.advertising.AdvertisingDataStructures¶

Bases: msgspec.Struct

Complete parsed advertising data structures organized by category.

Contains all AD Types parsed from advertising PDUs (both legacy and extended). These are payload content, not PDU-level metadata.

core¶: Device identification and services (manufacturer data, UUIDs, name)

properties¶: Device capabilities (flags, appearance, tx_power, features)

directed¶: Directed advertising parameters (target addresses, intervals)

oob_security¶: Out-of-Band security data for pairing

location¶: Location and sensing data

mesh¶: Mesh network and broadcast audio data

security¶: Encrypted advertising and privacy data

core: CoreAdvertisingData¶

directed: DirectedAdvertisingData¶

location: LocationAndSensingData¶

mesh: MeshAndBroadcastData¶

oob_security: OOBSecurityData¶

properties: DeviceProperties¶

security: SecurityData¶

class src.bluetooth_sig.types.advertising.BLEAdvertisingFlags¶

Bases: enum.IntFlag

BLE Advertising Flags (Core Spec Supplement, Part A, Section 1.3).

These flags indicate the discoverable mode and capabilities of the advertising device.

BR_EDR_NOT_SUPPORTED = 4¶

LE_GENERAL_DISCOVERABLE_MODE = 2¶

LE_LIMITED_DISCOVERABLE_MODE = 1¶

RESERVED_BIT_5 = 32¶

RESERVED_BIT_6 = 64¶

RESERVED_BIT_7 = 128¶

SIMULTANEOUS_LE_BR_EDR_CONTROLLER = 8¶

SIMULTANEOUS_LE_BR_EDR_HOST = 16¶

class src.bluetooth_sig.types.advertising.BLEAdvertisingPDU¶

Bases: msgspec.Struct

BLE Advertising PDU structure.

advertiser_address: bytes = b''¶

extended_header: BLEExtendedHeader | None = None¶

property is_extended_advertising: bool¶: Check if this is an extended advertising PDU.

property is_legacy_advertising: bool¶: Check if this is a legacy advertising PDU.

length: int¶

payload: bytes = b''¶

property pdu_name: str¶: Get human-readable PDU type name.

pdu_type: PDUType¶

rx_add: bool¶

target_address: bytes = b''¶

tx_add: bool¶

class src.bluetooth_sig.types.advertising.BLEExtendedHeader¶

Bases: msgspec.Struct

Extended Advertising Header fields (BLE 5.0+).

additional_controller_advertising_data: bytes = b''¶

adv_mode: int = 0¶

advertising_data_info: bytes = b''¶

auxiliary_pointer: bytes = b''¶

cte_info: bytes = b''¶

extended_advertiser_address: bytes = b''¶

extended_header_length: int = 0¶

extended_target_address: bytes = b''¶

property has_additional_controller_data: bool¶: Check if additional controller advertising data is present.

property has_advertising_data_info: bool¶: Check if advertising data info is present.

property has_auxiliary_pointer: bool¶: Check if auxiliary pointer is present.

property has_cte_info: bool¶: Check if CTE info is present.

property has_extended_advertiser_address: bool¶: Check if extended advertiser address is present.

property has_extended_target_address: bool¶: Check if extended target address is present.

property has_sync_info: bool¶: Check if sync info is present.

property has_tx_power: bool¶: Check if TX power is present.

sync_info: bytes = b''¶

tx_power: int | None = None¶

class src.bluetooth_sig.types.advertising.CoreAdvertisingData¶

Bases: msgspec.Struct

Core advertising data - device identification and services.

manufacturer_data¶: Manufacturer-specific data keyed by company ID

manufacturer_names¶: Resolved company names keyed by company ID

service_uuids¶: List of advertised service UUIDs

service_data¶: Service-specific data keyed by service UUID

solicited_service_uuids¶: List of service UUIDs the device is seeking

local_name¶: Device’s local name (complete or shortened)

uri_data¶: Parsed URI with scheme info from UriSchemesRegistry

local_name: str = ''¶

manufacturer_data: dict[int, bytes]¶

manufacturer_names: dict[int, str]¶

service_data: dict[bluetooth_sig.types.uuid.BluetoothUUID, bytes]¶

service_uuids: list[bluetooth_sig.types.uuid.BluetoothUUID]¶

solicited_service_uuids: list[bluetooth_sig.types.uuid.BluetoothUUID]¶

uri_data: bluetooth_sig.types.uri.URIData | None = None¶

class src.bluetooth_sig.types.advertising.DeviceProperties¶

Bases: msgspec.Struct

Device capability and appearance properties.

flags¶: BLE advertising flags (discoverable mode, capabilities)

appearance¶: Device appearance category and subcategory

tx_power¶: Transmission power level in dBm

le_role¶: LE role (peripheral, central, etc.)

le_supported_features¶: LE supported features bit field

class_of_device¶: Classic Bluetooth Class of Device value

class_of_device_info¶: Parsed Class of Device information

appearance: bluetooth_sig.types.appearance.AppearanceData | None = None¶

class_of_device: bluetooth_sig.types.registry.class_of_device.ClassOfDeviceInfo | None = None¶

flags: BLEAdvertisingFlags¶

le_role: int | None = None¶

le_supported_features: bytes = b''¶

tx_power: int = 0¶

class src.bluetooth_sig.types.advertising.DirectedAdvertisingData¶

Bases: msgspec.Struct

Directed advertising and timing parameters.

These AD types specify target devices and advertising timing.

public_target_address¶: List of public target addresses (AD 0x17)

random_target_address¶: List of random target addresses (AD 0x18)

le_bluetooth_device_address¶: LE Bluetooth device address (AD 0x1B)

advertising_interval¶: Advertising interval in 0.625ms units (AD 0x1A)

advertising_interval_long¶: Long advertising interval (AD 0x2F)

peripheral_connection_interval_range¶: Preferred connection interval (AD 0x12)

advertising_interval: int | None = None¶

advertising_interval_long: int | None = None¶

le_bluetooth_device_address: str = ''¶

peripheral_connection_interval_range: bytes = b''¶

public_target_address: list[str]¶

random_target_address: list[str]¶

class src.bluetooth_sig.types.advertising.ExtendedAdvertisingData¶

Bases: msgspec.Struct

Extended advertising PDU-level metadata (BLE 5.0+).

This contains PDU-level information specific to extended advertising, NOT AD types (which go in AdvertisingDataStructures).

extended_payload¶: Raw extended advertising payload bytes

auxiliary_packets¶: Chained AUX_ADV_IND packets via AuxPtr

periodic_advertising_data¶: Data from periodic advertising train

auxiliary_packets: list[BLEAdvertisingPDU]¶

extended_payload: bytes = b''¶

periodic_advertising_data: bytes = b''¶

class src.bluetooth_sig.types.advertising.ExtendedHeaderFlags¶

Bases: enum.IntEnum

Extended advertising header field presence flags (BLE 5.0+).

Each flag indicates whether a corresponding field is present in the extended advertising header.

ACAD = 128¶

ADV_ADDR = 1¶

ADV_DATA_INFO = 8¶

AUX_PTR = 16¶

CTE_INFO = 4¶

SYNC_INFO = 32¶

TARGET_ADDR = 2¶

TX_POWER = 64¶

class src.bluetooth_sig.types.advertising.LocationAndSensingData¶

Bases: msgspec.Struct

Location, positioning, and sensing related data.

indoor_positioning¶: Indoor positioning data

three_d_information¶: 3D information data

transport_discovery_data¶: Transport Discovery Data

channel_map_update_indication¶: Channel Map Update Indication

channel_map_update_indication: bytes = b''¶

indoor_positioning: bytes = b''¶

three_d_information: bytes = b''¶

transport_discovery_data: bytes = b''¶

class src.bluetooth_sig.types.advertising.MeshAndBroadcastData¶

Bases: msgspec.Struct

Bluetooth Mesh and audio broadcast related data.

mesh_message¶: Mesh Message

mesh_beacon¶: Mesh Beacon

pb_adv¶: Provisioning Bearer over advertising

broadcast_name¶: Broadcast name

broadcast_code¶: Broadcast Code for encrypted audio

biginfo¶: BIG Info for Broadcast Isochronous Groups

periodic_advertising_response_timing¶: Periodic Advertising Response Timing Info

electronic_shelf_label¶: Electronic Shelf Label data

biginfo: bytes = b''¶

broadcast_code: bytes = b''¶

broadcast_name: str = ''¶

electronic_shelf_label: bytes = b''¶

mesh_beacon: bytes = b''¶

mesh_message: bytes = b''¶

pb_adv: bytes = b''¶

periodic_advertising_response_timing: bytes = b''¶

class src.bluetooth_sig.types.advertising.OOBSecurityData¶

Bases: msgspec.Struct

Out-of-Band (OOB) security data advertised for pairing.

These AD types provide security material for OOB pairing mechanisms.

simple_pairing_hash_c¶: Simple Pairing Hash C-192/C-256 (AD 0x0E, 0x1D)

simple_pairing_randomizer_r¶: Simple Pairing Randomizer R-192/R-256 (AD 0x0F, 0x1E)

secure_connections_confirmation¶: LE SC Confirmation Value (AD 0x22)

secure_connections_random¶: LE SC Random Value (AD 0x23)

security_manager_tk_value¶: Security Manager TK Value (AD 0x10)

security_manager_oob_flags¶: SM Out of Band Flags (AD 0x11)

secure_connections_confirmation: bytes = b''¶

secure_connections_random: bytes = b''¶

security_manager_oob_flags: bytes = b''¶

security_manager_tk_value: bytes = b''¶

simple_pairing_hash_c: bytes = b''¶

simple_pairing_randomizer_r: bytes = b''¶

class src.bluetooth_sig.types.advertising.PDUHeaderFlags¶

Bases: enum.IntFlag

BLE PDU header bit masks for parsing operations.

These masks are pre-positioned to their correct bit locations, eliminating the need for shifts during extraction.

classmethod extract_bits(header: int, mask: int) → int | bool¶

Extract bits from header using the specified mask.

Returns int for multi-bit masks, bool for single-bit masks.

classmethod extract_pdu_type(header: int) → PDUType¶: Extract PDU type from header byte and return as PDUType enum.

classmethod extract_rx_add(header: int) → bool¶: Extract RX address type from header.

classmethod extract_tx_add(header: int) → bool¶: Extract TX address type from header.

RFU_BIT_4 = 16¶

RFU_BIT_5 = 32¶

RX_ADD_MASK = 128¶

TX_ADD_MASK = 64¶

TYPE_MASK = 15¶

class src.bluetooth_sig.types.advertising.PDULayout¶

BLE PDU structure size and offset constants.

Defines the sizes and offsets of fields within BLE PDU structures following Bluetooth Core Spec Vol 6, Part B.

ADV_ADDR_OFFSET: int = 2¶

ADV_DATA_INFO: int = 2¶

ADV_DATA_INFO_OFFSET: int = 2¶

ADV_MODE: int = 1¶

AUX_PTR: int = 3¶

AUX_PTR_OFFSET: int = 3¶

BLE_ADDR: int = 6¶

CTE_INFO: int = 1¶

CTE_INFO_OFFSET: int = 1¶

EXTENDED_HEADER_START: int = 3¶

EXT_HEADER_LENGTH: int = 1¶

MIN_EXTENDED_PDU: int = 3¶

PDU_HEADER: int = 2¶

PDU_LENGTH_OFFSET: int = 2¶

SYNC_INFO: int = 18¶

SYNC_INFO_OFFSET: int = 18¶

TARGET_ADDR_OFFSET: int = 2¶

TX_POWER: int = 1¶

TX_POWER_OFFSET: int = 1¶

class src.bluetooth_sig.types.advertising.PDUType¶

Bases: enum.IntEnum

BLE Advertising PDU Types (Core Spec Vol 6, Part B, Section 2.3).

ADV_AUX_IND = 8¶

ADV_DIRECT_IND = 1¶

ADV_EXT_IND = 7¶

ADV_IND = 0¶

ADV_NONCONN_IND = 2¶

ADV_SCAN_IND = 6¶

CONNECT_IND = 5¶

SCAN_REQ = 3¶

SCAN_RSP = 4¶

property is_extended_advertising: bool¶: Check if this is an extended advertising PDU.

property is_legacy_advertising: bool¶: Check if this is a legacy advertising PDU.

class src.bluetooth_sig.types.advertising.SecurityData¶

Bases: msgspec.Struct

Security and encryption related advertising data.

encrypted_advertising_data¶: Encrypted Advertising Data

resolvable_set_identifier¶: Resolvable Set Identifier

encrypted_advertising_data: bytes = b''¶

resolvable_set_identifier: bytes = b''¶