GATT Client#

GATT client operations: discovery, read/write, notifications and indications, MTU exchange, and using GATT across multiple connections.

GATT Client Operations#

This section covers GATT client operations for discovering and accessing services and characteristics provided by GATT servers.

Note: While central devices commonly act as GATT clients, GATT roles (Client/Server) are independent of GAP roles (Central/Peripheral). A peripheral can also act as a GATT client, and a central can act as a GATT server. A device can be both GATT client and GATT server simultaneously.

Service Discovery#

Discovering Services:

• Use rsi_ble_get_profiles_async() to discover all primary services; response received through rsi_ble_on_event_profiles_list_t callback (contains rsi_ble_event_profiles_list_t)

• Or use rsi_ble_get_profile_async() to discover a service by UUID; response received through rsi_ble_on_event_profile_by_uuid_t callback (contains rsi_ble_event_profile_by_uuid_t)

Discovering Characteristics:

• Use rsi_ble_get_char_services_async() to discover characteristics in a service

• Success response received through rsi_ble_on_event_read_by_inc_services_t callback; errors through rsi_ble_on_gatt_error_resp_t

• Characteristic information includes: UUID, handle, properties (read, write, notify, indicate)

Discovering Descriptors:

• Use rsi_ble_get_att_descriptors_async() to discover descriptors for a characteristic

• Important descriptors: Client Characteristic Configuration Descriptor (CCCD) for notifications/indications

• Success response received through rsi_ble_on_gatt_desc_val_event_t callback; errors through rsi_ble_on_gatt_error_resp_t

Included Services:

• Use rsi_ble_get_inc_services_async() to discover included services (services referenced by another service)

• Success response received through rsi_ble_on_event_read_att_value_t callback; errors through rsi_ble_on_gatt_error_resp_t

Reading Characteristics#

Read by Handle:

• Use rsi_ble_get_att_value_async() to read characteristic value by handle

• Success response received through rsi_ble_on_event_read_resp_t callback; errors through rsi_ble_on_gatt_error_resp_t

• Value length may be limited by ATT MTU (typically 23 bytes default; on SiWx917, ATT MTU is capped at 232 bytes)

Read by UUID:

• Use rsi_ble_get_char_value_by_uuid_async() to read characteristic value by UUID

• Useful when handle is unknown but UUID is known

• Success response received through rsi_ble_on_event_read_att_value_t callback; errors through rsi_ble_on_gatt_error_resp_t

Long Read:

• Use rsi_ble_get_long_att_value_async() for characteristics larger than ATT MTU

• Automatically handles multiple read requests

• Success response received through rsi_ble_on_event_read_resp_t callback; errors through rsi_ble_on_gatt_error_resp_t

Multiple Reads:

• Use rsi_ble_get_multiple_att_values_async() to read multiple characteristics in one operation

• Efficient for reading multiple related values

• Success response received through rsi_ble_on_event_read_resp_t callback; errors through rsi_ble_on_gatt_error_resp_t

Writing Characteristics#

Write with Response:

• Use rsi_ble_set_att_value_async() to write characteristic value (requires acknowledgment)

• Success response received through rsi_ble_on_event_write_resp_t callback; errors through rsi_ble_on_gatt_error_resp_t

• Use for critical data that must be confirmed

Write without Response:

• Use rsi_ble_set_att_cmd_async() to write without acknowledgment

• Faster but no confirmation of delivery

• Use for high-frequency, non-critical data

Long Write:

• Use rsi_ble_prepare_write_async() to prepare write (queues data); success response through rsi_ble_on_event_prepare_write_resp_t, errors through rsi_ble_on_gatt_error_resp_t

• Use rsi_ble_execute_write_async() to execute queued writes; success response through rsi_ble_on_event_write_resp_t, errors through rsi_ble_on_gatt_error_resp_t

• Required for writes larger than ATT MTU

Notifications and Indications#

Enabling Notifications:

• Write 0x0001 to Client Characteristic Configuration Descriptor (CCCD)

• Use rsi_ble_set_att_value_async() to write to CCCD handle

• After enabling, peripheral will send notifications through rsi_ble_on_gatt_write_event_t callback with event ID RSI_BLE_EVENT_GATT_NOTIFICATION

Enabling Indications:

• Write 0x0002 to CCCD

• After enabling, peripheral will send indications through rsi_ble_on_gatt_write_event_t callback with event ID RSI_BLE_EVENT_GATT_INDICATION

Note: rsi_ble_indicate_confirm() must be called when RSI_BLE_INDICATE_CONFIRMATION_FROM_HOST is enabled in opermode configuration.

Receiving Notifications/Indications:

• Register GATT callbacks using rsi_ble_gatt_register_callbacks()

• Handle notifications and indications through rsi_ble_on_gatt_write_event_t callback

• Event ID RSI_BLE_EVENT_GATT_NOTIFICATION for notifications

• Event ID RSI_BLE_EVENT_GATT_INDICATION for indications

• Event data provided in rsi_ble_event_write_t structure

MTU Exchange#

MTU Exchange Overview:

• MTU exchange is driven by ATT roles (Client/Server), not GAP roles (Central/Peripheral)

• ATT Client initiates MTU exchange by sending ATT_EXCHANGE_MTU_REQ (at most once per connection per spec)

• ATT Server responds with ATT_EXCHANGE_MTU_RSP

• Both sides use ATT_MTU = min(client Rx MTU, server Rx MTU)

Note: A device can be both ATT Client and ATT Server simultaneously, allowing one outstanding transaction in each direction

Initiating MTU Exchange (as ATT Client):

• When RSI_BLE_MTU_EXCHANGE_FROM_HOST is enabled, the application receives rsi_ble_mtu_exchange_event() when MTU exchange is triggered. MTU exchange can be initiated after the connect event or enhance connect event is received.

• Larger MTU enables more efficient data transfer (on SiWx917, up to 232 bytes, including ATT header)

• Response received through rsi_ble_on_mtu_event_t callback (contains rsi_ble_event_mtu_t structure)

• For detailed MTU exchange information including initiator details, register rsi_ble_on_mtu_exchange_info_t callback through rsi_ble_gatt_extended_register_callbacks() (contains rsi_ble_event_mtu_exchange_information_t structure)

Note: When RSI_BLE_MTU_EXCHANGE_FROM_HOST is not enabled, firmware handles MTU exchange automatically

Responding to MTU Exchange (as ATT Server):

• Use rsi_ble_mtu_exchange_resp() to respond to MTU exchange requests (when RSI_BLE_MTU_EXCHANGE_FROM_HOST is enabled)

MTU Benefits:

• Reduces number of packets for large data transfers

• Lower overhead and latency

• Recommended for applications with frequent large data transfers

GATT Operations Across Connections#

Per-Connection Context:

• Each connection has independent GATT database

• Service discovery, read/write operations are per-connection

• Track which services/characteristics belong to which connection

Concurrent Operations:

• GATT operations can be performed concurrently on different connections

• Use device address to specify target connection for each operation

• Handle responses/events with connection context

Best Practices:

• Complete service discovery on each connection before operations

• Cache service/characteristic handles per connection

• Handle connection-specific events appropriately

• Implement connection timeout handling

APIs Used in This Section#