GATT Client API

Application Example

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

This is a GATT client demo and its tutorial. This demo can scan for devices, connect to the GATT server and discover its services.
- bluetooth/bluedroid/ble/gatt_client
- GATT Client Example Walkthrough
This is a multiple connection demo and its tutorial. This demo can connect to multiple GATT server devices and discover their services.
- bluetooth/bluedroid/ble/gattc_multi_connect
- GATT Client Multi-connection Example Walkthrough
This is a demo similar to Bluetooth® Low Energy (Bluetooth LE) SPP. This demo, which acts as a GATT client, can receive data from UART and then send the data to the peer device automatically.
- bluetooth/bluedroid/ble/ble_spp_client

API Reference

Header File

components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
This header file can be included with:
#include "esp_gattc_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_gattc_register_callback(esp_gattc_cb_t callback)

Register GATT Client application callbacks.

Parameters

callback -- [in] The pointer to the application callback function

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_gattc_cb_t esp_ble_gattc_get_callback(void)

Get the current application callbacks.

Returns

esp_gattc_cb_t: Current callback

esp_err_t esp_ble_gattc_app_register(uint16_t app_id)

Register a GATT Client application.

Note

This function triggers ESP_GATTC_REG_EVT.
The maximum number of applications is limited to 4.

Parameters

app_id -- [in] The UUID for different application

Returns

ESP_OK: Success
ESP_ERR_INVALID_ARG: The input app_id exceeds ESP_APP_ID_MAX (0x7fff) defined in esp_bt_defs.h
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if)

Unregister a GATT Client application.

Note

This function triggers ESP_GATTC_UNREG_EVT.

Parameters

gattc_if -- [in] GATT Client access interface

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_enh_open(esp_gatt_if_t gattc_if, esp_ble_gatt_creat_conn_params_t *esp_gatt_create_conn)

Create an ACL connection.

Note

Do not enable BT_BLE_42_FEATURES_SUPPORTED and BT_BLE_50_FEATURES_SUPPORTED in the menuconfig simultaneously.

The function always triggers ESP_GATTC_CONNECT_EVT and ESP_GATTC_OPEN_EVT.
When the device acts as GATT server, besides the above two events, this function triggers ESP_GATTS_CONNECT_EVT as well.
This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

Parameters

gattc_if -- [in] GATT client access interface.
esp_gatt_create_conn -- [in] Pointer to the structure containing connection parameters.

Returns

ESP_OK: Success
others: Operation failed

esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct)

Create an ACL connection when BT_BLE_42_FEATURES_SUPPORTED is enabled in the menuconfig.

Note

The function always triggers ESP_GATTC_CONNECT_EVT and ESP_GATTC_OPEN_EVT.
When the device acts as GATT server, besides the above two events, this function triggers ESP_GATTS_CONNECT_EVT as well.
This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

Parameters

gattc_if -- [in] GATT Client access interface
remote_bda -- [in] Remote device address
remote_addr_type -- [in] Remote device address type
is_direct -- [in] True indicates a direct connection, while False indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct)

Create an ACL connection when BT_BLE_50_FEATURES_SUPPORTED is enabled in the menuconfig.

Note

The function always triggers ESP_GATTC_CONNECT_EVT and ESP_GATTC_OPEN_EVT.
When the device acts as GATT server, besides the above two events, this function triggers ESP_GATTS_CONNECT_EVT as well.
This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

Parameters

gattc_if -- [in] GATT Client access interface
remote_bda -- [in] Remote device address
remote_addr_type -- [in] Remote device address type
is_direct -- [in] True indicates a direct connection, while False indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id)

Close the virtual GATT Client connection.

Note

This function triggers ESP_GATTC_CLOSE_EVT.
There may be multiple virtual GATT server connections when multiple app_id got registered.
This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection.
The API esp_ble_gap_disconnect can be used to disconnect the physical connection directly.
If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition and triggers ESP_GATTC_DISCONNECT_EVT. Then there is no need to call esp_ble_gap_disconnect anymore.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID to be closed

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_send_mtu_req(esp_gatt_if_t gattc_if, uint16_t conn_id)

