ABleAdvertisement

ABleAdvertisements are added to ABlePeripheral instances to configure advertising. The advertisement can be configured using the methods below for tinkering with service uuids and data, the local name, manufacturing data and there’s more to come! The advertisement should be configured, then added to the peripheral before starting the peripheral by calling listen(). There are also plugins which define specialized advertisements, see the plugin category below for more details.

Please see the Advertising Guide section in the programming guide for some examples to get started with advertising with ABle!

Class Definition

class able.advertisement.ABleAdvertisement(local_name, *args, **kwargs)[source]

A platform agnostic BLE le_advertisement class. This wrapper illustrates the platform specific le_advertisement implementations and utilizes the implementation of each backends specific le_advertisement in the self.le_advertisement member.

Note that validation of inputs for member functions is handled in this class instead of having the validation duplicated on each backend, the only exception to this is platform specific restrictions.

Parameters

local_name (str) – The name you wish to include within le_advertisement packets as the local name

Advertising Plugins

These advertising plugins provide pre-configured ABleAdvertisement instances which are setup for specific advertising types, feel free to open PRs with new plugins, there is interest right now for adding AltBeacons, Google’s URIBeacons, and more!

Configuration

Service Data

able.advertisement.ABleAdvertisement.add_service_uuid(self, service_uuid)

Adds a service uuid to the le_advertisement. Please see the Bluetooth SIG’s specification for service uuids and which uuids are assigned/reserved.

Raises

ValueError – if service_uuid is not of type str or uuid.UUID

Parameters

service_uuid (Union[str, UUID]) – the service uuid to add to the le_advertisement

Return type

None

Returns

None

able.advertisement.ABleAdvertisement.add_service_data(self, service_uuid, service_data)

Adds service data for a service uuid within the le_advertisement. Note that the service uuid must be added before the service data can be added.

Raises

ValueError – if service_uuid is not of type str or uuid.UUID or if service_data is not of type str or bytes

Parameters

  • service_uuid (Union[str, UUID]) – The uuid of the service to add the service data to, this must be a service uuid you have already added to the le_advertisement

  • service_data (Union[str, bytes]) – The service data to include in the le_advertisement under the service uuid

Return type

None

Returns

None

async able.advertisement.ABleAdvertisement.update_service_data(self, service_uuid, service_data)

Update previously set service data with new data and refresh the le_advertisement using the bound application. This can be only called after the ABlePeripheralServer that owns this le_advertisement has started advertising.

Raises

ValueError – if service_uuid is not of type str or uuid.UUID or if service_data is not of type str or bytes

Parameters

  • service_uuid (Union[str, UUID]) – the uuid of the service whose service data you are updating.

  • service_data (Union[str, bytes]) – the service data to overwrite the previous service data with.

Return type

None

Returns

None

Manufacturer Data

able.advertisement.ABleAdvertisement.add_manufacturer_data(self, manufacturer_id, manufacturer_data)

Updates the manufacturer data of the le_advertisement to include the specified manufacturer data. Refer to the reference doc above for the limitations on manufacturer data.

Raises

ValueError – if manufacturer_id is not of type 16-bit unsigned int or manufacturer_data is not of type str or bytes

Parameters

  • manufacturer_id (int) – the id of the manufacturer to add the manufacturer data to, see the Bluetooth Special Interest groups website for what manufacturer id’s are valid to be used in your use case.

  • manufacturer_data (Union[str, bytes]) – the manufacturer data to add

Return type

None

Returns

None