GATT Configuration Guide
========================

The purpose of this section is to show you how to setup a GATT table on the peripheral server using ABle. Do note that
this requires prior knowledge on what GATT services and characteristics are, if you need a refresher check out the
references on this page [1]_ [2]_.

Do note that ABle currently does not support descriptors.

Adding a Service
++++++++++++++++

Adding services is super easy, using the template provided in the getting started guide, we can add a service.

.. code-block:: python3

    service = ABleService(uuid.uuid4())
    able_peripheral.add_service(service)

This will add a service with a random UUID, but you can swap the param that the `ABleService` is initialized with to
a string or another python UUID.

.. note:: If you are interested more in how the `ABleService` works, check out its base class documentation
    :doc:`here <../api_reference/service>`.

Adding a Characteristic
+++++++++++++++++++++++

After you add a service, you can add a characteristic to that service. Characteristics require their own UUID as well
as a link to the service that it will be under so this step has to be after adding a service.

.. code-block:: python3

    new_char = ABleCharacteristic(characteristic_uuid=uuid.uuid4())
    able_peripheral.add_characteristic(service, new_char)

Similar to the service, this will create a characteristic with a random UUID, but it can be initialized with an instance
of `uuid.UUID`.

At this point your GATT Table has a service with one characteristic, this is sufficient to progress in the guide to
connections and communications, however if you wish to configure the table more, read on!


.. note:: If you are interested more in how the `ABleCharacteristic` works, check out its base class documentation
    :doc:`here <../api_reference/characteristic>`.

Configuring Characteristics
+++++++++++++++++++++++++++

Characteristics are very configurable, ABle characteristics currently support modifying the flags/permissions on that
characteristic to (dis/en)able writing, reading, indications, notifications, reliable writes, as well as initializing
the characteristic with bytes already on it.

Flags and Permissions
*********************

By default `ABleCharacteristics` are configured for reading, writing and notifications, but if you wish to change these
you can pass in a list of flags in the initialization of the characteristic.
For example we can create a characteristic to send indications instead of notifications.

.. code-block:: python3

    from able.characteristic import CharacteristicFlags

    characteristic = ABleCharacteristic(
        characteristic_uuid=uuid.uuid4(),
        flags=[
            CharacteristicFlags.READ,
            CharacteristicFlags.WRITE,
            CharacteristicFlags.INDICATE,
        ],
    )

Poke around the characteristic flags enum to see all the ways a characteristic can be configured.

Default Value
*************

A characteristic can also be initialized with a value already on it. Note that only bytes are valid to be the initial
value of the characteristic and if the data is too long it may be truncated.

.. code-block:: python3

    characteristic = ABleCharacteristic(
        characteristic_uuid=uuid.uuid4(),
        value=b"1234",
    )

Nickname
********

Often times we've been bewildered trying to keep track of everything that is happening with characteristics, so there
is an optional `name` parameter that can be used in initializing the characteristic that will be used to identify
the characteristic in logs to make them more human friendly.

.. code-block:: python3

    characteristic = ABleCharacteristic(
        characteristic_uuid=uuid.uuid4(),
        name="CommunicationCharacteristic",
    )

References
++++++++++

.. [1] `Introduction to GATT Tables <https://www.bluetooth.com/bluetooth-resources/intro-to-bluetooth-gap-gatt/>`_
.. [2] `Getting Started with GATT <https://www.oreilly.com/library/view/getting-started-with/9781491900550/ch04.html>`_