STM32WB-WBA GATT Caching feature

1. GATT Caching feature

Bluetooth® 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 consume 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 (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.

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)

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:
  • 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

• Non-bonded devices
  

The Database Hash characteristic stores a 128 bits 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.1.2. Client Supported Feature characteristic

• Non-bonded devices
  

• In case Robust Caching is enabled on server by client, if there is a change in database, client will receive Database Out-Of-Sync error when it sends an ATT command to server.
  

• After this, the client becomes change-aware (from server’s perspective).
  

• 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 has changed, the client needs to rediscover the GATT database.

1.2. Flag configuration on STM32WB

To enable GATT Caching feature on STM32WB:
Use SHCI_C2_BLE_INIT_OPTIONS_GATT_CACHING_USED to configure CFG_BLE_OPTIONS in app_conf.h

Feature available only in "full extended" ble stack and certified in Cube 1.16.

Enable GATT caching feature with CubeMX

1.3. Flag configuration on STM32WBA

To enable GATT Caching feature on STM32WB:
Use BLE_OPTIONS_GATT_CACHING to initialize "options" field in pInitParams structure in app_ble.c

1.4. how to implement on STM32WB and STM32WBA applications

1.4.1. On Server

Enable the flag as described above.

1.4.2. On Client

To enable GATT caching on client side:

Read the Database Hash characteristic upon each connection and compare its value with the last stored value.
Code ex.. If the values match, it is safe to use stored characteristic handles. If they do not match, start a service discovery to discover characteristic handles.

Enable Robust Caching by writing to the Client Supported Features characteristic of the server:
Code ex..

Check for database out-of-sync error after each GATT operation.
Code ex..

2. Example of GATT Caching feature use

..