GATT Client APIs

Data Structures
struct	bt_gatt_exchange_params
	GATT Exchange MTU parameters. More...
struct	bt_gatt_discover_params
	GATT Discover Attributes parameters. More...
struct	bt_gatt_read_params
	GATT Read parameters. More...
struct	bt_gatt_write_params
	GATT Write parameters. More...
struct	bt_gatt_subscribe_params
	GATT Subscribe parameters. More...

Typedefs
typedef uint8_t(*	bt_gatt_discover_func_t) (struct bt_conn *conn, const struct bt_gatt_attr *attr, struct bt_gatt_discover_params *params)
	Discover attribute callback function.
typedef uint8_t(*	bt_gatt_read_func_t) (struct bt_conn *conn, uint8_t err, struct bt_gatt_read_params *params, const void *data, uint16_t length)
	Read callback function.
typedef void(*	bt_gatt_write_func_t) (struct bt_conn *conn, uint8_t err, struct bt_gatt_write_params *params)
	Write callback function.
typedef uint8_t(*	bt_gatt_notify_func_t) (struct bt_conn *conn, struct bt_gatt_subscribe_params *params, const void *data, uint16_t length)
	Notification callback function.
typedef void(*	bt_gatt_subscribe_func_t) (struct bt_conn *conn, uint8_t err, struct bt_gatt_subscribe_params *params)
	Subscription callback function.

Enumerations
enum	{   BT_GATT_DISCOVER_PRIMARY , BT_GATT_DISCOVER_SECONDARY , BT_GATT_DISCOVER_INCLUDE , BT_GATT_DISCOVER_CHARACTERISTIC ,   BT_GATT_DISCOVER_DESCRIPTOR , BT_GATT_DISCOVER_ATTRIBUTE , BT_GATT_DISCOVER_STD_CHAR_DESC }
	GATT Discover types. More...
enum	{   BT_GATT_SUBSCRIBE_FLAG_VOLATILE , BT_GATT_SUBSCRIBE_FLAG_NO_RESUB , BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING , BT_GATT_SUBSCRIBE_FLAG_SENT ,   BT_GATT_SUBSCRIBE_NUM_FLAGS }
	Subscription flags. More...

Functions
int	bt_gatt_exchange_mtu (struct bt_conn *conn, struct bt_gatt_exchange_params *params)
	Exchange MTU.
int	bt_gatt_discover (struct bt_conn *conn, struct bt_gatt_discover_params *params)
	GATT Discover function.
int	bt_gatt_read (struct bt_conn *conn, struct bt_gatt_read_params *params)
	Read Attribute Value by handle.
int	bt_gatt_write (struct bt_conn *conn, struct bt_gatt_write_params *params)
	Write Attribute Value by handle.
int	bt_gatt_write_without_response_cb (struct bt_conn *conn, uint16_t handle, const void *data, uint16_t length, bool sign, bt_gatt_complete_func_t func, void *user_data)
	Write Attribute Value by handle without response with callback.
static int	bt_gatt_write_without_response (struct bt_conn *conn, uint16_t handle, const void *data, uint16_t length, bool sign)
	Write Attribute Value by handle without response.
int	bt_gatt_subscribe (struct bt_conn *conn, struct bt_gatt_subscribe_params *params)
	Subscribe Attribute Value Notification.
int	bt_gatt_resubscribe (uint8_t id, const bt_addr_le_t *peer, struct bt_gatt_subscribe_params *params)
	Resubscribe Attribute Value Notification subscription.
int	bt_gatt_unsubscribe (struct bt_conn *conn, struct bt_gatt_subscribe_params *params)
	Unsubscribe Attribute Value Notification.
void	bt_gatt_cancel (struct bt_conn *conn, void *params)
	Try to cancel the first pending request identified by params.

Detailed Description

Typedef Documentation

bt_gatt_discover_func_t

bt_gatt_discover_func_t

#include <zephyr/bluetooth/gatt.h>

Discover attribute callback function.

Parameters

conn	Connection object.
attr	Attribute found, or NULL if not found.
params	Discovery parameters given.

If discovery procedure has completed this callback will be called with attr set to NULL. This will not happen if procedure was stopped by returning BT_GATT_ITER_STOP.

The attribute object as well as its UUID and value objects are temporary and must be copied to in order to cache its information. Only the following fields of the attribute contains valid information:

• uuid UUID representing the type of attribute.
• handle Handle in the remote database.
• user_data The value of the attribute, if the discovery type maps to an ATT operation that provides this information. NULL otherwise. See below.

The effective type of attr->user_data is determined by params. Note that the fields params->type and params->uuid are left unchanged by the discovery procedure.

