GATT 服务器 API
应用示例
以下示例及其教程存放在 ESP-IDF 示例的 bluetooth/bluedroid/ble 目录下：
- 以下为 GATT 服务器示例及其教程，该示例创建了一个带有属性表的 GATT 服务器，无需逐个添加属性。建议通过以下方式添加属性（官方推荐）。
* [bluetooth/bluedroid/ble/gatt_server_service_table](https://github.com/espressif/esp-idf/tree/v5.2.1/examples/bluetooth/bluedroid/ble/gatt_server_service_table) * [GATT 服务器服务表示例 ](https://github.com/espressif/esp-idf/blob/v5.2.1/examples/bluetooth/bluedroid/ble/gatt_server_service_table/tutorial/Gatt_Server_Service_Table_Example_Walkthrough.md)
- 以下为 GATT 服务器示例及其教程，该示例逐个添加 Bluedroid 定义的属性，创建 GATT 服务。建议通过以下方式添加属性。
* [bluetooth/bluedroid/ble/gatt_server](https://github.com/espressif/esp-idf/tree/v5.2.1/examples/bluetooth/bluedroid/ble/gatt_server) * [GATT 服务器示例 ](https://github.com/espressif/esp-idf/blob/v5.2.1/examples/bluetooth/bluedroid/ble/gatt_server/tutorial/Gatt_Server_Example_Walkthrough.md)
- 以下示例与低功耗蓝牙 (Bluetooth® LE) SPP 类似。在该示例中，GATT 服务器可以接收来自 UART 的数据，并将数据自动发送到对端设备。
* [bluetooth/bluedroid/ble/ble_spp_server](https://github.com/espressif/esp-idf/tree/v5.2.1/examples/bluetooth/bluedroid/ble/ble_spp_server)
API 参考
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
btcomponent. To declare that your component depends onbt, add the following to your CMakeLists.txt:
REQUIRES btor
> 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.
返回
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.
返回
- 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.
返回
ESP_OK : success
other : failed
esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if)
unregister with GATT Server.
参数
gatts_if -- [in] GATT server access interface
返回
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.
参数
gatts_if -- [in] GATT server access interface
service_id -- [in] service ID.
num_handle -- [in] number of handle requested for this service.
返回
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.
参数
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
返回
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.
参数
service_handle -- [in] service handle to which this included service is to be added.
included_service_handle -- [in] the service ID to be included.
返回
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.
参数
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
返回
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.
参数
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
返回
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.
参数
service_handle -- [in] service_handle to be deleted.
返回
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.
参数
service_handle -- [in] the service handle to be started.
返回
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.
参数
service_handle -- [in] - service to be topped.
返回
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".
参数
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.
返回
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.
参数
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.
返回
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.
参数
attr_handle -- [in] the attribute handle which to be set
length -- [in] the value length
value -- [in] the pointer to the attribute value
返回
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.
参数
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
返回
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.
参数
gatts_if -- [in] GATT server access interface
remote_bda -- [in] remote device bluetooth device address.
is_direct -- [in] direct connection or background auto connection
返回
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.
参数
gatts_if -- [in] GATT server access interface
conn_id -- [in] connection ID to be closed.
返回
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.
参数
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
返回
ESP_OK : success
other : failed
esp_err_t esp_ble_gatts_show_local_database(void)
Print local database (GATT service table)
返回
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