# Bluetooth® HFP AG API

## Overview

HFP (Hands-Free Profile) AG API provides functions for a Bluetooth device to act as an Audio Gateway (AG), enabling communication with HFP Client devices such as headsets or car kits. It supports connection management, call handling, volume control, and other hands-free operations.

## Application Examples

- bluetooth/bluedroid/classic_bt/hfp_ag demonstrates how to use the Hands-Free Audio Gateway (HF-AG) component to communicate with a device that implements Hands-Free Client Role, such as a headphone set. It provides commands for configuring the project, establishing connections, controlling volume, and answering or rejecting calls.

## API Reference

### Header File

- components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h

- This header file can be included with:

  >     #include "esp_hf_ag_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_hf_ag_register_callback(esp_hf_cb_t callback)

  Register application callback function to HFP AG module. This function should be called only after esp_bluedroid_enable() completes successfully.

  Parameters:

    callback -- [in] HFP AG event callback function

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: if callback is a NULL function pointer

esp_err_t esp_hf_ag_init(void)

  Initialize the bluetooth HF AG module. This function should be called after esp_bluedroid_enable() completes successfully. ESP_HF_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer.

  Returns:

    - ESP_OK: if the initialization request is sent successfully

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_deinit(void)

  De-initialize for HF AG module. This function should be called only after esp_bluedroid_enable() completes successfully. ESP_HF_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer.

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_slc_connect(esp_bd_addr_t remote_bda)

  To establish a Service Level Connection to remote bluetooth HFP client device. This function must be called after esp_hf_ag_init() and before esp_hf_ag_deinit().

  Parameters:

    remote_bda -- [in] remote bluetooth HFP client device address

  Returns:

    - ESP_OK: connect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_slc_disconnect(esp_bd_addr_t remote_bda)

  Disconnect from the remote HFP client. This function must be called after esp_hf_ag_init() and before esp_hf_ag_deinit().

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: disconnect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_audio_connect(esp_bd_addr_t remote_bda)

  Create audio connection with remote HFP client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: audio connect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_audio_disconnect(esp_bd_addr_t remote_bda)

  Release the established audio connection with remote HFP client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: audio disconnect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_vra_control(esp_bd_addr_t remote_bda, esp_hf_vr_state_t value)

  Response of Volume Recognition Command(AT+VRA) from HFP client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_bda -- [in] the device address of voice recognition initiator

    - value -- [in] 0 - voice recognition disabled, 1- voice recognition enabled

  Returns:

    - ESP_OK: response of volume recognition is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_volume_control(esp_bd_addr_t remote_bda, esp_hf_volume_control_target_t type, int volume)

  Volume synchronization with HFP client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_bda -- [in] remote bluetooth device address

    - type -- [in] volume control target, speaker or microphone

    - volume -- [in] gain of the speaker of microphone, ranges 0 to 15

  Returns:

    - ESP_OK: volume synchronization control is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_ERR_INVALID_ARG: if arguments are invalid

    - ESP_FAIL: others

esp_err_t esp_hf_ag_unknown_at_send(esp_bd_addr_t remote_addr, char *unat)

  Handle Unknown AT command from HFP Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - unat -- [in] User AT command response to HF Client. It will response "ERROR" by default if unat is NULL.

  Returns:

    - ESP_OK: response of unknown AT command is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_cmee_send(esp_bd_addr_t remote_bda, esp_hf_at_response_code_t response_code, esp_hf_cme_err_t error_code)

  Unsolicited send extend AT error code to HFP Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_bda -- [in] remote bluetooth device address

    - response_code -- [in] AT command response code

    - error_code -- [in] CME error code

  Returns:

    - ESP_OK: extend error code is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_ciev_report(esp_bd_addr_t remote_addr, esp_hf_ciev_report_type_t ind_type, int value)

  Send indicator report "+CIEV: <ind> <value>" to HFP Client. "CIEV" means “indicator events reporting", and all indicator types can be sent one type at a time. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - ind_type -- [in] indicator type

    - value -- [in] indicator value

  Returns:

    - ESP_OK: indicator report is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_cind_response(esp_bd_addr_t remote_addr, esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, esp_hf_network_state_t ntk_state, int signal, esp_hf_roaming_status_t roam, int batt_lev, esp_hf_call_held_status_t call_held_status)

  Response to device individual indicators to HFP Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - call_state -- [in] call state

    - call_setup_state -- [in] call setup state

    - ntk_state -- [in] network service state

    - signal -- [in] signal strength from 0 to 5

    - roam -- [in] roam state

    - batt_lev -- [in] battery level from 0 to 5

    - call_held_status -- [in] call held status

  Returns:

    - ESP_OK: response to device individual indicators is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_ERR_INVALID_ARG: if the arguments are invalid

    - ESP_FAIL: others

