1.. _bt_gatt:
2
3
4Generic Attribute Profile (GATT)
5################################
6
7The GATT layer manages the service database providing APIs for service
8registration and attribute declaration.
9
10The GATT Client initiates commands and requests towards the GATT Server, and can
11receive responses, indications and notifications sent by the server. It is
12enabled through the configuration option:
13:kconfig:option:`CONFIG_BT_GATT_CLIENT`
14
15The GATT Server accepts incoming commands and requests from the GATT Client, and
16sends responses, indications and notifications to the client.
17
18Services can be registered using the :c:func:`bt_gatt_service_register` API
19which takes the :c:struct:`bt_gatt_service` struct that provides the list of
20attributes the service contains. The helper macro :c:macro:`BT_GATT_SERVICE()`
21can be used to declare a service.
22
23Attributes can be declared using the :c:struct:`bt_gatt_attr` struct or using
24one of the helper macros:
25
26    :c:macro:`BT_GATT_PRIMARY_SERVICE`
27        Declares a Primary Service.
28
29    :c:macro:`BT_GATT_SECONDARY_SERVICE`
30        Declares a Secondary Service.
31
32    :c:macro:`BT_GATT_INCLUDE_SERVICE`
33        Declares a Include Service.
34
35    :c:macro:`BT_GATT_CHARACTERISTIC`
36        Declares a Characteristic.
37
38    :c:macro:`BT_GATT_DESCRIPTOR`
39        Declares a Descriptor.
40
41    :c:macro:`BT_GATT_ATTRIBUTE`
42        Declares an Attribute.
43
44    :c:macro:`BT_GATT_CCC`
45        Declares a Client Characteristic Configuration.
46
47    :c:macro:`BT_GATT_CEP`
48        Declares a Characteristic Extended Properties.
49
50    :c:macro:`BT_GATT_CUD`
51        Declares a Characteristic User Format.
52
53Each attribute contain a ``uuid``, which describes their type, a ``read``
54callback, a ``write`` callback and a set of permission. Both read and write
55callbacks can be set to NULL if the attribute permission don't allow their
56respective operations.
57
58.. note::
59   32-bit UUIDs are not supported in GATT. All 32-bit UUIDs shall be converted
60   to 128-bit UUIDs when the UUID is contained in an ATT PDU.
61
62.. note::
63  Attribute ``read`` and ``write`` callbacks are called directly from RX Thread
64  thus it is not recommended to block for long periods of time in them.
65
66Attribute value changes can be notified using :c:func:`bt_gatt_notify` API,
67alternatively there is :c:func:`bt_gatt_notify_cb` where it is possible to
68pass a callback to be called when it is necessary to know the exact instant when
69the data has been transmitted over the air. Indications are supported by
70:c:func:`bt_gatt_indicate` API.
71
72Discover procedures can be initiated with the use of
73:c:func:`bt_gatt_discover` API which takes the
74:c:struct:`bt_gatt_discover_params` struct which describes the type of
75discovery. The parameters also serves as a filter when setting the ``uuid``
76field only attributes which matches will be discovered, in contrast setting it
77to NULL allows all attributes to be discovered.
78
79.. note::
80  Caching discovered attributes is not supported.
81
82Read procedures are supported by :c:func:`bt_gatt_read` API which takes the
83:c:struct:`bt_gatt_read_params` struct as parameters. In the parameters one or
84more attributes can be set, though setting multiple handles requires the option:
85:kconfig:option:`CONFIG_BT_GATT_READ_MULTIPLE`
86
87Write procedures are supported by :c:func:`bt_gatt_write` API and takes
88:c:struct:`bt_gatt_write_params` struct as parameters. In case the write
89operation don't require a response :c:func:`bt_gatt_write_without_response`
90or :c:func:`bt_gatt_write_without_response_cb` APIs can be used, with the
91later working similarly to :c:func:`bt_gatt_notify_cb`.
92
93Subscriptions to notification and indication can be initiated with use of
94:c:func:`bt_gatt_subscribe` API which takes
95:c:struct:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to
96the same attribute are supported so there could be multiple ``notify`` callback
97being triggered for the same attribute. Subscriptions can be removed with use of
98:c:func:`bt_gatt_unsubscribe` API.
99
100.. note::
101  When subscriptions are removed ``notify`` callback is called with the data
102  set to NULL.
103
104API Reference
105*************
106
107.. doxygengroup:: bt_gatt
108
109GATT Server
110===========
111
112.. doxygengroup:: bt_gatt_server
113
114GATT Client
115===========
116
117.. doxygengroup:: bt_gatt_client
118