src.bluetooth_sig.advertising.state¶

Typed state classes for payload interpretation.

State management is the caller’s responsibility (connection manager, device tracker). The interpreter receives state, uses it, and returns updated values. The caller decides when/how to persist.

Based on Bluetooth SIG Core Specification Supplement for advertising data patterns and real-world implementations (BTHome, Xiaomi MiBeacon, RuuviTag).

Classes¶

Name	Description
`DeviceAdvertisingState`	Complete advertising state for a device.
`EncryptionState`	Encryption-related state for a device.
`PacketState`	Packet tracking state for duplicate/replay detection.

Module Contents¶

class src.bluetooth_sig.advertising.state.DeviceAdvertisingState¶

Bases: msgspec.Struct

Complete advertising state for a device.

Managed by caller (connection manager, device tracker). Passed to interpreter; interpreter updates state directly.

address¶: Device MAC address or platform identifier.

encryption¶: Encryption-related state.

packets¶: Packet tracking state.

device_type¶: Detected device type from payload (e.g., “BTHome sensor”).

protocol_version¶: Detected protocol version (e.g., “v2”, “MiBeacon v5”).

is_sleepy_device¶: Whether device uses irregular advertising intervals.

address: str = ''¶

device_type: str | None = None¶

encryption: EncryptionState¶

is_sleepy_device: bool = False¶

packets: PacketState¶

protocol_version: str | None = None¶

class src.bluetooth_sig.advertising.state.EncryptionState¶

Bases: msgspec.Struct

Encryption-related state for a device.

Caller is responsible for persisting and updating this state. Interpreter reads current values and returns new values.

bindkey¶: 16-byte AES-CCM key for decryption (pre-shared).

bindkey_verified¶: Whether bindkey has successfully decrypted a payload.

encryption_counter¶: Monotonically increasing counter for replay protection. BTHome/Xiaomi use 4-byte counter in advertisement payload.

decryption_failed¶: Whether last decryption attempt failed.

bindkey: bytes | None = None¶

bindkey_verified: bool = False¶

decryption_failed: bool = False¶

encryption_counter: int = 0¶

class src.bluetooth_sig.advertising.state.PacketState¶

Bases: msgspec.Struct

Packet tracking state for duplicate/replay detection.

Caller is responsible for persisting and updating this state.

packet_id¶: Last seen packet ID (for BTHome v2 duplicate filtering).

last_seen_timestamp¶: Timestamp of last valid advertisement (Unix epoch seconds).

last_service_data_hash¶: Hash of last service data payload (for same-payload detection).

last_seen_timestamp: float = 0.0¶

last_service_data_hash: int | None = None¶

packet_id: int | None = None¶