Warning

This document is not updated for ESP32C6 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

GATT SERVER API

Application Example

Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following demos and their tutorials:

API Reference

Header File

Functions

esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback)

This function is called to register application callbacks with BTA GATTS module.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_app_register(uint16_t app_id)

This function is called to register application identifier.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if)

unregister with GATT Server.

Parameters

gatts_if – [in] GATT server access interface

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, esp_gatt_srvc_id_t *service_id, uint16_t num_handle)

Create a service. When service creation is done, a callback event ESP_GATTS_CREATE_EVT is called to report status and service ID to the profile. The service ID obtained in the callback function needs to be used when adding included service and characteristics/descriptors into the service.

Parameters

  • gatts_if – [in] GATT server access interface

  • service_id – [in] service ID.

  • num_handle – [in] number of handle requested for this service.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, esp_gatt_if_t gatts_if, uint16_t max_nb_attr, uint8_t srvc_inst_id)

Create a service attribute tab.

Parameters

  • gatts_attr_db – [in] the pointer to the service attr tab

  • gatts_if – [in] GATT server access interface

  • max_nb_attr – [in] the number of attribute to be added to the service database.

  • srvc_inst_id – [in] the instance id of the service

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle)

This function is called to add an included service. This function have to be called between ‘esp_ble_gatts_create_service’ and ‘esp_ble_gatts_add_char’. After included service is included, a callback event ESP_GATTS_ADD_INCL_SRVC_EVT is reported the included service ID.

Parameters

  • service_handle – [in] service handle to which this included service is to be added.

  • included_service_handle – [in] the service ID to be included.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val, esp_attr_control_t *control)

This function is called to add a characteristic into a service.

Parameters

  • service_handle – [in] service handle to which this included service is to be added.

  • char_uuid – [in] : Characteristic UUID.

  • perm – [in] : Characteristic value declaration attribute permission.

  • property – [in] : Characteristic Properties

  • char_val – [in] : Characteristic value

  • control – [in] : attribute response control byte

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_add_char_descr(uint16_t service_handle, esp_bt_uuid_t *descr_uuid, esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val, esp_attr_control_t *control)

This function is called to add characteristic descriptor. When it’s done, a callback event ESP_GATTS_ADD_DESCR_EVT is called to report the status and an ID number for this descriptor.

Parameters

  • service_handle – [in] service handle to which this characteristic descriptor is to be added.

  • perm – [in] descriptor access permission.

  • descr_uuid – [in] descriptor UUID.

  • char_descr_val – [in] : Characteristic descriptor value

  • control – [in] : attribute response control byte

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle)

This function is called to delete a service. When this is done, a callback event ESP_GATTS_DELETE_EVT is report with the status.

Parameters

service_handle – [in] service_handle to be deleted.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_start_service(uint16_t service_handle)

This function is called to start a service.

Parameters

service_handle – [in] the service handle to be started.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle)

This function is called to stop a service.

Parameters

service_handle – [in] - service to be topped.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, uint16_t value_len, uint8_t *value, bool need_confirm)

Send indicate or notify to GATT client. Set param need_confirm as false will send notification, otherwise indication.

Parameters

  • gatts_if – [in] GATT server access interface

  • conn_id – [in] - connection id to indicate.

  • attr_handle – [in] - attribute handle to indicate.

  • value_len – [in] - indicate value length.

  • value – [in] value to indicate.

  • need_confirm – [in] - Whether a confirmation is required. false sends a GATT notification, true sends a GATT indication.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp)

This function is called to send a response to a request.

Parameters

  • gatts_if – [in] GATT server access interface

  • conn_id – [in] - connection identifier.

  • trans_id – [in] - transfer id

  • status – [in] - response status

  • rsp – [in] - response data.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value)

This function is called to set the attribute value by the application.

Parameters

  • attr_handle – [in] the attribute handle which to be set

  • length – [in] the value length

  • value – [in] the pointer to the attribute value

Returns

  • ESP_OK : success

  • other : failed

esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value)

Retrieve attribute value.

Parameters

  • attr_handle – [in] Attribute handle.

  • length – [out] pointer to the attribute value length

  • value – [out] Pointer to attribute value payload, the value cannot be modified by user

Returns

  • ESP_GATT_OK : success

  • other : failed

esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct)

Open a direct open connection or add a background auto connection.

Parameters

  • gatts_if – [in] GATT server access interface

  • remote_bda – [in] remote device bluetooth device address.

  • is_direct – [in] direct connection or background auto connection

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id)

Close a connection a remote device.

Parameters

  • gatts_if – [in] GATT server access interface

  • conn_id – [in] connection ID to be closed.

Returns

  • ESP_OK : success

  • other : failed

esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda)

Send service change indication.

Parameters

  • gatts_if – [in] GATT server access interface

  • remote_bda – [in] remote device bluetooth device address. If remote_bda is NULL then it will send service change indication to all the connected devices and if not then to a specific device

Returns

  • ESP_OK : success

  • other : failed

Unions

