GATT Server API

[中文]

Application Examples

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

API Reference

Header File

  • components/bt/host/bluedroid/api/include/api/esp_gatts_api.h

  • This header file can be included with:

    #include "esp_gatts_api.h"

  • This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

    REQUIRES bt

    or

    PRIV_REQUIRES bt

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_gatts_cb_t esp_ble_gatts_get_callback(void)

This function is called to get the current application callbacks with BTA GATTS module.

Returns

  • esp_gatts_cb_t : current callback

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. Note: the size of indicate or notify data need less than MTU size,see "esp_ble_gattc_send_mtu_req".

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

esp_err_t esp_ble_gatts_show_local_database(void)

Print local database (GATT service table)

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 conn_id

Connection id

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