GATT CLIENT API¶
应用程序示例¶
请检查 ESP-IDF 示例中的 bluetooth 文件夹,它包含如下示例:
这是一个 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 typegatts_if
: : GATT client access interface, normally different gattc_if correspond to different profileparam
: : 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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
struct
esp_ble_gattc_cb_param_t::
gattc_search_cmpl_evt_param
¶ ESP_GATTC_SEARCH_CMPL_EVT.
-
struct
esp_ble_gattc_cb_param_t::
gattc_search_res_evt_param
¶ ESP_GATTC_SEARCH_RES_EVT.
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
struct
esp_ble_gattc_cb_param_t::
gattc_exec_cmpl_evt_param
¶ ESP_GATTC_EXEC_EVT.
-
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
-
uint16_t
-
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
-
esp_bd_addr_t
-
struct
esp_ble_gattc_cb_param_t::
gattc_congest_evt_param
¶ ESP_GATTC_CONGEST_EVT.
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
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
-
esp_gatt_status_t
-
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_gatt_status_t
函数¶
-
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 IDstart_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 IDsrvc_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.