Configure the MTU size in the GATT channel.

Note

This function triggers ESP_GATTC_CFG_MTU_EVT.
You could call esp_ble_gatt_set_local_mtu to set the desired MTU size locally before this API. If not set, the GATT channel uses the default MTU size (23 bytes).

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID

Returns

ESP_OK: Success
ESP_FAIL: Failure

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

Search services from the local GATTC cache.

Note

This function triggers ESP_GATTC_SEARCH_RES_EVT each time a service is retrieved.
This function triggers ESP_GATTC_SEARCH_CMPL_EVT when the search is completed.
The 128-bit base UUID will be converted to a 16-bit UUID automatically in the search results. Other types of UUID remain unchanged.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
filter_uuid -- [in] A UUID of the intended service. If NULL is passed, this API will return all services.

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *svc_uuid, esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset)

Get the service with the given service UUID in the local GATTC cache.

Note

This API does not trigger any event.
esp_ble_gattc_cache_refresh can be used to discover services again.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
svc_uuid -- [in] The pointer to the service UUID. If NULL is passed, the API will retrieve all services.
result -- [out] The pointer to the service which has been found in the local GATTC cache
count -- [inout] The number of services to retrieve. It will be updated with the actual number of services found.
offset -- [in] The position offset to retrieve

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_char_elem_t *result, uint16_t *count, uint16_t offset)

Get all characteristics with the given handle range in the local GATTC cache.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
result -- [out] The pointer to the characteristic in the service
count -- [inout] The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.
offset -- [in] The position offset to retrieve

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT start_handle or end_handle
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t char_handle, esp_gattc_descr_elem_t *result, uint16_t *count, uint16_t offset)

Get all descriptors with the given characteristic in the local GATTC cache.

Note

This API does not trigger any event.
char_handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID which identifies the server
char_handle -- [in] The given characteristic handle
result -- [out] The pointer to the descriptor in the characteristic
count -- [inout] The number of descriptors to retrieve. It will be updated with the actual number of descriptors found.
offset -- [in] The position offset to retrieve

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT char_handle
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t char_uuid, esp_gattc_char_elem_t *result, uint16_t *count)

Get the characteristic with the given characteristic UUID in the local GATTC cache.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
char_uuid -- [in] The characteristic UUID
result -- [out] The pointer to the characteristic in the service
count -- [inout] The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT start_handle or end_handle
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t char_uuid, esp_bt_uuid_t descr_uuid, esp_gattc_descr_elem_t *result, uint16_t *count)

Get the descriptor with the given characteristic UUID in the local GATTC cache.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
char_uuid -- [in] The characteristic UUID
descr_uuid -- [in] The descriptor UUID.
result -- [out] The pointer to the descriptor in the given characteristic.
count -- [inout] The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.

Returns

ESP_OK: Success
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t char_handle, esp_bt_uuid_t descr_uuid, esp_gattc_descr_elem_t *result, uint16_t *count)

Get the descriptor with the given characteristic handle in the local GATTC cache.

Note

This API does not trigger any event.
char_handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID which identifies the server
char_handle -- [in] The characteristic handle
descr_uuid -- [in] The descriptor UUID
result -- [out] The pointer to the descriptor in the given characteristic
count -- [inout] The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT char_handle
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t *incl_uuid, esp_gattc_incl_svc_elem_t *result, uint16_t *count)

Get the included services with the given service handle in the local GATTC cache.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID which identifies the server
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
incl_uuid -- [in] The included service UUID
result -- [out] The pointer to the included service with the given service handle.
count -- [inout] The number of included services to retrieve. It will be updated with the actual number of included services found.

Returns

ESP_OK: Success
ESP_GATT_INVALID_PDU: NULL pointer to result or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_db_attr_type_t type, uint16_t start_handle, uint16_t end_handle, uint16_t char_handle, uint16_t *count)