esp_err_t esp_hf_ag_cops_response(esp_bd_addr_t remote_addr, char *name)

  Response for AT+COPS command from HF Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - name -- [in] current operator name

  Returns:

    - ESP_OK: response for AT+COPS command is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_clcc_response(esp_bd_addr_t remote_addr, int index, esp_hf_current_call_direction_t dir, esp_hf_current_call_status_t current_call_state, esp_hf_current_call_mode_t mode, esp_hf_current_call_mpty_type_t mpty, char *number, esp_hf_call_addr_type_t type)

  Response to AT+CLCC command from HFP Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - index -- [in] the index of current call, starting with 1, finishing response with 0 (send OK)

    - dir -- [in] call direction (incoming/outgoing)

    - current_call_state -- [in] current call state

    - mode -- [in] current call mode (voice/data/fax)

    - mpty -- [in] single or multi type

    - number -- [in] current call number

    - type -- [in] international type or unknown

  Returns:

    - ESP_OK: response to AT+CLCC command is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_cnum_response(esp_bd_addr_t remote_addr, char *number, int number_type, esp_hf_subscriber_service_type_t service_type)

  Response for AT+CNUM command from HF Client. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - number -- [in] registration number

    - number_type -- [in] value of number type from 128-143: national or international, may contain prefix and/or escape digits 144-159: international, includes country code prefix, add "+" if needed 160-175: national, but no prefix nor escape digits

    - service_type -- [in] service type (unknown/voice/fax)

  Returns:

    - ESP_OK: response for AT+CNUM command is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_bsir(esp_bd_addr_t remote_addr, esp_hf_in_band_ring_state_t state)

  Inform HF Client that AG Provided in-band ring tone or not. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - state -- [in] in-band ring tone state

  Returns:

    - ESP_OK: information of in-band ring tone is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_ERR_INVALID_ARG: if arguments are invalid

    - ESP_FAIL: others

esp_err_t esp_hf_ag_answer_call(esp_bd_addr_t remote_addr, int num_active, int num_held, esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, char *number, esp_hf_call_addr_type_t call_addr_type)

  Answer Incoming Call from AG. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - num_active -- [in] the number of active call

    - num_held -- [in] the number of held call

    - call_state -- [in] call state

    - call_setup_state -- [in] call setup state

    - number -- [in] number of the incoming call

    - call_addr_type -- [in] call address type

  Returns:

    - ESP_OK: answer incoming call is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_reject_call(esp_bd_addr_t remote_addr, int num_active, int num_held, esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, char *number, esp_hf_call_addr_type_t call_addr_type)

  Reject Incoming Call from AG. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - num_active -- [in] the number of active call

    - num_held -- [in] the number of held call

    - call_state -- [in] call state

    - call_setup_state -- [in] call setup state

    - number -- [in] number of the incoming call

    - call_addr_type -- [in] call address type

  Returns:

    - ESP_OK: reject incoming call is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_out_call(esp_bd_addr_t remote_addr, int num_active, int num_held, esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, char *number, esp_hf_call_addr_type_t call_addr_type)

  Initiate a call from AG. As a precondition to use this API, Service Level Connection shall exist with HFP client. If the AG is driven by the HF to call esp_hf_ag_out_call, it needs to response an OK or ERROR to HF. But if the AG is actively calling esp_hf_ag_out_call, it does not need to take a response to HF.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - num_active -- [in] the number of active call

    - num_held -- [in] the number of held call

    - call_state -- [in] call state

    - call_setup_state -- [in] call setup state

    - number -- [in] number of the outgoing call

    - call_addr_type -- [in] call address type

  Returns:

    - ESP_OK: a call initiation is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_end_call(esp_bd_addr_t remote_addr, int num_active, int num_held, esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, char *number, esp_hf_call_addr_type_t call_addr_type)

  End an ongoing call. As a precondition to use this API, Service Level Connection shall exist with HFP client.

  Parameters:

    - remote_addr -- [in] remote bluetooth device address

    - num_active -- [in] the number of active call

    - num_held -- [in] the number of held call

    - call_state -- [in] call state

    - call_setup_state -- [in] call setup state

    - number -- [in] number of the call

    - call_addr_type -- [in] call address type

  Returns:

    - ESP_OK: end an ongoing call is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_register_audio_data_callback(esp_hf_ag_audio_data_cb_t callback)

  Register HFP AG audio data output function; the callback is only used in the case that Voice Over HCI is enabled.

  Parameters:

    callback -- [in] HFP AG incoming audio data callback function

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_hf_audio_buff_t *esp_hf_ag_audio_buff_alloc(uint16_t size)

  Allocate a audio buffer to store and send audio data. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    size -- [in] buffer size to allocate

  Returns:

    allocated audio buffer, if Bluedroid is not enabled, no memory, or size is zeros, will return NULL

