NimBLE Host GATT Client Reference¶

Introduction¶

The Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The client half of the GATT API initiates GATT procedures.

API¶

typedef int ble_gatt_mtu_fn(uint16_t conn_handle, const struct ble_gatt_error *error, uint16_t mtu, void *arg)¶: Function prototype for the GATT MTU exchange callback.

typedef int ble_gatt_disc_svc_fn(uint16_t conn_handle, const struct ble_gatt_error *error, const struct ble_gatt_svc *service, void *arg)¶: Function prototype for the GATT service discovery callback.

typedef int ble_gatt_attr_fn(uint16_t conn_handle, const struct ble_gatt_error *error, struct ble_gatt_attr *attr, void *arg)¶

The host will free the attribute mbuf automatically after the callback is executed.

The application can take ownership of the mbuf and prevent it from being freed by assigning NULL to attr->om.

typedef int ble_gatt_reliable_attr_fn(uint16_t conn_handle, const struct ble_gatt_error *error, struct ble_gatt_attr *attrs, uint8_t num_attrs, void *arg)¶

The host will free the attribute mbufs automatically after the callback is executed.

The application can take ownership of the mbufs and prevent them from being freed by assigning NULL to each attribute’s om field.

typedef int ble_gatt_chr_fn(uint16_t conn_handle, const struct ble_gatt_error *error, const struct ble_gatt_chr *chr, void *arg)¶: Function prototype for the GATT characteristic callback.

typedef int ble_gatt_dsc_fn(uint16_t conn_handle, const struct ble_gatt_error *error, uint16_t chr_val_handle, const struct ble_gatt_dsc *dsc, void *arg)¶: Function prototype for the GATT descriptor callback.

typedef int ble_gatt_access_fn(uint16_t conn_handle, uint16_t attr_handle, struct ble_gatt_access_ctxt *ctxt, void *arg)¶: Type definition for GATT access callback function.

typedef uint16_t ble_gatt_chr_flags¶: Type definition for GATT characteristic flags.

typedef void ble_gatt_register_fn(struct ble_gatt_register_ctxt *ctxt, void *arg)¶: Type definition for GATT registration callback function.

typedef void (*ble_gatt_svc_foreach_fn)(const struct ble_gatt_svc_def *svc, uint16_t handle, uint16_t end_group_handle, void *arg)¶: Type definition for GATT service iteration callback function.

