Generic Attribute Profile (GATT)

GATT layer manages the service database providing APIs for service registration and attribute declaration.

Services can be registered using bt_gatt_service_register() API which takes the bt_gatt_service struct that provides the list of attributes the service contains. The helper macro BT_GATT_SERVICE() can be used to declare a service.

Attributes can be declared using the bt_gatt_attr struct or using one of the helper macros:

BT_GATT_PRIMARY_SERVICE
Declares a Primary Service.

BT_GATT_SECONDARY_SERVICE
Declares a Secondary Service.

BT_GATT_INCLUDE_SERVICE
Declares a Include Service.

BT_GATT_CHARACTERISTIC
Declares a Characteristic.

BT_GATT_DESCRIPTOR
Declares a Descriptor.

BT_GATT_ATTRIBUTE
Declares an Attribute.

BT_GATT_CCC
Declares a Client Characteristic Configuration.

BT_GATT_CEP
Declares a Characteristic Extended Properties.

BT_GATT_CUD
Declares a Characteristic User Format.

Each attribute contain a uuid, which describes their type, a read callback, a write callback and a set of permission. Both read and write callbacks can be set to NULL if the attribute permission don’t allow their respective operations.

Note

32-bit UUIDs are not supported in GATT. All 32-bit UUIDs shall be converted to 128-bit UUIDs when the UUID is contained in an ATT PDU.

Note

Attribute read and write callbacks are called directly from RX Thread thus it is not recommended to block for long periods of time in them.

Attribute value changes can be notified using bt_gatt_notify() API, alternatively there is bt_gatt_notify_cb() where it is possible to 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 bt_gatt_indicate() API.

Client procedures can be enabled with the configuration option: CONFIG_BT_GATT_CLIENT

Discover procedures can be initiated with the use of bt_gatt_discover() API which takes the bt_gatt_discover_params struct which describes the type of discovery. The parameters also serves as a filter when setting the uuid field only attributes which matches will be discovered, in contrast setting it to NULL allows all attributes to be discovered.

Note

Caching discovered attributes is not supported.

Read procedures are supported by bt_gatt_read() API which takes the bt_gatt_read_params struct as parameters. In the parameters one or more attributes can be set, though setting multiple handles requires the option: CONFIG_BT_GATT_READ_MULTIPLE

Write procedures are supported by bt_gatt_write() API and takes bt_gatt_write_params struct as parameters. In case the write operation don’t require a response bt_gatt_write_without_response() or bt_gatt_write_without_response_cb() APIs can be used, with the later working similarly to bt_gatt_notify_cb().

Subscriptions to notification and indication can be initiated with use of bt_gatt_subscribe() API which takes bt_gatt_subscribe_params as parameters. Multiple subscriptions to the same attribute are supported so there could be multiple notify callback being triggered for the same attribute. Subscriptions can be removed with use of bt_gatt_unsubscribe() API.

Note

When subscriptions are removed notify callback is called with the data set to NULL.

API Reference

Related code samples

BLE logging backend: Send log messages over BLE using the BLE logging backend.

group bt_gatt

Generic Attribute Profile (GATT)

Defines

BT_GATT_ERR(_att_err)

Construct error return value for attribute read and write callbacks.

Parameters:

_att_err – ATT error code

Returns:

Appropriate error code for the attribute callbacks.

BT_GATT_CHRC_BROADCAST

Characteristic Properties Bit field values.

Characteristic broadcast property.

If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor.

BT_GATT_CHRC_READ

Characteristic read property.

If set, permits reads of the Characteristic Value.

BT_GATT_CHRC_WRITE_WITHOUT_RESP

Characteristic write without response property.

If set, permits write of the Characteristic Value without response.

BT_GATT_CHRC_WRITE

Characteristic write with response property.

If set, permits write of the Characteristic Value with response.

BT_GATT_CHRC_NOTIFY

Characteristic notify property.

If set, permits notifications of a Characteristic Value without acknowledgment.

BT_GATT_CHRC_INDICATE

Characteristic indicate property.

If set, permits indications of a Characteristic Value with acknowledgment.

BT_GATT_CHRC_AUTH

Characteristic Authenticated Signed Writes property.

If set, permits signed writes to the Characteristic Value.

BT_GATT_CHRC_EXT_PROP

Characteristic Extended Properties property.

If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.

BT_GATT_CEP_RELIABLE_WRITE: Characteristic Extended Properties Bit field values.

BT_GATT_CEP_WRITABLE_AUX

BT_GATT_CCC_NOTIFY

Client Characteristic Configuration Values.

Client Characteristic Configuration Notification.

