GATT

GATT client operations, GATT events and the Service Changed characteristic. More...

Data Structures
struct	pbl_bt_gatt_device_connection_event
	A GATT connection was established. More...
struct	pbl_bt_gatt_device_disconnection_event
	A GATT connection was terminated. More...
struct	pbl_bt_gatt_device_buffer_empty_event
	The transmit buffers to a peer became available again. More...
struct	pbl_bt_gatt_server_notif_indic_event
	A notification or indication was received from a peer's GATT server. More...
struct	pbl_bt_gatt_device_mtu_update_event
	The ATT MTU of a connection changed. More...
struct	pbl_bt_gatt_server_changed_confirmation_event
	A peer confirmed a Service Changed indication. More...
struct	pbl_bt_gatt_server_read_subscription_event
	A peer read the Service Changed CCCD. More...
struct	pbl_bt_gatt_server_subscribe_event
	A peer (un)subscribed to Service Changed indications. More...
struct	pbl_bt_gatt_client_op_response_hdr
	Common header of GATT client operation responses. More...
struct	pbl_bt_gatt_client_op_read_response
	Response to pbl_bt_gatt_read(). More...
struct	pbl_bt_gatt_client_op_write_response
	Response to pbl_bt_gatt_write(). More...

Macros
#define	PBL_BT_GATT_SERVICE_UUID   ((uint16_t)0x1801)
	16-bit UUID of the Generic Attribute service.
#define	PBL_BT_GATT_SERVICE_CHANGED_CHARACTERISTIC_UUID   ((uint16_t)0x2A05)
	16-bit UUID of the Service Changed characteristic.
#define	PBL_BT_GATT_CCCD_UUID   ((uint16_t)0x2902)
	16-bit UUID of the Client Characteristic Configuration Descriptor.

Enumerations
enum	pbl_bt_gatt_client_op_response_type { PBL_BT_GATT_CLIENT_OP_RESPONSE_READ , PBL_BT_GATT_CLIENT_OP_RESPONSE_WRITE }
	Type of a GATT client operation response. More...

Functions
void	pbl_bt_gatt_respond_read_subscription (uint32_t transaction_id, uint16_t response_code)
	Answer a read of the Service Changed CCCD.
void	pbl_bt_gatt_send_changed_indication (const struct pbl_bt_device_internal *device, const struct pbl_bt_att_handle_range *data)
	Indicate a change of the local GATT database to a peer.
enum pbl_bt_errno	pbl_bt_gatt_write_without_response (GAPLEConnection *connection, const uint8_t *value, size_t value_length, uint16_t att_handle)
	Write a characteristic value without response.
enum pbl_bt_errno	pbl_bt_gatt_write (GAPLEConnection *connection, const uint8_t *value, size_t value_length, uint16_t att_handle, void *context)
	Write an attribute value.
enum pbl_bt_errno	pbl_bt_gatt_read (GAPLEConnection *connection, uint16_t att_handle, void *context)
	Read an attribute value.
void	pbl_bt_cb_gatt_handle_connect (const struct pbl_bt_gatt_device_connection_event *event)
	Called when a GATT connection is established.
void	pbl_bt_cb_gatt_handle_disconnect (const struct pbl_bt_gatt_device_disconnection_event *event)
	Called when a GATT connection is terminated.
void	pbl_bt_cb_gatt_handle_buffer_empty (const struct pbl_bt_gatt_device_buffer_empty_event *event)
	Called when the transmit buffers became available again.
void	pbl_bt_cb_gatt_handle_mtu_update (const struct pbl_bt_gatt_device_mtu_update_event *event)
	Called when the ATT MTU of a connection changed.
void	pbl_bt_cb_gatt_handle_notification (const struct pbl_bt_gatt_server_notif_indic_event *event)
	Called when a notification is received.
void	pbl_bt_cb_gatt_handle_indication (const struct pbl_bt_gatt_server_notif_indic_event *event)
	Called when an indication is received.
void	pbl_bt_cb_gatt_service_changed_server_confirmation (const struct pbl_bt_gatt_server_changed_confirmation_event *event)
	Called when a peer confirmed a Service Changed indication.
void	pbl_bt_cb_gatt_service_changed_server_subscribe (const struct pbl_bt_gatt_server_subscribe_event *event)
	Called when a peer (un)subscribed to Service Changed indications.
void	pbl_bt_cb_gatt_service_changed_server_read_subscription (const struct pbl_bt_gatt_server_read_subscription_event *event)
	Called when a peer read the Service Changed CCCD.
