STM32WB-WBA GATT Data Base and bonded devices information storage

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Bluetooth^® Low Energy GATT Data Base SRAM computation

The Bluetooth^® Low Energy GATT Data Base SRAM computation describes the default GATT and GAP services in addition to services and characteristics for specific Bluetooth^® Low Energy user applications.

This computation includes the calculation of the number of services, the number of attributes and the Size of the storage area for the attribute values.

In the following chapters, there are descriptions of number of services (CFG_BLE_NUM_GATT_SERVICES), number of attributes (CFG_BLE_NUM_GATT_ATTRIBUTES) and Size of the storage area for the attribute values (CFG_BLE_ATT_VALUE_ARRAY_SIZE).

2. How to calculate CFG_BLE_NUM_GATT_SERVICES ?

CFG_BLE_NUM_GATT_SERVICES defines the number of services to be stored in the GATT database.
Note that the default GAP and GATT services are automatically added at initialization.
The parameter CFG_BLE_NUM_GATT_SERVICES must be the number of user services increased by 2 (number of default services: GAP and GATT services).
CFG_BLE_NUM_GATT_SERVICES = 2 + number of user's services

3. How to calculate CFG_BLE_NUM_GATT_ATTRIBUTES ?

CFG_BLE_NUM_GATT_ATTRIBUTES defines the number of attribute records related to all the characteristics for the specific user's Bluetooth^® Low Energy application.

For each characteristic:
The number of attribute records is from 2 to 5 depending on the characteristic properties:

Minimum of 2 (1 for declaration and 1 for the value)
Add 1 more record for each additional property: Notify or Indicate, Broadcast, Extended property
- Notify and Indicate properties correspond to CCCD (Client Characteristic Configuration Descriptor)
- Broadcast property corresponds to SCCD (Server Characteristic Configuration Descriptor)
- Extended property corresponds to CEPD (Characteristic Extended Property Descriptor)

The parameter CFG_BLE_NUM_GATT_ATTRIBUTES must be the number of the user's application attributes increased by 9 (the number of attributes of GAP and GATT default services)

CFG_BLE_NUM_GATT_ATTRIBUTES = 9 (number of attributes of default GAP and GATT services) + number of user's attributes

Number of attributes for default GAP and GATT services:

GAP Service:
- 2 bytes for the Device Name characteristic (1 byte for declaration + 1 byte for the value)
- 2 bytes for Appearance characteristic (1 byte for declaration + 1 byte for the value)
- 2 bytes Peripheral Preferred Connection Parameters characteristic (1 byte for declaration + 1 byte for the value)
GATT Service:
- 3 bytes for Service Changed characteristic (1 byte for declaration + 1 byte for the value + 1 byte for Notify property)

The number of attributes for default GAP and GATT services is equal to 9 bytes (6 bytes for GAP service + 3 bytes for GATT service):

Attributes of default GAP and GATT services (number = 9)

Example of service including characteristics with notification:

Attributes of service including characteristics with notification

4. How to calculate CFG_BLE_ATT_VALUE_ARRAY_SIZE ?

CFG_BLE_ATT_VALUE_ARRAY_SIZE defines the size of the storage area for the attribute values.

Each characteristic contributes to the Attribute Value Array Size as follows:
Characteristic value length plus:
– 5 bytes if characteristic UUID is 16 bits
– 19 bytes if characteristic UUID is 128 bits
– 2 bytes if characteristic has a server configuration descriptor
– 2 bytes * CFG_BLE_NUM_LINK if the characteristic has a client configuration descriptor
– 2 bytes if the characteristic has extended properties

Additionally, it is necessary to add characteristics related to the default GAP and GATT services:

GATT - Service change characteristic (if not removed): 9 bytes (5+2+2), 5 for UUID, 2 for indicate, 2 for characteristic value length
GAP - Device Name: 11 bytes (5+6), 5 for UUID, 6 for name length
GAP - Appearance: 7 bytes (5+2), 5 for UUID, 2 for attribute length
GAP - Peripheral Preferred Connection Parameters: 13 bytes (5+8), 5 for UUID, 8 for attribute length

Attribute Value Array Size of default GAP and GATT services

For this case default value array size: 9 + 31 = 40 bytes

