GATT Defines

API Reference

Header File

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

  • This header file can be included with:

    #include "esp_gatt_defs.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

Unions

union esp_gatt_rsp_t
#include <esp_gatt_defs.h>

Represents the response type for a GATT remote read request.

Public Members

esp_gatt_value_t attr_value

The GATT attribute value, including its data, handle, and metadata.

uint16_t handle

Only the handle of the GATT attribute, when that's the only required information.

Structures

struct esp_gatt_id_t

Represents a GATT identifier.

Public Members

esp_bt_uuid_t uuid

The UUID component of the GATT ID.

uint8_t inst_id

The instance ID component of the GATT ID, providing further differentiation of the GATT ID.

struct esp_gatt_srvc_id_t

Represents a GATT service identifier.

Public Members

esp_gatt_id_t id

Encapsulates the UUID and instance ID of the GATT service.

bool is_primary

Indicates if the service is primary. A value of true means it is a primary service, false indicates a secondary service.

struct esp_attr_desc_t

Defines an attribute's description.

This structure is used to describe an attribute in the GATT database. It includes details such as the UUID of the attribute, its permissions, and its value.

Public Members

uint16_t uuid_length

Length of the UUID in bytes.

uint8_t *uuid_p

Pointer to the UUID value.

uint16_t perm

Attribute permissions, defined by esp_gatt_perm_t.

uint16_t max_length

Maximum length of the attribute's value.

uint16_t length

Current length of the attribute's value.

uint8_t *value

Pointer to the attribute's value array.

struct esp_attr_control_t

Defines the auto response setting for attribute operations.

This structure is used to control whether the GATT stack or the application will handle responses to Read/Write operations.

Public Members

uint8_t auto_rsp

Controls who handles the response to Read/Write operations.

  • If set to ESP_GATT_RSP_BY_APP, the application is responsible for generating the response.

  • If set to ESP_GATT_AUTO_RSP, the GATT stack will automatically generate the response.

struct esp_gatts_attr_db_t

attribute type added to the GATT server database

Public Members

esp_attr_control_t attr_control

The attribute control type

esp_attr_desc_t att_desc

The attribute type

struct esp_attr_value_t

set the attribute value type

Public Members

uint16_t attr_max_len

attribute max value length

uint16_t attr_len

attribute current value length

uint8_t *attr_value

the pointer to attribute value

struct esp_gatts_incl_svc_desc_t

Gatt include service entry element.

Public Members

uint16_t start_hdl

Gatt start handle value of included service

uint16_t end_hdl

Gatt end handle value of included service

uint16_t uuid

Gatt attribute value UUID of included service

struct esp_gatts_incl128_svc_desc_t

Gatt include 128 bit service entry element.

Public Members

uint16_t start_hdl

Gatt start handle value of included 128 bit service

uint16_t end_hdl

Gatt end handle value of included 128 bit service

struct esp_gatt_value_t

Represents a GATT attribute's value.

Public Members

uint8_t value[ESP_GATT_MAX_ATTR_LEN]

Array holding the value of the GATT attribute.

uint16_t handle

Unique identifier (handle) of the GATT attribute.

uint16_t offset

Offset within the attribute's value, for partial updates.

uint16_t len

Current length of the data in the value array.

uint8_t auth_req

Authentication requirements for accessing this attribute.

struct esp_gatt_conn_params_t

Connection parameters for GATT.

Public Members

uint16_t interval

Connection interval.

uint16_t latency

Slave latency for the connection in number of connection events.

uint16_t timeout

Supervision timeout for the LE Link.

struct esp_gattc_multi_t

Represents multiple attributes for reading.

Public Members

uint8_t num_attr

Number of attributes.

uint16_t handles[ESP_GATT_MAX_READ_MULTI_HANDLES]

List of attribute handles.

struct esp_gattc_db_elem_t

GATT database attribute element.

Public Members

esp_gatt_db_attr_type_t type

