Advertising Guide¶
Advertising is a core part of BLE as it is how centrals are able to discover your peripheral before connecting 1. Centrals leverage the data captured in BLE advertisements to be able to connect to a peripheral and that data can include information about the different services in a peripherals GATT table, manufacturer data and more. See the below examples on different ways to configure an advertisement with ABle.
If you are interested in learning more about advertising, check out this great primer 2.
Tip
We highly suggest looking at the getting started doc before looking at this guide as that will introduce you to the setup required before using the examples below.
Simplest Use Case¶
The simplest use case adds an advertisement with the name ABle to a peripheral. Note this must be ran in an event loop, see the getting started page on more about this, the code below will replace the ellipses in that guide.
# Create an Advertisement and add it
advertisement = ABleAdvertisement()
await able_peripheral.add_advertisement(advertisement)
At this point feel free to move on to the next section about configuring the GATT table, if you are interested in getting fancier with advertising, please read on.
Configuring an Advertisement¶
There are a lot of ways to configure an advertisement. Right now ABle supports configuring the service uuids, service data, the local name, the advertisement type, and manufacturer data.
Below is an example on how to configure all of the aforementioned params. Note that most advertisement packets have a length limit, so be diligent when configuring advertisements to not go over this limit, there will be an error adding the advertisement if it is too long.
# Create an advertisement with a name and a type
advertisement = ABleAdvertisement(
local_name="Able", advertisement_type=AdvertisementType.PERIPHERAL
)
# Add a service uuid with some service data
advertisement.add_service_uuid("FFF0")
advertisement.add_service_data("FFF0", bytes.fromhex("0df0ad8b"))
# Add some manufacturer data
advertisement.add_manufacturer_data(1234, "1234")
Note that this example does not include setting up the peripheral and adding the advertisement to it, those steps are the same as the example above.
Hint
Check out simple example to run this example code with all
the setup already done and a little extra.
Dynamic Service Data¶
Using some magic and trickery in the platform backends, we support changing service data after starting the peripheral that handles the advertisement. See an example below which sets the service data initially then in a while true loop will toggle that data every five seconds. This can be used to broadcast state of a peripheral which is dynamic without having to connect.
# Add our advertisement with our UUID
advertisement = ABleAdvertisement()
advertisement.add_service_uuid("FFF0")
data = b"1111"
advertisement.add_service_data("FFF0", data)
await able_peripheral.add_advertisement(advertisement)
...
# After the peripheral server starts
while True:
data = b"0000" if data == b"1111" else b"1111"
await advertisement.update_service_data("FFF0", service_data=data)
await asyncio.sleep(5)
Plugins¶
Below are examples demonstrating use of the plugins ABle currently supports with advertising.
iBeacons¶
You can also construct and add an iBeacon as your advertisement. The device_uuid argument can be passed in as a str or uuid.UUID object, and major, minor, and tx_power must each be passed in as a list of bytes as shown. See the iBeacon Wikipedia Page for information on the format of iBeacon advertisement packets. The initialization is slightly different from other advertisements, but it is handled the same by the peripheral server.
# User Configurable Params
device_uuid = 'efdf8903-83d6-4427-a5f4-53975ac390cd'
major = [b"\x11", b"\x12"]
minor = [b"\x33", b"\x44"]
tx_power = [b"\xB3"]
# Create the iBeacon advertisement instance
iBeacon = ABleiBeacon(
local_name="Able",
device_uuid=device_uuid,
major=major,
minor=minor,
tx_power=tx_power,
)
# Add the iBeacon just like a regular advertisement
await able_peripheral.add_advertisement(iBeacon)