Example of service including characteristics with notification - Attribute Value Array Size

Attribute Value Array Size of service including characteristics with notification

5. GATT database size in SRAM

5.1. STM32WB

Maximum size of SRAM allocation for the GATT database cannot be changed by the user's FW and varies for different stacks.

Calculation of the Max size allocated for GATT Data Base in SRAM is done in M0.

Max size table

	Bluetooth® LE Light stack	Bluetooth® LE Full stack	Bluetooth® LE Extended stack	Bluetooth® LE Full stack +Thread	Bluetooth® LE Full stack + Zigbee	Bluetooth® LE Full stack + MAC 802.15.4
WB55	10.5 kB	10.5 kB	10.5 kB	10.5 kB	10.5 kB	10.5 kB
WB15	2.7 kB	2.7 kB	2.7 kB	Not supported	Not supported	Not supported

To fit with the RAM memory size, the number of services, the number of attributes and the attribute value array size should follow this rule:

CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE < Max size

To apply the limitation, it is necessary to calculate the number of services, the number of attributes and the attribute value array size.

The document GATT_DB_Size_SRAM_NVM.xlsx ^[1] is part of the STM32WBCube delivery in \Middlewares\ST\STM32_WPAN\ble\core\doc.
This file allows the GATT database SRAM computation as well as the Bluetooth^® LE GATT database and security record in NVM depending on the user application.

5.2. STM32WBA

For STM32WBA, the application allocates the necessary GATT Data Base SRAM at Bluetooth® LE stack initialization. The value passed to the stack is equal to BLE_GATT_BUF_SIZE. This value is calculated thanks to CFG_BLE_NUM_GATT_ATTRIBUTES, CFG_BLE_NUM_GATT_SERVICES and CFG_BLE_ATT_VALUE_ARRAY_SIZE values initialized through CubeMX.

BLE_GATT_BUF_SIZE = CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE

Application configuration - BLE stack

6. Bluetooth^® Low Energy GATT database and security record in NVM

Some flags are available to store either the full GATT database or a reduce GATT database in NVM which allow the storage of more bonded devices.

6.1. Bluetooth^® Low Energy GATT Database record in NVM - FULL_GATTDB_NVM flag

See CFG_BLE_OPTIONS define in app_conf.h file, SHCI_C2_BLE_INIT_OPTIONS_FULL_GATTDB_NVM flag.

Application parameters

When SHCI_C2_BLE_INIT_OPTIONS_FULL_GATTDB_NVM flag is set in CFG_BLE_OPTIONS, the GATT Database record in NVM is composed:

Per service:
- 2 bytes for handle
- 3 bytes if 16-bit UUID or 17 bytes if 128-bit UUID

Per characteristic attribute:
- 2 bytes for handle
- 3 bytes if 16-bit UUID or 17 bytes if 128-bit UUID
- 2 bytes for CCCD value (only if the attribute is a CCCD)

if GATT Caching enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic

if Enhanced ATT enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic
- Add (3 x number of links) bytes for Server Supported Feature characteristic

The total corresponds to size_of_gatt record.

6.2. Bluetooth^® Low Energy GATT Database record in NVM - REDUC_GATTDB_NVM and NO_SVC_CHANGE_DESC flags

See CFG_BLE_OPTIONS define in app_conf.h file, SHCI_C2_BLE_INIT_OPTIONS_REDUC_GATTDB_NVM and SHCI_C2_BLE_INIT_OPTIONS_NO_SVC_CHANGE_DESC flags.

Application parameters

When SHCI_C2_BLE_INIT_OPTIONS_REDUC_GATTDB_NVM and SHCI_C2_BLE_INIT_OPTIONS_NO_SVC_CHANGE_DESC flags are set in CFG_BLE_OPTIONS, the GATT database record in NVM is composed:

Per characteristic attribute:
- 3 bytes for CCCD value (only if the attribute is a CCCD)

if GATT Caching enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic

if Enhanced ATT enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic
- Add (3 x number of links) bytes for Server Supported Feature characteristic

This is size_of_gatt record.

6.3. Bluetooth^® Low Energy GATT DB record in NVM - REDUC_GATTDB_NVM and WITH_SVC_CHANGE_DESC flags