If set, changes to Characteristic Value shall be notified.

BT_GATT_CCC_INDICATE

Client Characteristic Configuration Indication.

If set, changes to Characteristic Value shall be indicated.

BT_GATT_SCC_BROADCAST

Server Characteristic Configuration Values.

Server Characteristic Configuration Broadcast

If set, the characteristic value shall be broadcast in the advertising data when the server is advertising.

Typedefs

typedef ssize_t (*bt_gatt_attr_read_func_t)(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Attribute read callback.

The callback can also be used locally to read the contents of the attribute in which case no connection will be set.

Param conn:: The connection that is requesting to read
Param attr:: The attribute that’s being read
Param buf:: Buffer to place the read result in
Param len:: Length of data to read
Param offset:: Offset to start reading from
Return:: Number of bytes read, or in case of an error BT_GATT_ERR() with a specific BT_ATT_ERR_* error code.

typedef ssize_t (*bt_gatt_attr_write_func_t)(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *buf, uint16_t len, uint16_t offset, uint8_t flags)

Attribute write callback.

Param conn:: The connection that is requesting to write
Param attr:: The attribute that’s being written
Param buf:: Buffer with the data to write
Param len:: Number of bytes in the buffer
Param offset:: Offset to start writing from
Param flags:: Flags (BT_GATT_WRITE_FLAG_*)
Return:: Number of bytes written, or in case of an error BT_GATT_ERR() with a specific BT_ATT_ERR_* error code.

Enums

enum bt_gatt_perm

GATT attribute permission bit field values.

Values:

enumerator BT_GATT_PERM_NONE = 0

No operations supported, e.g.

for notify-only

enumerator BT_GATT_PERM_READ = BIT(0): Attribute read permission.

enumerator BT_GATT_PERM_WRITE = BIT(1): Attribute write permission.

enumerator BT_GATT_PERM_READ_ENCRYPT = BIT(2)

Attribute read permission with encryption.

    If set, requires encryption for read access.

enumerator BT_GATT_PERM_WRITE_ENCRYPT = BIT(3)

Attribute write permission with encryption.

    If set, requires encryption for write access.

enumerator BT_GATT_PERM_READ_AUTHEN = BIT(4)

Attribute read permission with authentication.

    If set, requires encryption using authenticated link-key for read
    access.

enumerator BT_GATT_PERM_WRITE_AUTHEN = BIT(5)

Attribute write permission with authentication.

    If set, requires encryption using authenticated link-key for write
    access.

enumerator BT_GATT_PERM_PREPARE_WRITE = BIT(6)

Attribute prepare write permission.

    If set, allows prepare writes with use of ``BT_GATT_WRITE_FLAG_PREPARE``
    passed to write callback.

enumerator BT_GATT_PERM_READ_LESC = BIT(7)

Attribute read permission with LE Secure Connection encryption.

    If set, requires that LE Secure Connections is used for read access.

enumerator BT_GATT_PERM_WRITE_LESC = BIT(8)

Attribute write permission with LE Secure Connection encryption.

    If set, requires that LE Secure Connections is used for write access.

GATT attribute write flags.

Values:

enumerator BT_GATT_WRITE_FLAG_PREPARE = BIT(0)

Attribute prepare write flag.

   If set, write callback should only check if the device is
   authorized but no data shall be written.

enumerator BT_GATT_WRITE_FLAG_CMD = BIT(1)

Attribute write command flag.

   If set, indicates that write operation is a command (Write without
   response) which doesn't generate any response.

enumerator BT_GATT_WRITE_FLAG_EXECUTE = BIT(2)

Attribute write execute flag.

   If set, indicates that write operation is a execute, which indicates
   the end of a long write, and will come after 1 or more
   @ref BT_GATT_WRITE_FLAG_PREPARE.

struct bt_gatt_attr

#include <gatt.h>

GATT Attribute structure.

Public Members

const struct bt_uuid *uuid: Attribute UUID.

bt_gatt_attr_read_func_t read: Attribute read callback.

bt_gatt_attr_write_func_t write: Attribute write callback.

void *user_data: Attribute user data.

uint16_t handle: Attribute handle.

uint16_t perm

Attribute permissions.

Will be 0 if returned from bt_gatt_discover().

struct bt_gatt_service_static

#include <gatt.h>

GATT Service structure.

Public Members

const struct bt_gatt_attr *attrs: Service Attributes.

size_t attr_count: Service Attribute count.

struct bt_gatt_service

#include <gatt.h>

GATT Service structure.

Public Members

struct bt_gatt_attr *attrs: Service Attributes.

size_t attr_count: Service Attribute count.

struct bt_gatt_service_val

#include <gatt.h>

Service Attribute Value.

Public Members

const struct bt_uuid *uuid: Service UUID.

uint16_t end_handle: Service end handle.

struct bt_gatt_include

#include <gatt.h>

Include Attribute Value.

Public Members

const struct bt_uuid *uuid: Service UUID.

uint16_t start_handle: Service start handle.

uint16_t end_handle: Service end handle.

struct bt_gatt_cb

#include <gatt.h>

GATT callback structure.

Public Members

void (*att_mtu_updated)(struct bt_conn *conn, uint16_t tx, uint16_t rx)

The maximum ATT MTU on a connection has changed.

This callback notifies the application that the maximum TX or RX ATT MTU has increased.

Param conn:: Connection object.
Param tx:: Updated TX ATT MTU.
Param rx:: Updated RX ATT MTU.

struct bt_gatt_authorization_cb

#include <gatt.h>

GATT authorization callback structure.

Public Members

bool (*read_authorize)(struct bt_conn *conn, const struct bt_gatt_attr *attr)

Authorize the GATT read operation.

This callback allows the application to authorize the GATT read operation for the attribute that is being read.

Param conn:: Connection object.
Param attr:: The attribute that is being read.
Retval true:: Authorize the operation and allow it to execute.
Retval false:: Reject the operation and prevent it from executing.

bool (*write_authorize)(struct bt_conn *conn, const struct bt_gatt_attr *attr)

Authorize the GATT write operation.

This callback allows the application to authorize the GATT write operation for the attribute that is being written.

Param conn:: Connection object.
Param attr:: The attribute that is being written.
Retval true:: Authorize the operation and allow it to execute.
Retval false:: Reject the operation and prevent it from executing.

struct bt_gatt_chrc

#include <gatt.h>

Characteristic Attribute Value.

Public Members

const struct bt_uuid *uuid: Characteristic UUID.

uint16_t value_handle: Characteristic Value handle.

uint8_t properties: Characteristic properties.

struct bt_gatt_cep

#include <gatt.h>

Characteristic Extended Properties Attribute Value.

Public Members

uint16_t properties: Characteristic Extended properties.

struct bt_gatt_ccc

#include <gatt.h>

Client Characteristic Configuration Attribute Value.

Public Members

uint16_t flags: Client Characteristic Configuration flags.

struct bt_gatt_scc

#include <gatt.h>

Server Characteristic Configuration Attribute Value.

Public Members

uint16_t flags: Server Characteristic Configuration flags.

struct bt_gatt_cpf

#include <gatt.h>

GATT Characteristic Presentation Format Attribute Value.

Public Members

uint8_t format: Format of the value of the characteristic.

int8_t exponent: Exponent field to determine how the value of this characteristic is further formatted.

uint16_t unit: Unit of the characteristic.

uint8_t name_space: Name space of the description.

uint16_t description: Description of the characteristic as defined in a higher layer profile.

GATT Server

group bt_gatt_server

Defines

BT_GATT_SERVICE_DEFINE(_name, ...)

Statically define and register a service.

Helper macro to statically define and register a service.

Parameters:

_name – Service name.

BT_GATT_SERVICE_INSTANCE_DEFINE(_name, _instances, _instance_num, _attrs_def)

Statically define service structure array.

Helper macro to statically define service structure array. Each element of the array is linked to the service attribute array which is also defined in this scope using _attrs_def macro.

Parameters:

_name – Name of service structure array.
_instances – Array of instances to pass as user context to the attribute callbacks.
_instance_num – Number of elements in instance array.
_attrs_def – Macro provided by the user that defines attribute array for the service. This macro should accept single parameter which is the instance context.

BT_GATT_SERVICE(_attrs)

Service Structure Declaration Macro.

Helper macro to declare a service structure.

Parameters:

_attrs – Service attributes.

BT_GATT_PRIMARY_SERVICE(_service)

Primary Service Declaration Macro.

Helper macro to declare a primary service attribute.

Parameters:

_service – Service attribute value.

BT_GATT_SECONDARY_SERVICE(_service)

Secondary Service Declaration Macro.

Helper macro to declare a secondary service attribute.

Note

A secondary service is only intended to be included from a primary service or another secondary service or other higher layer specification.

Parameters:

_service – Service attribute value.

BT_GATT_INCLUDE_SERVICE(_service_incl)

Include Service Declaration Macro.

Helper macro to declare database internal include service attribute.

Parameters:

_service_incl – the first service attribute of service to include

BT_GATT_CHRC_INIT(_uuid, _handle, _props)

BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _user_data)

