GATT Throughput Service

The GATT Throughput Service is a custom service that receives and writes data and returns metrics about these operations.

To test GATT throughput, the client (central) writes without response to the characteristic on the server (peripheral). The client can then read the characteristic to retrieve the metrics.

The GATT Throughput Service is used in the Bluetooth: Throughput sample.

Service UUID

The 128-bit service UUID is 0483DADD-6C9D-6CA9-5D41-03AD4FFF4ABB.

Characteristics

This service has one characteristic.

Throughput (0x1524)

Write Without Response

  • Write any data to the characteristic to measure throughput.

  • Write 0 bytes to the characteristic to reset the metrics.

Read

The read operation returns 3*4 bytes (12 bytes) that contain the metrics:

  • 4 bytes unsigned: Number of GATT writes received

  • 4 bytes unsigned: Total bytes received

  • 4 bytes unsigned: Throughput in bits per second

API documentation

Header file: include/throughput.h
Source file: subsys/bluetooth/services/throughput.c
group bt_throughput

API for the Bluetooth LE GATT Throughput Service.

Defines

BT_UUID_THROUGHPUT_CHAR

Throughput Characteristic UUID.

BT_UUID_THROUGHPUT

Throughput Service UUID.

Functions

int bt_throughput_init(struct bt_throughput *throughput, const struct bt_throughput_cb *cb)

Initialize the GATT Throughput Service.

Parameters

  • [in] throughput: Throughput Service instance.

  • [in] cb: Callbacks.

Return Value

  • 0: If the operation was successful. Otherwise, a negative error code is returned.

int bt_throughput_handles_assign(struct bt_gatt_dm *dm, struct bt_throughput *throughput)

Assign handles to the Throughput Service instance.

This function should be called when a link with a peer has been established, to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module. The GATT attribute handles are provided by the GATT Discovery Manager.

Parameters

  • [in] dm: Discovery object.

  • [inout] throughput: Throughput Service instance.

Return Value

  • 0: If the operation was successful. Otherwise, a negative error code is returned.

  • (-ENOTSUP): Special error code used when the UUID of the service does not match the expected UUID.

int bt_throughput_read(struct bt_throughput *throughput)

Read data from the server.

Note

This procedure is asynchronous.

Parameters

  • [in] throughput: Throughput Service instance.

Return Value

  • 0: If the operation was successful. Otherwise, a negative error code is returned.

int bt_throughput_write(struct bt_throughput *throughput, const uint8_t *data, uint16_t len)

Write data to the server.

Parameters

  • [in] throughput: Throughput Service instance.

  • [in] data: Data.

  • [in] len: Data length.

Return Value

  • 0: If the operation was successful. Otherwise, a negative error code is returned.

struct bt_throughput_metrics
#include <throughput.h>

Throughput metrics.

Public Members

uint32_t write_count

Number of GATT writes received.

uint32_t write_len

Number of bytes received.

uint32_t write_rate

Transfer speed in bits per second.

struct bt_throughput_cb
#include <throughput.h>

Throughput callback structure.

Public Members

uint8_t (*data_read)(const struct bt_throughput_metrics *met)

Data read callback.

This function is called when data has been read from the Throughput Characteristic.

Parameters

  • [in] met: Throughput metrics.

Return Value

  • BT_GATT_ITER_CONTINUE: To keep notifications enabled.

  • BT_GATT_ITER_STOP: To disable notifications.

void (*data_received)(const struct bt_throughput_metrics *met)

Data received callback.

This function is called when data has been received by the Throughput Characteristic.

Parameters

  • [in] met: Throughput metrics.

void (*data_send)(const struct bt_throughput_metrics *met)

Data send callback.

This function is called when data has been sent to the Throughput Characteristic.

Parameters

  • [in] met: Throughput metrics.

struct bt_throughput
#include <throughput.h>

Throughput structure.

Public Members

uint16_t char_handle

Throughput Characteristic handle.

struct bt_gatt_read_params read_params

GATT read parameters for the Throughput Characteristic.

struct bt_throughput_cb *cb

Throughput callback structure.

struct bt_conn *conn

Connection object.