params->type	params->uuid	Type of attr->user_data
BT_GATT_DISCOVER_PRIMARY	any	bt_gatt_service_val
BT_GATT_DISCOVER_SECONDARY	any	bt_gatt_service_val
BT_GATT_DISCOVER_INCLUDE	any	bt_gatt_include
BT_GATT_DISCOVER_CHARACTERISTIC	any	bt_gatt_chrc
BT_GATT_DISCOVER_STD_CHAR_DESC	BT_UUID_GATT_CEP	bt_gatt_cep
BT_GATT_DISCOVER_STD_CHAR_DESC	BT_UUID_GATT_CCC	bt_gatt_ccc
BT_GATT_DISCOVER_STD_CHAR_DESC	BT_UUID_GATT_SCC	bt_gatt_scc
BT_GATT_DISCOVER_STD_CHAR_DESC	BT_UUID_GATT_CPF	bt_gatt_cpf
BT_GATT_DISCOVER_DESCRIPTOR	any	NULL
BT_GATT_DISCOVER_ATTRIBUTE	any	NULL

Also consider if using read-by-type instead of discovery is more convenient. See bt_gatt_read with bt_gatt_read_params::handle_count set to 0.

Returns

BT_GATT_ITER_CONTINUE to continue discovery procedure.

BT_GATT_ITER_STOP to stop discovery procedure.

bt_gatt_notify_func_t

bt_gatt_notify_func_t

#include <zephyr/bluetooth/gatt.h>

Notification callback function.

In the case of an empty notification, the data pointer will be non-NULL while the length will be 0, which is due to the special case where a data NULL pointer means unsubscribed.

Parameters

conn	Connection object. May be NULL, indicating that the peer is being unpaired
params	Subscription parameters.
data	Attribute value data. If NULL then subscription was removed.
length	Attribute value length.

Returns

BT_GATT_ITER_CONTINUE to continue receiving value notifications. BT_GATT_ITER_STOP to unsubscribe from value notifications.

bt_gatt_read_func_t

bt_gatt_read_func_t

#include <zephyr/bluetooth/gatt.h>

Read callback function.

When reading using by_uuid, params->start_handle is the attribute handle for this data item.

Parameters

conn	Connection object.
err	ATT error code.
params	Read parameters used.
data	Attribute value data. NULL means read has completed.
length	Attribute value length.

Returns

BT_GATT_ITER_CONTINUE if should continue to the next attribute.

BT_GATT_ITER_STOP to stop.

bt_gatt_subscribe_func_t

bt_gatt_subscribe_func_t

#include <zephyr/bluetooth/gatt.h>

Subscription callback function.

Parameters

conn	Connection object.
err	ATT error code.
params	Subscription parameters used.

bt_gatt_write_func_t

bt_gatt_write_func_t

#include <zephyr/bluetooth/gatt.h>

Write callback function.

Parameters

conn	Connection object.
err	ATT error code.
params	Write parameters used.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <zephyr/bluetooth/gatt.h>

GATT Discover types.

Enumerator
BT_GATT_DISCOVER_PRIMARY	Discover Primary Services.
BT_GATT_DISCOVER_SECONDARY	Discover Secondary Services.
BT_GATT_DISCOVER_INCLUDE	Discover Included Services.
BT_GATT_DISCOVER_CHARACTERISTIC	Discover Characteristic Values. Discover Characteristic Value and its properties.
BT_GATT_DISCOVER_DESCRIPTOR	Discover Descriptors. Discover Attributes which are not services or characteristics. @note The use of this type of discover is not recommended for discovering in ranges across multiple services/characteristics as it may incur in extra round trips.
BT_GATT_DISCOVER_ATTRIBUTE	Discover Attributes. Discover Attributes of any type. @note The use of this type of discover is not recommended for discovering in ranges across multiple services/characteristics as it may incur in more round trips.
BT_GATT_DISCOVER_STD_CHAR_DESC	Discover standard characteristic descriptor values. Discover standard characteristic descriptor values and their properties. Supported descriptors: - Characteristic Extended Properties - Client Characteristic Configuration - Server Characteristic Configuration - Characteristic Presentation Format

anonymous enum

anonymous enum

#include <zephyr/bluetooth/gatt.h>

Subscription flags.

