.. _Guide-Advertising:

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 :doc:`getting started doc<./getting_started>` 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 :doc:`getting started page <./starting>` on
more about this, the code below will replace the ellipses in that guide.

.. code-block:: python3

    # 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.

.. code-block:: python3

    # 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 :download:`simple example <../../examples/simple_example.py>` 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.

.. code-block:: python3
    :emphasize-lines: 13

    # 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 <https://en.wikipedia.org/wiki/IBeacon>`_ 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.

.. code-block:: python3

    # 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)

..
    Other
    +++++

    Automatically Recovering Advertisements
    +++++++++++++++++++++++++++++++++++++++

    In the standard use case we include some magic handling in the background to re-add the advertisement in the case
    that the local bluetooth stack crashes, if you with to disable this feature this must be specified in the peripheral
    server's initialization.

    .. code-block:: python3

        ble_peripheral = ABlePeripheralServer(auto_recover=False)

References
++++++++++

.. [1] `Starting with advertising <https://www.bluetooth.com/blog/bluetooth-low-energy-it-starts-with-advertising/>`_
.. [2] `Quickstart to BLE Advertisements <https://www.argenox.com/library/bluetooth-low-energy/ble-advertising-primer/>`_