HFP AG API¶
Overview¶
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, used by HFP AG.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: if callback is a NULL function pointer
- Parameters
callback
: HFP AG event callback function
-
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.
- Return
- ESP_OK: if the initialization request is sent successfully
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device address
-
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.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device address
-
esp_err_t
esp_bt_hf_connect
(esp_bd_addr_t remote_bda)¶ Connect to remote bluetooth HFP client device, must after esp_bt_hf_init()
- Return
- ESP_OK: connect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth HFP client device address
-
esp_err_t
esp_bt_hf_disconnect
(esp_bd_addr_t remote_bda)¶ Disconnect from the remote HFP client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
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 between HF client and AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
esp_err_t
esp_bt_hf_disconnect_audio
(esp_bd_addr_t remote_bda)¶ Release the established audio connection with remote HFP client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
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.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: volume control target, speaker or microphonevalue
: gain of the speaker of microphone, ranges 0 to 15
-
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.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device addresstype
: volume control target, speaker or microphonevolume
: gain of the speaker of microphone, ranges 0 to 15
-
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 between AG and HF Client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressunat
: User AT command response to HF Client. It will response “ERROR” by default if unat is NULL.
-
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 between AG and HF Client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device addressresponse_code
: AT command response codeerror_code
: CME error code
-
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 between AG and HF Client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addresscall_state
: call statecall_setup_state
: call setup statentk_state
: network service statesignal
: signal strength from 0 to 5
-
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 between AG and HF Client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addresscall_state
: call statecall_setup_state
: call setup statentk_state
: network service statesignal
: signal strength from 0 to 5roam
: roam statebatt_lev
: batery level from 0 to 5call_held_status
: call held status
-
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.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressname
: current operator name
-
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 between AG and HF Client.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressindex
: the index of current calldir
: call direction (incoming/outgoing)current_call_state
: current call statemode
: current call mode (voice/data/fax)mpty
: single or multi typenumber
: current call numbertype
: international type or unknow
-
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 AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressnumber
: registration numbertype
: service type (unknown/voice/fax)
-
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 AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressstate
: in-band ring tone state
-
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 AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressnum_active
: the number of active callnum_held
: the number of held callcall_state
: call statecall_setup_state
: call setup statenumber
: number of the incoming callcall_addr_type
: call address type
-
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 AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressnum_active
: the number of active callnum_held
: the number of held callcall_state
: call statecall_setup_state
: call setup statenumber
: number of the incoming callcall_addr_type
: call address type
-
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)¶ Reject incoming call from AG. As a precondition to use this API, Service Level Connection shall exist with AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressnum_active
: the number of active callnum_held
: the number of held callcall_state
: call statecall_setup_state
: call setup statenumber
: number of the outgoing callcall_addr_type
: call address type
-
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 AG.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_addr
: remote bluetooth device addressnum_active
: the number of active callnum_held
: the number of held callcall_state
: call statecall_setup_state
: call setup statenumber
: number of the callcall_addr_type
: call address type
-
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.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: if callback is a NULL function pointer
- Parameters
recv
: HFP client incoming data callback functionsend
: HFP client outgoing data callback function
-
void
esp_hf_outgoing_data_ready
(void)¶ Trigger the lower-layer to fetch and send audio data. This function is only only used in the case that Voice Over HCI is enabled. Precondition is that the HFP audio connection is connected. 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
-
esp_bd_addr_t
-
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
-
esp_hf_wbs_config_t
-
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
-
esp_hf_call_status_t
-
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
-
esp_bd_addr_t
-
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
-
esp_hf_nrec_t
-
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
-
esp_bd_addr_t
-
struct
hf_unat_rep_param
¶ - #include <esp_hf_ag_api.h>
ESP_HF_UNAT_RESPOSNE_EVT.
Public Members
-
char *
unat
¶ unknown AT command string
-
char *
-
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
-
esp_hf_volume_type_t
-
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
-
esp_bd_addr_t
-
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
-
char *
-
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
-
esp_hf_wbs_config_t
-
struct esp_hf_cb_param_t::hf_conn_stat_param
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_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.
- Parameters
buf
: : 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.len
: : 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.
- Parameters
buf
: : 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.len
: : size(in bytes) in buflength
: 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.
- Parameters
event
: : Event typeparam
: : Pointer to callback parameter
Enumerations¶
-
enum
esp_hf_cb_event_t
¶ HF callback events.
Values:
-
ESP_HF_CONNECTION_STATE_EVT
= 0¶ Connection state changed event
-
ESP_HF_AUDIO_STATE_EVT
¶ Audio connection state change event
-
ESP_HF_BVRA_RESPONSE_EVT
¶ Voice recognition state change event
-
ESP_HF_VOLUME_CONTROL_EVT
¶ Audio volume control command from HF Client, provided by +VGM or +VGS message
-
ESP_HF_UNAT_RESPONSE_EVT
¶ Unknown AT cmd Response
-
ESP_HF_IND_UPDATE_EVT
¶ Indicator Update Event
-
ESP_HF_CIND_RESPONSE_EVT
¶ Call And Device Indicator Response
-
ESP_HF_COPS_RESPONSE_EVT
¶ Current operator information
-
ESP_HF_CLCC_RESPONSE_EVT
¶ List of current calls notification
-
ESP_HF_CNUM_RESPONSE_EVT
¶ Subscriber information response from HF Client
-
ESP_HF_VTS_RESPONSE_EVT
¶ Enable or not DTMF
-
ESP_HF_NREC_RESPONSE_EVT
¶ Enable or not NREC
-
ESP_HF_ATA_RESPONSE_EVT
¶ Answer an Incoming Call
-
ESP_HF_CHUP_RESPONSE_EVT
¶ Reject an Incoming Call
-
ESP_HF_DIAL_EVT
¶ Origin an outgoing call with specific number or the dial the last number
-
ESP_HF_WBS_RESPONSE_EVT
¶ Codec Status
-
ESP_HF_BCS_RESPONSE_EVT
¶ Final Codec Choice
-