Enumerator
BT_GATT_SUBSCRIBE_FLAG_VOLATILE	Persistence flag. If set, indicates that the subscription is not saved on the GATT server side. Therefore, upon disconnection, the subscription will be automatically removed from the client's subscriptions list and when the client reconnects, it will have to issue a new subscription.
BT_GATT_SUBSCRIBE_FLAG_NO_RESUB	No resubscribe flag. By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the subscription will be automatically renewed when the client reconnects, as a workaround for GATT servers that do not persist subscriptions. This flag will disable the automatic resubscription. It is useful if the application layer knows that the GATT server remembers subscriptions from previous connections and wants to avoid renewing the subscriptions.
BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING	Write pending flag. If set, indicates write operation is pending waiting remote end to respond. @note Internal use only.
BT_GATT_SUBSCRIBE_FLAG_SENT	Sent flag. If set, indicates that a subscription request (CCC write) has already been sent in the active connection. Used to avoid sending subscription requests multiple times when the \htmlonly <code>CONFIG_BT_GATT_AUTO_RESUBSCRIBE</code> \endhtmlonly \xmlonly <verbatim>embed:rst:inline :kconfig:option:`CONFIG_BT_GATT_AUTO_RESUBSCRIBE`</verbatim> \endxmlonly quirk is enabled. @note Internal use only.
BT_GATT_SUBSCRIBE_NUM_FLAGS

Function Documentation

bt_gatt_cancel()

void bt_gatt_cancel	(	struct bt_conn *	conn,
		void *	params
	)

#include <zephyr/bluetooth/gatt.h>

Try to cancel the first pending request identified by params.

This function does not release params for reuse. The usual callbacks for the request still apply. A successful cancel simulates a BT_ATT_ERR_UNLIKELY response from the server.

This function can cancel the following request functions:

• bt_gatt_exchange_mtu
• bt_gatt_discover
• bt_gatt_read
• bt_gatt_write
• bt_gatt_subscribe
• bt_gatt_unsubscribe

Parameters

conn	The connection the request was issued on.
params	The address params used in the request function call.

bt_gatt_discover()