Attribute type.

uint16_t attribute_handle

Attribute handle.

uint16_t start_handle

Service start handle.

uint16_t end_handle

Service end handle.

esp_gatt_char_prop_t properties

Characteristic properties.

esp_bt_uuid_t uuid

Attribute UUID.

struct esp_gattc_service_elem_t

Represents a GATT service element.

Public Members

bool is_primary

Indicates if the service is primary.

uint16_t start_handle

Service start handle.

uint16_t end_handle

Service end handle.

esp_bt_uuid_t uuid

Service UUID.

struct esp_gattc_char_elem_t

Represents a GATT characteristic element.

Public Members

uint16_t char_handle

Characteristic handle.

esp_gatt_char_prop_t properties

Characteristic properties.

esp_bt_uuid_t uuid

Characteristic UUID.

struct esp_gattc_descr_elem_t

Represents a GATT descriptor element.

Public Members

uint16_t handle

Descriptor handle.

esp_bt_uuid_t uuid

Descriptor UUID.

struct esp_gattc_incl_svc_elem_t

Represents an included GATT service element.

Public Members

uint16_t handle

Current attribute handle of the included service.

uint16_t incl_srvc_s_handle

Start handle of the included service.

uint16_t incl_srvc_e_handle

End handle of the included service.

esp_bt_uuid_t uuid

Included service UUID.

struct esp_ble_gatt_creat_conn_params_t

Represents a creat connection element.

Public Members

esp_bd_addr_t remote_bda

The Bluetooth address of the remote device

esp_ble_addr_type_t remote_addr_type

Address type of the remote device

bool is_direct