Characteristic and Value Declaration Macro.

Helper macro to declare a characteristic attribute along with its attribute value.

Parameters:

_uuid – Characteristic attribute uuid.
_props – Characteristic attribute properties, a bitmap of BT_GATT_CHRC_* macros.
_perm – Characteristic Attribute access permissions, a bitmap of bt_gatt_perm values.
_read – Characteristic Attribute read callback (bt_gatt_attr_read_func_t).
_write – Characteristic Attribute write callback (bt_gatt_attr_write_func_t).
_user_data – Characteristic Attribute user data.

BT_GATT_CCC_MAX

BT_GATT_CCC_INITIALIZER(_changed, _write, _match)

Initialize Client Characteristic Configuration Declaration Macro.

Helper macro to initialize a Managed CCC attribute value.

Parameters:

_changed – Configuration changed callback.
_write – Configuration write callback.
_match – Configuration match callback.

BT_GATT_CCC_MANAGED(_ccc, _perm)

Managed Client Characteristic Configuration Declaration Macro.

Helper macro to declare a Managed CCC attribute.

Parameters:

_ccc – CCC attribute user data, shall point to a _bt_gatt_ccc.
_perm – CCC access permissions, a bitmap of bt_gatt_perm values.

BT_GATT_CCC(_changed, _perm)

