advertising

Advertising is the first phase of BLE where devices can broadcast

to_hex(seq: bytes) → str

Pretty prints a byte sequence as hex values.

to_bytes_literal(seq: bytes) → str

Prints a byte sequence as a Python bytes literal that only uses hex encoding.

decode_data(data: bytes, *, key_encoding: str = 'B') → Dict[Any, bytes | List[bytes]]

Helper which decodes length encoded structures into a dictionary with the given key encoding.

compute_length(data_dict: Dict[Any, bytes | List[bytes]], *, key_encoding: str = 'B') → int

Computes the length of the encoded data dictionary.

encode_data(data_dict: Dict[Any, bytes | List[bytes]], *, key_encoding: str = 'B') → bytes

Helper which encodes dictionaries into length encoded structures with the given key encoding.

class AdvertisingDataField

Top level class for any descriptor classes that live in Advertisement or its subclasses.

class AdvertisingFlag(bit_position: int)

A single bit flag within an AdvertisingFlags object.

class AdvertisingFlags(advertisement: Advertisement, advertising_data_type: int)

Standard advertising flags

limited_discovery

Discoverable only for a limited time period.

general_discovery

Will advertise until discovered.

le_only

BR/EDR not supported.

class String(*, advertising_data_type: int)

UTF-8 encoded string in an Advertisement.

Not null terminated once encoded because length is always transmitted.

class Struct(struct_format: str, *, advertising_data_type: int)

struct encoded data in an Advertisement.

class LazyObjectField(cls: Any, attribute_name: str, *, advertising_data_type: int, **kwargs)

Non-data descriptor useful for lazily binding a complex object to an advertisement object.

property advertising_data_type: int

Return the data type value used to indicate this field.

class Advertisement(*, entry: ScanEntry | None = None)

Core Advertisement type.

The class attribute match_prefixes, if not None, is a tuple of bytestring prefixes to match against the multiple data structures in the advertisement.

match_prefixes = ()

For Advertisement, match_prefixes will always return True. Subclasses may override this value.

short_name

Short local device name (shortened to fit).

complete_name

Complete local device name.

tx_power

Transmit power level

appearance

Appearance.

property rssi: int | None

Signal strength of the scanned advertisement. Only available on Advertisements returned from BLERadio.start_scan(). (read-only)

classmethod get_prefix_bytes() → bytes | None

Return a merged version of match_prefixes as a single bytes object, with length headers.

classmethod matches(entry: ScanEntry) → bool

Returns True if the given _bleio.ScanEntry advertisement fields matches all of the given prefixes in the match_prefixes tuple attribute. Subclasses may override this to match any instead of all.

classmethod matches_prefixes(entry: ScanEntry, *, all_: bool) → bool

Returns True if the given _bleio.ScanEntry advertisement fields match any or all of the given prefixes in the match_prefixes tuple attribute. If all_ is True, all the prefixes must match. If all_ is False, returns True if at least one of the prefixes match.

standard

This module provides BLE standard defined advertisements. The Advertisements are single purpose even though multiple purposes may actually be present in a single packet.

class BoundServiceList(advertisement: ProvideServicesAdvertisement | SolicitServicesAdvertisement, *, standard_services: List[int], vendor_services: List[int])

Sequence-like object of Service UUID objects. It stores both standard and vendor UUIDs.

append(service: Service) → None

Append a service to the list.

extend(services: Iterable[Service]) → None

Appends all services in the iterable to the list.

class ServiceList(*, standard_services: List[int], vendor_services: List[int])

Descriptor for a list of Service UUIDs that lazily binds a corresponding BoundServiceList.

class ProvideServicesAdvertisement(*services: Service, entry: ScanEntry | None = None)

Advertise what services that the device makes available upon connection.

match_prefixes = (b'\x02', b'\x03', b'\x06', b'\x07')

For Advertisement, match_prefixes will always return True. Subclasses may override this value.

services

List of services the device can provide.

classmethod matches(entry: ScanEntry) → bool

Only one kind of service list need be present in a ProvideServicesAdvertisement, so override the default behavior and match any prefix, not all.

class SolicitServicesAdvertisement(*services: Service, entry: ScanEntry | None = None)

Advertise what services the device would like to use over a connection.

match_prefixes = (b'\x14', b'\x15')

For Advertisement, match_prefixes will always return True. Subclasses may override this value.

solicited_services

List of services the device would like to use.

class ManufacturerData(obj: ProvideServicesAdvertisement | SolicitServicesAdvertisement, *, advertising_data_type: int = 255, company_id: int, key_encoding: str = 'B')

Encapsulates manufacturer specific keyed data bytes. The manufacturer is identified by the company_id and the data is structured like an advertisement with a configurable key format. The order of the serialized data is determined by the order that the ManufacturerDataField attributes are set in - this can be useful for match_prefixes in an Advertisement sub-class.

class ManufacturerDataField(key: int, value_format: str, field_names: Iterable[str] | None = None)

A single piece of data within the manufacturer specific data. The format can be repeated.

class ServiceData(service: Service)

Encapsulates service data. It is read as a memoryview which can be manipulated or set as a bytearray to change the size.

adafruit

This module provides Adafruit defined advertisements.

Adafruit manufacturing data is key encoded like advertisement data and the Apple manufacturing data. However, the keys are 16-bits to enable many different uses. Keys above 0xf000 can be used by Adafruit customers for their own data.

MANUFACTURING_DATA_ADT = 255

The advertising data type for manufacturer-specific data

ADAFRUIT_COMPANY_ID = 2082

Company Identifier for Adafruit Industries

class AdafruitColor(*, entry: ScanEntry | None = None)

Broadcast a single RGB color.

match_prefixes = (b'\xff"\x08\x06\x00\x00',)

For Advertisement, match_prefixes will always return True. Subclasses may override this value.

color

Color to broadcast as RGB integer.