Get the attribute count with the given service or characteristic in the local GATTC cache.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle if the type is not ESP_GATT_DB_DESCRIPTOR.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
type -- [in] The attribute type
start_handle -- [in] The attribute start handle. If the type is ESP_GATT_DB_DESCRIPTOR, this parameter will be ignored.
end_handle -- [in] The attribute end handle. If the type is ESP_GATT_DB_DESCRIPTOR, this parameter will be ignored.
char_handle -- [in] The characteristic handle. This parameter is valid only if the type is ESP_GATT_DB_DESCRIPTOR.
count -- [out] The number of attributes found in the local GATTC cache with the given attribute type

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT start_handle, end_handle
ESP_GATT_INVALID_PDU: NULL pointer to count
ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_db(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_db_elem_t *db, uint16_t *count)

Get the GATT database elements.

Note

This API does not trigger any event.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
conn_id -- [in] Connection ID
db -- [out] The pointer to GATT database elements
count -- [inout] The number of elements in the database to retrieve. It will be updated with the actual number of elements found.

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE: Invalid GATT start_handle, end_handle
ESP_GATT_INVALID_PDU: NULL pointer to db or NULL pointer to count or the count value is 0
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, esp_gatt_auth_req_t auth_req)

Read the characteristics value of the given characteristic handle.

Note

This function triggers ESP_GATTC_READ_CHAR_EVT.
This function should be called only after the connection has been established.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] Characteristic handle to read
auth_req -- [in] Authenticate request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE: Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_by_type(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t *uuid, esp_gatt_auth_req_t auth_req)

Read the characteristics value of the given characteristic UUID.

Note

This function triggers ESP_GATTC_READ_CHAR_EVT.
This function should be called only after the connection has been established.
start_handle must be greater than 0, and smaller than end_handle.

Parameters

gattc_if -- [in] GATT Client access interface.
conn_id -- [in] Connection ID
start_handle -- [in] The attribute start handle
end_handle -- [in] The attribute end handle
uuid -- [in] The pointer to UUID of attribute to read
auth_req -- [in] Authenticate request type

Returns

ESP_OK: Success
ESP_GATT_ILLEGAL_PARAMETER: NULL pointer to uuid
ESP_ERR_INVALID_STATE: The connection has not been established
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req)

Read multiple characteristic or descriptor values.

Note

This function triggers ESP_GATTC_READ_MULTIPLE_EVT.
This function should be called only after the connection has been established.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID which specifies the server
read_multi -- [in] Pointer to esp_gattc_multi_t
auth_req -- [in] Authenticate request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_multiple_variable(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req)

Read multiple variable length characteristic values.

Note

This function triggers ESP_GATTC_READ_MULTI_VAR_EVT.
This function should be called only after the connection has been established.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
read_multi -- [in] The pointer to the esp_gattc_multi_t
auth_req -- [in] Authenticate request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, esp_gatt_auth_req_t auth_req)

Read a characteristics descriptor.

Note

This function triggers ESP_GATTC_READ_DESCR_EVT.
This function should be called only after the connection has been established.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] Descriptor handle to read
auth_req -- [in] Authenticate request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_write_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

Write the characteristic value of a given characteristic handle.

Note

This function triggers ESP_GATTC_WRITE_CHAR_EVT.
This function should be called only after the connection has been established.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] The characteristic handle to write
value_len -- [in] The length of the value to write in bytes
value -- [in] The value to write
write_type -- [in] The type of Attribute write operation
auth_req -- [in] Authentication request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

Write Characteristic descriptor value of a given descriptor handle.

Note

This function triggers ESP_GATTC_WRITE_DESCR_EVT.
This function should be called only after the connection has been established.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] The descriptor handle to write.
value_len -- [in] The length of the value to write in bytes.
value -- [in] The value to write
write_type -- [in] The type of Attribute write operation
auth_req -- [in] Authentication request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req)

Prepare to write a characteristic value which is longer than the MTU size to a specified characteristic handle.

Note