void esp_hf_ag_audio_buff_free(esp_hf_audio_buff_t *audio_buf)

  Free a audio buffer allocated by esp_hf_ag_audio_buff_alloc. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    audio_buf -- [in] audio buffer to free

esp_err_t esp_hf_ag_audio_data_send(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf)

  Send audio data, the audio buffer should by allocated by esp_hf_ag_audio_buff_alloc. If the length of the audio data is equal to preferred_frame_size indicated by ESP_HF_AUDIO_STATE_EVT, then we can reduce one memory copy inside the Bluedroid stack. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    - sync_conn_hdl -- [in] (e)SCO connection handle

    - audio_buf -- [in] audio buffer that audio data stored

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_ERR_INVALID_ARG: invalid parameter

    - ESP_FAIL: others

esp_err_t esp_hf_ag_pkt_stat_nums_get(uint16_t sync_conn_handle)

  Get the number of packets received and sent.

                   This function is only used in the case that Voice Over HCI is enabled and the audio state is connected.
                   When the operation is completed, the callback function will be called with ESP_HF_PKT_STAT_NUMS_GET_EVT.

  Parameters:

    sync_conn_handle -- [in] the (e)SCO connection handle

  Returns:

    - ESP_OK: if the request is sent successfully

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_ag_get_profile_status(esp_hf_profile_status_t *profile_status)

  This function is used to get the status of hfp ag.

  Parameters:

    profile_status -- [out] - hfp ag status

  Returns:

    - ESP_OK: success

    - other: failed

### Unions