void	pbl_bt_cb_gatt_client_discovery_handle_service_changed (GAPLEConnection *connection, uint16_t handle)
	Called after subscribing to a peer's Service Changed indications.
void	pbl_bt_cb_gatt_client_operations_handle_response (struct pbl_bt_gatt_client_op_response_hdr *event)
	Called with the result of pbl_bt_gatt_read() or pbl_bt_gatt_write().

Detailed Description

GATT client operations, GATT events and the Service Changed characteristic.

Reads and writes complete asynchronously: the result is delivered to pbl_bt_cb_gatt_client_operations_handle_response() on the NimBLE host task, together with the context passed when issuing the operation.

enum pbl_bt_errno err = pbl_bt_gatt_read(connection, value_handle, my_ctx);
if (err != PBL_BT_ERRNO_OK) {
  // Not issued, no response will follow.
}
 
static const uint8_t enable[] = { 0x01, 0x00 };
pbl_bt_gatt_write(connection, enable, sizeof(enable), cccd_handle, my_ctx);
 
void pbl_bt_cb_gatt_client_operations_handle_response(
    struct pbl_bt_gatt_client_op_response_hdr *event) {
  if (event->type == PBL_BT_GATT_CLIENT_OP_RESPONSE_READ &&
      event->error_code == PBL_BT_GATT_ERROR_SUCCESS) {
    const struct pbl_bt_gatt_client_op_read_response *rsp = (const void *)event;
    // rsp->value is only valid during the callback.
    prv_handle_value(event->context, rsp->value, rsp->value_length);
  }
}

The events identify the peer by struct pbl_bt_addr: the address type is not available.

---

Data Structure Documentation

pbl_bt_gatt_device_connection_event

struct pbl_bt_gatt_device_connection_event

A GATT connection was established.

Not reported by the NimBLE backend.

Data Fields
uint32_t	connection_id	Backend specific connection identifier.
struct pbl_bt_addr	dev_address	Address of the peer.
uint16_t	mtu	ATT MTU.

pbl_bt_gatt_device_disconnection_event

struct pbl_bt_gatt_device_disconnection_event

A GATT connection was terminated.

Data Fields
struct pbl_bt_addr	dev_address	Address of the peer.

pbl_bt_gatt_device_buffer_empty_event

struct pbl_bt_gatt_device_buffer_empty_event

The transmit buffers to a peer became available again.

Not reported by NimBLE.

Data Fields
struct pbl_bt_addr	dev_address	Address of the peer.

pbl_bt_gatt_server_notif_indic_event

struct pbl_bt_gatt_server_notif_indic_event

A notification or indication was received from a peer's GATT server.

Data Fields
uint16_t	attr_handle	Handle of the attribute.
uint8_t *	attr_val	Attribute value. Only valid during the callback.
uint16_t	attr_val_len	Length of attr_val in bytes.
void *	context	Unused by the NimBLE backend.
struct pbl_bt_addr	dev_address	Address of the peer.

pbl_bt_gatt_device_mtu_update_event

struct pbl_bt_gatt_device_mtu_update_event

The ATT MTU of a connection changed.

Data Fields
struct pbl_bt_addr	dev_address	Address of the peer.
uint16_t	mtu	New ATT MTU.

pbl_bt_gatt_server_changed_confirmation_event

struct pbl_bt_gatt_server_changed_confirmation_event

A peer confirmed a Service Changed indication.

Not reported by NimBLE.

Data Fields
uint32_t	connection_id	Backend specific connection identifier.
struct pbl_bt_addr	dev_address	Address of the peer.
enum pbl_bt_hci_status	status_code	Status of the confirmation.
uint32_t	transaction_id	Backend specific transaction identifier.

pbl_bt_gatt_server_read_subscription_event

struct pbl_bt_gatt_server_read_subscription_event

A peer read the Service Changed CCCD.

Not reported by NimBLE.

Data Fields
uint32_t	connection_id	Backend specific connection identifier.
struct pbl_bt_addr	dev_address	Address of the peer.
uint32_t	transaction_id	Transaction to answer with pbl_bt_gatt_respond_read_subscription().

pbl_bt_gatt_server_subscribe_event

struct pbl_bt_gatt_server_subscribe_event

A peer (un)subscribed to Service Changed indications.

Not reported by NimBLE.

Data Fields
uint32_t	connection_id	Backend specific connection identifier.
struct pbl_bt_addr	dev_address	Address of the peer.
bool	is_subscribing	True when subscribing, false when unsubscribing.