This function should be called only after the connection has been established.
After using this API, use esp_ble_gattc_execute_write to write.
This function triggers ESP_GATTC_PREP_WRITE_EVT.
If value_len is less than or equal to MTU size, it is recommended to esp_ble_gattc_write_char to write directly.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] Characteristic handle to prepare to write
offset -- [in] The position offset to write
value_len -- [in] The length of the value to write in bytes
value -- [in] The value to write
auth_req -- [in] Authentication request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req)

Prepare to write a characteristic descriptor value at a given handle.

Note

This function triggers ESP_GATTC_WRITE_CHAR_EVT.
This function should be called only after the connection has been established.
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
handle -- [in] Characteristic descriptor handle to prepare to write
offset -- [in] The position offset to write
value_len -- [in] The length of the value to write in bytes
value -- [in] The value to write
auth_req -- [in] Authentication request type

Returns

ESP_OK: Success
ESP_ERR_INVALID_STATE: The connection has not been established.
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

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

Execute a prepared writing sequence.

Note

This function triggers ESP_GATTC_EXEC_EVT.

Parameters

gattc_if -- [in] GATT Client access interface
conn_id -- [in] Connection ID
is_execute -- [in] True if it is to execute the writing sequence; false if it is to cancel the writing sequence.

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_register_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle)

Register to receive notification/indication of a characteristic.

Note

This function triggers ESP_GATTC_REG_FOR_NOTIFY_EVT.
You should call esp_ble_gattc_write_char_descr() after this API to write Client Characteristic Configuration (CCC) descriptor to the value of 1 (Enable Notification) or 2 (Enable Indication).
handle must be greater than 0.

Parameters

gattc_if -- [in] GATT Client access interface
server_bda -- [in] Target GATT server device address
handle -- [in] Target GATT characteristic handle

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_unregister_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle)

Unregister the notification of a service.

Note

This function triggers ESP_GATTC_UNREG_FOR_NOTIFY_EVT.
You should call esp_ble_gattc_write_char_descr() after this API to write Client Characteristic Configuration (CCC) descriptor value to 0.
handle must be greater than 0

Parameters

gattc_if -- [in] GATT Client access interface
server_bda -- [in] Target GATT server device address
handle -- [in] Target GATT characteristic handle

Returns

ESP_OK: Success
ESP_GATT_INVALID_HANDLE：Invalid handle
ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda)

Refresh the cache of the remote device.

Note

If the device is connected, this API will restart the discovery of service information of the remote device.
This function triggers ESP_GATTC_DIS_SRVC_CMPL_EVT only after the ACL connection is established. Otherwise, no events will be triggered.

Parameters

remote_bda -- [in] Remote device address

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, esp_bd_addr_t assoc_addr, bool is_assoc)

Add or remove the association between the address in the local GATTC cache with the source address of the remote device.

Note

This API is primarily used when the client has a stored server-side database (assoc_addr) and needs to connect to another device (src_addr) with the same attribute database. By invoking this API, the stored database is utilized as the peer server database, eliminating the need for attribute database search and discovery. This reduces processing time and accelerates the connection process.
The attribute table of a device with assoc_addr must be stored in the local GATTC cache first. Then, the attribute table of the device with src_addr must be the same as the one with assoc_addr.
This function triggers ESP_GATTC_SET_ASSOC_EVT.

Parameters

gattc_if -- [in] GATT Client access interface
src_addr -- [in] The source address intended to be associated to the assoc_addr which has been stored in the local GATTC cache
assoc_addr -- [in] The associated device address intended to share the attribute table with the source address
is_assoc -- [in] True if adding the association; false if removing the association.

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if)

Get the address list stored in the local GATTC cache.

Note

This function triggers ESP_GATTC_GET_ADDR_LIST_EVT.

Parameters

gattc_if -- [in] GATT Client access interface

Returns

ESP_OK: Success
ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda)

Clean the service cache of the target device in the local GATTC cache.

Parameters

remote_bda -- [in] Remote device address

Returns

ESP_OK: Success
ESP_FAIL: Failure

Unions

union esp_ble_gattc_cb_param_t

#include <esp_gattc_api.h>

GATT Client callback parameters.

Public Members

