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)"]
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.
| 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.
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 write01 00to this CCCD - NimBLE creates the CCCD automatically and, when it is written, notifies you with the
BLE_GAP_EVENT_SUBSCRIBEevent
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.
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 last3.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.
- 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