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
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 is 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¶
-
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 broadcast property.
Characteristic Properties Bit field values
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 Notification.
Client Characteristic Configuration Values
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 Broadcast.
Server Characteristic Configuration Values
If set, the characteristic value shall be broadcast in the advertising data when the server is advertising.
Enums
-
enum [anonymous]¶
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_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
-
struct
bt_gatt_attr
¶ - #include <gatt.h>
GATT Attribute structure.
Public Members
-
ssize_t (*
read
)(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.
- Parameters
conn – The connection that is requesting to read
attr – The attribute that’s being read
buf – Buffer to place the read result in
len – Length of data to read
offset – Offset to start reading from
- Returns
Number fo bytes read, or in case of an error BT_GATT_ERR() with a specific ATT error code.
-
ssize_t (*
write
)(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.
- Parameters
conn – The connection that is requesting to write
attr – The attribute that’s being written
buf – Buffer with the data to write
len – Number of bytes in the buffer
offset – Offset to start writing from
flags – Flags (BT_GATT_WRITE_*)
- Returns
Number of bytes written, or in case of an error BT_GATT_ERR() with a specific ATT error code.
-
void *
user_data
¶ Attribute user data
-
uint16_t
handle
¶ Attribute handle
-
uint8_t
perm
¶ Attribute permissions
-
ssize_t (*
-
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
-
const struct bt_gatt_attr *
-
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_attr *
-
struct
bt_gatt_service_val
¶ - #include <gatt.h>
Service Attribute Value.
-
struct
bt_gatt_include
¶ - #include <gatt.h>
Include Attribute Value.
-
struct
bt_gatt_chrc
¶ - #include <gatt.h>
Characteristic Attribute Value.
-
struct
bt_gatt_cep
¶ - #include <gatt.h>
Characteristic Extended Properties Attribute Value.
Public Members
-
uint16_t
properties
¶ Characteristic Extended properties
-
uint16_t
-
struct
bt_gatt_ccc
¶ - #include <gatt.h>
Client Characteristic Configuration Attribute Value
Public Members
-
uint16_t
flags
¶ Client Characteristic Configuration flags
-
uint16_t
-
struct
bt_gatt_scc
¶ - #include <gatt.h>
Server Characterestic Configuration Attribute Value
Public Members
-
uint16_t
flags
¶ Server Characteristic Configuration flags
-
uint16_t
-
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
-
uint8_t
-
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 serivce. 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.
- 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, _value)¶ 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.
_perm – Characteristic Attribute access permissions.
_read – Characteristic Attribute read callback.
_write – Characteristic Attribute write callback.
_value – Characteristic Attribute value.
-
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.
-
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.
-
BT_GATT_CEP
(_value)¶ Characteristic Extended Properties Declaration Macro.
Helper macro to declare a CEP attribute.
- Parameters
_value – Descriptor attribute value.
-
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.
-
BT_GATT_CPF
(_value)¶ Characteristic Presentation Format Descriptor Declaration Macro.
Helper macro to declare a CPF attribute.
- Parameters
_value – Descriptor attribute value.
-
BT_GATT_DESCRIPTOR
(_uuid, _perm, _read, _write, _value)¶ Descriptor Declaration Macro.
Helper macro to declare a descriptor attribute.
- Parameters
_uuid – Descriptor attribute uuid.
_perm – Descriptor attribute access permissions.
_read – Descriptor attribute read callback.
_write – Descriptor attribute write callback.
_value – Descriptor attribute value.
-
BT_GATT_ATTRIBUTE
(_uuid, _perm, _read, _write, _value)¶ Attribute Declaration Macro.
Helper macro to declare an attribute.
- Parameters
_uuid – Attribute uuid.
_perm – Attribute access permissions.
_read – Attribute read callback.
_write – Attribute write callback.
_value – Attribute value.
Typedefs
-
typedef uint8_t (*
bt_gatt_attr_func_t
)(const struct bt_gatt_attr *attr, uint16_t handle, void *user_data)¶ Attribute iterator callback.
- Parameters
attr – Attribute found.
handle – Attribute handle found.
user_data – Data given.
- Returns
BT_GATT_ITER_CONTINUE if should continue to the next attribute.
- Returns
BT_GATT_ITER_STOP to stop.
-
typedef void (*
bt_gatt_complete_func_t
)(struct bt_conn *conn, void *user_data)¶ Notification complete result callback.
- Parameters
conn – Connection object.
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.
- Parameters
conn – Connection object.
params – Indication params object.
err – ATT error code
-
typedef void (*
bt_gatt_indicate_params_destroy_t
)(struct bt_gatt_indicate_params *params)¶
Functions
-
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
andCONFIG_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.- Parameters
svc – Service containing the available attributes
- Returns
0 in case of success or negative value in case of error.
-
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.
-
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.
-
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 given 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)¶ Notify multiple attribute value change.
This function works in the same way as bt_gatt_notify_cb.
- Parameters
conn – Connection object.
num_params – Number of notification parameters.
params – Array of notification parameters.
- Returns
0 in case of success or negative value in case of error.
-
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 given 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_value)¶ 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_value – The subscription type, either notifications or indications.
- 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.
-
uint8_t
-
struct
bt_gatt_notify_params
¶ - #include <gatt.h>
Public Members
-
const struct bt_gatt_attr *
attr
¶ Notification Attribute object
-
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
-
const struct bt_gatt_attr *
-
struct
bt_gatt_indicate_params
¶ - #include <gatt.h>
GATT Indicate Value parameters.
Public Members
-
const struct bt_gatt_attr *
attr
¶ Indicate Attribute object
-
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
-
const struct bt_gatt_attr *
-
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. Will be NULL when discovering descriptors
To be able to read the value of the discovered attribute the user_data must be cast to an appropriate type.
bt_gatt_service_val when UUID is BT_UUID_GATT_PRIMARY or BT_UUID_GATT_SECONDARY.
bt_gatt_include when UUID is BT_UUID_GATT_INCLUDE.
bt_gatt_chrc when UUID is BT_UUID_GATT_CHRC.
- Parameters
conn – Connection object.
attr – Attribute found, or NULL if not found.
params – Discovery parameters given.
- Returns
BT_GATT_ITER_CONTINUE to continue discovery procedure.
- Returns
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.
- 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.
- Returns
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.
- Parameters
conn – Connection object.
err – ATT error code.
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 thelength
will be 0, which is due to the special case where adata
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.
Enums
-
enum [anonymous]¶
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 characterestic descriptor values and their properties. Supported descriptors: - Characteristic Extended Properties - Client Characteristic Configuration - Server Characteristic Configuration - Characteristic Presentation Format
-
enumerator
-
enum [anonymous]¶
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.
-
enumerator
BT_GATT_SUBSCRIBE_NUM_FLAGS
¶
-
enumerator
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.
Note
Shall only be used once per connection.
- Parameters
conn – Connection object.
params – Exchange MTU parameters.
- Returns
0 in case of success or negative value in case of error.
-
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 specific Primary Service based on 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.
Note
This procedure is asynchronous therefore the parameters need to remains valid while it is active.
- Parameters
conn – Connection object.
params – Discover parameters.
- Returns
0 in case of success or negative value in case of error.
-
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.
If an instance does contain a long value which cannot be read entirely the caller will need to read the remaining data separately using the handle and offset.
Note
This procedure is asynchronous therefore the parameters need to remains valid while it is active.
- Parameters
conn – Connection object.
params – Read parameters.
- Returns
0 in case of success or negative value in case of error.
-
int
bt_gatt_write
(struct bt_conn *conn, struct bt_gatt_write_params *params)¶ Write Attribute Value by handle.
This procedure write the attribute value and return the result in the callback.
Note
This procedure is asynchronous therefore the parameters need to remains valid while it is active.
- Parameters
conn – Connection object.
params – Write parameters.
- Returns
0 in case of success or negative value in case of error.
-
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.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.
- Returns
0 in case of success or negative value in case of error.
-
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
- Parameters
conn – Connection object.
handle – Attribute handle.
data – Data to be written.
length – Data length.
sign – Whether to sign data
- Returns
0 in case of success or negative value in case of error.
-
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.
Note
Notifications are asynchronous therefore the parameters need to remain valid while subscribed.
- Parameters
conn – Connection object.
params – Subscribe parameters.
- Returns
0 in case of success or negative value in case of error.
-
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.
- Parameters
conn – Connection object.
params – Subscribe parameters.
- Returns
0 in case of success or negative value in case of error.
-
void
bt_gatt_cancel
(struct bt_conn *conn, void *params)¶ Cancel GATT pending request.
- Parameters
conn – Connection object.
params – Requested params address.
-
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
-
void (*
-
struct
bt_gatt_discover_params
¶ - #include <gatt.h>
GATT Discover Attributes parameters.
Public Members
-
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
-
bt_gatt_discover_func_t
-
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 >1 Read Multiple Characteristic Values is performed and 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
¶ Handles to read in Read Multiple Characteristic Values.
-
uint16_t
start_handle
¶ First requested handle number.
-
uint16_t
end_handle
¶ Last requested handle number.
-
bt_gatt_read_func_t
-
struct
bt_gatt_write_params
¶ - #include <gatt.h>
GATT Write parameters.
-
struct
bt_gatt_subscribe_params
¶ - #include <gatt.h>
GATT Subscribe parameters.
Public Members
-
bt_gatt_notify_func_t
notify
¶ Notification value callback
-
bt_gatt_write_func_t
write
¶ Subscribe CCC write request response callback
-
uint16_t
value_handle
¶ Subscribe value handle
-
uint16_t
ccc_handle
¶ Subscribe CCC handle
-
uint16_t
value
¶ Subscribe value
-
atomic_t
flags
[ATOMIC_BITMAP_SIZE
(BT_GATT_SUBSCRIBE_NUM_FLAGS
)]¶ Subscription flags
-
bt_gatt_notify_func_t
-
typedef uint8_t (*