3  ATT and GATT: the framework for exchanging data

After connecting, data is exchanged with a protocol called ATT, following a structure called GATT. These two are what you rely on most when building your own BLE device.

3.1 ATT: the attribute table

In ATT (Attribute Protocol), the GATT Server (peripheral) holds an attribute table, and the GATT Client (phone) reads and writes it. One attribute consists of the following four elements.

Element Details
Handle A 16-bit sequence number (0x0001–0xFFFF). The row number in the table
Type A UUID representing the kind of attribute
Value The data itself (variable length)
Permissions Readable, writable, encryption required, authentication required…

The client specifies attributes by handle, as in “read handle 0x0012” or “write to handle 0x0015”.

3.1.1 Main ATT operations

Operation Direction Response Use
Read Request Client → Server Read Response Read a value
Write Request Client → Server Write Response Write a value (success/failure is returned)
Write Command Client → Server None Write a value (fast, but you don’t know whether it arrived)
Handle Value Notification Server → Client None Inform (Notify) of a value change
Handle Value Indication Server → Client Confirmation Inform of a value change and get an acknowledgement of receipt (Indicate)
Exchange MTU Client → Server Response Negotiate the maximum length of one packet (MTU)

Only Notify and Indicate can be sent spontaneously from server to client. To have the peripheral “send data every second”, you use one of these.

3.2 GATT: services and characteristics

As is, the ATT attribute table is just a sequence of rows. GATT (Generic Attribute Profile) is a set of conventions for using that table as a nested structure of service → characteristic → descriptor.

flowchart TB
  P["GATT Server (ESP32-C3)"]
  P --> S1["Service: GAP (0x1800)"]
  P --> S2["Service: GATT (0x1801)"]
  P --> S3["Service: custom (c0a60001-…)"]
  S1 --> C11["Device Name (0x2A00)"]
  S1 --> C12["Appearance (0x2A01)"]
  S3 --> C1["Characteristic: Counter<br/>Read / Notify"]
  S3 --> C2["Characteristic: Command<br/>Write / Notify"]
  C1 --> D1["Descriptor: CCCD (0x2902)"]
  C2 --> D2["Descriptor: CCCD (0x2902)"]

Term Meaning Examples
Service A group of related functions Heart Rate service, Battery service, custom service
Characteristic A container for one value. The unit of reading/writing/notification Heart rate, battery level, counter
Descriptor Additional information about a characteristic CCCD (notification subscription setting), description text

3.2.1 Seen as an attribute table

This hands-on’s custom service becomes rows like the following in the ATT table (handle numbers are examples; actual values are determined by registration order).

Handle Type (UUID) Value Meaning
0x000A 0x2800 Primary Service c0a60001-… Service declaration
0x000B 0x2803 Characteristic properties 0x12, value handle 0x000C, UUID c0a60002-… Characteristic declaration
0x000C c0a60002-… counter value (4 bytes) Value
0x000D 0x2902 CCCD 00 00 / 01 00 Subscription setting
0x000E 0x2803 Characteristic properties 0x18, value handle 0x000F, UUID c0a60003-… Characteristic declaration
0x000F c0a60003-… (the command written) Value
0x0010 0x2902 CCCD 00 00 / 01 00 Subscription setting

One characteristic consists of several rows: declaration, value and (descriptors). When you register a characteristic with NimBLE, what comes back in val_handle is the handle of the value row. You use this handle when notifying, and when determining which characteristic an access targets.

After connecting, the client reads this table via Service Discovery before operating on it. The list shown first when you connect with nRF Connect is the result of this discovery.

3.2.2 Properties

The properties in a characteristic declaration are a combination of bits telling the client what can be done with that characteristic.

Bit Name NimBLE flag
0x02 Read BLE_GATT_CHR_F_READ
0x04 Write Without Response BLE_GATT_CHR_F_WRITE_NO_RSP
0x08 Write BLE_GATT_CHR_F_WRITE
0x10 Notify BLE_GATT_CHR_F_NOTIFY
0x20 Indicate BLE_GATT_CHR_F_INDICATE

Counter is Read + Notify, giving 0x12; Command is Write + Notify, giving 0x18.

NoteProperties vs. permissions

Properties are a declaration “this operation is supported” (guidance for the client). Permissions are access control “reject unless this condition is met”, and are not visible to the client. NimBLE’s BLE_GATT_CHR_F_READ_ENC (encryption required) and the like are permission-side flags (Chapter 9).

3.2.3 CCCD: the Notify subscription switch

Notify / Indicate are not something the server may send on its own. They can be sent only when the client has enabled the subscription by writing to the CCCD (Client Characteristic Configuration Descriptor, UUID 0x2902).

