# 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

    Determines whether to use BLE 5.0 or BLE 4.2 create connection interface.

    - If set to true, the BLE 5.0 interface (extended connection) will be used.

    - If set to false, the BLE 4.2 interface (legacy connection) will be used.

    - Note: When connecting to a legacy advertising device using BLE 5.0 interface, is_aux should be set to true.

    - Auto-setting (handled in L2CAP layer): The system will automatically set this parameter based on the enabled BLE features: If only BLE 4.2 feature is enabled, is_aux will be automatically set to false. If only BLE 5.0 feature is enabled, is_aux will be automatically set to true. If both BLE 4.2 and BLE 5.0 features are enabled (not recommended), the stack will automatically infer whether to use BLE 5.0 or BLE 4.2 interface based on previously used APIs. Otherwise, the user-specified value will be used.

    - Note: It is strongly recommended NOT to enable both BLE 4.2 and BLE 5.0 features simultaneously.

  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. Note: Establishing an ACL connection over the LE Coded PHY will significantly degrade Wi-Fi performance, because the on-air transmission time of a Coded PHY packet (S=2 or S=8) is much longer than that of a 1M/2M PHY packet, so the Bluetooth controller occupies the radio for a longer time and leaves less airtime for Wi-Fi. In Bluetooth/Wi-Fi coexistence scenarios, it is recommended to use the LE 2M PHY or LE 1M PHY first, and only fall back to the LE Coded PHY when the long-range capability is really required.

struct esp_ble_gatt_pawr_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

  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.

  uint8_t adv_handle

    Advertising_Handle identifying the periodic advertising train. Range: 0x00 to 0xEF or 0xFF

  uint8_t subevent

    Subevent where the connection request is to be sent. Range: 0x00 to 0x7F or 0xFF

  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. Note: Establishing an ACL connection over the LE Coded PHY will significantly degrade Wi-Fi performance, because the on-air transmission time of a Coded PHY packet (S=2 or S=8) is much longer than that of a 1M/2M PHY packet, so the Bluetooth controller occupies the radio for a longer time and leaves less airtime for Wi-Fi. In Bluetooth/Wi-Fi coexistence scenarios, it is recommended to use the LE 2M PHY or LE 1M PHY first, and only fall back to the LE Coded PHY when the long-range capability is really required.

### 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.

  Used as the `auth_req` argument in GATT client read/write APIs. It specifies the link security level required before the ATT request is sent, and is independent of server-side attribute permission flags (`ESP_GATT_PERM_xxx`).

  Corresponds to the `BTA_GATT_AUTH_REQ_xxx` values defined in `bta/bta_gatt_api.h`.

  Note

  If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start link encryption or SMP pairing before the GATT operation. Handle `ESP_GAP_BLE_PASSKEY_REQ_EVT` and call `esp_ble_passkey_reply()` if needed.

  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?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.