union esp_hf_cb_param_t
  #include <esp_hf_ag_api.h>

  HFP AG callback parameters.

  Public Members

  struct esp_hf_cb_param_t::hf_conn_stat_param conn_stat

    AG callback param of ESP_HF_CONNECTION_STATE_EVT

  struct esp_hf_cb_param_t::hf_audio_stat_param audio_stat

    AG callback param of ESP_HF_AUDIO_STATE_EVT

  struct esp_hf_cb_param_t::hf_vra_rep_param vra_rep

    AG callback param of ESP_HF_BVRA_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_volume_control_param volume_control

    AG callback param of ESP_HF_VOLUME_CONTROL_EVT

  struct esp_hf_cb_param_t::hf_unat_rep_param unat_rep

    AG callback param of ESP_HF_UNAT_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_out_call_param out_call

    AG callback param of ESP_HF_DIAL_EVT

  struct esp_hf_cb_param_t::hf_ind_upd_param ind_upd

    AG callback param of ESP_HF_IND_UPDATE_EVT

  struct esp_hf_cb_param_t::hf_cind_rep_param cind_rep

    AG callback param of ESP_HF_CIND_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_cops_rep_param cops_rep

    AG callback param of ESP_HF_COPS_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_clcc_rep_param clcc_rep

    AG callback param of ESP_HF_CLCC_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_cnum_rep_param cnum_rep

    AG callback param of ESP_HF_CNUM_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_vts_rep_param vts_rep

    AG callback param of ESP_HF_VTS_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_nrec_param nrec

    AG callback param of ESP_HF_NREC_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_ata_rep_param ata_rep

    AG callback param of ESP_HF_ATA_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_chup_rep_param chup_rep

    AG callback param of ESP_HF_CHUP_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_wbs_rep_param wbs_rep

    AG callback param of ESP_HF_WBS_RESPONSE_EVT

  struct esp_hf_cb_param_t::hf_bcs_rep_param bcs_rep

    AG callback param of ESP_HF_BCS_RESPONSE_EVT

  struct esp_hf_cb_param_t::ag_pkt_status_nums pkt_nums

    AG callback param of ESP_HF_PKT_STAT_NUMS_GET_EVT

  struct esp_hf_cb_param_t::ag_prof_stat_param prof_stat

    status to indicate hf prof init or deinit

  struct ag_pkt_status_nums
    #include <esp_hf_ag_api.h>

    ESP_HF_PKT_STAT_NUMS_GET_EVT.

    Public Members

    uint32_t rx_total

      the total number of packets received

    uint32_t rx_correct

      the total number of packets data correctly received

    uint32_t rx_err

      the total number of packets data with possible invalid

    uint32_t rx_none

      the total number of packets data not received

    uint32_t rx_lost

      the total number of packets data partially lost

    uint32_t tx_total

      the total number of packets sent

    uint32_t tx_discarded

      the total number of packets sent and lost

  struct ag_prof_stat_param
    #include <esp_hf_ag_api.h>

    ESP_HF_PROF_STATE_EVT.

    Public Members

    esp_hf_prof_state_t state

      hf profile state param

  struct hf_ata_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_ATA_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_audio_stat_param
    #include <esp_hf_ag_api.h>

    ESP_HF_AUDIO_STATE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_audio_state_t state

      Audio connection state

    esp_hf_sync_conn_hdl_t sync_conn_handle

      (e)SCO connection handle

    uint16_t preferred_frame_size

      Valid only when Voice Over HCI is enabled, recommended frame size to send

  struct hf_bcs_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_BCS_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_wbs_config_t mode

      codec mode CVSD or mSBC

  struct hf_chup_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_CHUP_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_cind_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_CIND_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_clcc_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_CLCC_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_cnum_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_CNUM_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_conn_stat_param
    #include <esp_hf_ag_api.h>

    ESP_HF_CONNECTION_STATE_EVT.

    Public Members

    esp_bd_addr_t remote_bda

      Remote Bluetooth device address

    esp_hf_connection_state_t state

      Connection state

    uint32_t peer_feat

      HF supported features

    uint32_t chld_feat

      AG supported features on call hold and multiparty services

  struct hf_cops_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_COPS_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_ind_upd_param
    #include <esp_hf_ag_api.h>

    ESP_HF_IND_UPDATE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

  struct hf_nrec_param
    #include <esp_hf_ag_api.h>

    ESP_HF_NREC_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_nrec_t state

      NREC enabled or disabled

  struct hf_out_call_param
    #include <esp_hf_ag_api.h>

    ESP_HF_DIAL_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      remote bluetooth device address

    esp_hf_dial_type_t type

      dial type

    char *num_or_loc

      location in phone memory

  struct hf_unat_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_UNAT_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    char *unat

      Unknown AT command string

  struct hf_volume_control_param
    #include <esp_hf_ag_api.h>

    ESP_HF_VOLUME_CONTROL_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_volume_type_t type

      Volume control target, speaker or microphone

    int volume

      Gain, ranges from 0 to 15

  struct hf_vra_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_BVRA_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_vr_state_t value

      Voice recognition state

  struct hf_vts_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_VTS_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    char *code

      MTF code from HF Client

  struct hf_wbs_rep_param
    #include <esp_hf_ag_api.h>

    ESP_HF_WBS_RESPONSE_EVT.

    Public Members

    esp_bd_addr_t remote_addr

      Remote bluetooth device address

    esp_hf_wbs_config_t codec

      codec mode CVSD or mSBC

### Structures

struct esp_hf_profile_status_t

  HFP AG profile status parameters.

  Public Members

  bool hfp_ag_inited

    hfp ag initialization

  uint8_t slc_conn_num

    Number of Service Level Connections

  uint8_t sync_conn_num

    Number of (e)SCO Connections

### Macros

ESP_HF_PEER_FEAT_3WAY

  Three-way calling

ESP_HF_PEER_FEAT_ECNR

  Echo cancellation and/or noise reduction

ESP_HF_PEER_FEAT_VREC

  Voice recognition

ESP_HF_PEER_FEAT_INBAND

  In-band ring tone

ESP_HF_PEER_FEAT_VTAG

  Attach a phone number to a voice tag

ESP_HF_PEER_FEAT_REJECT

  Ability to reject incoming call