CCCD value Meaning
00 00 Not subscribed (initial value)
01 00 Subscribed to Notify
02 00 Subscribed to Indicate

sequenceDiagram
  participant C as Phone (GATT Client)
  participant S as ESP32-C3 (GATT Server)
  C->>S: Write Request: CCCD(0x000D) = 01 00
  S-->>C: Write Response
  Note over S: BLE_GAP_EVENT_SUBSCRIBE (cur_notify=1)
  loop every second
    S->>C: Handle Value Notification: handle 0x000C, value
  end
  C->>S: Write Request: CCCD(0x000D) = 00 00
  Note over S: BLE_GAP_EVENT_SUBSCRIBE (cur_notify=0)

  • The CCCD is a value per connection and per client. When disconnected, the subscription is cleared (unless bonded)
  • The “↓↓↓” icon in nRF Connect and startNotifications() in Web Bluetooth are both operations that write 01 00 to this CCCD
  • NimBLE creates the CCCD automatically and, when it is written, notifies you with the BLE_GAP_EVENT_SUBSCRIBE event

3.2.4 Notify vs. Indicate

Notify Indicate
Acknowledgement None Yes (cannot send the next one until the Confirmation returns)
Speed Fast (several per connection event) Slow (one per round trip)
Reliability Retransmitted by the Link Layer, so it arrives as long as the connection holds. But you don’t know whether the app received and processed it You can confirm that the client’s ATT layer received it
Suitable for Continuous sensor values Notification of setting changes, events you don’t want to miss

This hands-on uses Notify.

3.3 UUIDs

Kinds of services and characteristics are expressed by UUIDs.

3.3.1 16-bit UUIDs and the Bluetooth Base UUID

Standard services and characteristics defined by the Bluetooth SIG are assigned short 16-bit UUIDs.

UUID Name
0x180D Heart Rate service
0x180F Battery service
0x2A19 Battery Level characteristic
0x2902 CCCD

A 16-bit UUID is actually an abbreviation of a 128-bit UUID formed by replacing part of the Bluetooth Base UUID.

0000xxxx-0000-1000-8000-00805F9B34FB
    ^^^^ the 16-bit UUID goes here

3.3.2 Custom 128-bit UUIDs

For services you create yourself, use a randomly generated 128-bit UUID (you can make one with the uuidgen command or Python’s uuid.uuid4()). In this hands-on,

Use UUID
Service c0a60001-18ff-4cd1-afce-4832ee44bcb7
Counter c0a60002-18ff-4cd1-afce-4832ee44bcb7
Command c0a60003-18ff-4cd1-afce-4832ee44bcb7

they are numbered sequentially by changing the 3rd–4th bytes of a single base UUID.

WarningDon’t reuse well-known UUIDs

6e400001-b5a3-f393-e0a9-e50e24dcca9e, often seen in samples on the net, is the UUID of Nordic’s UART Service (NUS). Using it with a different meaning makes tools like nRF Connect show it as “UART RX / TX”, which causes confusion. For your own services, use UUIDs you generated yourself.

3.3.3 Watch the byte order

When a 128-bit UUID is handled as a byte sequence, inside BLE it is laid out little-endian (reversed). NimBLE’s BLE_UUID128_INIT() is also written starting from the last byte.

// c0a60001-18ff-4cd1-afce-4832ee44bcb7
BLE_UUID128_INIT(0xb7, 0xbc, 0x44, 0xee, 0x32, 0x48, 0xce, 0xaf,
                 0xd1, 0x4c, 0xff, 0x18, 0x01, 0x00, 0xa6, 0xc0);
//                                       ^^^^^^^^^^^^^^^^^^^^^^ the leading c0a60001 comes last

3.4 MTU and how much can be sent at once

ATT_MTU is the maximum length of one ATT packet.

  • The default is 23 bytes. Subtracting the Notify header (opcode 1 + handle 2) gives 20 bytes, the length of value that one Notify can carry
  • After connecting, when the client sends Exchange MTU, the smaller of the two sides’ preferences is chosen. ESP-IDF’s NimBLE prefers 256 by default (CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU)
  • iOS and Android often negotiate the MTU right after connecting, widening it to 185, 247, etc. In NimBLE you are informed via BLE_GAP_EVENT_MTU

The responses in this hands-on are at most 9 bytes, so they fit in the default 20 bytes. If you design to send data longer than 20 bytes, split it rather than relying on the MTU, or send only after confirming the MTU has been widened.

ImportantKey points
  • ATT is reading/writing an attribute table addressed by handle
  • GATT is the convention for using the table as service → characteristic → descriptor
  • The server can only send Notify / Indicate, and only when the client has subscribed by writing to the CCCD
  • Custom services use 128-bit UUIDs you generated yourself. As bytes they are reversed
  • One Notify carries up to 20 bytes by default