struct esp_ble_gattc_cb_param_t::gattc_reg_evt_param reg: Callback parameter for the event ESP_GATTC_REG_EVT

struct esp_ble_gattc_cb_param_t::gattc_open_evt_param open: Callback parameter for the event ESP_GATTC_OPEN_EVT

struct esp_ble_gattc_cb_param_t::gattc_close_evt_param close: Callback parameter for the event ESP_GATTC_CLOSE_EVT

struct esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param cfg_mtu: Callback parameter for the event ESP_GATTC_CFG_MTU_EVT

struct esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param search_cmpl: Callback parameter for the event ESP_GATTC_SEARCH_CMPL_EVT

struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param search_res: Callback parameter for the event ESP_GATTC_SEARCH_RES_EVT

struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param read: Callback parameter for events: ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT, ESP_GATTC_READ_MULTIPLE_EVT, ESP_GATTC_READ_MULTI_VAR_EVT

struct esp_ble_gattc_cb_param_t::gattc_write_evt_param write: Callback parameter for the events: ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT

struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param exec_cmpl: Callback parameter for the event ESP_GATTC_EXEC_EVT

struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param notify: Callback parameter for the event ESP_GATTC_NOTIFY_EVT

struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param srvc_chg: Callback parameter for the event ESP_GATTC_SRVC_CHG_EVT

struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param congest: Callback parameter for the event ESP_GATTC_CONGEST_EVT

struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param reg_for_notify: Callback parameter for the event ESP_GATTC_REG_FOR_NOTIFY_EVT

struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param unreg_for_notify: Callback parameter for the event ESP_GATTC_UNREG_FOR_NOTIFY_EVT

struct esp_ble_gattc_cb_param_t::gattc_connect_evt_param connect: Callback parameter for the event ESP_GATTC_CONNECT_EVT

struct esp_ble_gattc_cb_param_t::gattc_disconnect_evt_param disconnect: Callback parameter for the event ESP_GATTC_DISCONNECT_EVT

struct esp_ble_gattc_cb_param_t::gattc_set_assoc_addr_cmp_evt_param set_assoc_cmp: Callback parameter for the event ESP_GATTC_SET_ASSOC_EVT

struct esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt_param get_addr_list: Callback parameter for the event ESP_GATTC_GET_ADDR_LIST_EVT

struct esp_ble_gattc_cb_param_t::gattc_queue_full_evt_param queue_full: Callback parameter for the event ESP_GATTC_QUEUE_FULL_EVT

struct esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt_param dis_srvc_cmpl: Callback parameter for the event ESP_GATTC_DIS_SRVC_CMPL_EVT

struct gattc_cfg_mtu_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event 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 gattc_close_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event 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 gattc_congest_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_CONGEST_EVT

Public Members

uint16_t conn_id: Connection ID

bool congested: True indicates that the connection is congested, false otherwise

struct gattc_connect_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_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 device address

esp_gatt_conn_params_t conn_params: Current connection parameters

esp_ble_addr_type_t ble_addr_type: Remote device address type

uint16_t conn_handle: HCI connection handle

struct gattc_dis_srvc_cmpl_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_DIS_SRVC_CMPL_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t conn_id: Connection ID

struct gattc_disconnect_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_DISCONNECT_EVT

Public Members

esp_gatt_conn_reason_t reason: Disconnection reason

uint16_t conn_id: Connection ID

esp_bd_addr_t remote_bda: Remote device address

struct gattc_exec_cmpl_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_EXEC_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t conn_id: Connection ID

struct gattc_get_addr_list_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_GET_ADDR_LIST_EVT

Public Members

esp_gatt_status_t status: Operation status

uint8_t num_addr: The number of addresses in the local GATTC cache address list

esp_bd_addr_t *addr_list: The pointer to the address list which has been retrieved from the local GATTC cache

struct gattc_notify_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_NOTIFY_EVT

Public Members

uint16_t conn_id: Connection ID

esp_bd_addr_t remote_bda: Remote Bluetooth device address.

uint16_t handle: The characteristic or descriptor handle