pbl_bt_gatt_client_op_response_hdr

struct pbl_bt_gatt_client_op_response_hdr

Common header of GATT client operation responses.

Data Fields
void *	context	Context passed to pbl_bt_gatt_read() or pbl_bt_gatt_write().
enum pbl_bt_gatt_error	error_code	Result. ATT errors are reported as is; other failures as PBL_BT_ERRNO_INTERNAL_ERROR_BEGIN plus the backend error code.
enum pbl_bt_gatt_client_op_response_type	type	Response type, tells which response structure embeds this header.

pbl_bt_gatt_client_op_read_response

struct pbl_bt_gatt_client_op_read_response

Response to pbl_bt_gatt_read().

Data Fields
struct pbl_bt_gatt_client_op_response_hdr	hdr	Common header.
uint8_t *	value	Value read. Only valid during the callback.
uint16_t	value_length	Length of value in bytes.

pbl_bt_gatt_client_op_write_response

struct pbl_bt_gatt_client_op_write_response

Response to pbl_bt_gatt_write().

Data Fields
struct pbl_bt_gatt_client_op_response_hdr	hdr	Common header.

Macro Definition Documentation

PBL_BT_GATT_CCCD_UUID

#define PBL_BT_GATT_CCCD_UUID   ((uint16_t)0x2902)

16-bit UUID of the Client Characteristic Configuration Descriptor.

PBL_BT_GATT_SERVICE_CHANGED_CHARACTERISTIC_UUID

#define PBL_BT_GATT_SERVICE_CHANGED_CHARACTERISTIC_UUID   ((uint16_t)0x2A05)

16-bit UUID of the Service Changed characteristic.

PBL_BT_GATT_SERVICE_UUID

#define PBL_BT_GATT_SERVICE_UUID   ((uint16_t)0x1801)

16-bit UUID of the Generic Attribute service.

Enumeration Type Documentation

pbl_bt_gatt_client_op_response_type

enum pbl_bt_gatt_client_op_response_type

Type of a GATT client operation response.

Enumerator
PBL_BT_GATT_CLIENT_OP_RESPONSE_READ	Response to pbl_bt_gatt_read(), a struct pbl_bt_gatt_client_op_read_response.
PBL_BT_GATT_CLIENT_OP_RESPONSE_WRITE	Response to pbl_bt_gatt_write(), a struct pbl_bt_gatt_client_op_write_response.

Function Documentation

pbl_bt_cb_gatt_client_discovery_handle_service_changed()

void pbl_bt_cb_gatt_client_discovery_handle_service_changed ( GAPLEConnection *  connection, uint16_t  handle  )

extern

Called after subscribing to a peer's Service Changed indications.

Parameters

connection	The connection.
handle	Value handle of the peer's Service Changed characteristic.

pbl_bt_cb_gatt_client_operations_handle_response()

void pbl_bt_cb_gatt_client_operations_handle_response ( struct pbl_bt_gatt_client_op_response_hdr *  event )

extern

Called with the result of pbl_bt_gatt_read() or pbl_bt_gatt_write().

Parameters

event

Response header. Cast to the structure given by its type.

pbl_bt_cb_gatt_handle_buffer_empty()

void pbl_bt_cb_gatt_handle_buffer_empty ( const struct pbl_bt_gatt_device_buffer_empty_event *  event )

extern

Called when the transmit buffers became available again.

Not invoked by NimBLE.

Parameters

event

The peer.

pbl_bt_cb_gatt_handle_connect()

void pbl_bt_cb_gatt_handle_connect ( const struct pbl_bt_gatt_device_connection_event *  event )

extern

Called when a GATT connection is established.

Not invoked by the NimBLE backend.

Parameters

event

The connection.

pbl_bt_cb_gatt_handle_disconnect()

void pbl_bt_cb_gatt_handle_disconnect ( const struct pbl_bt_gatt_device_disconnection_event *  event )

extern

Called when a GATT connection is terminated.

Invoked before pbl_bt_handle_le_disconnection_complete_event().

Parameters

event

The disconnection.

pbl_bt_cb_gatt_handle_indication()

void pbl_bt_cb_gatt_handle_indication ( const struct pbl_bt_gatt_server_notif_indic_event *  event )

extern

Called when an indication is received.

The backend confirms the indication on reception, before this is called.

Parameters

event

The indication.

pbl_bt_cb_gatt_handle_mtu_update()

