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