GATT CLIENT API

应用程序示例

请检查 ESP-IDF 示例中的 bluetooth 文件夹，它包含如下示例：

bluetooth/gatt_client

这是一个 GATT 客户端 demo。这个 demo 可以扫描设备、连接到 GATT 服务端以及发下服务。

API 参考手册

宏

ESP_GATT_DEF_BLE_MTU_SIZE

Maximum Transmission Unit used in GATT.

ESP_GATT_MAX_MTU_SIZE

Maximum Transmission Unit allowed in GATT.

类型定义

typedef void (*esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param)

GATT Client callback function type.

Parameters
  • event: : Event type
  • gatts_if: : GATT client access interface, normally different gattc_if correspond to different profile
  • param: : Point to callback parameter, currently is union type

枚举

enum esp_gattc_cb_event_t

GATT Client callback function events.

Values:

ESP_GATTC_REG_EVT = 0

When GATT client is registered, the event comes

ESP_GATTC_UNREG_EVT = 1

When GATT client is unregistered, the event comes

ESP_GATTC_OPEN_EVT = 2

When GATT connection is set up, the event comes

ESP_GATTC_READ_CHAR_EVT = 3

When GATT characteristic is read, the event comes

ESP_GATTC_WRITE_CHAR_EVT = 4

When GATT characteristic write operation completes, the event comes

ESP_GATTC_CLOSE_EVT = 5

When GATT connection is closed, the event comes

ESP_GATTC_SEARCH_CMPL_EVT = 6

When GATT service discovery is completed, the event comes

ESP_GATTC_SEARCH_RES_EVT = 7

When GATT service discovery result is got, the event comes

ESP_GATTC_READ_DESCR_EVT = 8

When GATT characteristic descriptor read completes, the event comes

ESP_GATTC_WRITE_DESCR_EVT = 9

When GATT characteristic descriptor write completes, the event comes

ESP_GATTC_NOTIFY_EVT = 10

When GATT notification or indication arrives, the event comes

ESP_GATTC_PREP_WRITE_EVT = 11

When GATT prepare-write operation completes, the event comes

ESP_GATTC_EXEC_EVT = 12

When write execution completes, the event comes

ESP_GATTC_ACL_EVT = 13

When ACL connection is up, the event comes

ESP_GATTC_CANCEL_OPEN_EVT = 14

When GATT client ongoing connection is cancelled, the event comes

ESP_GATTC_SRVC_CHG_EVT = 15

When “service changed” occurs, the event comes

ESP_GATTC_ENC_CMPL_CB_EVT = 17

When encryption procedure completes, the event comes

ESP_GATTC_CFG_MTU_EVT = 18

When configuration of MTU completes, the event comes

ESP_GATTC_ADV_DATA_EVT = 19

When advertising of data, the event comes

ESP_GATTC_MULT_ADV_ENB_EVT = 20

When multi-advertising is enabled, the event comes

ESP_GATTC_MULT_ADV_UPD_EVT = 21

When multi-advertising parameters are updated, the event comes

ESP_GATTC_MULT_ADV_DATA_EVT = 22

When multi-advertising data arrives, the event comes

ESP_GATTC_MULT_ADV_DIS_EVT = 23

When multi-advertising is disabled, the event comes

ESP_GATTC_CONGEST_EVT = 24

When GATT connection congestion comes, the event comes

ESP_GATTC_BTH_SCAN_ENB_EVT = 25

When batch scan is enabled, the event comes

ESP_GATTC_BTH_SCAN_CFG_EVT = 26

When batch scan storage is configured, the event comes

ESP_GATTC_BTH_SCAN_RD_EVT = 27

When Batch scan read event is reported, the event comes

ESP_GATTC_BTH_SCAN_THR_EVT = 28

When Batch scan threshold is set, the event comes

ESP_GATTC_BTH_SCAN_PARAM_EVT = 29

When Batch scan parameters are set, the event comes

ESP_GATTC_BTH_SCAN_DIS_EVT = 30

When Batch scan is disabled, the event comes

ESP_GATTC_SCAN_FLT_CFG_EVT = 31

When Scan filter configuration completes, the event comes

ESP_GATTC_SCAN_FLT_PARAM_EVT = 32

When Scan filter parameters are set, the event comes