int ble_gattc_exchange_mtu(uint16_t conn_handle, ble_gatt_mtu_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Exchange MTU.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_disc_all_svcs(uint16_t conn_handle, ble_gatt_disc_svc_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Discover All Primary Services.

Parameters

conn_handle: The connection over which to execute the procedure.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_disc_svc_by_uuid(uint16_t conn_handle, const ble_uuid_t *uuid, ble_gatt_disc_svc_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Discover Primary Service by Service UUID.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
uuid: The 128-bit UUID of the service to discover.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_find_inc_svcs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_disc_svc_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Find Included Services.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
start_handle: The handle to begin the search at (generally the service definition handle).
end_handle: The handle to end the search at (generally the last handle in the service).
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_chr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Discover All Characteristics of a Service.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
start_handle: The handle to begin the search at (generally the service definition handle).
end_handle: The handle to end the search at (generally the last handle in the service).
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, ble_gatt_chr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Discover Characteristics by UUID.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
start_handle: The handle to begin the search at (generally the service definition handle).
end_handle: The handle to end the search at (generally the last handle in the service).
uuid: The 128-bit UUID of the characteristic to discover.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_disc_all_dscs(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, ble_gatt_dsc_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Discover All Characteristic Descriptors.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
start_handle: The handle of the characteristic value attribute.
end_handle: The last handle in the characteristic definition.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_read(uint16_t conn_handle, uint16_t attr_handle, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Read Characteristic Value.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to read.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle, const ble_uuid_t *uuid, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Read Using Characteristic UUID.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
start_handle: The first handle to search (generally the handle of the service definition).
end_handle: The last handle to search (generally the last handle in the service definition).
uuid: The 128-bit UUID of the characteristic to read.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_read_long(uint16_t conn_handle, uint16_t handle, uint16_t offset, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Read Long Characteristic Values.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
handle: The handle of the characteristic value to read.
offset: The offset within the characteristic value to start reading.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_read_mult(uint16_t conn_handle, const uint16_t *handles, uint8_t num_handles, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Read Multiple Characteristic Values.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
handles: An array of 16-bit attribute handles to read.
num_handles: The number of entries in the “handles” array.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)¶

Initiates GATT procedure: Write Without Response.

This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to write to.
om: The value to write to the characteristic.

int ble_gattc_write_no_rsp_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len)¶

Initiates GATT procedure: Write Without Response.

This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to write to.
data: The value to write to the characteristic.
data_len: The number of bytes to write.

int ble_gattc_write(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Write Characteristic Value.

This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to write to.
om: The value to write to the characteristic.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_write_flat(uint16_t conn_handle, uint16_t attr_handle, const void *data, uint16_t data_len, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Write Characteristic Value (flat buffer version).

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to write to.
data: The value to write to the characteristic.
data_len: The number of bytes to write.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_write_long(uint16_t conn_handle, uint16_t attr_handle, uint16_t offset, struct os_mbuf *om, ble_gatt_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Write Long Characteristic Values.

This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
attr_handle: The handle of the characteristic value to write to.
offset: The offset at which to begin writing the value.
om: The value to write to the characteristic.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gattc_write_reliable(uint16_t conn_handle, struct ble_gatt_attr *attrs, int num_attrs, ble_gatt_reliable_attr_fn *cb, void *cb_arg)¶

Initiates GATT procedure: Reliable Writes.

This function consumes the supplied mbufs regardless of the outcome.

Parameters

conn_handle: The connection over which to execute the procedure.
attrs: An array of attribute descriptors; specifies which characteristics to write to and what data to write to them. The mbuf pointer in each attribute is set to NULL by this function.
num_attrs: The number of characteristics to write; equal to the number of elements in the ‘attrs’ array.
cb: The function to call to report procedure status updates; null for no callback.
cb_arg: The optional argument to pass to the callback function.

int ble_gatts_notify_custom(uint16_t conn_handle, uint16_t att_handle, struct os_mbuf *om)¶

Sends a “free-form” characteristic notification.

This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
att_handle: The attribute handle to indicate in the outgoing notification.
om: The value to write to the characteristic.

int ble_gattc_notify_custom(uint16_t conn_handle, uint16_t att_handle, struct os_mbuf *om)¶

Deprecated.

Should not be used. Use ble_gatts_notify_custom instead.

int ble_gatts_notify(uint16_t conn_handle, uint16_t chr_val_handle)¶

Sends a characteristic notification.

The content of the message is read from the specified characteristic.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
chr_val_handle: The value attribute handle of the characteristic to include in the outgoing notification.

int ble_gattc_notify(uint16_t conn_handle, uint16_t chr_val_handle)¶

Deprecated.

Should not be used. Use ble_gatts_notify instead.

int ble_gatts_indicate_custom(uint16_t conn_handle, uint16_t chr_val_handle, struct os_mbuf *txom)¶

Sends a “free-form” characteristic indication.

The provided mbuf contains the indication payload. This function consumes the supplied mbuf regardless of the outcome.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
chr_val_handle: The value attribute handle of the characteristic to include in the outgoing indication.
txom: The data to include in the indication.

int ble_gattc_indicate_custom(uint16_t conn_handle, uint16_t chr_val_handle, struct os_mbuf *txom)¶

Deprecated.

Should not be used. Use ble_gatts_indicate_custom instead.

int ble_gatts_indicate(uint16_t conn_handle, uint16_t chr_val_handle)¶

Sends a characteristic indication.

The content of the message is read from the specified characteristic.

Return

0 on success; nonzero on failure.

Parameters

conn_handle: The connection over which to execute the procedure.
chr_val_handle: The value attribute handle of the characteristic to include in the outgoing indication.

int ble_gattc_indicate(uint16_t conn_handle, uint16_t chr_val_handle)¶

Deprecated.

Should not be used. Use ble_gatts_indicate instead.

int ble_gattc_init(void)¶: Initialize the BLE GATT client.

int ble_gatts_add_svcs(const struct ble_gatt_svc_def *svcs)¶

Queues a set of service definitions for registration.

All services queued in this manner get registered when ble_gatts_start() is called.

Return

0 on success; BLE_HS_ENOMEM on heap exhaustion.

Parameters

svcs: An array of service definitions to queue for registration. This array must be terminated with an entry whose ‘type’ equals 0.

int ble_gatts_svc_set_visibility(uint16_t handle, int visible)¶

Set visibility of local GATT service.

Invisible services are not removed from database but are not discoverable by peer devices. Service Changed should be handled by application when needed by calling ble_svc_gatt_changed().

Return

0 on success; BLE_HS_ENOENT if service wasn’t found.

Parameters

handle: Handle of service
visible: non-zero if service should be visible

int ble_gatts_count_cfg(const struct ble_gatt_svc_def *defs)¶

Adjusts a host configuration object’s settings to accommodate the specified service definition array.

This function adds the counts to the appropriate fields in the supplied configuration object without clearing them first, so it can be called repeatedly with different inputs to calculate totals. Be sure to zero the GATT server settings prior to the first call to this function.

Return

0 on success; BLE_HS_EINVAL if the svcs array contains an invalid resource definition.

Parameters

defs: The service array containing the resource definitions to be counted.

void ble_gatts_chr_updated(uint16_t chr_val_handle)¶

Send notification (or indication) to any connected devices that have subscribed for notification (or indication) for specified characteristic.

Parameters

chr_val_handle: Characteristic value handle

int ble_gatts_find_svc(const ble_uuid_t *uuid, uint16_t *out_handle)¶

Retrieves the attribute handle associated with a local GATT service.

Return

0 on success; BLE_HS_ENOENT if the specified service could not be found.

Parameters

uuid: The UUID of the service to look up.
out_handle: On success, populated with the handle of the service attribute. Pass null if you don’t need this value.

int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, uint16_t *out_def_handle, uint16_t *out_val_handle)¶

Retrieves the pair of attribute handles associated with a local GATT characteristic.

Return

0 on success; BLE_HS_ENOENT if the specified service or characteristic could not be found.

Parameters

svc_uuid: The UUID of the parent service.
chr_uuid: The UUID of the characteristic to look up.
out_def_handle: On success, populated with the handle of the characteristic definition attribute. Pass null if you don’t need this value.
out_val_handle: On success, populated with the handle of the characteristic value attribute. Pass null if you don’t need this value.

int ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid, const ble_uuid_t *dsc_uuid, uint16_t *out_dsc_handle)¶

Retrieves the attribute handle associated with a local GATT descriptor.

Return

0 on success; BLE_HS_ENOENT if the specified service, characteristic, or descriptor could not be found.

Parameters

svc_uuid: The UUID of the grandparent service.
chr_uuid: The UUID of the parent characteristic.
dsc_uuid: The UUID of the descriptor ro look up.
out_dsc_handle: On success, populated with the handle of the descriptor attribute. Pass null if you don’t need this value.

void ble_gatts_show_local(void)¶

Prints dump of local GATT database.

This is useful to log local state of database in human readable form.

int ble_gatts_reset(void)¶

Resets the GATT server to its initial state.

On success, this function removes all supported services, characteristics, and descriptors. This function requires that: o No peers are connected, and o No GAP operations are active (advertise, discover, or connect).

Return: 0 on success; BLE_HS_EBUSY if the GATT server could not be reset due to existing connections or active GAP procedures.

int ble_gatts_start(void)¶

Makes all registered services available to peers.

This function gets called automatically by the NimBLE host on startup; manual calls are only necessary for replacing the set of supported services with a new one. This function requires that: o No peers are connected, and o No GAP operations are active (advertise, discover, or connect).

Return: 0 on success; A BLE host core return code on unexpected error.

struct ble_gatt_error¶

#include <ble_gatt.h>

Represents a GATT error.

Public Members

uint16_t status¶: The GATT status code indicating the type of error.

uint16_t att_handle¶: The attribute handle associated with the error.

struct ble_gatt_svc¶

#include <ble_gatt.h>

Represents a GATT Service.

Public Members

uint16_t start_handle¶: The start handle of the GATT service.

uint16_t end_handle¶: The end handle of the GATT service.

ble_uuid_any_t uuid¶: The UUID of the GATT service.

struct ble_gatt_attr¶

#include <ble_gatt.h>

Represents a GATT attribute.

Public Members

uint16_t handle¶: The handle of the GATT attribute.

uint16_t offset¶: The offset of the data within the attribute.

struct os_mbuf *om¶: Pointer to the data buffer represented by an os_mbuf.

struct ble_gatt_chr¶

#include <ble_gatt.h>

Represents a GATT characteristic.

Public Members

uint16_t def_handle¶: The handle of the GATT characteristic definition.

uint16_t val_handle¶: The handle of the GATT characteristic value.

uint8_t properties¶: The properties of the GATT characteristic.

ble_uuid_any_t uuid¶: The UUID of the GATT characteristic.

struct ble_gatt_dsc¶

#include <ble_gatt.h>

Represents a GATT descriptor.

Public Members

uint16_t handle¶: The handle of the GATT descriptor.

ble_uuid_any_t uuid¶: The UUID of the GATT descriptor.

struct ble_gatt_chr_def¶

#include <ble_gatt.h>

Represents the definition of a GATT characteristic.

Public Members

const ble_uuid_t *uuid¶: Pointer to characteristic UUID; use BLE_UUIDxx_DECLARE macros to declare proper UUID; NULL if there are no more characteristics in the service.

ble_gatt_access_fn *access_cb¶: Callback that gets executed when this characteristic is read or written.

void *arg¶: Optional argument for callback.

struct ble_gatt_dsc_def *descriptors¶

Array of this characteristic’s descriptors.

NULL if no descriptors. Do not include CCCD; it gets added automatically if this characteristic’s notify or indicate flag is set.

ble_gatt_chr_flags flags¶: Specifies the set of permitted operations for this characteristic.

uint8_t min_key_size¶: Specifies minimum required key size to access this characteristic.

uint16_t *val_handle¶: At registration time, this is filled in with the characteristic’s value attribute handle.

struct ble_gatt_svc_def¶

#include <ble_gatt.h>

Represents the definition of a GATT service.

Public Members

uint8_t type¶: One of the following: o BLE_GATT_SVC_TYPE_PRIMARY - primary service o BLE_GATT_SVC_TYPE_SECONDARY - secondary service o 0 - No more services in this array.

const ble_uuid_t *uuid¶: Pointer to service UUID; use BLE_UUIDxx_DECLARE macros to declare proper UUID; NULL if there are no more characteristics in the service.

const struct ble_gatt_svc_def **includes¶

Array of pointers to other service definitions.

These services are reported as “included services” during service discovery. Terminate the array with NULL.

const struct ble_gatt_chr_def *characteristics¶: Array of characteristic definitions corresponding to characteristics belonging to this service.

struct ble_gatt_dsc_def¶

#include <ble_gatt.h>

Represents the definition of a GATT descriptor.

Public Members

const ble_uuid_t *uuid¶: Pointer to descriptor UUID; use BLE_UUIDxx_DECLARE macros to declare proper UUID; NULL if there are no more characteristics in the service.

uint8_t att_flags¶: Specifies the set of permitted operations for this descriptor.

uint8_t min_key_size¶: Specifies minimum required key size to access this descriptor.

ble_gatt_access_fn *access_cb¶: Callback that gets executed when the descriptor is read or written.

void *arg¶: Optional argument for callback.

struct ble_gatt_access_ctxt¶

#include <ble_gatt.h>

Context for an access to a GATT characteristic or descriptor.

When a client reads or writes a locally registered characteristic or descriptor, an instance of this struct gets passed to the application callback.

Public Members

uint8_t op¶

Indicates the gatt operation being performed.

This is equal to one of the following values: o BLE_GATT_ACCESS_OP_READ_CHR o BLE_GATT_ACCESS_OP_WRITE_CHR o BLE_GATT_ACCESS_OP_READ_DSC o BLE_GATT_ACCESS_OP_WRITE_DSC

struct os_mbuf *om¶

A container for the GATT access data.

o For reads: The application populates this with the value of the characteristic or descriptor being read. o For writes: This is already populated with the value being written by the peer. If the application wishes to retain this mbuf for later use, the access callback must set this pointer to NULL to prevent the stack from freeing it.

union ble_gatt_access_ctxt.[anonymous] [anonymous]¶

The GATT operation being performed dictates which field in this union is valid.

If a characteristic is being accessed, the chr field is valid. Otherwise a descriptor is being accessed, in which case the dsc field is valid.

struct ble_gatt_register_ctxt¶

#include <ble_gatt.h>

Context passed to the registration callback; represents the GATT service, characteristic, or descriptor being registered.

Public Members

uint8_t op¶

Indicates the gatt registration operation just performed.

This is equal to one of the following values: o BLE_GATT_REGISTER_OP_SVC o BLE_GATT_REGISTER_OP_CHR o BLE_GATT_REGISTER_OP_DSC

union ble_gatt_register_ctxt.[anonymous] [anonymous]¶: The value of the op field determines which field in this union is valid.

An OS to build, deploy and securely manage billions of devices

Latest News:

NimBLE Host GATT Client Reference¶

Introduction¶

API¶