ESP_HF_PEER_FEAT_ECS

  Enhanced Call Status

ESP_HF_PEER_FEAT_ECC

  Enhanced Call Control

ESP_HF_PEER_FEAT_EXTERR

  Extended error codes

ESP_HF_PEER_FEAT_CODEC

  Codec Negotiation

ESP_HF_PEER_FEAT_HF_IND

  HF Indicators

ESP_HF_PEER_FEAT_ESCO_S4

  eSCO S4 Setting Supported

ESP_HF_CHLD_FEAT_REL

  0 Release waiting call or held calls

ESP_HF_CHLD_FEAT_REL_ACC

  1 Release active calls and accept other waiting or held call

ESP_HF_CHLD_FEAT_REL_X

  1x Release specified active call only

ESP_HF_CHLD_FEAT_HOLD_ACC

  2 Active calls on hold and accept other waiting or held call

ESP_HF_CHLD_FEAT_PRIV_X

  2x Request private mode with specified call(put the rest on hold)

ESP_HF_CHLD_FEAT_MERGE

  3 Add held call to multiparty

ESP_HF_CHLD_FEAT_MERGE_DETACH

  4 Connect two calls and leave(disconnect from multiparty)

### Type Definitions

typedef void (*esp_hf_cb_t)(esp_hf_cb_event_t event, esp_hf_cb_param_t *param)

  HF AG callback function type.

  Param event:

    [in] : Event type

  Param param:

    [in] : Pointer to callback parameter

typedef void (*esp_hf_ag_audio_data_cb_t)(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf, bool is_bad_frame)

  HFP AG incoming audio data callback function, user should copy audio_buf struct to other place before return. This callback is used in case of Voice Over HCI.

  Param sync_conn_hdl:

    [in] (e)SCO connection handle

  Param audio_buf:

    [in] pointer to incoming data(payload of HCI synchronous data packet), user should free audio buffer by calling esp_hf_ag_audio_buff_free

  Param is_bad_frame:

    [in] whether this packet is marked as bad frame by baseband

### Enumerations

enum esp_hf_cb_event_t

  HF callback events.

  Values:

  enumerator ESP_HF_CONNECTION_STATE_EVT

    Connection state changed event

  enumerator ESP_HF_AUDIO_STATE_EVT

    Audio connection state change event

  enumerator ESP_HF_BVRA_RESPONSE_EVT

    Voice recognition state change event

  enumerator ESP_HF_VOLUME_CONTROL_EVT

    Audio volume control command from HF Client, provided by +VGM or +VGS message

  enumerator ESP_HF_UNAT_RESPONSE_EVT

    Unknown AT cmd Response

  enumerator ESP_HF_IND_UPDATE_EVT

    Indicator Update Event

  enumerator ESP_HF_CIND_RESPONSE_EVT

    Call And Device Indicator Response

  enumerator ESP_HF_COPS_RESPONSE_EVT

    Current operator information

  enumerator ESP_HF_CLCC_RESPONSE_EVT

    List of current calls notification

  enumerator ESP_HF_CNUM_RESPONSE_EVT

    Subscriber information response from HF Client

  enumerator ESP_HF_VTS_RESPONSE_EVT

    Enable or not DTMF

  enumerator ESP_HF_NREC_RESPONSE_EVT

    Enable or not NREC

  enumerator ESP_HF_ATA_RESPONSE_EVT

    Answer an Incoming Call

  enumerator ESP_HF_CHUP_RESPONSE_EVT

    Reject an Incoming Call

  enumerator ESP_HF_DIAL_EVT

    Originate an outgoing call with specific number or dial the last number

  enumerator ESP_HF_WBS_RESPONSE_EVT

    Codec Status

  enumerator ESP_HF_BCS_RESPONSE_EVT

    Final Codec Choice

  enumerator ESP_HF_PKT_STAT_NUMS_GET_EVT

    Request number of packet different status

  enumerator ESP_HF_PROF_STATE_EVT

    Indicate HF init or deinit complete

enum esp_hf_dial_type_t

  Dial type of ESP_HF_DIAL_EVT.

  Values:

  enumerator ESP_HF_DIAL_NUM

    Dial with a phone number

  enumerator ESP_HF_DIAL_VOIP

    Dial with VoIP

  enumerator ESP_HF_DIAL_MEM

    Dial with a memory position

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.