Client Characteristic Configuration Declaration Macro.

Helper macro to declare a CCC attribute.

Parameters:

_changed – Configuration changed callback.
_perm – CCC access permissions, a bitmap of bt_gatt_perm values.

BT_GATT_CEP(_value)

Characteristic Extended Properties Declaration Macro.

Helper macro to declare a CEP attribute.

Parameters:

_value – Pointer to a struct bt_gatt_cep.

BT_GATT_CUD(_value, _perm)

Characteristic User Format Descriptor Declaration Macro.

Helper macro to declare a CUD attribute.

Parameters:

_value – User description NULL-terminated C string.
_perm – Descriptor attribute access permissions, a bitmap of bt_gatt_perm values.

BT_GATT_CPF(_value)

Characteristic Presentation Format Descriptor Declaration Macro.

Helper macro to declare a CPF attribute.

Parameters:

_value – Pointer to a struct bt_gatt_cpf.

BT_GATT_DESCRIPTOR(_uuid, _perm, _read, _write, _user_data)

Descriptor Declaration Macro.

Helper macro to declare a descriptor attribute.

Parameters:

_uuid – Descriptor attribute uuid.
_perm – Descriptor attribute access permissions, a bitmap of bt_gatt_perm values.
_read – Descriptor attribute read callback (bt_gatt_attr_read_func_t).
_write – Descriptor attribute write callback (bt_gatt_attr_write_func_t).
_user_data – Descriptor attribute user data.

BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)

Attribute Declaration Macro.

Helper macro to declare an attribute.

Parameters:

_uuid – Attribute uuid.
_perm – Attribute access permissions, a bitmap of bt_gatt_perm values.
_read – Attribute read callback (bt_gatt_attr_read_func_t).
_write – Attribute write callback (bt_gatt_attr_write_func_t).
_user_data – Attribute user data.

Typedefs

typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr, uint16_t handle, void *user_data)

Attribute iterator callback.

Param attr:: Attribute found.
Param handle:: Attribute handle found.
Param user_data:: Data given.
Return:: BT_GATT_ITER_CONTINUE if should continue to the next attribute.
Return:: BT_GATT_ITER_STOP to stop.

typedef void (*bt_gatt_complete_func_t)(struct bt_conn *conn, void *user_data)

Notification complete result callback.

Param conn:: Connection object.
Param user_data:: Data passed in by the user.

typedef void (*bt_gatt_indicate_func_t)(struct bt_conn *conn, struct bt_gatt_indicate_params *params, uint8_t err)

Indication complete result callback.

Param conn:: Connection object.
Param params:: Indication params object.
Param err:: ATT error code

typedef void (*bt_gatt_indicate_params_destroy_t)(struct bt_gatt_indicate_params *params)

Enums

Values:

enumerator BT_GATT_ITER_STOP = 0

enumerator BT_GATT_ITER_CONTINUE

Functions

static inline const char *bt_gatt_err_to_str(int gatt_err)

Converts a GATT error to string.

The GATT errors are created with BT_GATT_ERR.

The error codes are described in the Bluetooth Core specification, Vol 3, Part F, Section 3.4.1.1.

The ATT and GATT documentation found in Vol 4, Part F and Part G describe when the different error codes are used.