See CFG_BLE_OPTIONS define in app_conf.h file, SHCI_C2_BLE_INIT_OPTIONS_REDUC_GATTDB_NVM and SHCI_C2_BLE_INIT_OPTIONS_WITH_SVC_CHANGE_DESC flags.

Application parameters

When SHCI_C2_BLE_INIT_OPTIONS_REDUC_GATTDB_NVM and SHCI_C2_BLE_INIT_OPTIONS_WITH_SVC_CHANGE_DESC flags are set in CFG_BLE_OPTIONS, the GATT database record in NVM is composed:

Per characteristic attribute:
- 3 bytes for CCCD value (only if the attribute is a CCCD)

if GATT Caching enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic

if Enhanced ATT enabled
- Add (3 x number of links) bytes for Client Supported Feature characteristic
- Add (3 x number of links) bytes for Server Supported Feature characteristic

+ 16 bytes (The Data Base hash stores a 128 bits value calculated from the Data Base structure.
Any change in the Data Base structure results in a different hash value.)

This is size_of_gatt record.

6.4. Bluetooth^® Low Energy security record

The security record in NVM is fixed and equal to 80 bytes, corresponding to size_of_sec record.

The security record includes the BD address of bonded device, and different keys: IRK, LTK and CSRK.

7. STM32WB - Bluetooth^® Low Energy number of bonded devices in NVM

Regarding the size of NVM, the computation of number n of bonded devices that can be stored in NVM is the following:

n = (total_size_of_nvm-1) / [ (size_of_sec_record+1) + (size_of_gatt record+1) ]

total_size_of_nvm = 2028 bytes (fixed in M0)
size_of_sec_record = 80 bytes (this is a constant from the BLE stack)
size_of_gatt_record is dependent on the flags chosen in the application in app_conf.h file.

See the description in the previous chapter.

7.1. Example 1 - Default GATT configuration without adding services

Default GATT configuration without adding services:

CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE
= 2 x 48 + 9 x 40 + 40
= 496 bytes

Size of default GATT record in SRAM is equal to 496 bytes.

7.1.1. When FULL_GATTDB_NVM flag is set

5 bytes for the GATT service (2 bytes for handle + 3 bytes for service 16-bit UUID)
+ 7 bytes for the Service Changed characteristic (2 bytes for handle + 3 bytes for service 16-bit UUID + 2 bytes for CCCD)
+ 5 bytes for the GAP service (2 bytes for handle + 3 bytes for service 16-bit UUID)
+ 5 bytes for the Device Name characteristic (2 bytes for handle + 3 bytes for service 16-bit UUID)
+ 5 bytes for the Appearance characteristic (2 bytes for handle + 3 bytes for service 16-bit UUID)
+ 5 bytes for the Peripheral Preferred Connection Parameters characteristic (2 bytes for handle + 3 bytes for service 16-bit UUID)
= 32 bytes

Size of default GATT record in NVM is equal to 32 bytes.

7.1.2. When REDUC_GATTDB_NVM and WITH_SVC_CHANGE_DESC flags are set

3 bytes for the Service Changed characteristic CCCD
+16 bytes for the data base hash
= 19 bytes

Size of default GATT record in NVM is equal to 19 bytes.

7.1.3. When REDUC_GATTDB_NVM and NO_SVC_CHANGE_DESC flags are set

Nothing is saved in NVM.

7.2. Example 2 - Default GATT configuration with 1 empty service

Default GATT configuration with 1 empty service:

CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE
= 3 x 48 + 9 x 40 + 40
= 544 bytes

Size of GATT record in SRAM is equal to 544 bytes.

7.2.1. When FULL_GATTDB_NVM flag is set

32 bytes for default GATT record
+ 5 bytes for the service (2 bytes for handle + 3 bytes for service 16-bit UUID)
= 37 bytes

Size of GATT record in NVM is equal to 37 bytes.

7.2.2. When REDUC_GATTDB_NVM and WITH_SVC_CHANGE_DESC flags are set

19 bytes for default GATT record
= 19 bytes

Size of GATT record in NVM is equal to 19 bytes.

7.2.3. When REDUC_GATTDB_NVM and NO_SVC_CHANGE_DESC flags are set

Nothing is saved in NVM.

