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 when link is established, 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).
  

It is the client's responsability to restart a discovery of the services, characteristics and store the new database.

1.2. Flag configuration on STM32WB and STM32WBA

To enable GATT Caching feature on STM32WB-WBA:

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

Enable GATT caching feature with CubeMX-WB

Feature available in "full ble stack"

Enable GATT caching feature with CubeMX-WBA

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

• Reads the Database Hash characteristic upon each connection and compare its value with the last stored value.
  

use:
aci_gatt_read_using_char_uuid(connHdl, 0x0001, 0xFFFF, UUID_TYPE_16, &uuid_DatabaseHash);  
UUID_t uuid_DatabaseHash; 
uuid_DatabaseHash.UUID_16 = (0x2B2A);

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.

• Enables Robust Caching feature by writing to the Client Supported Features characteristic of the server:
  

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

2. Example of GATT Caching feature use

2.1. Advertising data

At startup, Gatt caching Server application starts Advertising.
Data advertised are composed as follows:

Gatt caching Server Advertising packet
Description Length AD Type Value Device Name 8 0x09 GC_XX (XX: last byte of BD address) Manufacturer Data 15 0xFF See table below Flags 2 0x01 0x06 (GeneralDiscoverable, BrEdrNotSupported)

Manufacturer data are encoded following STMicroelectronics BlueST SDK v2 as described below:

STMicroelectronics Manufacturer Advertising data
Byte Index 0 1 2-3 4 5 6 7 8 9 10-15 Function Length Manufacturer ID Company BlueST SDK Version Device ID Firmware ID Option 1 Option 2 Option 3 Device Address Value 0x0F 0xFF 0x0030 STMicro 0x02 0x8B Nucleo-WBA 0xE0 - Gatt caching Server 0x00 0x00 0x00 0x08E12Axxxx

2.2. On-board buttons configuration

Button configuration for Bluetooth® Low Energy Gatt caching application on Nucleo-WBA55CG boards
Application Condition B1 Click B1 Long Press B2 Click B2 Long Press B3 Click B3 Long Press Gatt caching Server Idle Connected Add char3 characteristic Add char3 characteristic / Delete char3 characteristic Delete char3 characteristic / - - / Gatt caching Client Idle Connected Starts scan then connects, discovers service/characteristics - / - Sends disconnection request / - Read char3 data /

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
File:connectivity database Hash charac2.png

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 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
File:connectivity robust caching ClientSupportedFeature charac3.png

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 race condition if the client would like to initiate a GATT operation too quickly after connection establishment.