From 8efc9f4869ee3cbc2f63ebd453ba51e268039673 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Reierstad?= Date: Thu, 27 Feb 2025 12:39:43 +0100 Subject: [PATCH] Bluetooth: Host: Improve more GATT documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds improvement to the GATT API documentation by providing examples of where (and how) certain structs are used, and adds specification references to the fields of bt_gatt_cpf to clarify their purpose. Signed-off-by: Håvard Reierstad --- doc/connectivity/bluetooth/api/gatt.rst | 17 ++-- include/zephyr/bluetooth/gatt.h | 125 +++++++++++++++++------- 2 files changed, 100 insertions(+), 42 deletions(-) diff --git a/doc/connectivity/bluetooth/api/gatt.rst b/doc/connectivity/bluetooth/api/gatt.rst index bb4487f57dd8..58920cdcb657 100644 --- a/doc/connectivity/bluetooth/api/gatt.rst +++ b/doc/connectivity/bluetooth/api/gatt.rst @@ -4,10 +4,18 @@ Generic Attribute Profile (GATT) ################################ -GATT layer manages the service database providing APIs for service registration -and attribute declaration. +The GATT layer manages the service database providing APIs for service +registration and attribute declaration. -Services can be registered using :c:func:`bt_gatt_service_register` API +The GATT Client initiates commands and requests towards the GATT Server, and can +receive responses, indications and notifications sent by the server. It is +enabled through the configuration option: +:kconfig:option:`CONFIG_BT_GATT_CLIENT` + +The GATT Server accepts incoming commands and requests from the GATT Client, and +sends responses, indications and notifications to the client. + +Services can be registered using the :c:func:`bt_gatt_service_register` API which takes the :c:struct:`bt_gatt_service` struct that provides the list of attributes the service contains. The helper macro :c:macro:`BT_GATT_SERVICE()` can be used to declare a service. @@ -61,9 +69,6 @@ pass a callback to be called when it is necessary to know the exact instant when the data has been transmitted over the air. Indications are supported by :c:func:`bt_gatt_indicate` API. -Client procedures can be enabled with the configuration option: -:kconfig:option:`CONFIG_BT_GATT_CLIENT` - Discover procedures can be initiated with the use of :c:func:`bt_gatt_discover` API which takes the :c:struct:`bt_gatt_discover_params` struct which describes the type of diff --git a/include/zephyr/bluetooth/gatt.h b/include/zephyr/bluetooth/gatt.h index d736c95ae5fe..180faf1d1958 100644 --- a/include/zephyr/bluetooth/gatt.h +++ b/include/zephyr/bluetooth/gatt.h @@ -12,6 +12,9 @@ /** * @brief Generic Attribute Profile (GATT) + * @details The GATT layer manages the service database by providing APIs for + * service registration and attribute declaration. For more + * information, see @ref bt_gatt_client and @ref bt_gatt_server. * @defgroup bt_gatt Generic Attribute Profile (GATT) * @ingroup bluetooth * @{ @@ -222,9 +225,9 @@ typedef ssize_t (*bt_gatt_attr_write_func_t)(struct bt_conn *conn, * pass the pointer to GATT server APIs. */ struct bt_gatt_attr { - /** @brief Attribute Type, aka. "UUID" + /** @brief Attribute Type * - * The Attribute Type determines the interface that can + * The Attribute Type is a UUID which determines the interface that can * be expected from the read() and write() methods and * the possible permission configurations. * @@ -275,16 +278,13 @@ struct bt_gatt_attr { */ void *user_data; - /** @brief Attribute Handle or zero, maybe? + /** @brief Attribute Handle * - * The meaning of this field varies and is not specified here. - * Some APIs use this field as input/output. It does not always - * contain the Attribute Handle. + * The Attribute Handle is an index corresponding to a specific + * Attribute in the ATT database. * * @note Use bt_gatt_attr_get_handle() for attributes in the * local ATT database. - * - * @sa bt_gatt_discover_func_t about this field. */ uint16_t handle; @@ -294,8 +294,6 @@ struct bt_gatt_attr { * * The permissions are security requirements that must be * satisfied before calling read() or write(). - * - * @sa bt_gatt_discover_func_t about this field. */ uint16_t perm: 15; @@ -311,7 +309,12 @@ struct bt_gatt_attr { /** @endcond */ }; -/** @brief GATT Service structure */ +/** @brief Static GATT Service structure + * + * Allows the user the declare static GATT Services with the aim of reducing the + * used RAM. The @ref BT_GATT_SERVICE_DEFINE macro can be used to statically + * define and register a service. + */ struct bt_gatt_service_static { /** Service Attributes */ const struct bt_gatt_attr *attrs; @@ -319,31 +322,45 @@ struct bt_gatt_service_static { size_t attr_count; }; -/** @brief GATT Service structure */ +/** @brief GATT Service structure + * + * This structure is used to define GATT services which can be registered and + * unregistered at runtime. See @ref bt_gatt_service_register for when services + * should be registered. + */ struct bt_gatt_service { /** Service Attributes */ struct bt_gatt_attr *attrs; /** Service Attribute count */ size_t attr_count; - + /** Internally used field for list handling */ sys_snode_t node; }; -/** @brief Service Attribute Value. */ +/** @brief Service Attribute Value. + * + * This is the data described by the Attribute Type and indexed by the + * Attribute Handle in the database. + */ struct bt_gatt_service_val { /** Service UUID. */ const struct bt_uuid *uuid; - /** Service end handle. */ + /** Handle of the last Attribute within the Service. */ uint16_t end_handle; }; -/** @brief Include Attribute Value. */ +/** @brief Include Attribute Value. + * + * This structure represents an included service attribute in the GATT + * server. An included service is a service that is referenced within another + * service, allowing for the reuse of common service definitions. + */ struct bt_gatt_include { /** Service UUID. */ const struct bt_uuid *uuid; - /** Service start handle. */ + /** Handle of the first attribute within the included service. */ uint16_t start_handle; - /** Service end handle. */ + /** Handle of the last attribute within the included service. */ uint16_t end_handle; }; @@ -360,6 +377,7 @@ struct bt_gatt_cb { */ void (*att_mtu_updated)(struct bt_conn *conn, uint16_t tx, uint16_t rx); + /** Internally used field for list handling */ sys_snode_t node; }; @@ -448,13 +466,17 @@ struct bt_gatt_authorization_cb { */ #define BT_GATT_CHRC_EXT_PROP 0x80 -/** @brief Characteristic Attribute Value. */ +/** @brief Attribute Value of a Characteristic Declaration. + * + * This is the data associated with the characteristic, and can be read from or + * written to by a GATT client depending on the characteristic properties. + */ struct bt_gatt_chrc { /** Characteristic UUID. */ const struct bt_uuid *uuid; /** Characteristic Value handle. */ uint16_t value_handle; - /** Characteristic properties. */ + /** Characteristic properties, a bitmap of ``BT_GATT_CHRC_*`` macros. */ uint8_t properties; }; @@ -462,9 +484,15 @@ struct bt_gatt_chrc { #define BT_GATT_CEP_RELIABLE_WRITE 0x0001 #define BT_GATT_CEP_WRITABLE_AUX 0x0002 -/** @brief Characteristic Extended Properties Attribute Value. */ +/** @brief Characteristic Extended Properties Attribute Value. + * + * Used in the discovery of standard characteristic descriptor values. Shall + * exist if the @ref BT_GATT_CHRC_EXT_PROP bit is set in the characteristic + * properties. Can be used with the @ref BT_GATT_CEP macro to declare the CEP + * descriptor. + */ struct bt_gatt_cep { - /** Characteristic Extended properties */ + /** Characteristic Extended properties, a bitmap of ``BT_GATT_CEP_*`` macros. */ uint16_t properties; }; @@ -483,9 +511,12 @@ struct bt_gatt_cep { */ #define BT_GATT_CCC_INDICATE 0x0002 -/** Client Characteristic Configuration Attribute Value */ +/** @brief Client Characteristic Configuration Attribute Value + * + * Used in the discovery of standard characteristic descriptor values. + */ struct bt_gatt_ccc { - /** Client Characteristic Configuration flags */ + /** Client Characteristic Configuration flags, a bitmap of ``BT_GATT_CCC_*`` macros. */ uint16_t flags; }; @@ -499,25 +530,45 @@ struct bt_gatt_ccc { */ #define BT_GATT_SCC_BROADCAST 0x0001 -/** Server Characteristic Configuration Attribute Value */ +/** @brief Server Characteristic Configuration Attribute Value + * + * Used in the discovery of standard characteristic descriptor values. + */ struct bt_gatt_scc { - /** Server Characteristic Configuration flags */ + /** Server Characteristic Configuration flags, a bitmap of ``BT_GATT_SCC_*`` macros. */ uint16_t flags; }; -/** @brief GATT Characteristic Presentation Format Attribute Value. */ +/** @brief GATT Characteristic Presentation Format Attribute Value. + * + * Used in the discovery of standard characteristic descriptor values. Can be + * used with the @ref BT_GATT_CPF macro to declare the CPF descriptor. + */ struct bt_gatt_cpf { - /** Format of the value of the characteristic */ + /** Format of the value of the characteristic. The format types can be + * found in section 2.4.1 of the Bluetooth SIG Assigned Numbers document. + */ uint8_t format; /** Exponent field to determine how the value of this characteristic is - * further formatted + * further formatted. Only used on integer format types. + * actual value = Characteristic Value x 10^Exponent */ int8_t exponent; - /** Unit of the characteristic */ + /** UUID of the unit of the characteristic. The units can be found in + * section 3.5 of the Bluetooth SIG Assigned Numbers document. + */ uint16_t unit; - /** Name space of the description */ + /** Name space of the description, used to identify the organization + * that is responsible for defining the enumerations for the + * description field. See section 2.4.2 of the Bluetooth SIG Assigned + * Numbers document. + */ uint8_t name_space; - /** Description of the characteristic as defined in a higher layer profile */ + /** Description of the characteristic as defined in a higher layer + * profile. An enumerated value defined by the organization identified + * by the name_space field. See section 2.4.2.1 of the Bluetooth SIG + * Assigned Numbers document. + */ uint16_t description; }; @@ -717,8 +768,8 @@ uint16_t bt_gatt_attr_get_handle(const struct bt_gatt_attr *attr); * * @param attr A Characteristic Attribute. * - * @note The ``user_data`` of the attribute must of type @ref bt_gatt_chrc and the ``uuid`` shall be - * BT_UUID_GATT_CHRC + * @note The ``user_data`` of the attribute must be of type @ref bt_gatt_chrc and the ``uuid`` shall + * be BT_UUID_GATT_CHRC. * * @return the handle of the corresponding Characteristic Value. The value will * be zero (the invalid handle) if @p attr was not a characteristic @@ -1666,6 +1717,7 @@ struct bt_gatt_discover_params { /** Discover attribute callback */ bt_gatt_discover_func_t func; union { + /** See @ref bt_gatt_include for more on included services. */ struct { /** Include service attribute declaration handle */ uint16_t attr_handle; @@ -1784,9 +1836,9 @@ struct bt_gatt_read_params { bool variable; } multiple; struct { - /** First requested handle number. */ + /** Attribute handle to start reading from. */ uint16_t start_handle; - /** Last requested handle number. */ + /** Attribute handle to stop reading at. */ uint16_t end_handle; /** 2 or 16 octet UUID. */ const struct bt_uuid *uuid; @@ -2074,6 +2126,7 @@ struct bt_gatt_subscribe_params { /** Subscription flags */ ATOMIC_DEFINE(flags, BT_GATT_SUBSCRIBE_NUM_FLAGS); + /** Internally used field for list handling */ sys_snode_t node; #if defined(CONFIG_BT_EATT) enum bt_att_chan_opt chan_opt;