See also the defined BT_ATT_ERR_* macros.

Returns:: The string representation of the GATT error code. If CONFIG_BT_ATT_ERR_TO_STR is not enabled, this just returns the empty string.

void bt_gatt_cb_register(struct bt_gatt_cb *cb)

Register GATT callbacks.

Register callbacks to monitor the state of GATT. The callback struct must remain valid for the remainder of the program.

Parameters:

cb – Callback struct.

int bt_gatt_authorization_cb_register(const struct bt_gatt_authorization_cb *cb)

Register GATT authorization callbacks.

Register callbacks to perform application-specific authorization of GATT operations on all registered GATT attributes. The callback structure must remain valid throughout the entire duration of the Bluetooth subsys activity.

The CONFIG_BT_GATT_AUTHORIZATION_CUSTOM Kconfig must be enabled to make this API functional.

This API allows the user to register only one callback structure concurrently. Passing NULL unregisters the previous set of callbacks and makes it possible to register a new one.

Parameters:

cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

int bt_gatt_service_register(struct bt_gatt_service *svc)

Register GATT service.

Register GATT service. Applications can make use of macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC, BT_GATT_DESCRIPTOR, etc.

When using CONFIG_BT_SETTINGS then all services that should have bond configuration loaded, i.e. CCC values, must be registered before calling settings_load.

When using CONFIG_BT_GATT_CACHING and CONFIG_BT_SETTINGS then all services that should be included in the GATT Database Hash calculation should be added before calling settings_load. All services registered after settings_load will trigger a new database hash calculation and a new hash stored.

There are two situations where this function can be called: either before bt_init() has been called, or after settings_load() has been called. Registering a service in the middle is not supported and will return an error.

Parameters:

svc – Service containing the available attributes

Returns:

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

Returns:

-EAGAIN if bt_init() has been called but settings_load() hasn’t yet.

int bt_gatt_service_unregister(struct bt_gatt_service *svc)

Unregister GATT service.

Parameters:

svc – Service to be unregistered.

Returns:

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

bool bt_gatt_service_is_registered(const struct bt_gatt_service *svc)

Check if GATT service is registered.

Parameters:

svc – Service to be checked.

Returns:

true if registered or false if not register.

void bt_gatt_foreach_attr_type(uint16_t start_handle, uint16_t end_handle, const struct bt_uuid *uuid, const void *attr_data, uint16_t num_matches, bt_gatt_attr_func_t func, void *user_data)

Attribute iterator by type.

Iterate attributes in the given range matching given UUID and/or data.

Parameters:

start_handle – Start handle.
end_handle – End handle.
uuid – UUID to match, passing NULL skips UUID matching.
attr_data – Attribute data to match, passing NULL skips data matching.
num_matches – Number matches, passing 0 makes it unlimited.
func – Callback function.
user_data – Data to pass to the callback.

static inline void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle, bt_gatt_attr_func_t func, void *user_data)

Attribute iterator.

Iterate attributes in the given range.

Parameters:

start_handle – Start handle.
end_handle – End handle.
func – Callback function.
user_data – Data to pass to the callback.

struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr)

Iterate to the next attribute.

Iterate to the next attribute following a given attribute.

Parameters:

attr – Current Attribute.

Returns:

The next attribute or NULL if it cannot be found.

struct bt_gatt_attr *bt_gatt_find_by_uuid(const struct bt_gatt_attr *attr, uint16_t attr_count, const struct bt_uuid *uuid)

Find Attribute by UUID.

Find the attribute with the matching UUID. To limit the search to a service set the attr to the service attributes and the attr_count to the service attribute count .

Parameters:

attr – Pointer to an attribute that serves as the starting point for the search of a match for the UUID. Passing NULL will search the entire range.
attr_count – The number of attributes from the starting point to search for a match for the UUID. Set to 0 to search until the end.
uuid – UUID to match.

uint16_t bt_gatt_attr_get_handle(const struct bt_gatt_attr *attr)

Get Attribute handle.

Parameters:

attr – Attribute object.

Returns:

Handle of the corresponding attribute or zero if the attribute could not be found.

uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr)

Get the handle of the characteristic value descriptor.

Note

The user_data of the attribute must of type bt_gatt_chrc.

Parameters:

attr – A Characteristic Attribute.

Returns:

the handle of the corresponding Characteristic Value. The value will be zero (the invalid handle) if attr was not a characteristic attribute.

ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t buf_len, uint16_t offset, const void *value, uint16_t value_len)

Generic Read Attribute value helper.