union esp_ble_gatts_cb_param_t
#include <esp_gatts_api.h>

Gatt server callback parameters union.

Public Members

struct esp_ble_gatts_cb_param_t::gatts_reg_evt_param reg

Gatt server callback param of ESP_GATTS_REG_EVT

struct esp_ble_gatts_cb_param_t::gatts_read_evt_param read

Gatt server callback param of ESP_GATTS_READ_EVT

struct esp_ble_gatts_cb_param_t::gatts_write_evt_param write

Gatt server callback param of ESP_GATTS_WRITE_EVT

struct esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param exec_write

Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT

struct esp_ble_gatts_cb_param_t::gatts_mtu_evt_param mtu

Gatt server callback param of ESP_GATTS_MTU_EVT

struct esp_ble_gatts_cb_param_t::gatts_conf_evt_param conf

Gatt server callback param of ESP_GATTS_CONF_EVT (confirm)

struct esp_ble_gatts_cb_param_t::gatts_create_evt_param create

Gatt server callback param of ESP_GATTS_CREATE_EVT

struct esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param add_incl_srvc

Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT

struct esp_ble_gatts_cb_param_t::gatts_add_char_evt_param add_char

Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT

struct esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param add_char_descr

Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT

struct esp_ble_gatts_cb_param_t::gatts_delete_evt_param del

Gatt server callback param of ESP_GATTS_DELETE_EVT

struct esp_ble_gatts_cb_param_t::gatts_start_evt_param start

Gatt server callback param of ESP_GATTS_START_EVT

struct esp_ble_gatts_cb_param_t::gatts_stop_evt_param stop

Gatt server callback param of ESP_GATTS_STOP_EVT

struct esp_ble_gatts_cb_param_t::gatts_connect_evt_param connect

Gatt server callback param of ESP_GATTS_CONNECT_EVT

struct esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param disconnect

Gatt server callback param of ESP_GATTS_DISCONNECT_EVT

struct esp_ble_gatts_cb_param_t::gatts_open_evt_param open

Gatt server callback param of ESP_GATTS_OPEN_EVT

struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open

Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT

struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close

Gatt server callback param of ESP_GATTS_CLOSE_EVT

struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest

Gatt server callback param of ESP_GATTS_CONGEST_EVT

struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp

Gatt server callback param of ESP_GATTS_RESPONSE_EVT

struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab

Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT

struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val

Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT

struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change

Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT

struct gatts_add_attr_tab_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_CREAT_ATTR_TAB_EVT.

Public Members

esp_gatt_status_t status

Operation status

esp_bt_uuid_t svc_uuid

Service uuid type

uint8_t svc_inst_id

Service id

uint16_t num_handle

The number of the attribute handle to be added to the gatts database

uint16_t *handles

The number to the handles

struct gatts_add_char_descr_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_ADD_CHAR_DESCR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t attr_handle

Descriptor attribute handle

uint16_t service_handle

Service attribute handle

esp_bt_uuid_t descr_uuid

Characteristic descriptor uuid

struct gatts_add_char_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_ADD_CHAR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t attr_handle

Characteristic attribute handle

uint16_t service_handle

Service attribute handle

esp_bt_uuid_t char_uuid

Characteristic uuid

struct gatts_add_incl_srvc_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_ADD_INCL_SRVC_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t attr_handle

Included service attribute handle

uint16_t service_handle

Service attribute handle

struct gatts_cancel_open_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_CANCEL_OPEN_EVT.

Public Members

esp_gatt_status_t status

Operation status

struct gatts_close_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_CLOSE_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

struct gatts_conf_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_CONF_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

uint16_t handle

attribute handle

uint16_t len

The indication or notification value length, len is valid when send notification or indication failed

uint8_t *value

The indication or notification value , value is valid when send notification or indication failed

struct gatts_congest_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_LISTEN_EVT.

ESP_GATTS_CONGEST_EVT

Public Members

uint16_t conn_id

Connection id

bool congested

Congested or not

struct gatts_connect_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_CONNECT_EVT.

Public Members

uint16_t conn_id

Connection id

uint8_t link_role

Link role : master role = 0 ; slave role = 1

esp_bd_addr_t remote_bda

Remote bluetooth device address

esp_gatt_conn_params_t conn_params

current Connection parameters

esp_ble_addr_type_t ble_addr_type

Remote BLE device address type

uint16_t conn_handle

HCI connection handle

struct gatts_create_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_UNREG_EVT.

ESP_GATTS_CREATE_EVT

Public Members

esp_gatt_status_t status

Operation status

uint16_t service_handle

Service attribute handle

esp_gatt_srvc_id_t service_id

Service id, include service uuid and other information

struct gatts_delete_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_DELETE_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t service_handle

Service attribute handle

struct gatts_disconnect_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_DISCONNECT_EVT.

Public Members

uint16_t conn_id

Connection id

esp_bd_addr_t remote_bda

Remote bluetooth device address

esp_gatt_conn_reason_t reason

Indicate the reason of disconnection