Direct connection or background auto connection(by now, background auto connection is not supported

bool is_aux

Set to true for BLE 5.0 or higher to enable auxiliary connections; set to false for BLE 4.2 or lower.

esp_ble_addr_type_t own_addr_type

Specifies the address type used in the connection request. Set to 0xFF if the address type is unknown.

esp_ble_phy_mask_t phy_mask

Indicates which PHY connection parameters will be used. When is_aux is false, only the connection params for 1M PHY can be specified

const esp_ble_conn_params_t *phy_1m_conn_params

Connection parameters for the LE 1M PHY

const esp_ble_conn_params_t *phy_2m_conn_params

Connection parameters for the LE 2M PHY

const esp_ble_conn_params_t *phy_coded_conn_params

Connection parameters for the LE Coded PHY

Macros

ESP_GATT_ILLEGAL_UUID

GATT INVALID UUID.

ESP_GATT_ILLEGAL_HANDLE

GATT INVALID HANDLE.

ESP_GATT_ATTR_HANDLE_MAX

GATT attribute max handle.

ESP_GATT_MAX_READ_MULTI_HANDLES

Maximum number of attributes to read in one request.

ESP_GATT_MAX_ATTR_LEN

Defines the maximum length of a GATT attribute.

This definition specifies the maximum number of bytes that a GATT attribute can hold. As same as GATT_MAX_ATTR_LEN.

ESP_GATT_RSP_BY_APP

Defines attribute control for GATT operations.

This module provides definitions for controlling attribute auto responses in GATT operations.

Response to Write/Read operations should be handled by the application.

ESP_GATT_AUTO_RSP

Response to Write/Read operations should be automatically handled by the GATT stack.

ESP_GATT_IF_NONE

Macro indicating no specific GATT interface.

No specific application GATT interface.

Type Definitions

typedef uint16_t esp_gatt_perm_t

Type to represent GATT attribute permissions.

typedef uint8_t esp_gatt_char_prop_t

Type for characteristic properties bitmask.

typedef uint8_t esp_gatt_if_t

GATT interface type for client applications.

Enumerations

enum esp_gatt_prep_write_type

Defines the attribute write operation types from the client.

These values are used to specify the type of write operation in a prepare write sequence. relate to BTA_GATT_PREP_WRITE_xxx in bta/bta_gatt_api.h.

Values:

enumerator ESP_GATT_PREP_WRITE_CANCEL

Prepare write cancel. Corresponds to BTA_GATT_PREP_WRITE_CANCEL.

enumerator ESP_GATT_PREP_WRITE_EXEC

Prepare write execute. Corresponds to BTA_GATT_PREP_WRITE_EXEC.

enum esp_gatt_status_t

GATT operation status codes.

These status codes are used to indicate the result of various GATT operations. relate to BTA_GATT_xxx in bta/bta_gatt_api.h .

Values:

enumerator ESP_GATT_OK

0x0, Operation successful. Corresponds to BTA_GATT_OK.

enumerator ESP_GATT_INVALID_HANDLE

0x01, Invalid handle. Corresponds to BTA_GATT_INVALID_HANDLE.

enumerator ESP_GATT_READ_NOT_PERMIT

0x02, Read operation not permitted. Corresponds to BTA_GATT_READ_NOT_PERMIT.

enumerator ESP_GATT_WRITE_NOT_PERMIT

0x03, Write operation not permitted. Corresponds to BTA_GATT_WRITE_NOT_PERMIT.

enumerator ESP_GATT_INVALID_PDU

0x04, Invalid PDU. Corresponds to BTA_GATT_INVALID_PDU.

enumerator ESP_GATT_INSUF_AUTHENTICATION

0x05, Insufficient authentication. Corresponds to BTA_GATT_INSUF_AUTHENTICATION.

enumerator ESP_GATT_REQ_NOT_SUPPORTED

0x06, Request not supported. Corresponds to BTA_GATT_REQ_NOT_SUPPORTED.

enumerator ESP_GATT_INVALID_OFFSET

0x07, Invalid offset. Corresponds to BTA_GATT_INVALID_OFFSET.

enumerator ESP_GATT_INSUF_AUTHORIZATION

0x08, Insufficient authorization. Corresponds to BTA_GATT_INSUF_AUTHORIZATION.

enumerator ESP_GATT_PREPARE_Q_FULL

0x09, Prepare queue full. Corresponds to BTA_GATT_PREPARE_Q_FULL.

enumerator ESP_GATT_NOT_FOUND

0x0a, Not found. Corresponds to BTA_GATT_NOT_FOUND.

enumerator ESP_GATT_NOT_LONG

0x0b, Not long. Corresponds to BTA_GATT_NOT_LONG.

enumerator ESP_GATT_INSUF_KEY_SIZE

0x0c, Insufficient key size. Corresponds to BTA_GATT_INSUF_KEY_SIZE.

enumerator ESP_GATT_INVALID_ATTR_LEN

0x0d, Invalid attribute length. Corresponds to BTA_GATT_INVALID_ATTR_LEN.

enumerator ESP_GATT_ERR_UNLIKELY

0x0e, Unlikely error. Corresponds to BTA_GATT_ERR_UNLIKELY.

enumerator ESP_GATT_INSUF_ENCRYPTION

0x0f, Insufficient encryption. Corresponds to BTA_GATT_INSUF_ENCRYPTION.

enumerator ESP_GATT_UNSUPPORT_GRP_TYPE

0x10, Unsupported group type. Corresponds to BTA_GATT_UNSUPPORT_GRP_TYPE.

enumerator ESP_GATT_INSUF_RESOURCE

0x11, Insufficient resource. Corresponds to BTA_GATT_INSUF_RESOURCE.

enumerator ESP_GATT_NO_RESOURCES

0x80, No resources. Corresponds to BTA_GATT_NO_RESOURCES.

enumerator ESP_GATT_INTERNAL_ERROR

0x81, Internal error. Corresponds to BTA_GATT_INTERNAL_ERROR.

enumerator ESP_GATT_WRONG_STATE

0x82, Wrong state. Corresponds to BTA_GATT_WRONG_STATE.

enumerator ESP_GATT_DB_FULL

0x83, Database full. Corresponds to BTA_GATT_DB_FULL.

enumerator ESP_GATT_BUSY

0x84, Busy. Corresponds to BTA_GATT_BUSY.

enumerator ESP_GATT_ERROR

0x85, Generic error. Corresponds to BTA_GATT_ERROR.

enumerator ESP_GATT_CMD_STARTED

0x86, Command started. Corresponds to BTA_GATT_CMD_STARTED.

enumerator ESP_GATT_ILLEGAL_PARAMETER

0x87, Illegal parameter. Corresponds to BTA_GATT_ILLEGAL_PARAMETER.

enumerator ESP_GATT_PENDING

0x88, Operation pending. Corresponds to BTA_GATT_PENDING.

enumerator ESP_GATT_AUTH_FAIL

0x89, Authentication failed. Corresponds to BTA_GATT_AUTH_FAIL.

enumerator ESP_GATT_MORE

0x8a, More data available. Corresponds to BTA_GATT_MORE.

enumerator ESP_GATT_INVALID_CFG

0x8b, Invalid configuration. Corresponds to BTA_GATT_INVALID_CFG.

enumerator ESP_GATT_SERVICE_STARTED

0x8c, Service started. Corresponds to BTA_GATT_SERVICE_STARTED.

enumerator ESP_GATT_ENCRYPTED_MITM

0x0, Encrypted, with MITM protection. Corresponds to BTA_GATT_ENCRYPTED_MITM.

enumerator ESP_GATT_ENCRYPTED_NO_MITM

0x8d, Encrypted, without MITM protection. Corresponds to BTA_GATT_ENCRYPTED_NO_MITM.

enumerator ESP_GATT_NOT_ENCRYPTED

0x8e, Not encrypted. Corresponds to BTA_GATT_NOT_ENCRYPTED.

enumerator ESP_GATT_CONGESTED

0x8f, Congested. Corresponds to BTA_GATT_CONGESTED.

enumerator ESP_GATT_DUP_REG

0x90, Duplicate registration. Corresponds to BTA_GATT_DUP_REG.

enumerator ESP_GATT_ALREADY_OPEN

0x91, Already open. Corresponds to BTA_GATT_ALREADY_OPEN.

enumerator ESP_GATT_CANCEL

0x92, Operation cancelled. Corresponds to BTA_GATT_CANCEL.

enumerator ESP_GATT_STACK_RSP

0xe0, Stack response. Corresponds to BTA_GATT_STACK_RSP.

enumerator ESP_GATT_APP_RSP

0xe1, Application response. Corresponds to BTA_GATT_APP_RSP.

enumerator ESP_GATT_UNKNOWN_ERROR

0xef, Unknown error. Corresponds to BTA_GATT_UNKNOWN_ERROR.

enumerator ESP_GATT_CCC_CFG_ERR

0xfd, Client Characteristic Configuration Descriptor improperly configured. Corresponds to BTA_GATT_CCC_CFG_ERR.

enumerator ESP_GATT_PRC_IN_PROGRESS

0xfe, Procedure already in progress. Corresponds to BTA_GATT_PRC_IN_PROGRESS.

enumerator ESP_GATT_OUT_OF_RANGE

0xff, Attribute value out of range. Corresponds to BTA_GATT_OUT_OF_RANGE.

enum esp_gatt_conn_reason_t

Enumerates reasons for GATT connection.

Values:

enumerator ESP_GATT_CONN_UNKNOWN

Unknown connection reason. Corresponds to BTA_GATT_CONN_UNKNOWN in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_L2C_FAILURE

General L2CAP failure. Corresponds to BTA_GATT_CONN_L2C_FAILURE in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_TIMEOUT

Connection timeout. Corresponds to BTA_GATT_CONN_TIMEOUT in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_TERMINATE_PEER_USER

Connection terminated by peer user. Corresponds to BTA_GATT_CONN_TERMINATE_PEER_USER in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_TERMINATE_LOCAL_HOST

Connection terminated by local host. Corresponds to BTA_GATT_CONN_TERMINATE_LOCAL_HOST in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_FAIL_ESTABLISH

Failure to establish connection. Corresponds to BTA_GATT_CONN_FAIL_ESTABLISH in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_LMP_TIMEOUT

Connection failed due to LMP response timeout. Corresponds to BTA_GATT_CONN_LMP_TIMEOUT in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_CONN_CANCEL

L2CAP connection cancelled. Corresponds to BTA_GATT_CONN_CONN_CANCEL in bta/bta_gatt_api.h

enumerator ESP_GATT_CONN_NONE

No connection to cancel. Corresponds to BTA_GATT_CONN_NONE in bta/bta_gatt_api.h

enum esp_gatt_auth_req_t

Defines the GATT authentication request types.

This enumeration lists the types of authentication requests that can be made. It corresponds to the BTA_GATT_AUTH_REQ_xxx values defined in bta/bta_gatt_api.h. The types include options for no authentication, unauthenticated encryption, authenticated encryption, and both signed versions with and without MITM (Man-In-The-Middle) protection.

Values:

enumerator ESP_GATT_AUTH_REQ_NONE

No authentication required. Corresponds to BTA_GATT_AUTH_REQ_NONE.

enumerator ESP_GATT_AUTH_REQ_NO_MITM

Unauthenticated encryption. Corresponds to BTA_GATT_AUTH_REQ_NO_MITM.

enumerator ESP_GATT_AUTH_REQ_MITM

Authenticated encryption (MITM protection). Corresponds to BTA_GATT_AUTH_REQ_MITM.

enumerator ESP_GATT_AUTH_REQ_SIGNED_NO_MITM

Signed data, no MITM protection. Corresponds to BTA_GATT_AUTH_REQ_SIGNED_NO_MITM.

enumerator ESP_GATT_AUTH_REQ_SIGNED_MITM

Signed data with MITM protection. Corresponds to BTA_GATT_AUTH_REQ_SIGNED_MITM.

enum esp_service_source_t

Enumerates the possible sources of a GATT service discovery.

This enumeration identifies the source of a GATT service discovery process, indicating whether the service information was obtained from a remote device, from NVS (Non-Volatile Storage) flash, or the source is unknown.

Values:

enumerator ESP_GATT_SERVICE_FROM_REMOTE_DEVICE

Service information from a remote device. Relates to BTA_GATTC_SERVICE_INFO_FROM_REMOTE_DEVICE.

enumerator ESP_GATT_SERVICE_FROM_NVS_FLASH

Service information from NVS flash. Relates to BTA_GATTC_SERVICE_INFO_FROM_NVS_FLASH.

enumerator ESP_GATT_SERVICE_FROM_UNKNOWN

Service source is unknown. Relates to BTA_GATTC_SERVICE_INFO_FROM_UNKNOWN.

enum esp_gatt_write_type_t

Defines the types of GATT write operations.

Values:

enumerator ESP_GATT_WRITE_TYPE_NO_RSP

Write operation where no response is needed.

enumerator ESP_GATT_WRITE_TYPE_RSP

Write operation that requires a remote response.

enum esp_gatt_db_attr_type_t

Enumerates types of GATT database attributes.

Values:

enumerator ESP_GATT_DB_PRIMARY_SERVICE

Primary service attribute.

enumerator ESP_GATT_DB_SECONDARY_SERVICE

Secondary service attribute.

enumerator ESP_GATT_DB_CHARACTERISTIC

Characteristic attribute.

enumerator ESP_GATT_DB_DESCRIPTOR

Descriptor attribute.

enumerator ESP_GATT_DB_INCLUDED_SERVICE

Included service attribute.

enumerator ESP_GATT_DB_ALL

All attribute types.

Was this page helpful?