/
GATT Client Guide

GATT Client Guide

While reading all attributes from a GATT server, keep in mind that most GATT servers follow a similar structure:

Profiles: These are logical groupings defined by the Bluetooth SIG, such as the Heart Rate Profile. Although not part of the actual GATT attribute table, they define how services and characteristics should work together.

Services: These represent a specific function of the device and group related characteristics. A single GATT server may have multiple services.

Characteristics: These are the actual data points that can be read, written to, or subscribed to. Each characteristic includes a declaration and a value. Optionally, it may include one or more descriptors that provide additional metadata or control behavior.

One common descriptor is the Client Characteristic Configuration (CCC) with UUID 0x2902. This descriptor enables notifications or indications, allowing clients to subscribe to changes in the characteristic's value.

image-20250530-075343.png

GATT Server structure example:

The functions bt_gatt_client_attr_discover and bt_gatt_client_attr_get can be used to read the entire GATT (Generic Attribute Profile) server of a Bluetooth device.

image-20250530-103456.png

 

The example above shows a data dump from a Bluetooth beacon. It illustrates how the data is structured within the GATT server.

Understanding GATT Server Layout

One of the key elements in the GATT server is the handle. Each attribute (such as services, characteristics, and descriptors) is assigned a unique handle. These handles are crucial for:

  • Determining the sequence and hierarchy of data within the GATT server.

  • Performing read and write operations on characteristics or descriptors.

  • Subscribing to notifications or indications from characteristics that support them.

By analyzing the handle values and using them with the GATT client functions, developers can navigate the server structure and interact with the desired attributes effectively.

Subscribing to a Characteristic

To subscribe to notifications or indications from a GATT characteristic, both the characteristic's value handle and the Client Characteristic Configuration (CCC) descriptor handle are required. Subscribing enables the client to receive asynchronous updates when the characteristic value changes.

Function Signature

bt_gatt_client_subscribe(connection_id, chrc_value_handle, ccc_handle, subscription_type);

Parameters

  • connection_id: The identifier of the active Bluetooth connection.

  • chrc_value_handle: The handle of the characteristic value to subscribe to.

  • ccc_handle: The handle of the Client Characteristic Configuration descriptor associated with the characteristic. This is required to enable notifications or indications.

  • subscription_type: Type of subscription. This typically specifies whether notifications or indications should be enabled.

Notes

  • When writing data to a characteristic, only the characteristic value handle is needed.

  • When subscribing to a characteristic, both the characteristic value handle and the CCC descriptor handle must be provided.

  • The CCC descriptor controls the client's subscription status and is used to enable or disable notifications or indications for a specific characteristic.

Example

bt_gatt_client_subscribe(CONN_ID_1, 0x0003, 0x0004, BT_GATT_CCC_NOTIFY);

In this example:

  • 0x0003 is the characteristic value handle.

  • 0x0004 is the CCC descriptor handle.

  • BT_GATT_SUBSCRIBE_FLAG_NOTIFY enables notifications for this characteristic.