Read attribute value from local database storing the result into buffer.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value.
buf_len – Buffer length.
offset – Start offset.
value – Attribute value.
value_len – Length of the attribute value.

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_service(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Service Attribute helper.

Read service attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a bt_uuid.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value read.
len – Buffer length.
offset – Start offset.

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_included(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Include Attribute helper.

Read include service attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a bt_gatt_include.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value read.
len – Buffer length.
offset – Start offset.

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Attribute helper.

Read characteristic attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a bt_gatt_chrc.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value read.
len – Buffer length.
offset – Start offset.

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Client Characteristic Configuration Attribute helper.

Read CCC attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a _bt_gatt_ccc.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value read.
len – Buffer length.
offset – Start offset.

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *buf, uint16_t len, uint16_t offset, uint8_t flags)

Write Client Characteristic Configuration Attribute helper.

Write value in the buffer into CCC attribute.

Note

Only use this with attributes which user_data is a _bt_gatt_ccc.

Parameters:

conn – Connection object.
attr – Attribute to read.
buf – Buffer to store the value read.
len – Buffer length.
offset – Start offset.
flags – Write flags.

Returns:

number of bytes written in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Extended Properties Attribute helper.

Read CEP attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a bt_gatt_cep.

Parameters:

conn – Connection object
attr – Attribute to read
buf – Buffer to store the value read
len – Buffer length
offset – Start offset

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic User Description Descriptor Attribute helper.

Read CUD attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a NULL-terminated C string.

Parameters:

conn – Connection object
attr – Attribute to read
buf – Buffer to store the value read
len – Buffer length
offset – Start offset

Returns:

number of bytes read in case of success or negative values in case of error.

ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Presentation format Descriptor Attribute helper.

Read CPF attribute value from local database storing the result into buffer after encoding it.

Note

Only use this with attributes which user_data is a bt_gatt_pf.

Parameters:

conn – Connection object
attr – Attribute to read
buf – Buffer to store the value read
len – Buffer length
offset – Start offset

Returns:

number of bytes read in case of success or negative values in case of error.

int bt_gatt_notify_cb(struct bt_conn *conn, struct bt_gatt_notify_params *params)

Notify attribute value change.

This function works in the same way as bt_gatt_notify. With the addition that after sending the notification 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.

Alternatively it is possible to notify by UUID by setting it on the parameters, when using this method the attribute if provided is used as the start range when looking up for possible matches.

Parameters:

conn – Connection object.
params – Notification parameters.

Returns:

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

int bt_gatt_notify_multiple(struct bt_conn *conn, uint16_t num_params, struct bt_gatt_notify_params params[])

Send multiple notifications in a single PDU.

The GATT Server will send a single ATT_MULTIPLE_HANDLE_VALUE_NTF PDU containing all the notifications passed to this API.

All params must have the same func and user_data (due to implementation limitation). But func(user_data) will be invoked for each parameter.

As this API may block to wait for Bluetooth Host resources, it is not recommended to call it from a cooperative thread or a Bluetooth callback.

The peer’s GATT Client must write to this device’s Client Supported Features attribute and set the bit for Multiple Handle Value Notifications before this API can be used.

Only use this API to force the use of the ATT_MULTIPLE_HANDLE_VALUE_NTF PDU. For standard applications, bt_gatt_notify_cb is preferred, as it will use this PDU if supported and automatically fallback to ATT_HANDLE_VALUE_NTF when not supported by the peer.

This API has an additional limitation: it only accepts valid attribute references and not UUIDs like bt_gatt_notify and bt_gatt_notify_cb.

Parameters:

conn – Target client. Notifying all connected clients by passing NULL is not yet supported, please use bt_gatt_notify instead.
num_params – Element count of params array. Has to be greater than 1.
params – Array of notification parameters. It is okay to free this after calling this function.

Return values:

0 – Success. The PDU is queued for sending.
-EINVAL –
- One of the attribute handles is invalid.
- Only one parameter was passed. This API expects 2 or more.
- Not all func were equal or not all user_data were equal.
- One of the characteristics is not notifiable.
- An UUID was passed in one of the parameters.
-ERANGE –
- The notifications cannot all fit in a single ATT_MULTIPLE_HANDLE_VALUE_NTF.
- They exceed the MTU of all open ATT bearers.
-EPERM – The connection has a lower security level than required by one of the attributes.
-EOPNOTSUPP – The peer hasn’t yet communicated that it supports this PDU type.

static inline int bt_gatt_notify(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *data, uint16_t len)

Notify attribute value change.

Send notification of attribute value change, if connection is NULL notify all peer that have notification enabled via CCC otherwise do a direct notification only the given connection.

The attribute object on the parameters can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC.

Parameters:

conn – Connection object.
attr – Characteristic or Characteristic Value attribute.
data – Pointer to Attribute data.
len – Attribute value length.

Returns:

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

static inline int bt_gatt_notify_uuid(struct bt_conn *conn, const struct bt_uuid *uuid, const struct bt_gatt_attr *attr, const void *data, uint16_t len)

Notify attribute value change by UUID.

Send notification of attribute value change, if connection is NULL notify all peer that have notification enabled via CCC otherwise do a direct notification only on the given connection.

The attribute object is the starting point for the search of the UUID.

Parameters:

conn – Connection object.
uuid – The UUID. If the server contains multiple services with the same UUID, then the first occurrence, starting from the attr given, is used.
attr – Pointer to an attribute that serves as the starting point for the search of a match for the UUID.
data – Pointer to Attribute data.
len – Attribute value length.

Returns:

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

int bt_gatt_indicate(struct bt_conn *conn, struct bt_gatt_indicate_params *params)

Indicate attribute value change.

Send an indication of attribute value change. if connection is NULL indicate all peer that have notification enabled via CCC otherwise do a direct indication only the given connection.

The attribute object on the parameters can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC.

Alternatively it is possible to indicate by UUID by setting it on the parameters, when using this method the attribute if provided is used as the start range when looking up for possible matches.

Note

This procedure is asynchronous therefore the parameters need to remains valid while it is active. The procedure is active until the destroy callback is run.

Parameters:

conn – Connection object.
params – Indicate parameters.

Returns:

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

bool bt_gatt_is_subscribed(struct bt_conn *conn, const struct bt_gatt_attr *attr, uint16_t ccc_type)

Check if connection have subscribed to attribute.

Check if connection has subscribed to attribute value change.

The attribute object can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC, or the Client Characteristic Configuration Descriptor (CCCD) which is created by BT_GATT_CCC.

Parameters:

conn – Connection object.
attr – Attribute object.
ccc_type – The subscription type, BT_GATT_CCC_NOTIFY and/or BT_GATT_CCC_INDICATE.

Returns:

true if the attribute object has been subscribed.

uint16_t bt_gatt_get_mtu(struct bt_conn *conn)

Get ATT MTU for a connection.

Get negotiated ATT connection MTU, note that this does not equal the largest amount of attribute data that can be transferred within a single packet.

Parameters:

conn – Connection object.

Returns:

MTU in bytes

struct bt_gatt_ccc_cfg

#include <gatt.h>

GATT CCC configuration entry.

Public Members

uint8_t id: Local identity, BT_ID_DEFAULT in most cases.

bt_addr_le_t peer: Remote peer address.

uint16_t value: Configuration value.

struct bt_gatt_notify_params

#include <gatt.h>

Public Members

const struct bt_uuid *uuid

Notification Attribute UUID type.

Optional, use to search for an attribute with matching UUID when the attribute object pointer is not known.

const struct bt_gatt_attr *attr

Notification Attribute object.

Optional if uuid is provided, in this case it will be used as start range to search for the attribute with the given UUID.

const void *data: Notification Value data.

uint16_t len: Notification Value length.

bt_gatt_complete_func_t func: Notification Value callback.

void *user_data: Notification Value callback user data.

struct bt_gatt_indicate_params

#include <gatt.h>

GATT Indicate Value parameters.

Public Members

const struct bt_uuid *uuid

Indicate Attribute UUID type.

Optional, use to search for an attribute with matching UUID when the attribute object pointer is not known.

const struct bt_gatt_attr *attr

Indicate Attribute object.

Optional if uuid is provided, in this case it will be used as start range to search for the attribute with the given UUID.

bt_gatt_indicate_func_t func: Indicate Value callback.

bt_gatt_indicate_params_destroy_t destroy: Indicate operation complete callback.

const void *data: Indicate Value data.

uint16_t len: Indicate Value length.

GATT Client

group bt_gatt_client

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.

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.

Param conn:: Connection object.
Param attr:: Attribute found, or NULL if not found.
Param params:: Discovery parameters given.
Return:: BT_GATT_ITER_CONTINUE to continue discovery procedure.
Return:: BT_GATT_ITER_STOP to stop discovery procedure.

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.

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

Param conn:: Connection object.
Param err:: ATT error code.
Param params:: Read parameters used.
Param data:: Attribute value data. NULL means read has completed.
Param length:: Attribute value length.
Return:: BT_GATT_ITER_CONTINUE if should continue to the next attribute.
Return:: BT_GATT_ITER_STOP to stop.

typedef void (*bt_gatt_write_func_t)(struct bt_conn *conn, uint8_t err, struct bt_gatt_write_params *params)

Write callback function.

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

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.

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.

Param conn:: Connection object. May be NULL, indicating that the peer is being unpaired
Param params:: Subscription parameters.
Param data:: Attribute value data. If NULL then subscription was removed.
Param length:: Attribute value length.
Return:: BT_GATT_ITER_CONTINUE to continue receiving value notifications. BT_GATT_ITER_STOP to unsubscribe from value notifications.

typedef void (*bt_gatt_subscribe_func_t)(struct bt_conn *conn, uint8_t err, struct bt_gatt_subscribe_params *params)

Subscription callback function.

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

Enums

GATT Discover types.

Values:

enumerator BT_GATT_DISCOVER_PRIMARY: Discover Primary Services.

enumerator BT_GATT_DISCOVER_SECONDARY: Discover Secondary Services.

enumerator BT_GATT_DISCOVER_INCLUDE: Discover Included Services.

enumerator BT_GATT_DISCOVER_CHARACTERISTIC

Discover Characteristic Values.

    Discover Characteristic Value and its properties.

enumerator 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.

enumerator 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.

enumerator 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

Subscription flags.

Values:

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.

enumerator 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.

enumerator 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.

enumerator 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.

enumerator BT_GATT_SUBSCRIBE_NUM_FLAGS

Functions

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

Exchange MTU.

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

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.

Note

Shall only be used once per connection.

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.

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

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 .

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

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 .

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

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 .

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.

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.

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.

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.

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 .

static inline 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.

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 .

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

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.

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.

Note

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

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.

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

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.

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

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 .

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

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.

struct bt_gatt_exchange_params

#include <gatt.h>

GATT Exchange MTU parameters.

Public Members

void (*func)(struct bt_conn *conn, uint8_t err, struct bt_gatt_exchange_params *params): Response callback.

struct bt_gatt_discover_params

#include <gatt.h>

GATT Discover Attributes parameters.

Public Members

const struct bt_uuid *uuid: Discover UUID type.

bt_gatt_discover_func_t func: Discover attribute callback.

uint16_t attr_handle: Include service attribute declaration handle.

uint16_t start_handle

Included service start handle.

Discover start handle.

uint16_t end_handle

Included service end handle.

Discover end handle.

uint8_t type: Discover type.

struct bt_gatt_subscribe_params *sub_params: Only for stack-internal use, used for automatic discovery.

struct bt_gatt_read_params

#include <gatt.h>

GATT Read parameters.

Public Members

bt_gatt_read_func_t func: Read attribute callback.

size_t handle_count

If equals to 1 single.handle and single.offset are used.

If greater than 1 multiple.handles are used. If equals to 0 by_uuid is used for Read Using Characteristic UUID.

uint16_t handle: Attribute handle.

uint16_t offset: Attribute data offset.

uint16_t *handles: Attribute handles to read with Read Multiple Characteristic Values.

bool variable

If true use Read Multiple Variable Length Characteristic Values procedure.

The values of the set of attributes may be of variable or unknown length. If false use Read Multiple Characteristic Values procedure. The values of the set of attributes must be of a known fixed length, with the exception of the last value that can have a variable length.

uint16_t start_handle: First requested handle number.

uint16_t end_handle: Last requested handle number.

const struct bt_uuid *uuid: 2 or 16 octet UUID.

struct bt_gatt_write_params

#include <gatt.h>

GATT Write parameters.

Public Members

bt_gatt_write_func_t func: Response callback.

uint16_t handle: Attribute handle.

uint16_t offset: Attribute data offset.

const void *data: Data to be written.

uint16_t length: Length of the data.

struct bt_gatt_subscribe_params

#include <gatt.h>

GATT Subscribe parameters.

Public Members

bt_gatt_notify_func_t notify: Notification value callback.

bt_gatt_subscribe_func_t subscribe: Subscribe CCC write request response callback If given, called with the subscription parameters given when subscribing.

uint16_t value_handle: Subscribe value handle.

uint16_t ccc_handle: Subscribe CCC handle.

uint16_t end_handle: Subscribe End handle (for automatic discovery)

struct bt_gatt_discover_params *disc_params: Discover parameters used when ccc_handle = 0.

uint16_t value: Subscribe value.

bt_security_t min_security

Minimum required security for received notification.

Notifications and indications received over a connection with a lower security level are silently discarded.

atomic_t flags[ATOMIC_BITMAP_SIZE(BT_GATT_SUBSCRIBE_NUM_FLAGS)]: Subscription flags.