1. Bluetooth® Low Energy GATT caching feature
| Bluetooth® Low Energy service discovery and attributes caching |
|---|
 |
GATT clients perform a procedure known as services and characteristics discovery to acquire details of the attribute table of the connected GATT server device.
Discovering the GATT database of a remote device at each connection takes time and consumes energy.
To avoid this, most Bluetooth® Low Energy 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 (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, 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.
It works only if the peer devices are bonded.
The GATT caching feature was introduced in Bluetooth® 5.1 to overcome the bonding problem.
Using GATT caching, every device can make sure that it has stored 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).
The 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 Bluetooth® Low Energy stack.
GATT server implementation:
- At GATT initialization, two new characteristics to the GATT service are added:
- Database Hash
- Client Supported Features (for “Robust Caching”)
- 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
- Nonbonded devices
The Database Hash characteristic stores a 128-bits value, which is an AES-CMAC hash calculated from the GATT database structure.
Any change in the database structure will result in a different hash value.
After discovering the database once, the client store this value. Next time, when the client connects to the server, it only check if the Database Hash has changed.
- If it has not, 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.1.2. Client supported feature characteristic
- Nonbonded devices
- In case Robust Caching is enabled on server by client, if there is a change in the GATT database when the link is established, the client receives Database Out-Of-Sync error when it sends an ATT command to the server.
- After this, the client becomes change-aware (from the server’s perspective).
It is the client's responsibility to restart a discovery of the services, characteristics and store the new database.
1.2. Flag configuration on STM32WB and STM32WBA
To enable the GATT caching feature on STM32WB set the CFG_BLE_OPTIONS_GATT_CACHING value to SHCI_C2_BLE_INIT_OPTIONS_GATT_CACHING_USED using the STM32CubeMX interface. This feature is available and certified only with the "Full extended Bluetooth® LE stack" higher v1.16.0 (stm32wb5x_BLE_Stack_full_extended_fw.bin).
| Enable GATT caching feature with STM32CubeMX for STM32WB |
|---|
To enable GATT caching feature on STM32WBA set the BLE_OPTIONS_GATT_CACHING value to "GATT caching is used" using the STM32CubeMX interface. This feature is available only with the "Full Bluetooth® LE stack" (stm32wba_ble_stack_full.a).
| Enable GATT caching feature with STM32CubeMX for STM32WBA |
|---|
1.3. How to implement on STM32WB and STM32WBA applications
1.3.1. Server and client
Enable the flag as described above.
1.3.2. Client
1.3.2.1. Database hash characteristic
Reads the Database Hash characteristic (0x2B2A) upon each connection and compare its value with the last stored value using the following command:
| aci_gatt_read_using_char_uuid |
|---|
|
Description
|
If the values match, it is safe to use the stored characteristic handles. If they do not match, start a service discovery to discover characteristic handles.
1.3.2.2. Client supported features characteristic
Enables Robust Caching feature by setting the Robust Caching bit to 1 in the Client Supported Features characteristic, it is now able to be informed of server database change. If the client initiates a GATT operation and the server database has changed, the server sends a database out-of-sync error as a response.
2. Example of GATT caching feature use on STM32WBA
2.1. Advertising data
At startup, the GATT caching server application starts advertising.
Data advertised are composed as follows:
| GATT caching server advertising packet | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Manufacturer data are encoded following STMicroelectronics BlueST-SDK v2 as described below:
| STMicroelectronics manufacturer advertising data | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2.2. On-board buttons configuration
| Button configuration for Bluetooth® Low Energy GATT caching application on Nucleo-WBA55CG boards | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2.3. Database hash characteristic
If the client and the server are not bonded, then the server assumes, that the client checks the Database Hash and/or discovers the GATT database upon each connection before initiating any GATT operation.
| Bluetooth® Database hash characteristic |
|---|
 |
2.4. Client supported features characteristic
If the client enables Robust Caching, by setting the Robust Caching bit to 1 in the Client Supported Features characteristic, then the server can send a database out-of-sync error code (0x12) as a response to a GATT operation whenever it assumes, that the client has an out-of-date database.
| Bluetooth® Robust caching feature in client supported features characteristic |
|---|
If the client and the server are bonded, then the server checks if the database has changed since the last connection and notifies the client about the change via service change indication - just like before introducing GATT caching.
The only difference is, that if the client initiates a GATT operation before the indication is received and confirmed, the server can send a database out-of-sync error code. This helps to avoid a race condition if the client would like to initiate a GATT operation too quickly after connection establishment.