ESP_GATTC_SCAN_FLT_STATUS_EVT = 33

When Scan filter status is reported, the event comes

ESP_GATTC_ADV_VSC_EVT = 34

When advertising vendor spec content event is reported, the event comes

ESP_GATTC_GET_CHAR_EVT = 35

When characteristic is got from GATT server, the event comes

ESP_GATTC_GET_DESCR_EVT = 36

When characteristic descriptor is got from GATT server, the event comes

ESP_GATTC_GET_INCL_SRVC_EVT = 37

When included service is got from GATT server, the event comes

ESP_GATTC_REG_FOR_NOTIFY_EVT = 38

When register for notification of a service completes, the event comes

ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39

When unregister for notification of a service completes, the event comes

结构体

警告

doxygenstruct: Cannot find class “esp_ble_gattc_cb_param_t” in doxygen xml output for project “esp32-idf” from directory: xml/

struct esp_ble_gattc_cb_param_t::gattc_reg_evt_param

ESP_GATTC_REG_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t app_id

Application id which input in register API

struct esp_ble_gattc_cb_param_t::gattc_open_evt_param

ESP_GATTC_OPEN_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_bd_addr_t remote_bda

Remote bluetooth device address

uint16_t mtu

MTU size

struct esp_ble_gattc_cb_param_t::gattc_close_evt_param

ESP_GATTC_CLOSE_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_bd_addr_t remote_bda

Remote bluetooth device address

esp_gatt_conn_reason_t reason

The reason of gatt connection close

struct esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param

ESP_GATTC_CFG_MTU_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

uint16_t mtu

MTU size

struct esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param

ESP_GATTC_SEARCH_CMPL_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param

ESP_GATTC_SEARCH_RES_EVT.

Public Members

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param

ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

esp_gatt_id_t descr_id

Descriptor id, include descriptor uuid and other information

uint8_t *value

Characteristic value

uint16_t value_type

Characteristic value type

uint16_t value_len

Characteristic value length

struct esp_ble_gattc_cb_param_t::gattc_write_evt_param

ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

esp_gatt_id_t descr_id

Descriptor id, include descriptor uuid and other information

struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param

ESP_GATTC_EXEC_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param

ESP_GATTC_NOTIFY_EVT.

Public Members

uint16_t conn_id

Connection id

esp_bd_addr_t remote_bda

Remote bluetooth device address

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

esp_gatt_id_t descr_id

Descriptor id, include descriptor uuid and other information

uint16_t value_len

Notify attribute value

uint8_t *value

Notify attribute value

bool is_notify

True means notify, false means indicate

struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param

ESP_GATTC_SRVC_CHG_EVT.

Public Members

esp_bd_addr_t remote_bda

Remote bluetooth device address

struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param

ESP_GATTC_CONGEST_EVT.

Public Members

uint16_t conn_id

Connection id

bool congested

Congested or not

struct esp_ble_gattc_cb_param_t::gattc_get_char_evt_param

ESP_GATTC_GET_CHAR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

esp_gatt_char_prop_t char_prop

Characteristic property

struct esp_ble_gattc_cb_param_t::gattc_get_descr_evt_param

ESP_GATTC_GET_DESCR_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

esp_gatt_id_t descr_id

Descriptor id, include descriptor uuid and other information

struct esp_ble_gattc_cb_param_t::gattc_get_incl_srvc_evt_param

ESP_GATTC_GET_INCL_SRVC_EVT.

Public Members

esp_gatt_status_t status

Operation status

uint16_t conn_id

Connection id

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_srvc_id_t incl_srvc_id

Included service id, include service uuid and other information

struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param

ESP_GATTC_REG_FOR_NOTIFY_EVT.

Public Members

esp_gatt_status_t status

Operation status

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param

ESP_GATTC_UNREG_FOR_NOTIFY_EVT.

Public Members

esp_gatt_status_t status

Operation status

esp_gatt_srvc_id_t srvc_id

Service id, include service uuid and other information

esp_gatt_id_t char_id

Characteristic id, include characteristic uuid and other information

函数

esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback)

This function is called to register application callbacks with GATTC module.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • callback: : pointer to the application callback function.

esp_err_t esp_ble_gattc_app_register(uint16_t app_id)

