View source for GATT Profile Data in Bluetooth Low Energy

= GATT Profile Data =

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

== GATT characteristic declaration attribute ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== GATT characteristic value attribute ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101 

== GATT characteristic user description attribute ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.