GATT Profile Data in Bluetooth Low Energy - Revision history

Kai: /* Property Flags */

2025-05-10T08:27:41Z

Property Flags

← Older revision		Revision as of 2025-05-10T08:27:41
Line 59:		Line 59:

	==== Property Flags ====		==== Property Flags ====
	This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte)		This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte), the contents of which are not part of the Bluetooth Core Specification. These can be used Bluetooth frameworks for implementation-specific features.

	{\| class="wikitable" style="margin:right"		{\| class="wikitable" style="margin:right"
Line 65:		Line 65:
	! Property !! Value !! Description		! Property !! Value !! Description
	\|-		\|-
	\| Dynamic \|\| 0x01 \|\| indicates ~~to the BLE framework (e.g.,~~ BTstack) that read/write operations are implemented by custom user code		\| Dynamic \|\| 0x01 \|\| indicates in BTstack that read/write operations are implemented by custom user code
	\|-		\|-
	\| Long UUID \|\| 0x02 \|\| indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)		\| Long UUID \|\| 0x02 \|\| indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)

Kai at 2025-05-10T07:18:45

2025-05-10T07:18:45Z

← Older revision		Revision as of 2025-05-10T07:18:45
Line 1:		Line 1:
	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.		This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like [https://bluekitchen-gmbh.com/btstack BTstack], expect as setup input.

	= GATT characteristic attribute (descriptor) types =		= GATT characteristic attribute (descriptor) types =

Kai: /* Property Flags */

2025-05-10T07:17:11Z

Property Flags

← Older revision		Revision as of 2025-05-10T07:17:11
Line 65:		Line 65:
	! Property !! Value !! Description		! Property !! Value !! Description
	\|-		\|-
	\| Dynamic \|\| 0x01 \|\| indicates that ~~the~~ read ~~and~~ write operations ~~need to be~~ implemented by custom ~~application~~ code ~~in the GATT server~~		\| Dynamic \|\| 0x01 \|\| indicates to the BLE framework (e.g., BTstack) that read/write operations are implemented by custom user code
	\|-		\|-
	\| Long UUID \|\| 0x02 \|\| indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)		\| Long UUID \|\| 0x02 \|\| indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)

Kai: /* Characteristic value */

2025-05-10T07:09:12Z

Characteristic value

← Older revision		Revision as of 2025-05-10T07:09:12
Line 28:		Line 28:
	The bytes are grouped from left to right as follows:		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 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 combined properties and access permissions bitmasks of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
	* 2 bytes for the handle of the attribute: 0x0009		* 2 bytes for the handle of the attribute: 0x0009
	* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101		* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

	The ~~permission/property flags~~ for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.		The bitmask the determines the access permissions (or properties) for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

	The following table (from the Bluetooth 5.4 specification) defines the flags ~~that can be combined to set~~ the ~~properties of an attribute~~:		==== Access Permission Flags ====
			The following table (from the Bluetooth 5.4 specification) defines the flags for the 8-bit ''access permissions'' bitmask:
	{\| class="wikitable" style="margin:right"		{\| class="wikitable" style="margin:right"
	\|-		\|-
Line 54:		Line 55:
	\|-		\|-
	\| 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.		\| 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.
			\|-
			\|}

			==== Property Flags ====
			This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte)

			{\| class="wikitable" style="margin:right"
			\|-
			! Property !! Value !! Description
			\|-
			\| Dynamic \|\| 0x01 \|\| indicates that the read and write operations need to be implemented by custom application code in the GATT server
			\|-
			\| Long UUID \|\| 0x02 \|\| indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)
	\|-		\|-
	\|}		\|}

Kai at 2025-05-10T06:17:44

2025-05-10T06:17:44Z

@@ Line 19: / Line 19: @@
 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):
+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].
-{| class="wikitable" style="margin:auto"
 |-
-! Properties !! Value !! Description
+! Property !! 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.
@@ Line 41: / Line 56: @@
 |-
 |}
 == Characteristic Client Configuration ==

Kai at 2025-05-10T05:32:26

2025-05-10T05:32:26Z

← Older revision		Revision as of 2025-05-10T05:32:26
Line 1:		Line 1:
	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.		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~~ ==		= GATT characteristic attribute (descriptor) types =

			== Characteristic declaration ==

	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''		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''
Line 40:		Line 42:
	\|}		\|}

	== ~~GATT characteristic~~ value ~~attribute~~ ==		== Characteristic value ==

	<pre>		<pre>
Line 51:		Line 53:
	* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101		* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

	== ~~GATT characteristic client configuration attribute~~ ==		== Characteristic Client Configuration ==

	The client ~~characteristic~~ configuration attribute ~~(descriptor)~~ of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:		The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
	<pre>		<pre>
	0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00		0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
Line 74:		Line 76:
	All other bits are reserved for use in future changes to the GATT protocol.		All other bits are reserved for use in future changes to the GATT protocol.

	== ~~GATT characteristic user~~ description ~~attribute~~ ==		== User description ==

	Here is an example binary sequence for a GATT user description attribute.		Here is an example binary sequence for a GATT user description attribute.

Kai: /* GATT characteristic client configuration attribute */

2025-05-10T05:28:56Z

GATT characteristic client configuration attribute

@@ Line 53: / Line 53: @@
 == GATT characteristic client configuration attribute ==
-The client configuration attribute (descriptor) of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations.
+The client characteristic configuration attribute (descriptor) of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
 == GATT characteristic user description attribute ==

Kai at 2025-05-09T23:05:15

2025-05-09T23:05:15Z

← Older revision		Revision as of 2025-05-09T23:05:15
Line 50:		Line 50:
	* 2 bytes for the handle of the attribute: 0x0009		* 2 bytes for the handle of the attribute: 0x0009
	* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101		* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

			== GATT characteristic client configuration attribute ==

			The client configuration attribute (descriptor) of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations.

	== GATT characteristic user description attribute ==		== GATT characteristic user description attribute ==

Kai: /* GATT Profile Data */

2025-05-09T22:47:43Z

GATT Profile Data

← Older revision		Revision as of 2025-05-09T22:47:43
Line 1:		Line 1:
	~~= 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.		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.

Kai: Created page with "= 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-B0..."

2025-05-09T22:47:12Z

Created page with "= 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-B0..."

New page

= 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.