Bluetooth GATT attribute pools

GATT attribute pools can be used to dynamically create a service description, which can later be registered in the Zephyr GATT database.

Every GATT service is essentially a set of GATT attributes that are ordered in a particular way. There are different types of attributes that can be registered to create a service:

  • Primary Service attribute, containing service metadata

  • Characteristic attribute, containing characteristic metadata

  • CCC descriptor attribute, used for turning notifications for a characteristic on or off

  • Regular descriptor attribute, used for providing an additional description for a characteristic

The API of the GATT attribute pools module allows to register different types of GATT attributes listed above. After each registration, a part of the memory is reserved for each attribute. You can also unregister attributes that are no longer needed by using the module’s API. In this case, the previously reserved memory is released. This can be useful when you want to restructure your service by using the Service Changed feature that is supported by the Zephyr Bluetooth stack (see, for example, the GATT Human Interface Device (HID) Service).

Additionally, you can adjust the memory footprint of this module to your needs by changing the configuration options for the size of the module’s memory pool. If you are unsure about the proper values, print the module’s statistics to see how the pool utilization level is affected by the chosen configuration.

API documentation

Header file: include/bluetooth/gatt_pool.h
Source file: subsys/bluetooth/gatt_pool.c
group bt_gatt_pool

Bluetooth LE GATT attribute pools.

Defines

BT_GATT_POOL_INIT(_attr_array_size)

Initialization of the GATT attribute pool variable.

This macro creates the initializer for the new attribute pool.

Parameters

  • _attr_array_size: Size of the attribute array.

BT_GATT_POOL_DEF(_name, _attr_array_size)

Define a new GATT attribute pool.

This macro creates a new attribute pool.

Parameters

  • _name: Name of the pool created.

  • _attr_array_size: Size of the attribute array.

BT_GATT_POOL_SVC(_gp, _svc_uuid_init)

Register a primary service descriptor.

Parameters

  • _gp: GATT service object with dynamic attribute allocation.

  • _svc_uuid_init: Service UUID.

BT_GATT_POOL_CHRC(_gp, _uuid, _props, _perm, _read, _write, _value)

Register a characteristic descriptor.

Parameters

  • _gp: GATT service object with dynamic attribute allocation.

  • _uuid: Characteristic UUID.

  • _props: Characteristic properties.

  • _perm: Characteristic access permissions.

  • _read: Characteristic read callback.

  • _write: Characteristic write callback.

  • _value: Characteristic value.

BT_GATT_POOL_DESC(_gp, _uuid, _perm, _read, _write, _value)

Register an attribute descriptor.

Parameters

  • _gp: GATT service object with dynamic attribute allocation.

  • _uuid: Descriptor UUID.

  • _perm: Descriptor access permissions.

  • _read: Descriptor read callback.

  • _write: Descriptor write callback.

  • _value: Descriptor value.

BT_GATT_POOL_CCC(_gp, _ccc, _ccc_changed, _perm)

Register a CCC descriptor.

Parameters

  • _gp: GATT service object with dynamic attribute allocation.

  • _ccc: CCC descriptor configuration.

  • _ccc_changed: CCC value changed callback.

  • _perm: CCC descriptor permissions.

Functions

int bt_gatt_pool_svc_alloc(struct bt_gatt_pool *gp, struct bt_uuid const *svc_uuid)

Take a primary service descriptor from the pool.

Parameters

  • gp: GATT service object with dynamic attribute allocation.

  • svc_uuid: Service UUID.

Return Value

  • 0: Operation finished successfully.

  • -EINVAL: Invalid input value.

  • -ENOSPC: Number of arguments in svc would exceed array_size.

  • -ENOMEM: No internal memory in the gatt_poll module.

int bt_gatt_pool_chrc_alloc(struct bt_gatt_pool *gp, uint8_t props, struct bt_gatt_attr const *attr)

Take a characteristic descriptor from the pool.

Return

0 or a negative error code.

Parameters

  • gp: GATT service object with dynamic attribute allocation.

  • props: Properties of the characteristic.

  • attr: Characteristic value attribute.

int bt_gatt_pool_desc_alloc(struct bt_gatt_pool *gp, struct bt_gatt_attr const *descriptor)

Take an attribute descriptor from the pool.

Return

0 or negative error code.

Parameters

  • gp: GATT service object with dynamic attribute allocation.

  • descriptor: Attribute descriptor.

int bt_gatt_pool_ccc_alloc(struct bt_gatt_pool *gp, struct _bt_gatt_ccc *ccc, uint8_t perm)

Take a CCC descriptor from the pool.

Return

0 or negative error code.

Parameters

  • gp: GATT service object with dynamic attribute allocation.

  • ccc: CCC descriptor.

  • perm: Permissions to access CCC. Use the GATT attribute permission bit field values.

void bt_gatt_pool_free(struct bt_gatt_pool *gp)

Free the whole dynamically created GATT service.

Parameters

  • gp: GATT service object with dynamic attribute allocation.

struct bt_gatt_pool
#include <gatt_pool.h>

The GATT service object that uses dynamic attribute allocation.

This structure contains the SVC object together with the number of the attributes available.

Public Members

struct bt_gatt_service svc

GATT service descriptor.

size_t attr_array_size

Maximum number of attributes supported.