1. GATT Caching feature
Discovering the GATT database of a remote device every time a connection is made takes a lot of time and energy.
To avoid this, most Bluetooth devices use attribute caching, that means that once they discovered the GATT database of a remote device, they store the discovered attribute handles for future use (in other words they store a local copy of the remote database structure, or at least parts of it).
This works well as long as the remote device keeps its GATT database structure unchanged. If the database structure changes - for example because of a firmware update that introduces new features - the stored attribute handles become invalid.
There are two methods to notify peer devices about the change:
- using Service Change Indication
- using GATT Caching feature
Service Change Indication was introduced in Bluetooth 4.0.
The main disadvantage of this method is, that it works only if the peer devices are bonded.
GATT Caching feature was introduced in Bluetooth 5.1 to overcome the bonding problem. Using GATT caching, every device can make sure, if it stores the latest version of the GATT database structure. This is achieved by:
- Adding two new characteristics to the Generic Attribute service (Database Hash and Client Supported Features)
- Adding a new GATT error code (database out-of-sync)
GATT Caching feature is implemented for STM32WB and STM32WBA.
1.1. GATT Caching new capabilities
The GATT caching feature brings the following changes in the STM32WB and STM32WBA BLE stack.
GATT server implementation:
- At GATT initialization, two new characteristics to the GATT service are added:
- Client Supported Features (for “Robust Caching”)
- Database Hash
- New GATT error codes may be generated upon client requests:
- database out-of-sync (for “Robust Caching”)
- value not allowed (for “Robust Caching”)
- New GATT information stored in NVM:
- Client supported features (for “Robust Caching”)
- Client “change aware/unaware” state (for “Robust Caching”)
1.1.1. Database Hash characteristic
The Database Hash characteristic stores a 128bit value, which is a AES-CMAC hash calculated from the database structure.
Any change in the database structure will result in a different hash value.
After discovering the database once, the client should store this value. Next time, when the client connects to the server, it should only check if the Database Hash has changed. If it hasn't, it is safe to assume, that the database structure in unchanged, and the cached attribute handles are still valid. If it has changed, the client needs to rediscover the GATT database.
1.2. Existing GATT commands supporting the enhancement
Client commands
ACI_GATT_DISC_ALL_PRIMARY_SERVICES
ACI_GATT_DISC_PRIMARY_SERVICE_BY_UUID
ACI_GATT_FIND_INCLUDED_SERVICES
ACI_GATT_DISC_ALL_CHAR_OF_SERVICE
ACI_GATT_DISC_CHAR_BY_UUID
ACI_GATT_DISC_ALL_CHAR_DESC
ACI_GATT_READ_CHAR_VALUE
ACI_GATT_READ_USING_CHAR_UUID
ACI_GATT_READ_LONG_CHAR_VALUE
ACI_GATT_READ_MULTIPLE_CHAR_VALUE
ACI_GATT_READ_LONG_CHAR_DESC
ACI_GATT_READ_CHAR_DESC
ACI_GATT_WRITE_CHAR_VALUE
ACI_GATT_WRITE_LONG_CHAR_VALUE
ACI_GATT_WRITE_CHAR_RELIABLE
ACI_GATT_WRITE_LONG_CHAR_DESC
ACI_GATT_WRITE_CHAR_DESC
ACI_GATT_WRITE_WITHOUT_RESP
ACI_GATT_CONFIRM_INDICATION
Server commands
ACI_GATT_UPDATE_CHAR_VALUE_EXT
ACI_GATT_WRITE_RESP
ACI_GATT_ALLOW_READ
ACI_GATT_DENY_READ
1.3. Existing GATT events supporting the enhancement
Client events
ACI_GATT_PROC_COMPLETE_EVENT
ACI_ATT_FIND_INFO_RESP_EVENT
ACI_ATT_FIND_BY_TYPE_VALUE_RESP_EVENT
ACI_ATT_READ_BY_TYPE_RESP_EVENT
ACI_ATT_READ_RESP_EVENT
ACI_ATT_READ_BLOB_RESP_EVENT
ACI_ATT_READ_MULTIPLE_RESP_EVENT
ACI_ATT_READ_BY_GROUP_TYPE_RESP_EVENT
ACI_ATT_PREPARE_WRITE_RESP_EVENT
ACI_ATT_EXEC_WRITE_RESP_EVENT
ACI_GATT_ERROR_RESP_EVENT
ACI_GATT_DISC_READ_CHAR_BY_UUID_RESP_EVENT
ACI_GATT_INDICATION_EVENT
ACI_GATT_INDICATION_EXT_EVENT
ACI_GATT_NOTIFICATION_EVENT
ACI_GATT_NOTIFICATION_EXT_EVENT
Server events
ACI_GATT_SERVER_CONFIRMATION_EVENT
ACI_GATT_READ_PERMIT_REQ_EVENT
ACI_GATT_READ_MULTI_PERMIT_REQ_EVENT
ACI_GATT_WRITE_PERMIT_REQ_EVENT
ACI_GATT_PREPARE_WRITE_PERMIT_REQ_EVENT
1.4. Flag configuration on STM32WB
To enable EATT feature on STM32WB:
Use SHCI_C2_BLE_INIT_OPTIONS_ENHANCED_ATT_SUPPORTED to configure CFG_BLE_OPTIONS_EXT in app_conf.h
Feature available only in "full extended" ble stack and certified in Cube 1.16.
1.5. Flag configuration on STM32WBA
To enable EATT feature on STM32WB:
Use BLE_OPTIONS_ENHANCED_ATT to initialize "options" field in pInitParams structure in app_ble.c
1.6. how to implement on STM32WB and STM32WBA applications
1. Set the flag and build the application.
2. Set the variable CFG_BLE_NUM_LINK to 1 (BLE link) + Channel_Number (parameter in ACI_L2CAP_COC_CONNECT command).
This Channel_Number corresponds to the number of "bearers" we want to establish.
3. Pairing and bonding of BLE link.
4. Establish a Connection Oriented Channel (COC) over the BLE link.
5. If condition 2. is filled, Channel_Number x ACI_GATT_EATT_BEARER_EVENT are received on central and peripheral sides.
On central side, Channel_Index (in ACI_GATT_EATT_BEARER_EVENT) is included between 0x00 and 0x1F.
On peripheral side, Channel_Index (in ACI_GATT_EATT_BEARER_EVENT) is included between 0x20 and 0x3F.
To address separately each bearer:
The connection handle to apply is between 0xEA00 and 0xEA1F for the central.
The connection handle to apply is between 0xEA20 and 0xEA3F for the peripheral.
2. Example of EATT feature including 5 bearers and data exchange
| BLE and COC link establishment with EATT (SPSM=0x0027) |
|---|
| EATT bearers events |
|---|
| GATT data exchange |
|---|