struct gatts_exec_write_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_EXEC_WRITE_EVT.

Public Members

uint16_t conn_id

Connection id

uint32_t trans_id

Transfer id

esp_bd_addr_t bda

The bluetooth device address which been written

uint8_t exec_write_flag

Execute write flag

struct gatts_mtu_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_MTU_EVT.

Public Members

uint16_t conn_id

Connection id

uint16_t mtu

MTU size

struct gatts_open_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_OPEN_EVT.

Public Members

esp_gatt_status_t status

Operation status

struct gatts_read_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_READ_EVT.

Public Members

uint16_t conn_id

Connection id

uint32_t trans_id

Transfer id

esp_bd_addr_t bda

The bluetooth device address which been read

uint16_t handle

The attribute handle

uint16_t offset

Offset of the value, if the value is too long

bool is_long

The value is too long or not

bool need_rsp

The read operation need to do response

struct gatts_reg_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_REG_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t app_id

Application id which input in register API

struct gatts_rsp_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_RESPONSE_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t handle

Attribute handle which send response

struct gatts_send_service_change_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_SEND_SERVICE_CHANGE_EVT.

Public Members

esp_gatt_status_t status

Operation status

struct gatts_set_attr_val_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_SET_ATTR_VAL_EVT.

Public Members

uint16_t srvc_handle

The service handle

uint16_t attr_handle

The attribute handle

esp_gatt_status_t status

Operation status

struct gatts_start_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_START_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t service_handle

Service attribute handle

struct gatts_stop_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_STOP_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t service_handle

Service attribute handle

struct gatts_write_evt_param
#include <esp_gatts_api.h>

ESP_GATTS_WRITE_EVT.

Public Members

uint16_t conn_id

Connection id

uint32_t trans_id

Transfer id

esp_bd_addr_t bda

The bluetooth device address which been written

uint16_t handle

The attribute handle

uint16_t offset

Offset of the value, if the value is too long

bool need_rsp

The write operation need to do response

bool is_prep

This write operation is prepare write

uint16_t len

The write attribute value length

uint8_t *value

The write attribute value

Macros

ESP_GATT_PREP_WRITE_CANCEL

Prepare write flag to indicate cancel prepare write

ESP_GATT_PREP_WRITE_EXEC

Prepare write flag to indicate execute prepare write

Type Definitions

typedef void (*esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)

GATT Server callback function type.

Param event

: Event type

Param gatts_if

: GATT server access interface, normally different gatts_if correspond to different profile

Param param

: Point to callback parameter, currently is union type

Enumerations

enum esp_gatts_cb_event_t

GATT Server callback function events.

Values:

enumerator ESP_GATTS_REG_EVT

When register application id, the event comes

enumerator ESP_GATTS_READ_EVT

When gatt client request read operation, the event comes

enumerator ESP_GATTS_WRITE_EVT

When gatt client request write operation, the event comes

enumerator ESP_GATTS_EXEC_WRITE_EVT

When gatt client request execute write, the event comes

enumerator ESP_GATTS_MTU_EVT

When set mtu complete, the event comes

enumerator ESP_GATTS_CONF_EVT

When receive confirm, the event comes

enumerator ESP_GATTS_UNREG_EVT

When unregister application id, the event comes

enumerator ESP_GATTS_CREATE_EVT

When create service complete, the event comes

enumerator ESP_GATTS_ADD_INCL_SRVC_EVT

When add included service complete, the event comes

enumerator ESP_GATTS_ADD_CHAR_EVT

When add characteristic complete, the event comes

enumerator ESP_GATTS_ADD_CHAR_DESCR_EVT

When add descriptor complete, the event comes

enumerator ESP_GATTS_DELETE_EVT

When delete service complete, the event comes

enumerator ESP_GATTS_START_EVT

When start service complete, the event comes

enumerator ESP_GATTS_STOP_EVT

When stop service complete, the event comes

enumerator ESP_GATTS_CONNECT_EVT

When gatt client connect, the event comes

enumerator ESP_GATTS_DISCONNECT_EVT

When gatt client disconnect, the event comes

enumerator ESP_GATTS_OPEN_EVT

When connect to peer, the event comes

enumerator ESP_GATTS_CANCEL_OPEN_EVT

When disconnect from peer, the event comes

enumerator ESP_GATTS_CLOSE_EVT

When gatt server close, the event comes

enumerator ESP_GATTS_LISTEN_EVT

When gatt listen to be connected the event comes

enumerator ESP_GATTS_CONGEST_EVT

When congest happen, the event comes

enumerator ESP_GATTS_RESPONSE_EVT

When gatt send response complete, the event comes

enumerator ESP_GATTS_CREAT_ATTR_TAB_EVT

When gatt create table complete, the event comes

enumerator ESP_GATTS_SET_ATTR_VAL_EVT

When gatt set attr value complete, the event comes

enumerator ESP_GATTS_SEND_SERVICE_CHANGE_EVT

When gatt send service change indication complete, the event comes

Provide feedback about this document