This function is called to register application callbacks with GATTC module.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • app_id: : Application Identify (UUID), for different application

esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if)

This function is called to unregister an application from GATTC module.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.

esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, bool is_direct)

Open a direct connection or add a background auto connection.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • remote_bda: remote device bluetooth device address.
  • is_direct: direct connection or background auto connection

esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id)

Close a connection to a GATT server.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID to be closed.

esp_err_t esp_ble_gattc_config_mtu(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t mtu)

Configure the MTU size in the GATT channel. This can be done only once per connection.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID.
  • mtu: desired MTU size to use.

esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid)

This function is called to request a GATT service discovery on a GATT server. This function report service search result by a callback event, and followed by a service search complete event.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID.
  • filter_uuid: a UUID of the service application is interested in. If Null, discover for all services.

esp_err_t esp_ble_gattc_get_characteristic(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *start_char_id)

This function is called to find the first characteristic of the service on the given server.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID which identify the server.
  • srvc_id: service ID
  • start_char_id: the start characteristic ID

esp_err_t esp_ble_gattc_get_descriptor(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_id_t *start_descr_id)

This function is called to find the descriptor of the service on the given server.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID which identify the server.
  • srvc_id: the service ID of which the characteristic is belonged to.
  • char_id: Characteristic ID, if NULL find the first available characteristic.
  • start_descr_id: the start descriptor id

esp_err_t esp_ble_gattc_get_included_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_srvc_id_t *start_incl_srvc_id)

This function is called to find the first characteristic of the service on the given server.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: connection ID which identify the server.
  • srvc_id: the service ID of which the characteristic is belonged to.
  • start_incl_srvc_id: the start include service id

esp_err_t esp_ble_gattc_read_char(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_auth_req_t auth_req)

This function is called to read a service’s characteristics of the given characteristic ID.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID.
  • srvc_id: : service ID.
  • char_id: : characteristic ID to read.
  • auth_req: : authenticate request type

esp_err_t esp_ble_gattc_read_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_id_t *descr_id, esp_gatt_auth_req_t auth_req)

This function is called to read a characteristics descriptor.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID.
  • srvc_id: : service ID.
  • char_id: : characteristic ID to read.
  • descr_id: : characteristic descriptor ID to read.
  • auth_req: : authenticate request type

esp_err_t esp_ble_gattc_write_char(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

This function is called to write characteristic value.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID.
  • srvc_id: : service ID.
  • char_id: : characteristic ID to write.
  • value_len: length of the value to be written.
  • value: : the value to be written.
  • write_type: : the type of attribute write operation.
  • auth_req: : authentication request.

esp_err_t esp_ble_gattc_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_id_t *descr_id, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

This function is called to write characteristic descriptor value.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID
  • srvc_id: : service ID.
  • char_id: : characteristic ID.
  • descr_id: : characteristic descriptor ID to write.
  • value_len: length of the value to be written.
  • value: : the value to be written.
  • write_type: : the type of attribute write operation.
  • auth_req: : authentication request.

esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req)

This function is called to prepare write a characteristic value.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID.
  • srvc_id: : service ID.
  • char_id: : GATT characteristic ID of the service.
  • offset: : offset of the write value.
  • value_len: length of the value to be written.
  • value: : the value to be written.
  • auth_req: : authentication request.

esp_err_t esp_ble_gattc_execute_write(esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute)

This function is called to execute write a prepare write sequence.

Return
  • ESP_OK: success
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • conn_id: : connection ID.
  • is_execute: : execute or cancel.

esp_gatt_status_t esp_ble_gattc_register_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id)

This function is called to register for notification of a service.

Return
  • ESP_OK: registration succeeds
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • server_bda: : target GATT server.
  • srvc_id: : pointer to GATT service ID.
  • char_id: : pointer to GATT characteristic ID.

esp_gatt_status_t esp_ble_gattc_unregister_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id)

This function is called to de-register for notification of a service.

Return
  • ESP_OK: unregister succeeds
  • other: failed
Parameters
  • gattc_if: Gatt client access interface.
  • server_bda: : target GATT server.
  • srvc_id: : pointer to GATT service ID.
  • char_id: : pointer to GATT characteristic ID.