HFP AG API

API Reference

Functions

esp_err_t esp_bt_hf_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_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: if callback is a NULL function pointer

esp_err_t esp_bt_hf_init(esp_bd_addr_t remote_addr)

Initialize the bluetooth HF AG module. This function should be called after esp_bluedroid_enable() completes successfully.

Parameters

remote_addr – [in] remote bluetooth device address

Returns

  • ESP_OK: if the initialization request is sent successfully

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_deinit(esp_bd_addr_t remote_addr)

De-initialize for HF AG module. This function should be called only after esp_bluedroid_enable() completes successfully.

Parameters

remote_addr – [in] remote bluetooth device address

Returns

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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_bt_hf_init() and before esp_bt_hf_deinit().

Parameters

remote_bda – [in] remote bluetooth HFP client device address

Returns

  • ESP_OK: connect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_disconnect(esp_bd_addr_t remote_bda)

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

Parameters

remote_bda – [in] remote bluetooth device address

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_connect_audio(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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_disconnect_audio(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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_vra(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 recognization initiator

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

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_hf_unat_response(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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_cmee_response(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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_indchange_notification(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)

Usolicited send device status notificationto 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

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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 indicatiors 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] batery level from 0 to 5

  • call_held_status – [in] call held status

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_cops_response(esp_bd_addr_t remote_addr, char *name)

Reponse 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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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

  • 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 unknow

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_cnum_response(esp_bd_addr_t remote_addr, char *number, esp_hf_subscriber_service_type_t 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

  • type – [in] service type (unknown/voice/fax)

Returns

  • ESP_OK: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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.

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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_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: disconnect request is sent to lower layer

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_bt_hf_register_data_callback(esp_hf_incoming_data_cb_t recv, esp_hf_outgoing_data_cb_t send)

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

Parameters

  • recv – [in] HFP client incoming data callback function

  • send – [in] HFP client outgoing data callback function

Returns

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: if callback is a NULL function pointer

void esp_hf_outgoing_data_ready(void)

Trigger the lower-layer to fetch and send audio data.

This function is only used in the case that Voice Over HCI is enabled. As a precondition to use this API, Service Level Connection shall exist with HFP client. After this function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data

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_cind_param cind

AG callback param of ESP_HF_CIND_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_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_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 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

struct hf_bcs_rep_param
#include <esp_hf_ag_api.h>

ESP_HF_BCS_RESPONSE_EVT.

Public Members

esp_hf_wbs_config_t mode

codec mode CVSD or mSBC

struct hf_cind_param
#include <esp_hf_ag_api.h>

ESP_HF_CIND_RESPONSE_EVT.

Public Members

esp_hf_call_status_t call_status

call status indicator

esp_hf_call_setup_status_t call_setup_status

call setup status indicator

esp_hf_network_state_t svc

bluetooth proprietary call hold status indicator

int signal_strength

bluetooth proprietary call hold status indicator

esp_hf_roaming_status_t roam

bluetooth proprietary call hold status indicator

int battery_level

battery charge value, ranges from 0 to 5

esp_hf_call_held_status_t call_held_status

bluetooth proprietary call hold status indicator

struct hf_conn_stat_param
#include <esp_hf_ag_api.h>

ESP_HS_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_nrec_param
#include <esp_hf_ag_api.h>

ESP_HF_NREC_RESPOSNE_EVT.

Public Members

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

char *num_or_loc

location in phone memory

struct hf_unat_rep_param
#include <esp_hf_ag_api.h>

ESP_HF_UNAT_RESPOSNE_EVT.

Public Members

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_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_RESPOSNE_EVT.

Public Members

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_hf_wbs_config_t codec

codec mode CVSD or mSBC

Macros

ESP_HF_PEER_FEAT_3WAY
ESP_HF_PEER_FEAT_ECNR
ESP_HF_PEER_FEAT_VREC
ESP_HF_PEER_FEAT_INBAND
ESP_HF_PEER_FEAT_VTAG
ESP_HF_PEER_FEAT_REJECT
ESP_HF_PEER_FEAT_ECS
ESP_HF_PEER_FEAT_ECC
ESP_HF_PEER_FEAT_EXTERR
ESP_HF_PEER_FEAT_CODEC
ESP_HF_PEER_FEAT_HF_IND
ESP_HF_PEER_FEAT_ESCO_S4
ESP_HF_CHLD_FEAT_REL
ESP_HF_CHLD_FEAT_REL_ACC
ESP_HF_CHLD_FEAT_REL_X
ESP_HF_CHLD_FEAT_HOLD_ACC
ESP_HF_CHLD_FEAT_PRIV_X
ESP_HF_CHLD_FEAT_MERGE
ESP_HF_CHLD_FEAT_MERGE_DETACH

Type Definitions

typedef void (*esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len)

AG incoming data callback function, the callback is useful in case of Voice Over HCI.

Param buf

[in] : pointer to incoming data(payload of HCI synchronous data packet), the buffer is allocated inside bluetooth protocol stack and will be released after invoke of the callback is finished.

Param len

[in] : size(in bytes) in buf

typedef uint32_t (*esp_hf_outgoing_data_cb_t)(uint8_t *buf, uint32_t len)

AG outgoing data callback function, the callback is useful in case of Voice Over HCI. Once audio connection is set up and the application layer has prepared data to send, the lower layer will call this function to read data and then send. This callback is supposed to be implemented as non-blocking, and if data is not enough, return value 0 is supposed.

Param buf

[in] : pointer to incoming data(payload of HCI synchronous data packet), the buffer is allocated inside bluetooth protocol stack and will be released after invoke of the callback is finished.

Param len

[in] : size(in bytes) in buf

Return

length of data successfully read

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

: Event type

Param param

: Pointer to callback parameter

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

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

enumerator ESP_HF_WBS_RESPONSE_EVT

Codec Status

enumerator ESP_HF_BCS_RESPONSE_EVT

Final Codec Choice

Provide feedback about this document