int bt_gatt_discover	(	struct bt_conn *	conn,
		struct bt_gatt_discover_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

GATT Discover function.

This procedure is used by a client to discover attributes on a server.

Primary Service Discovery: Procedure allows to discover primary services either by Discover All Primary Services or Discover Primary Services by Service UUID. Include Service Discovery: Procedure allows to discover all Include Services within specified range. Characteristic Discovery: Procedure allows to discover all characteristics within specified handle range as well as discover characteristics with specified UUID. Descriptors Discovery: Procedure allows to discover all characteristic descriptors within specified range.

For each attribute found the callback is called which can then decide whether to continue discovering or stop.

The Response comes in callback params->func. The callback is run from the BT RX thread. params must remain valid until start of callback where iter attr is NULL or callback will return BT_GATT_ITER_STOP.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
params	Discover parameters.

Return values

0	Successfully queued request. Will call params->func on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .

bt_gatt_exchange_mtu()

int bt_gatt_exchange_mtu	(	struct bt_conn *	conn,
		struct bt_gatt_exchange_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Exchange MTU.

This client procedure can be used to set the MTU to the maximum possible size the buffers can hold.

Note

Shall only be used once per connection.

The Response comes in callback params->func. The callback is run from the context specified by 'config BT_RECV_CONTEXT'. params must remain valid until start of callback.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
params	Exchange MTU parameters.

Return values

0	Successfully queued request. Will call params->func on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .
-EALREADY	The MTU exchange procedure has been already performed.

bt_gatt_read()

int bt_gatt_read	(	struct bt_conn *	conn,
		struct bt_gatt_read_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Read Attribute Value by handle.

This procedure read the attribute value and return it to the callback.

When reading attributes by UUID the callback can be called multiple times depending on how many instances of given the UUID exists with the start_handle being updated for each instance.

To perform a GATT Long Read procedure, start with a Characteristic Value Read (by setting offset 0 and handle_count 1) and then return BT_GATT_ITER_CONTINUE from the callback. This is equivalent to calling bt_gatt_read again, but with the correct offset to continue the read. This may be repeated until the procedure is complete, which is signaled by the callback being called with data set to NULL.

Note that returning BT_GATT_ITER_CONTINUE is really starting a new ATT operation, so this can fail to allocate resources. However, all API errors are reported as if the server returned BT_ATT_ERR_UNLIKELY. There is no way to distinguish between this condition and a BT_ATT_ERR_UNLIKELY response from the server itself.

Note that the effect of returning BT_GATT_ITER_CONTINUE from the callback varies depending on the type of read operation.

The Response comes in callback params->func. The callback is run from the context specified by 'config BT_RECV_CONTEXT'. params must remain valid until start of callback.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
params	Read parameters.

Return values

0	Successfully queued request. Will call params->func on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .

bt_gatt_resubscribe()

int bt_gatt_resubscribe	(	uint8_t	id,
		const bt_addr_le_t *	peer,
		struct bt_gatt_subscribe_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Resubscribe Attribute Value Notification subscription.

Resubscribe to Attribute Value Notification when already subscribed from a previous connection. The GATT server will remember subscription from previous connections when bonded, so resubscribing can be done without performing a new subscribe procedure after a power cycle.

Note

Notifications are asynchronous therefore the parameters need to remain valid while subscribed.

Parameters

id	Local identity (in most cases BT_ID_DEFAULT).
peer	Remote address.
params	Subscribe parameters.

Returns

0 in case of success or negative value in case of error.

bt_gatt_subscribe()

int bt_gatt_subscribe	(	struct bt_conn *	conn,
		struct bt_gatt_subscribe_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Subscribe Attribute Value Notification.

This procedure subscribe to value notification using the Client Characteristic Configuration handle. If notification received subscribe value callback is called to return notified value. One may then decide whether to unsubscribe directly from this callback. Notification callback with NULL data will not be called if subscription was removed by this method.

The Response comes in callback params->subscribe. The callback is run from the context specified by 'config BT_RECV_CONTEXT'. The Notification callback params->notify is also called from the BT RX thread.

Note

Notifications are asynchronous therefore the params must remain valid while subscribed and cannot be reused for additional subscriptions whilst active.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
params	Subscribe parameters.

Return values

0	Successfully queued request. Will call params->write on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .
-EALREADY	if there already exist a subscription using the params.
-EBUSY	if params.ccc_handle is 0 and CONFIG_BT_GATT_AUTO_DISCOVER_CCC is enabled and discovery for the params is already in progress.

bt_gatt_unsubscribe()

int bt_gatt_unsubscribe	(	struct bt_conn *	conn,
		struct bt_gatt_subscribe_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Unsubscribe Attribute Value Notification.

This procedure unsubscribe to value notification using the Client Characteristic Configuration handle. Notification callback with NULL data will be called if subscription was removed by this call, until then the parameters cannot be reused.

The Response comes in callback params->func. The callback is run from the BT RX thread.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
params	Subscribe parameters. The parameters shall be a bt_gatt_subscribe_params from a previous call to bt_gatt_subscribe().

Return values

0	Successfully queued request. Will call params->write on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .

bt_gatt_write()

int bt_gatt_write	(	struct bt_conn *	conn,
		struct bt_gatt_write_params *	params
	)

#include <zephyr/bluetooth/gatt.h>

Write Attribute Value by handle.

The Response comes in callback params->func. The callback is run from the context specified by 'config BT_RECV_CONTEXT'. params must remain valid until start of callback.

This function will block while the ATT request queue is full, except when called from Bluetooth event context. When called from Bluetooth context, this function will instead instead return -ENOMEM if it would block to avoid a deadlock.

Parameters

conn	Connection object.
params	Write parameters.

Return values

0	Successfully queued request. Will call params->func on resolution.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside Bluetooth event context to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .

bt_gatt_write_without_response()

static int bt_gatt_write_without_response ( struct bt_conn *  conn, uint16_t  handle, const void *  data, uint16_t  length, bool  sign  )

inlinestatic

#include <zephyr/bluetooth/gatt.h>

Write Attribute Value by handle without response.

This procedure write the attribute value without requiring an acknowledgment that the write was successfully performed

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
handle	Attribute handle.
data	Data to be written.
length	Data length.
sign	Whether to sign data

Return values

0	Successfully queued request.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .

bt_gatt_write_without_response_cb()

int bt_gatt_write_without_response_cb	(	struct bt_conn *	conn,
		uint16_t	handle,
		const void *	data,
		uint16_t	length,
		bool	sign,
		bt_gatt_complete_func_t	func,
		void *	user_data
	)

#include <zephyr/bluetooth/gatt.h>

Write Attribute Value by handle without response with callback.

This function works in the same way as bt_gatt_write_without_response. With the addition that after sending the write the callback function will be called.

The callback is run from System Workqueue context. When called from the System Workqueue context this API will not wait for resources for the callback but instead return an error. The number of pending callbacks can be increased with the CONFIG_BT_CONN_TX_MAX option.

Note

By using a callback it also disable the internal flow control which would prevent sending multiple commands without waiting for their transmissions to complete, so if that is required the caller shall not submit more data until the callback is called.

This function will block while the ATT request queue is full, except when called from the BT RX thread, as this would cause a deadlock.

Parameters

conn	Connection object.
handle	Attribute handle.
data	Data to be written.
length	Data length.
sign	Whether to sign data
func	Transmission complete callback.
user_data	User data to be passed back to callback.

Return values

0	Successfully queued request.
-ENOMEM	ATT request queue is full and blocking would cause deadlock. Allow a pending request to resolve before retrying, or call this function outside the BT RX thread to get blocking behavior. Queue size is controlled by CONFIG_BT_ATT_TX_COUNT .