STM32WB-WBA GATT Caching feature

1. Bluetooth^® LE GATT Caching feature

Bluetooth® LE 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^® LE 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”)

Information

A state machine defines whether or not the client view of the attribute table and the server view of its attribute table are in sync. The revised specification for attribute caching introduces the defined concept of Robust Caching that formalizes this state machine and introduces mechanisms for using it. Clients are said to be in the change-aware state or are change-unaware.

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 GATT 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 GATT 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 set the CFG_BLE_OPTIONS_GATT_CACHING value to SHCI_C2_BLE_INIT_OPTIONS_GATT_CACHING_USED using 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 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

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

Use:

aci_gatt_read_using_char_uuid

Description This command sends a Read By Type Request packet to the server in order to read the value attribute of the characteristics specified by the UUID. Syntax tBleStatus aci_gatt_read_using_char_uuid( uint16_t Connection_handle, uint16_t Start_handle, uint16_t End_handle, uint16_t UUID_type, const UUID_t* UUID ); Parameters [in] Connection_handle Type: uint16_t Description: Specifies the ATT bearer for which the command applies [in] Start_handle Type: uint16_t Description: Starting handle of the range to be searched. [in] End_handle Type: uint16_t Description: End handle of the range to be searched. [in] UUID_type Type: uint8_t Description: UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID. [in] UUID Type: 2 or 16 bytes Description: 16-bit UUID or 128-bit UUID Return value [out] command status Type: uint8_t Events generated ACI_GATT_DISC_READ_CHAR_BY_UUID_RESP_EVENT ACI_GATT_ERROR_RESP_EVENT ACI_GATT_PROC_COMPLETE_EVENT

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 on STM32WBA

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 Add char3 characteristic / Delete char3 characteristic / - / Connected Gatt caching Client Idle Starts scan then connects, discovers service/characteristics / - / - / Connected - 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

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