From 0b0e1363b4e0332116d8ce19e1b892011e1c362a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eivind=20J=C3=B8lsgard?= Date: Wed, 8 Oct 2025 14:04:15 +0200 Subject: [PATCH] doc: lib: bluetooth: add GATT queue documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for BLE GATT queue. Signed-off-by: Eivind Jølsgard --- doc/nrf-bm/api/api.rst | 2 + .../libraries/bluetooth/ble_gatt_queue.rst | 76 +++++++++++++++++++ .../release_notes/release_notes_changelog.rst | 1 + 3 files changed, 79 insertions(+) create mode 100644 doc/nrf-bm/libraries/bluetooth/ble_gatt_queue.rst diff --git a/doc/nrf-bm/api/api.rst b/doc/nrf-bm/api/api.rst index d7b36f2271..6a50b5b327 100644 --- a/doc/nrf-bm/api/api.rst +++ b/doc/nrf-bm/api/api.rst @@ -105,6 +105,8 @@ Bare Metal Zephyr Memory Storage (ZMS) :inner: :members: +.. _api_gatt_queue: + GATT Queue ========== diff --git a/doc/nrf-bm/libraries/bluetooth/ble_gatt_queue.rst b/doc/nrf-bm/libraries/bluetooth/ble_gatt_queue.rst new file mode 100644 index 0000000000..ccf505251b --- /dev/null +++ b/doc/nrf-bm/libraries/bluetooth/ble_gatt_queue.rst @@ -0,0 +1,76 @@ +.. _lib_ble_gatt_queue: + +Bluetooth: GATT Queue +##################### + +.. contents:: + :local: + :depth: 2 + +The Bluetooth Low Energy® GATT Queue library can be used to buffer BLE GATT requests if the SoftDevice is not able to handle them at the moment. + +Overview +******** + +If the SoftDevice is not able to handle the GATT request at the moment, the BLE GATT Queue library buffers the request. +Later on, when the corresponding BLE event indicates that the SoftDevice may be free, the request is retried. +This library can be used in multiple connections scenario. + +The library currently handles the following types of GATT requests: + +* Read Characteristic or Descriptor (See ``sd_ble_gattc_read``) +* Write Characteristic Value or Descriptor (See ``sd_ble_gattc_write``) +* Primary Service Discovery (See ``sd_ble_gattc_primary_services_discover``) +* Characteristic Discovery (See ``sd_ble_gattc_characteristics_discover``) +* Descriptor Discovery (See ``sd_ble_gattc_descriptors_discover``) +* Notify or Indicate an attribute value. (See ``sd_ble_gatts_hvx``) + +The BLE GATT Queue can be used with BLE service clients and other BLE libraries that issue GATT requests to the SoftDevice. + +Configuration +************* + +The library is enabled and configured using the Kconfig system. +Set the :kconfig:option:`CONFIG_BLE_GATT_QUEUE` Kconfig option to enable the library. + +You can add an instance of the library to your application using the :c:macro:`BLE_GQ_DEF` macro. +If you need an instance that does not use the default parameters, it can be added with the :c:macro:`BLE_GQ_CUSTOM_DEF` macro. + +The library exposes the following Kconfig options for the default configuration: + +* :kconfig:option:`CONFIG_BLE_GQ_MAX_CONNECTIONS` - Sets the maximum simultaneous connections the GATT queue instance can manage. +* :kconfig:option:`CONFIG_BLE_GQ_QUEUE_SIZE` - Sets the max number of requests that can be queued for each connection that have been registered to the GATT queue instance. +* :kconfig:option:`CONFIG_BLE_GQ_HEAP_SIZE` - Sets the heap size for storing additional data that can be of variable size. + The heap is used for storing the data of write, notify and indicate requests. + +Initialization +============== + +The module does not require other initialization than adding the library instance as described above. + +Usage +***** + +Once defined, you can register a connection handle in the BLE Gatt Queue (BLE GQ) instance by calling the :c:func:`ble_gq_conn_handle_register` function. +From this point forward, the BLE GQ instance can handle GATT requests associated with the handle until the connection is no longer valid (for example when a disconnect event occurs). + +To add a GATT request to the BLE GQ instance, call the :c:func:`ble_gq_item_add` function. +This function adds a request to the BLE GQ instance and allocates the necessary memory for data that can be held within the request descriptor. +If the SoftDevice is free and the queue is empty, the request will be processed immediately. +Otherwise, the request is queued and processed later. + +Dependencies +************ + +This library uses the following |BMshort| libraries: + +* SoftDevice - :kconfig:option:`CONFIG_SOFTDEVICE` +* SoftDevice handler - :kconfig:option:`CONFIG_NRF_SDH` + +API documentation +***************** + +| Header file: :file:`include/bm/bluetooth/ble_gq.h` +| Source files: :file:`lib/bluetooth/ble_gq/` + +:ref:`Bluetooth LE GATT Queue library API reference ` diff --git a/doc/nrf-bm/release_notes/release_notes_changelog.rst b/doc/nrf-bm/release_notes/release_notes_changelog.rst index 5b522fa2b4..41dfe86cf7 100644 --- a/doc/nrf-bm/release_notes/release_notes_changelog.rst +++ b/doc/nrf-bm/release_notes/release_notes_changelog.rst @@ -134,5 +134,6 @@ Documentation * Added documentation for the :ref:`lib_bm_timer` library. * Added documentation for the :ref:`lib_ble_adv`. +* Added documentation for the :ref:`lib_ble_gatt_queue` library. * Added documentation for the :ref:`lib_event_scheduler` library. * Added documentation for the :ref:`lib_sensorsim` library.