uint16_t value_len: Notify attribute value length in bytes

uint8_t *value: Notify attribute value

bool is_notify: True means notification; false means indication

struct gattc_open_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event 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 gattc_queue_full_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_QUEUE_FULL_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t conn_id: Connection ID

bool is_full: True indicates the GATTC command queue is full; false otherwise.

struct gattc_read_char_evt_param

#include <esp_gattc_api.h>

Callback parameter for the events: ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT, ESP_GATTC_READ_MULTIPLE_EVT, ESP_GATTC_READ_MULTI_VAR_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t conn_id: Connection ID

uint16_t handle: Characteristic handle

uint8_t *value: Characteristic value

uint16_t value_len: Characteristic value length

struct gattc_reg_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_REG_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t app_id: Application ID

struct gattc_reg_for_notify_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_REG_FOR_NOTIFY_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t handle: The characteristic or descriptor handle

struct gattc_search_cmpl_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_SEARCH_CMPL_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t conn_id: Connection ID

esp_service_source_t searched_service_source: The source of the service information

struct gattc_search_res_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_SEARCH_RES_EVT

Public Members

uint16_t conn_id: Connection ID

uint16_t start_handle: Service start handle

uint16_t end_handle: Service end handle

esp_gatt_id_t srvc_id: Service ID, including service UUID and other information

bool is_primary: True indicates a primary service, false otherwise

struct gattc_set_assoc_addr_cmp_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_SET_ASSOC_EVT

Public Members

esp_gatt_status_t status: Operation status

struct gattc_srvc_chg_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_SRVC_CHG_EVT

Public Members

esp_bd_addr_t remote_bda: Remote Bluetooth device address

struct gattc_unreg_for_notify_evt_param

#include <esp_gattc_api.h>

Callback parameter for the event ESP_GATTC_UNREG_FOR_NOTIFY_EVT

Public Members

esp_gatt_status_t status: Operation status

uint16_t handle: The characteristic or descriptor handle

struct gattc_write_evt_param

#include <esp_gattc_api.h>

Callback parameter for the events: 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

uint16_t handle: The characteristic or descriptor handle

uint16_t offset: The position offset to write. This value is valid only for prepare write operation.

Type Definitions

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.

Param event: [in] Event type
Param gattc_if: [in] GATT Client access interface
Param param: [in] The pointer to callback parameter

Enumerations

enum esp_gattc_cb_event_t

GATT Client callback function events.

Values:

enumerator ESP_GATTC_REG_EVT: This event is triggered when a GATT Client application is registered using esp_ble_gattc_app_register.

enumerator ESP_GATTC_UNREG_EVT: This event is triggered when a GATT Client application is unregistered using esp_ble_gattc_app_unregister.

enumerator ESP_GATTC_OPEN_EVT: This event is triggered when a GATT virtual connection is set up using esp_ble_gattc_open.

enumerator ESP_GATTC_READ_CHAR_EVT: This event is triggered upon the completion of a GATT characteristic read operation using esp_ble_gattc_read_char.

enumerator ESP_GATTC_WRITE_CHAR_EVT: This event is triggered upon the completion of a GATT characteristic write operation using esp_ble_gattc_write_char.

enumerator ESP_GATTC_CLOSE_EVT: This event is triggered when a GATT virtual connection is closed via esp_ble_gattc_close, or when the physical connection is terminated.

enumerator ESP_GATTC_SEARCH_CMPL_EVT: This event is triggered upon the completion of a service discovery using esp_ble_gattc_search_service.

enumerator ESP_GATTC_SEARCH_RES_EVT: This event is triggered each time a service result is obtained using esp_ble_gattc_search_service.

enumerator ESP_GATTC_READ_DESCR_EVT: This event is triggered upon the completion of a GATT characteristic descriptor read operation using esp_ble_gattc_read_char_descr.

enumerator ESP_GATTC_WRITE_DESCR_EVT: This event is triggered upon the completion of a GATT characteristic descriptor write operation using esp_ble_gattc_write_char_descr.

