You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
4.2 KiB
117 lines
4.2 KiB
.. _bt_gatt: |
|
|
|
|
|
Generic Attribute Profile (GATT) |
|
################################ |
|
|
|
The GATT layer manages the service database providing APIs for service |
|
registration and attribute declaration. |
|
|
|
The GATT Client initiates commands and requests towards the GATT Server, and can |
|
receive responses, indications and notifications sent by the server. It is |
|
enabled through the configuration option: |
|
:kconfig:option:`CONFIG_BT_GATT_CLIENT` |
|
|
|
The GATT Server accepts incoming commands and requests from the GATT Client, and |
|
sends responses, indications and notifications to the client. |
|
|
|
Services can be registered using the :c:func:`bt_gatt_service_register` API |
|
which takes the :c:struct:`bt_gatt_service` struct that provides the list of |
|
attributes the service contains. The helper macro :c:macro:`BT_GATT_SERVICE()` |
|
can be used to declare a service. |
|
|
|
Attributes can be declared using the :c:struct:`bt_gatt_attr` struct or using |
|
one of the helper macros: |
|
|
|
:c:macro:`BT_GATT_PRIMARY_SERVICE` |
|
Declares a Primary Service. |
|
|
|
:c:macro:`BT_GATT_SECONDARY_SERVICE` |
|
Declares a Secondary Service. |
|
|
|
:c:macro:`BT_GATT_INCLUDE_SERVICE` |
|
Declares a Include Service. |
|
|
|
:c:macro:`BT_GATT_CHARACTERISTIC` |
|
Declares a Characteristic. |
|
|
|
:c:macro:`BT_GATT_DESCRIPTOR` |
|
Declares a Descriptor. |
|
|
|
:c:macro:`BT_GATT_ATTRIBUTE` |
|
Declares an Attribute. |
|
|
|
:c:macro:`BT_GATT_CCC` |
|
Declares a Client Characteristic Configuration. |
|
|
|
:c:macro:`BT_GATT_CEP` |
|
Declares a Characteristic Extended Properties. |
|
|
|
:c:macro:`BT_GATT_CUD` |
|
Declares a Characteristic User Format. |
|
|
|
Each attribute contain a ``uuid``, which describes their type, a ``read`` |
|
callback, a ``write`` callback and a set of permission. Both read and write |
|
callbacks can be set to NULL if the attribute permission don't allow their |
|
respective operations. |
|
|
|
.. note:: |
|
32-bit UUIDs are not supported in GATT. All 32-bit UUIDs shall be converted |
|
to 128-bit UUIDs when the UUID is contained in an ATT PDU. |
|
|
|
.. note:: |
|
Attribute ``read`` and ``write`` callbacks are called directly from RX Thread |
|
thus it is not recommended to block for long periods of time in them. |
|
|
|
Attribute value changes can be notified using :c:func:`bt_gatt_notify` API, |
|
alternatively there is :c:func:`bt_gatt_notify_cb` where it is possible to |
|
pass a callback to be called when it is necessary to know the exact instant when |
|
the data has been transmitted over the air. Indications are supported by |
|
:c:func:`bt_gatt_indicate` API. |
|
|
|
Discover procedures can be initiated with the use of |
|
:c:func:`bt_gatt_discover` API which takes the |
|
:c:struct:`bt_gatt_discover_params` struct which describes the type of |
|
discovery. The parameters also serves as a filter when setting the ``uuid`` |
|
field only attributes which matches will be discovered, in contrast setting it |
|
to NULL allows all attributes to be discovered. |
|
|
|
.. note:: |
|
Caching discovered attributes is not supported. |
|
|
|
Read procedures are supported by :c:func:`bt_gatt_read` API which takes the |
|
:c:struct:`bt_gatt_read_params` struct as parameters. In the parameters one or |
|
more attributes can be set, though setting multiple handles requires the option: |
|
:kconfig:option:`CONFIG_BT_GATT_READ_MULTIPLE` |
|
|
|
Write procedures are supported by :c:func:`bt_gatt_write` API and takes |
|
:c:struct:`bt_gatt_write_params` struct as parameters. In case the write |
|
operation don't require a response :c:func:`bt_gatt_write_without_response` |
|
or :c:func:`bt_gatt_write_without_response_cb` APIs can be used, with the |
|
later working similarly to :c:func:`bt_gatt_notify_cb`. |
|
|
|
Subscriptions to notification and indication can be initiated with use of |
|
:c:func:`bt_gatt_subscribe` API which takes |
|
:c:struct:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to |
|
the same attribute are supported so there could be multiple ``notify`` callback |
|
being triggered for the same attribute. Subscriptions can be removed with use of |
|
:c:func:`bt_gatt_unsubscribe` API. |
|
|
|
.. note:: |
|
When subscriptions are removed ``notify`` callback is called with the data |
|
set to NULL. |
|
|
|
API Reference |
|
************* |
|
|
|
.. doxygengroup:: bt_gatt |
|
|
|
GATT Server |
|
=========== |
|
|
|
.. doxygengroup:: bt_gatt_server |
|
|
|
GATT Client |
|
=========== |
|
|
|
.. doxygengroup:: bt_gatt_client
|
|
|