HFP CLIENT API

Overview

Instructions

API Reference

Functions

esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback)

Register application callback function to HFP client module. This function should be called only after esp_bluedroid_enable() completes successfully, used by HFP client.

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 client event callback function

esp_err_t esp_hf_client_init(void)

Initialize the bluetooth HFP client 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

esp_err_t esp_hf_client_deinit(void)

De-initialize for HFP client 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

esp_err_t esp_hf_client_connect(esp_bd_addr_t remote_bda)

Connect to remote bluetooth HFP audio gateway(AG) device, must after esp_hf_client_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 device address

esp_err_t esp_hf_client_disconnect(esp_bd_addr_t remote_bda)

Disconnect from the remote HFP audio gateway.

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_hf_client_connect_audio(esp_bd_addr_t remote_bda)

Create audio connection with remote HFP 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_bda: remote bluetooth device address

esp_err_t esp_hf_client_disconnect_audio(esp_bd_addr_t remote_bda)

Release the established audio connection with remote HFP 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_hf_client_start_voice_recognition(void)

Enable voice recognition in the 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

esp_err_t esp_hf_client_stop_voice_recognition(void)

Disable voice recognition in the 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

esp_err_t esp_hf_client_volume_update(esp_hf_volume_control_target_t type, int volume)

Volume synchronization with 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
  • type: volume control target, speaker or microphone
  • volume: gain of the speaker of microphone, ranges 0 to 15

esp_err_t esp_hf_client_dial(const char *number)

Place a call with a specified number, if number is NULL, last called number is called. 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
  • number: number string of the call. If NULL, the last number is called(aka re-dial)

esp_err_t esp_hf_client_dial_memory(int location)

Place a call with number specified by location(speed dial). 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
  • location: location of the number in the memory

esp_err_t esp_hf_client_send_chld_cmd(esp_hf_chld_type_t chld, int idx)

Send call hold and multiparty commands, or enhanced call control commands(Use AT+CHLD). 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
  • chld: AT+CHLD call hold and multiparty handling AT command.
  • idx: used in Enhanced Call Control Mechanisms, used if chld is ESP_HF_CHLD_TYPE_REL_X or ESP_HF_CHLD_TYPE_PRIV_X

esp_err_t esp_hf_client_send_btrh_cmd(esp_hf_btrh_cmd_t btrh)

Send response and hold action command(Send AT+BTRH command) 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
  • btrh: response and hold action to send

esp_err_t esp_hf_client_answer_call(void)

Answer an incoming call(send ATA command). 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

esp_err_t esp_hf_client_reject_call(void)

Reject an incoming call(send AT+CHUP command), 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

esp_err_t esp_hf_client_query_current_calls(void)

Query list of current calls in AG(send AT+CLCC command), 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

esp_err_t esp_hf_client_query_current_operator_name(void)

Query the name of currently selected network operator in AG(use AT+COPS commands) 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

esp_err_t esp_hf_client_retrieve_subscriber_info(void)

Get subscriber information number from AG(send AT+CNUM command) 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

esp_err_t esp_hf_client_send_dtmf(char code)

Transmit DTMF codes during an ongoing call(use AT+VTS commands) 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
  • code: dtmf code, single ascii character in the set 0-9, #, *, A-D

esp_err_t esp_hf_client_request_last_voice_tag_number(void)

Request a phone number from AG corresponding to last voice tag recorded (send AT+BINP command). 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

esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv, esp_hf_client_outgoing_data_cb_t send)

Register HFP client 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 function
  • send: HFP client outgoing data callback function

void esp_hf_client_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.

void esp_hf_client_pcm_resample_init(uint32_t src_sps, uint32_t bits, uint32_t channels)

Initialize the down sampling converter. This is a utility function that can only be used in the case that Voice Over HCI is enabled.

Parameters
  • src_sps: original samples per second(source audio data, i.e. 48000, 32000, 16000, 44100, 22050, 11025)
  • bits: number of bits per pcm sample (16)
  • channels: number of channels (i.e. mono(1), stereo(2)…)

int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst)

Down sampling utility to convert high sampling rate into 8K/16bits 1-channel mode PCM samples. This can only be used in the case that Voice Over HCI is enabled.

Return
number of samples converted
Parameters
  • src: pointer to the buffer where the original smapling PCM are stored
  • in_bytes: length of the input PCM sample buffer in byte
  • dst: pointer to the buffer which is to be used to store the converted PCM samples

Unions

union esp_hf_client_cb_param_t
#include <esp_hf_client_api.h>

HFP client callback parameters.

Public Members

struct esp_hf_client_cb_param_t::hf_client_conn_stat_param conn_stat

HF callback param of ESP_HF_CLIENT_CONNECTION_STATE_EVT

struct esp_hf_client_cb_param_t::hf_client_audio_stat_param audio_stat

HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT

struct esp_hf_client_cb_param_t::hf_client_bvra_param bvra

HF callback param of ESP_HF_CLIENT_BVRA_EVT

struct esp_hf_client_cb_param_t::hf_client_service_availability_param service_availability

HF callback param of ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT

struct esp_hf_client_cb_param_t::hf_client_network_roaming_param roaming

HF callback param of ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT

struct esp_hf_client_cb_param_t::hf_client_signal_strength_ind_param signal_strength

HF callback param of ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT

struct esp_hf_client_cb_param_t::hf_client_battery_level_ind_param battery_level

HF callback param of ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT

struct esp_hf_client_cb_param_t::hf_client_current_operator_param cops

HF callback param of ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT

struct esp_hf_client_cb_param_t::hf_client_call_ind_param call

HF callback param of ESP_HF_CLIENT_CIND_CALL_EVT

struct esp_hf_client_cb_param_t::hf_client_call_setup_ind_param call_setup

HF callback param of ESP_HF_CLIENT_BVRA_EVT

struct esp_hf_client_cb_param_t::hf_client_call_held_ind_param call_held

HF callback param of ESP_HF_CLIENT_CIND_CALL_HELD_EVT

struct esp_hf_client_cb_param_t::hf_client_btrh_param btrh

HF callback param of ESP_HF_CLIENT_BRTH_EVT

struct esp_hf_client_cb_param_t::hf_client_clip_param clip

HF callback param of ESP_HF_CLIENT_CLIP_EVT

struct esp_hf_client_cb_param_t::hf_client_ccwa_param ccwa

HF callback param of ESP_HF_CLIENT_BVRA_EVT

struct esp_hf_client_cb_param_t::hf_client_clcc_param clcc

HF callback param of ESP_HF_CLIENT_CLCC_EVT

struct esp_hf_client_cb_param_t::hf_client_volume_control_param volume_control

HF callback param of ESP_HF_CLIENT_VOLUME_CONTROL_EVT

struct esp_hf_client_cb_param_t::hf_client_at_response_param at_response

HF callback param of ESP_HF_CLIENT_AT_RESPONSE_EVT

struct esp_hf_client_cb_param_t::hf_client_cnum_param cnum

HF callback param of ESP_HF_CLIENT_CNUM_EVT

struct esp_hf_client_cb_param_t::hf_client_bsirparam bsir

HF callback param of ESP_HF_CLIENT_BSIR_EVT

struct esp_hf_client_cb_param_t::hf_client_binp_param binp

HF callback param of ESP_HF_CLIENT_BINP_EVT

struct hf_client_at_response_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_AT_RESPONSE_EVT.

Public Members

esp_hf_at_response_code_t code

AT response code

esp_hf_cme_err_t cme

Extended Audio Gateway Error Result Code

struct hf_client_audio_stat_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_AUDIO_STATE_EVT.

Public Members

esp_hf_client_audio_state_t state

audio connection state

esp_bd_addr_t remote_bda

remote bluetooth device address

struct hf_client_battery_level_ind_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT.

Public Members

int value

battery charge value, ranges from 0 to 5

struct hf_client_binp_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_BINP_EVT.

Public Members

const char *number

phone number corresponding to the last voice tag in the HF

struct hf_client_bsirparam
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_BSIR_EVT.

Public Members

esp_hf_client_in_band_ring_state_t state

setting state of in-band ring tone

struct hf_client_btrh_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_BTRH_EVT.

Public Members

esp_hf_btrh_status_t status

call hold and response status result code

struct hf_client_bvra_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_BVRA_EVT.

Public Members

esp_hf_vr_state_t value

voice recognition state

struct hf_client_call_held_ind_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_CALL_HELD_EVT.

Public Members

esp_hf_call_held_status_t status

bluetooth proprietary call hold status indocator

struct hf_client_call_ind_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_CALL_EVT.

Public Members

esp_hf_call_status_t status

call status indicator

struct hf_client_call_setup_ind_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_CALL_SETUP_EVT.

Public Members

esp_hf_call_setup_status_t status

call setup status indicator

struct hf_client_ccwa_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CCWA_EVT.

Public Members

const char *number

phone number string of waiting call

struct hf_client_clcc_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CLCC_EVT.

Public Members

int idx

numbering(starting with 1) of the call

esp_hf_current_call_direction_t dir

direction of the call

esp_hf_current_call_status_t status

status of the call

esp_hf_current_call_mpty_type_t mpty

multi-party flag

char *number

phone number(optional)

struct hf_client_clip_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CLIP_EVT.

Public Members

const char *number

phone number string of call

struct hf_client_cnum_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CNUM_EVT.

Public Members

const char *number

phone number string

esp_hf_subscriber_service_type_t type

service type that the phone number relates to

struct hf_client_conn_stat_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CONNECTION_STATE_EVT.

Public Members

esp_hf_client_connection_state_t state