enumerator ESP_GATTC_NOTIFY_EVT: This event is triggered when a GATT notification or indication is received from the Server.

enumerator ESP_GATTC_PREP_WRITE_EVT: This event is triggered upon the completion of a GATT prepare-write operation using esp_ble_gattc_prepare_write.

enumerator ESP_GATTC_EXEC_EVT: This event is triggered upon the completion of a GATT write execution using esp_ble_gattc_execute_write .

enumerator ESP_GATTC_ACL_EVT: Deprecated.

enumerator ESP_GATTC_CANCEL_OPEN_EVT: Deprecated.

enumerator ESP_GATTC_SRVC_CHG_EVT: This event is triggered when a service changed indication is received from the Server, indicating that the attribute database on the Server has been modified (e.g., services have been added, removed).

enumerator ESP_GATTC_ENC_CMPL_CB_EVT: Deprecated.

enumerator ESP_GATTC_CFG_MTU_EVT: This event is triggered upon the completion of the MTU configuration with esp_ble_gattc_send_mtu_req.

enumerator ESP_GATTC_ADV_DATA_EVT: Deprecated.

enumerator ESP_GATTC_MULT_ADV_ENB_EVT: Deprecated.

enumerator ESP_GATTC_MULT_ADV_UPD_EVT: Deprecated.

enumerator ESP_GATTC_MULT_ADV_DATA_EVT: Deprecated.

enumerator ESP_GATTC_MULT_ADV_DIS_EVT: Deprecated.

enumerator ESP_GATTC_CONGEST_EVT: This event is triggered when the GATT connection is congested.

enumerator ESP_GATTC_BTH_SCAN_ENB_EVT: Deprecated.

enumerator ESP_GATTC_BTH_SCAN_CFG_EVT: Deprecated.

enumerator ESP_GATTC_BTH_SCAN_RD_EVT: Deprecated.

enumerator ESP_GATTC_BTH_SCAN_THR_EVT: Deprecated.

enumerator ESP_GATTC_BTH_SCAN_PARAM_EVT: Deprecated.

enumerator ESP_GATTC_BTH_SCAN_DIS_EVT: Deprecated.

enumerator ESP_GATTC_SCAN_FLT_CFG_EVT: Deprecated.

enumerator ESP_GATTC_SCAN_FLT_PARAM_EVT: Deprecated.

enumerator ESP_GATTC_SCAN_FLT_STATUS_EVT: Deprecated.

enumerator ESP_GATTC_ADV_VSC_EVT: Deprecated.

enumerator ESP_GATTC_REG_FOR_NOTIFY_EVT: This event is triggered upon the completion of a service notification registration using esp_ble_gattc_register_for_notify.

enumerator ESP_GATTC_UNREG_FOR_NOTIFY_EVT: This event is triggered upon the completion of a service notification unregistration using esp_ble_gattc_unregister_for_notify.

enumerator ESP_GATTC_CONNECT_EVT: This event is triggered when the physical connection is set up.

enumerator ESP_GATTC_DISCONNECT_EVT: This event is triggered when the physical connection is terminated.

enumerator ESP_GATTC_READ_MULTIPLE_EVT: This event is triggered when the multiple characteristic or descriptor values are retrieved using esp_ble_gattc_read_multiple.

enumerator ESP_GATTC_QUEUE_FULL_EVT: This event is triggered when the GATTC command queue is full.

enumerator ESP_GATTC_SET_ASSOC_EVT: This event is triggered when the association between the source and the remote address is added or deleted using esp_ble_gattc_cache_assoc.

enumerator ESP_GATTC_GET_ADDR_LIST_EVT: This event is triggered when retrieving the address list from the GATTC cache is completed using esp_ble_gattc_cache_get_addr_list.

enumerator ESP_GATTC_DIS_SRVC_CMPL_EVT: This event is triggered when the GATT service discovery is completed.

enumerator ESP_GATTC_READ_MULTI_VAR_EVT: This event is triggered when multiple variable length characteristic values are retrieved using esp_ble_gattc_read_multiple.

Provide feedback about this document