7.3. Example 3 - Default GATT configuration with 1 service and 3 characteristics (3rd characteristic with notification property)

Default GATT configuration with 1 service and 3 characteristics (1 characteristic with notification property):

CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE
= 3 x 48 + 16 x 40 + 97
= 881 bytes

Size of GATT record in SRAM is equal to 881 bytes.

7.3.1. When FULL_GATTDB_NVM flag is set

32 bytes for default GATT record
+ 5 bytes for the service
+ 5 bytes for the 1st characteristic attribute
+ 5 bytes for the 2nd characteristic attribute
+ 7 bytes for the 3rd characteristic attribute (CCCD)
= 54 bytes

Size of GATT record in NVM is equal to 54 bytes.

7.3.2. When REDUC_GATTDB_NVM and WITH_SVC_CHANGE_DESC flags are set

19 bytes for default GATT record
+ 3 bytes for the 3rd characteristic attribute (CCCD)
= 22 bytes

Size of GATT record in NVM is equal to 22 bytes.

7.3.3. When REDUC_GATTDB_NVM and NO_SVC_CHANGE_DESC flags are set

3 bytes for the 3rd characteristic attribute (CCCD)

Size of GATT record in NVM is equal to 3 bytes.

7.4. Example 4 - Default GATT configuration with 4 services

Default GATT configuration with 4 services:

CFG_BLE_NUM_GATT_SERVICES x 48 + CFG_BLE_NUM_GATT_ATTRIBUTES x 40 + CFG_BLE_ATT_VALUE_ARRAY_SIZE
= 6 x 48 + 65 x 40 + 592
= 3480 bytes

Size of GATT record in SRAM is equal to 3480 bytes.

The following picture shows the GATT record size in NVM depending on flags choice:

Example 4 - Gatt record size difference depending on flags choice

7.4.1. When FULL_GATTDB_NVM flag is set

The GATT record size in NVM is equal to 469 bytes.

The number of bonded devices that can be stored in NVM is equal to:
n = (total_size_of_nvm-1) / [ (size_of_sec_record+1) + (size_of_gatt record+1) ]
= ((507x4)-1) / [(80+1) + (469+1)]
= 3

7.4.2. When REDUC_GATTDB_NVM and WITH_SVC_CHANGE_DESC flags are set

The GATT record size in NVM is equal to 37 bytes.

The number of bonded devices that can be stored in NVM is equal to:
n = (total_size_of_nvm-1) / [ (size_of_sec_record+1) + (size_of_gatt record+1) ]
= ((507x4)-1) / [(80+1) + (37+1)]
= 17

7.4.3. When REDUC_GATTDB_NVM and NO_SVC_CHANGE_DESC flags are set

The GATT record size in NVM is equal to 18 bytes.

The number of bonded devices that can be stored in NVM is equal to:
n = (total_size_of_nvm-1) / [ (size_of_sec_record+1) + (size_of_gatt record+1) ]
= ((507x4)-1) / [(80+1) + (18+1)]
= 20

8. STM32WBA - Bluetooth^® Low Energy number of bonded devices in NVM

Like in STM32WB, regarding the size of NVM, the computation of number n of bonded devices that can be stored in NVM is the following:

n = (total_size_of_nvm-1) / [ (size_of_sec_record+1) + (size_of_gatt record+1) ]

The total_size_of_nvm in STM32WBA can be adapted to the user's application needs and configured through CubeMX interface.

Application configuration - NVM

By default, in our application examples, SNVMA_NVM_NUMBER = 1, that defines 1 NVM with a 8192 bytes size.

total_size_of_nvm = 8192 bytes
size_of_sec_record = 80 bytes (this is a constant from the BLE stack)
size_of_gatt_record is dependent on the flags chosen in the application in app_conf.h file.

See the description in the previous point.

Refer to STM32CubeWBA Memory management wiki page for information on memory management.

9. General information concerning NVM

We don’t store values of attributes, only the CCCD value. It is applicable for GATT server only.

On server side it is used to: - check if services have changed - keep CCCD in memory

9.1. References

↑ GATT_DB_Size_SRAM_NVM.xlsx

[GATT_DB_Size_SRAM_NVM.xlsx-1] GATT_DB_Size_SRAM_NVM.xlsx

[1]