HF connection state

uint32_t peer_feat

AG supported features

uint32_t chld_feat

AG supported features on call hold and multiparty services

esp_bd_addr_t remote_bda

remote bluetooth device address

struct hf_client_current_operator_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT.

Public Members

const char *name

name of the network operator

struct hf_client_network_roaming_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT.

Public Members

esp_hf_roaming_status_t status

roaming status

struct hf_client_service_availability_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT.

Public Members

esp_hf_service_availability_status_t status

service availability status

struct hf_client_signal_strength_ind_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT.

Public Members

int value

singal strength value, ranges from 0 to 5

struct hf_client_volume_control_param
#include <esp_hf_client_api.h>

ESP_HF_CLIENT_VOLUME_CONTROL_EVT.

Public Members

esp_hf_volume_control_target_t type

volume control target, speaker or microphone

int volume

gain, ranges from 0 to 15

Macros

ESP_BT_HF_CLIENT_NUMBER_LEN
ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN
ESP_HF_CLIENT_PEER_FEAT_3WAY
ESP_HF_CLIENT_PEER_FEAT_ECNR
ESP_HF_CLIENT_PEER_FEAT_VREC
ESP_HF_CLIENT_PEER_FEAT_INBAND
ESP_HF_CLIENT_PEER_FEAT_VTAG
ESP_HF_CLIENT_PEER_FEAT_REJECT
ESP_HF_CLIENT_PEER_FEAT_ECS
ESP_HF_CLIENT_PEER_FEAT_ECC
ESP_HF_CLIENT_PEER_FEAT_EXTERR
ESP_HF_CLIENT_PEER_FEAT_CODEC
ESP_HF_CLIENT_CHLD_FEAT_REL
ESP_HF_CLIENT_CHLD_FEAT_REL_ACC
ESP_HF_CLIENT_CHLD_FEAT_REL_X
ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC
ESP_HF_CLIENT_CHLD_FEAT_PRIV_X
ESP_HF_CLIENT_CHLD_FEAT_MERGE
ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH

Type Definitions

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

HFP client 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_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len)

HFP client 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 buf
  • length: of data successfully read

typedef void (*esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t *param)

HFP client callback function type.

Parameters
  • event: : Event type
  • param: : Pointer to callback parameter

Enumerations

enum esp_hf_client_connection_state_t

Bluetooth HFP RFCOMM connection and service level connection status.

Values:

ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTED = 0

RFCOMM data link channel released

ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING

connecting remote device on the RFCOMM data link

ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED

RFCOMM connection established

ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED

service level connection established

ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING

disconnecting with remote device on the RFCOMM dat link

enum esp_hf_client_audio_state_t

Bluetooth HFP audio connection status.

Values:

ESP_HF_CLIENT_AUDIO_STATE_DISCONNECTED = 0

audio connection released

ESP_HF_CLIENT_AUDIO_STATE_CONNECTING

audio connection has been initiated

ESP_HF_CLIENT_AUDIO_STATE_CONNECTED

audio connection is established

ESP_HF_CLIENT_AUDIO_STATE_CONNECTED_MSBC

mSBC audio connection is estalibshed

enum esp_hf_client_in_band_ring_state_t

in-band ring tone state

Values:

ESP_HF_CLIENT_IN_BAND_RINGTONE_NOT_PROVIDED = 0
ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED
enum esp_hf_client_cb_event_t

HF CLIENT callback events.

Values:

ESP_HF_CLIENT_CONNECTION_STATE_EVT = 0

connection state changed event

ESP_HF_CLIENT_AUDIO_STATE_EVT

audio connection state change event

ESP_HF_CLIENT_BVRA_EVT

voice recognition state change event

ESP_HF_CLIENT_CIND_CALL_EVT

call indication

ESP_HF_CLIENT_CIND_CALL_SETUP_EVT

call setup indication

ESP_HF_CLIENT_CIND_CALL_HELD_EVT

call held indication

ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT

network service availability indication

ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT

signal strength indication

ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT

roaming status indication

ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT

battery level indication

ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT

current operator information

ESP_HF_CLIENT_BTRH_EVT

call response and hold event

ESP_HF_CLIENT_CLIP_EVT

Calling Line Identification notification

ESP_HF_CLIENT_CCWA_EVT

call waiting notification

ESP_HF_CLIENT_CLCC_EVT

list of current calls notification

ESP_HF_CLIENT_VOLUME_CONTROL_EVT

audio volume control command from AG, provided by +VGM or +VGS message

ESP_HF_CLIENT_AT_RESPONSE_EVT

AT command response event

ESP_HF_CLIENT_CNUM_EVT

subscriber information response from AG

ESP_HF_CLIENT_BSIR_EVT

setting of in-band ring tone

ESP_HF_CLIENT_BINP_EVT

requested number of last voice tag from AG

ESP_HF_CLIENT_RING_IND_EVT

ring indication event