void pbl_bt_cb_gatt_handle_mtu_update ( const struct pbl_bt_gatt_device_mtu_update_event *  event )

extern

Called when the ATT MTU of a connection changed.

Parameters

event

The new MTU.

pbl_bt_cb_gatt_handle_notification()

void pbl_bt_cb_gatt_handle_notification ( const struct pbl_bt_gatt_server_notif_indic_event *  event )

extern

Called when a notification is received.

Parameters

event

The notification.

pbl_bt_cb_gatt_service_changed_server_confirmation()

void pbl_bt_cb_gatt_service_changed_server_confirmation ( const struct pbl_bt_gatt_server_changed_confirmation_event *  event )

extern

Called when a peer confirmed a Service Changed indication.

Not invoked by NimBLE.

Parameters

event

The confirmation.

pbl_bt_cb_gatt_service_changed_server_read_subscription()

void pbl_bt_cb_gatt_service_changed_server_read_subscription ( const struct pbl_bt_gatt_server_read_subscription_event *  event )

extern

Called when a peer read the Service Changed CCCD.

Not invoked by NimBLE.

Answer with pbl_bt_gatt_respond_read_subscription().

Parameters

event

The read.

pbl_bt_cb_gatt_service_changed_server_subscribe()

void pbl_bt_cb_gatt_service_changed_server_subscribe ( const struct pbl_bt_gatt_server_subscribe_event *  event )

extern

Called when a peer (un)subscribed to Service Changed indications.

Not invoked by NimBLE.

Parameters

event

The subscription change.

pbl_bt_gatt_read()

enum pbl_bt_errno pbl_bt_gatt_read	(	GAPLEConnection *	connection,
		uint16_t	att_handle,
		void *	context
	)

Read an attribute value.

The value is reported through pbl_bt_cb_gatt_client_operations_handle_response().

Parameters

connection	The connection.
att_handle	Handle of the attribute.
context	Passed back in the response.

Return values

PBL_BT_ERRNO_OK	The read was issued.
PBL_BT_ERRNO_INVALID_STATE	connection is not connected.

Returns

PBL_BT_ERRNO_INTERNAL_ERROR_BEGIN plus the backend error code on other failures. No response follows a failure.

pbl_bt_gatt_respond_read_subscription()

void pbl_bt_gatt_respond_read_subscription	(	uint32_t	transaction_id,
		uint16_t	response_code
	)

Answer a read of the Service Changed CCCD.

Does nothing in the NimBLE backend.

Parameters

transaction_id	Transaction from struct pbl_bt_gatt_server_read_subscription_event.
response_code	CCCD value to return.

pbl_bt_gatt_send_changed_indication()

void pbl_bt_gatt_send_changed_indication	(	const struct pbl_bt_device_internal *	device,
		const struct pbl_bt_att_handle_range *	data
	)

Indicate a change of the local GATT database to a peer.

Sends a Service Changed indication with the affected handle range.

Parameters

device	The peer.
data	Changed handle range.

pbl_bt_gatt_write()

enum pbl_bt_errno pbl_bt_gatt_write	(	GAPLEConnection *	connection,
		const uint8_t *	value,
		size_t	value_length,
		uint16_t	att_handle,
		void *	context
	)

Write an attribute value.

The result is reported through pbl_bt_cb_gatt_client_operations_handle_response().

Parameters

connection	The connection.
value	Value to write. Copied during the call.
value_length	Length of value in bytes.
att_handle	Handle of the attribute.
context	Passed back in the response.

Return values

PBL_BT_ERRNO_OK	The write was issued.
PBL_BT_ERRNO_INVALID_STATE	connection is not connected.

Returns

PBL_BT_ERRNO_INTERNAL_ERROR_BEGIN plus the backend error code on other failures. No response follows a failure.

pbl_bt_gatt_write_without_response()

enum pbl_bt_errno pbl_bt_gatt_write_without_response	(	GAPLEConnection *	connection,
		const uint8_t *	value,
		size_t	value_length,
		uint16_t	att_handle
	)

Write a characteristic value without response.

Parameters

connection	The connection.
value	Value to write. Copied during the call.
value_length	Length of value in bytes, at most ATT MTU - 3.
att_handle	Handle of the attribute.

Return values

PBL_BT_ERRNO_OK	The write was queued.
PBL_BT_ERRNO_INVALID_STATE	connection is not connected.

Returns

PBL_BT_ERRNO_INTERNAL_ERROR_BEGIN plus the backend error code on other failures.