ESP-IDF 蓝牙经典 HFP 协议定义详解esp_hf_defs 常量、枚举与数据结构完全指南【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读本文围绕 ESP-IDF 中蓝牙经典Classic Bluetooth免提协议Hands-Free Profile, HFP的公共定义头文件展开系统讲解 HFP 涉及的连接状态、通话管理、音频控制、网络状态上报等核心常量、枚举与数据结构并结合 esp_hf_defs.h 源码与hfp_hf、hfp_ag两个官方示例说明每个定义在实际开发中的语义与用法。读完本文你将能够准确理解 HFP 客户端HF与音频网关AG通信时所有 AT 事件与状态机字段的含义并能在自己的蓝牙免提应用中正确使用这些类型。一、文档定位与作用本文所对应的官方 API 参考文档为 esp_hf_defs.rst它是 ESP-IDF 蓝牙经典 HFP 协议族Hands-Free Client 与 Hands-Free Audio Gateway的定义层文档其核心内容通过include-build-file:: inc/esp_hf_defs.inc直接由头文件 esp_hf_defs.h 自动生成。与 esp_hf_client_api.hHF 客户端 API、esp_hf_ag_api.h音频网关 API不同esp_hf_defs.h本身不包含任何函数声明它只负责定义两类东西HFP 协议层面的状态机枚举——如连接状态、音频连接状态、通话状态、呼叫保持状态等AT 命令与结果码相关的枚举与宏——如CIND、CLCC、CHLD、BTRH、CME等 AT 指令涉及的取值。也就是说无论你编写 HF 客户端相当于耳机侧还是 AG相当于手机侧应用回调事件中携带的所有状态字段最终都要对照这一定义文件来解析。它是理解 HFP 事件回调的字典。二、两个官方示例HFP 定义的实际应用场景文档明确给出了两个开箱即用的示例它们分别演示了上述定义的两种消费方式2.1 hfp_hf免提客户端示例examples/bluetooth/bluedroid/classic_bt/hfp_hf 演示如何使用Hands-Free Client 组件与实现了免提音频网关HF-AG的设备例如智能手机通信。该示例会把音频数据回送给 AG 设备因此连接后你能听到自己的声音。在示例的 bt_app_hf.c 回调处理中esp_hf_client_connection_state_t、esp_hf_client_audio_state_t、esp_hf_client_call_state_t等事件参数正是基于esp_hf_defs.h中定义的状态语义进行日志打印的。例如建立服务级连接后打印--connection state slc_connected, peer feats 0x16e, chld_feats 0x0其中slc_connected对应的正是下文将要介绍的ESP_HF_CONNECTION_STATE_SLC_CONNECTED。2.2 hfp_ag免提音频网关示例examples/bluetooth/bluedroid/classic_bt/hfp_ag 演示如何使用Hands-Free Audio GatewayHF-AG组件与实现了免提客户端角色的设备例如耳机通信并提供了一系列命令用于配置工程、建立连接、控制音量以及接听/拒接来电。两个示例的工程结构几乎完全对称bt_app_hf.c负责事件回调与日志、app_hf_msg_set.c维护 UART 命令表、gpio_pcm_config.c配置 PCM 音频接口。建议先运行hfp_ag网关再用hfp_hf客户端与之配对联调即可在日志中直观观察下文的各类状态枚举变化。提示示例的完整菜单配置数据通路 PCM/vHCI、编解码 CVSD/mSBC、PCM 信号角色/极性/声道模式参见两个示例各自的 README.md。三、核心枚举逐项详解3.1 连接状态RFCOMM 与服务级连接SLCtypedef enum { ESP_HF_CONNECTION_STATE_DISCONNECTED 0, /* RFCOMM 数据链路已释放 */ ESP_HF_CONNECTION_STATE_CONNECTING, /* 正在与远端设备建立 RFCOMM 数据链路 */ ESP_HF_CONNECTION_STATE_CONNECTED, /* RFCOMM 连接已建立 */ ESP_HF_CONNECTION_STATE_SLC_CONNECTED, /* 服务级连接SLC已建立 */ ESP_HF_CONNECTION_STATE_DISCONNECTING, /* 正在与远端设备断开 RFCOMM 数据链路 */ } esp_hf_connection_state_t;HFP 的连接分为两层先是底层RFCOMM 数据链路状态CONNECTING → CONNECTED随后双方通过 AT 命令握手建立服务级连接 SLCService Level Connection状态SLC_CONNECTED。从 hfp_hf README 的实际日志可以清晰看到这一跃迁过程connect I (79642) BT_HF: APP HFP event: CONNECTION_STATE_EVT I (79642) BT_HF: --connection state connected, peer feats 0x0, chld_feats 0x0 ... I (79852) BT_HF: APP HFP event: CONNECTION_STATE_EVT I (79862) BT_HF: --connection state slc_connected, peer feats 0x16e, chld_feats 0x0只有当状态到达ESP_HF_CONNECTION_STATE_SLC_CONNECTED之后拨号、音量控制、语音识别等其余 HFP 命令才可用官方文档与示例中对此有明确说明。3.2 音频连接状态与 mSBCtypedef enum { ESP_HF_AUDIO_STATE_DISCONNECTED 0, /* 音频连接已释放 */ ESP_HF_AUDIO_STATE_CONNECTING, /* 音频连接已发起 */ ESP_HF_AUDIO_STATE_CONNECTED, /* 音频连接已建立 */ ESP_HF_AUDIO_STATE_CONNECTED_MSBC, /* mSBC 音频连接已建立 */ } esp_hf_audio_state_t;HFP 的音频通道建立在 SCO/eSCO 链路上。该枚举用于区分普通 CVSD 音频连接CONNECTED与宽带语音 mSBC 连接CONNECTED_MSBC。示例日志展示了典型过程connect audio I (117232) BT_HF: APP HFP event: AUDIO_STATE_EVT I (117232) BT_HF: --audio state connecting E (117262) BT_BTM: btm_sco_connected, handle 181 I (117262) BT_HF: APP HFP event: AUDIO_STATE_EVT I (117262) BT_HF: --audio state connected根据示例说明以下场景会自动建立音频连接接听来电、启用语音识别、拨出电话以下场景会断开音频连接拒接来电、关闭语音识别。3.3 来电相关状态CIND 指示器CIND是 AG 上报的通话状态指示器集合esp_hf_defs.h为每个指示器单独定义了枚举枚举取值含义esp_hf_call_status_tNO_CALLS0/CALL_IN_PROGRESS1是否有通话正在进行活动或保持esp_hf_call_setup_status_tIDLE0/INCOMING1/OUTGOING_DIALING2/OUTGOING_ALERTING3呼叫建立阶段esp_hf_call_held_status_tNONE0/HELD_AND_ACTIVE1/HELD2呼叫保持状态esp_hf_network_state_tNOT_AVAILABLE0/AVAILABLE1网络服务可用性esp_hf_roaming_status_tINACTIVE0/ACTIVE1漫游状态这些枚举直接对应CIEV事件上报esp_hf_ciev_report_type_ttypedef enum { ESP_HF_IND_TYPE_CALL 1, /* call 指示器 */ ESP_HF_IND_TYPE_CALLSETUP, /* callsetup 指示器 */ ESP_HF_IND_TYPE_SERVICE, /* service 指示器 */ ESP_HF_IND_TYPE_SIGNAL, /* 信号强度指示器范围 0-5 */ ESP_HF_IND_TYPE_ROAM, /* 漫游指示器 */ ESP_HF_IND_TYPE_BATTCHG, /* 电量指示器范围 0-5 */ ESP_HF_IND_TYPE_CALLHELD /* callheld 指示器 */ } esp_hf_ciev_report_type_t;在hfp_hf示例中建立 SLC 后 AG 会依次推送全部指示器对应日志为I (79792) BT_HF: --Call indicator NO call in progress I (79802) BT_HF: --Call setup indicator NONE I (79812) BT_HF: --NETWORK STATE available I (79822) BT_HF: -- signal strength: 4 I (79832) BT_HF: --ROAMING: inactive I (79842) BT_HF: --battery level 3 I (79852) BT_HF: --Call held indicator NONE held服务类型由esp_hf_service_type_t描述HOME0表示归属地、ROAMING1表示漫游。3.4 当前通话列表CLCC 相关枚举CLCC用于列出当前通话一组枚举完整刻画每条通话的属性typedef enum { ESP_HF_CURRENT_CALL_STATUS_ACTIVE 0, /* 活动 */ ESP_HF_CURRENT_CALL_STATUS_HELD 1, /* 保持 */ ESP_HF_CURRENT_CALL_STATUS_DIALING 2, /* 拨号中仅呼出 */ ESP_HF_CURRENT_CALL_STATUS_ALERTING 3, /* 振铃中仅呼出 */ ESP_HF_CURRENT_CALL_STATUS_INCOMING 4, /* 来电仅呼入 */ ESP_HF_CURRENT_CALL_STATUS_WAITING 5, /* 等待中仅呼入 */ ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD 6, /* 被响应保持BTRH */ } esp_hf_current_call_status_t; typedef enum { ESP_HF_CURRENT_CALL_DIRECTION_OUTGOING 0, /* 呼出 */ ESP_HF_CURRENT_CALL_DIRECTION_INCOMING 1, /* 呼入 */ } esp_hf_current_call_direction_t; typedef enum { ESP_HF_CURRENT_CALL_MPTY_TYPE_SINGLE 0, /* 非多方通话成员 */ ESP_HF_CURRENT_CALL_MPTY_TYPE_MULTI 1, /* 多方通话成员 */ } esp_hf_current_call_mpty_type_t; typedef enum { ESP_HF_CURRENT_CALL_MODE_VOICE 0, /* 语音呼叫 */ ESP_HF_CURRENT_CALL_MODE_DATA 1, /* 数据呼叫 */ ESP_HF_CURRENT_CALL_MODE_FAX 2, /* 传真呼叫 */ } esp_hf_current_call_mode_t; typedef enum { ESP_HF_CALL_ADDR_TYPE_UNKNOWN 0x81, /* 未知地址类型 */ ESP_HF_CALL_ADDR_TYPE_INTERNATIONAL 0x91, /* 国际地址 */ } esp_hf_call_addr_type_t;注意ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD与BTRH响应与保持机制相关联而地址类型取值沿用了 GSM/ETSI 对电话号码类型的编码0x81 未知、0x91 国际。示例中查询当前通话列表命令qc的典型输出为I (354582) BT_HF: APP HFP event: CLCC_EVT I (354582) BT_HF: --Current call: idx 1, dir incoming, state active, mpty single, number 186xxxx55493.5 呼叫保持与三方通话CHLD 命令typedef enum { ESP_HF_CHLD_TYPE_REL 0, /* 0 结束所有保持通话或向等待通话返回忙音 */ ESP_HF_CHLD_TYPE_REL_ACC, /* 1 结束所有活动通话并接听等待/保持通话 */ ESP_HF_CHLD_TYPE_HOLD_ACC, /* 2 保持所有活动通话并接听等待/保持通话 */ ESP_HF_CHLD_TYPE_MERGE, /* 3 将所有保持通话加入电话会议 */ ESP_HF_CHLD_TYPE_MERGE_DETACH, /* 4 连接两路通话并断开用户与二者的连接 */ ESP_HF_CHLD_TYPE_REL_X, /* 1x 仅结束指定通话 */ ESP_HF_CHLD_TYPE_PRIV_X, /* 2x 与指定通话建立私有咨询模式 */ } esp_hf_chld_type_t;该枚举完整映射了 HFP 规范中ATCHLD的全部取值覆盖挂断、接听、保持、合并会议、指定通话操作五类场景。AG 侧通过chld_feats位域向上报支持哪些CHLD操作。3.6 响应与保持BTRHtypedef enum { ESP_HF_BTRH_STATUS_HELD 0, /* 来电已在 AG 侧被保持 */ ESP_HF_BTRH_STATUS_ACCEPTED, /* 被保持的来电已在 AG 侧被接听 */ ESP_HF_BTRH_STATUS_REJECTED, /* 被保持的来电已在 AG 侧被拒接 */ } esp_hf_btrh_status_t; typedef enum { ESP_HF_BTRH_CMD_HOLD 0, /* 将来电置于保持 */ ESP_HF_BTRH_CMD_ACCEPT 1, /* 接听被保持的来电 */ ESP_HF_BTRH_CMD_REJECT 2, /* 拒接被保持的来电 */ } esp_hf_btrh_cmd_t;esp_hf_btrh_cmd_t是客户端HF通过ATBTRH发送的指令esp_hf_btrh_status_t是网关AG返回的状态。在hfp_hf示例中对应命令rh btrh参数 0/1/2 分别表示保持当前通话、接听保持的通话、结束保持的通话。3.7 音量控制typedef enum { ESP_HF_VOLUME_CONTROL_TARGET_SPK 0, /* 扬声器 */ ESP_HF_VOLUME_CONTROL_TARGET_MIC, /* 麦克风 */ } esp_hf_volume_control_target_t; typedef enum { ESP_HF_VOLUME_TYPE_SPK 0, /* 扬声器 */ ESP_HF_VOLUME_TYPE_MIC /* 麦克风 */ } esp_hf_volume_type_t;两个枚举分别用于下发音量增益命令ESP_HF_VOLUME_CONTROL_TARGET_*和解析VGS/VGM上报事件ESP_HF_VOLUME_TYPE_*。示例命令格式为vu tgt vol其中tgt取值 0扬声器/1麦克风vol为 0–15 的整数vu 0 9 → AG 侧日志--Volume Target: SPEAKER, Volume 9 vu 1 9 → AG 侧日志--Volume Target: MICROPHONE, Volume 93.8 语音识别、响铃与 NRECtypedef enum { ESP_HF_VR_STATE_DISABLED 0, /* 语音识别关闭 */ ESP_HF_VR_STATE_ENABLED, /* 语音识别开启 */ } esp_hf_vr_state_t; typedef enum { ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED 0, /* 免提设备不提供带内铃声 */ ESP_HF_IN_BAND_RINGTONE_PROVIDED, /* 免提设备提供带内铃声 */ } esp_hf_in_band_ring_state_t; typedef enum { ESP_HF_NREC_STOP 0, /* 停止 NREC */ ESP_HF_NREC_START /* 启动 NREC */ } esp_hf_nrec_t;esp_hf_vr_state_t对应BVRA客户端可用vron/vroff命令开启/关闭 AG 的语音识别开启时通常伴随音频连接建立示例日志中Start voice recognition后即出现audio state connected。esp_hf_in_band_ring_state_t对应BSIR指示来电时是否由 AG 通过 SCO 链路下发带内铃声。示例建立 SLC 后打印--inband ring state Provided。esp_hf_nrec_t对应NREC控制回声消除/降噪NREC的启停。3.9 其他状态枚举esp_hf_prof_state_t初始化状态机取值ESP_HF_INIT_SUCCESS / ESP_HF_INIT_ALREADY / ESP_HF_INIT_FAIL / ESP_HF_DEINIT_SUCCESS / ESP_HF_DEINIT_ALREADY / ESP_HF_DEINIT_FAIL供esp_hf_client_init()/esp_hf_ag_init()等接口返回。esp_hf_call_waiting_status_tCCWA呼叫等待状态INACTIVE/ACTIVE。esp_hf_subscriber_service_type_tCNUM电话号码的服务类型UNKNOWN0/VOICE4/FAX5。示例rs命令输出--subscriber type unknown, number 186xxxx5549即对应此枚举。esp_hf_wbs_config_t宽带语音编解码配置WBS_NONE/WBS_NO/WBS_YES与菜单Component config -- Bluetooth -- Bluedroid Options -- Wide Band Speech对应。四、AT 响应码与 CME 扩展错误4.1 通用 AT 响应码typedef enum { ESP_HF_AT_RESPONSE_CODE_OK 0, /* 命令执行成功 */ ESP_HF_AT_RESPONSE_CODE_ERR, /* 命令未被接受 */ ESP_HF_AT_RESPONSE_CODE_NO_CARRIER, /* 连接终止 */ ESP_HF_AT_RESPONSE_CODE_BUSY, /* 检测到忙音 */ ESP_HF_AT_RESPONSE_CODE_NO_ANSWER, /* 连接建立超时 */ ESP_HF_AT_RESPONSE_CODE_DELAYED, /* 延迟 */ ESP_HF_AT_RESPONSE_CODE_BLACKLISTED, /* 被列入黑名单 */ ESP_HF_AT_RESPONSE_CODE_CME, /* CME 错误 */ } esp_hf_at_response_code_t; typedef enum { ESP_HF_AT_RESPONSE_ERROR 0, /* AT 命令响应出错 */ ESP_HF_AT_RESPONSE_OK /* AT 命令响应成功 */ } esp_hf_at_response_t;示例中每次 AT 操作完成后都会收到AT_RESPONSE事件日志--AT response event, code 0, cme 0表示esp_hf_at_response_t为ESP_HF_AT_RESPONSE_OK且无 CME 错误。当code为ESP_HF_AT_RESPONSE_CODE_CME时需要通过下文的esp_hf_cme_err_t进一步解析cme字段。4.2 扩展音频网关错误结果码CME ERRORtypedef enum { ESP_HF_CME_AG_FAILURE 0, /* AG 故障 */ ESP_HF_CME_NO_CONNECTION_TO_PHONE 1, /* 无电话连接 */ ESP_HF_CME_OPERATION_NOT_ALLOWED 3, /* 操作不允许 */ ESP_HF_CME_OPERATION_NOT_SUPPORTED 4, /* 操作不支持 */ ESP_HF_CME_PH_SIM_PIN_REQUIRED 5, /* 需要 PH-SIM PIN */ ESP_HF_CME_SIM_NOT_INSERTED 10, /* 未插入 SIM 卡 */ ESP_HF_CME_SIM_PIN_REQUIRED 11, /* 需要 SIM PIN */ ESP_HF_CME_SIM_PUK_REQUIRED 12, /* 需要 SIM PUK */ ESP_HF_CME_SIM_FAILURE 13, /* SIM 故障 */ ESP_HF_CME_SIM_BUSY 14, /* SIM 忙 */ ESP_HF_CME_INCORRECT_PASSWORD 16, /* 密码错误 */ ESP_HF_CME_SIM_PIN2_REQUIRED 17, /* 需要 SIM PIN2 */ ESP_HF_CME_SIM_PUK2_REQUIRED 18, /* 需要 SIM PUK2 */ ESP_HF_CME_MEMORY_FULL 20, /* 存储已满 */ ESP_HF_CME_INVALID_INDEX 21, /* 非法索引 */ ESP_HF_CME_MEMORY_FAILURE 23, /* 存储故障 */ ESP_HF_CME_TEXT_STRING_TOO_LONG 24, /* 文本串过长 */ ESP_HF_CME_INVALID_CHARACTERS_IN_TEXT_STRING 25, /* 文本串含非法字符 */ ESP_HF_CME_DIAL_STRING_TOO_LONG 26, /* 拨号串过长 */ ESP_HF_CME_INVALID_CHARACTERS_IN_DIAL_STRING 27, /* 拨号串含非法字符 */ ESP_HF_CME_NO_NETWORK_SERVICE 30, /* 无网络服务 */ ESP_HF_CME_NETWORK_TIMEOUT 31, /* 网络超时 */ ESP_HF_CME_NETWORK_NOT_ALLOWED 32, /* 网络不允许仅限紧急呼叫 */ } esp_hf_cme_err_t;esp_hf_cme_err_t覆盖了 HFP/3GPP 定义的扩展错误码全集0–32是与 SIM、网络、存储、拨号串相关的错误定位依据。在调试拨号失败无法读取订阅信息等场景时应优先检查该枚举的取值。五、音频数据缓冲结构typedef struct { uint16_t buff_size; /* 缓冲区大小 */ uint16_t data_len; /* 音频数据长度不得大于缓冲区大小 */ uint8_t *data; /* 音频数据起始指针 */ } esp_hf_audio_buff_t;esp_hf_audio_buff_t是 HFP 音频数据在应用层与协议栈之间传递的载体在 vHCIHCI 数据通路模式下SCO 音频数据经由蓝牙控制器 → vHCI → Bluedroid 主机栈到达应用层时即通过该结构体承载。使用要点必须先填充buff_size并分配data指向的内存填充数据后更新data_len且必须满足data_len buff_size收发方向均为数据指针 长度模式便于零拷贝接入编解码器。六、mSBC 宽带语音的固定编解码参数HFP 的 mSBC 使用一组固定编码参数esp_hf_defs.h以宏形式给出方便应用层初始化音频管线#define ESP_HF_MSBC_CHANNEL_MODE Mono /* 声道模式单声道 */ #define ESP_HF_MSBC_SAMPLING_RATE 16 kHz /* 采样率16 kHz */ #define ESP_HF_MSBC_ALLOCATION_METHOD Loudness/* 分配方法响度 */ #define ESP_HF_MSBC_SUBBANDS 8 /* 子带数 */ #define ESP_HF_MSBC_BLOCK_LENGTH 15 /* 块长度 */ #define ESP_HF_MSBC_BITPOOL 26 /* 比特池 */ #define ESP_HF_MSBC_ENCODED_FRAME_SIZE 57 /* mSBC 编码后的帧大小字节 */mSBC 属于 SBC 编码的宽带16 kHz 采样变体帧结构固定8 个子带、每块 15 字节、bitpool 26每帧编码后恰好 57 字节。这些宏同时被 Bluedroid 主机栈软件编码器与示例应用使用是实现vHCI 数据通路 Wide Band Speech时对接编解码器的直接依据。需要特别说明编解码选择与数据通路的关系来自 hfp_hf/hfp_ag 示例 README数据通路为 PCM只能使用 CVSD编解码由硬件完成即使打开Wide Band Speech也无法使用 mSBC因为 mSBC 由 Bluedroid 主机栈以软件方式实现数据通路为 vHCI 且打开Wide Band Speech编解码在 Bluedroid 中完成实际使用 mSBC数据通路为 vHCI 但关闭Wide Band Speech编解码由硬件完成实际使用 CVSD。数据通路在menuconfig中分别通过两处配置决定须在编译烧录前完成Component config -- Bluetooth controller -- BR/EDR Sync(SCO/eSCO) default data path -- PCM/HCIComponent config -- Bluetooth -- Bluedroid Options -- Hands Free/Handset Profile -- audio(SCO) data path -- PCM/HCI七、实践要点与故障排查7.1 正确的初始化顺序根据 hfp_hf README 的 Troubleshooting 部分使用 HFP 必须遵循先调用esp_hf_client_register_callback()或 AG 侧esp_hf_ag_register_callback()注册用户回调再调用esp_hf_client_init()或esp_hf_ag_init()完成初始化之后才能建立服务级连接连接目标地址可直接硬编码在示例的bt_app.c中例如esp_bd_addr_t peer_addr {0xb4, 0xe6, 0x2d, 0xeb, 0x09, 0x93};。初始化返回的esp_hf_prof_state_t会明确区分首次成功ESP_HF_INIT_SUCCESS与重复初始化ESP_HF_INIT_ALREADY便于做幂等保护。7.2 命令可用性前提只有 HFP 服务完成初始化且SLC 已建立ESP_HF_CONNECTION_STATE_SLC_CONNECTED之后拨号d num/rd/dm index、应答ac、拒接rc、音量vu、语音识别vron/vroff、查询运营商qop、查询订阅信息rs、查询通话列表qc、DTMFk dtmf等命令才可用。此外并非所有 AG 设备都支持命令表中的全部 AT 功能遇到CME ERROR时应结合esp_hf_cme_err_t判断是不支持ESP_HF_CME_OPERATION_NOT_SUPPORTED 4还是其他原因。八、源码阅读指引如需深入源码验证上述定义的使用方式可按以下路径继续阅读定义头文件本体esp_hf_defs.h与本文对应的权威来源HF 客户端 API 与事件枚举esp_hf_client_api.h音频网关 API 与事件枚举esp_hf_ag_api.h客户端示例实现hfp_hf/main/bt_app_hf.c事件回调与状态打印、hfp_hf/main/app_hf_msg_set.c命令表音频网关示例实现hfp_ag/main/bt_app_hf.c中文版文档esp_hf_defs.rst与英文版同步维护结语esp_hf_defs.h虽然只包含常量、枚举与结构体却是连接 HFP 协议规范与 ESP-IDF 事件回调的桥梁连接状态机esp_hf_connection_state_t、esp_hf_audio_state_t、通话指示器esp_hf_call_status_t、esp_hf_call_setup_status_t、esp_hf_call_held_status_t、通话列表esp_hf_current_call_*、呼叫保持esp_hf_chld_type_t、响应保持esp_hf_btrh_*、AT 错误码esp_hf_at_response_code_t、esp_hf_cme_err_t以及 mSBC 固定参数共同构成了开发蓝牙免提应用时最常查阅的协议字典。配合hfp_hf/hfp_ag两个官方示例开发者可以快速在真实链路上验证每一个状态枚举的实际行为。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP-IDF 蓝牙经典 HFP 协议定义详解：esp_hf_defs 常量、枚举与数据结构完全指南
ESP-IDF 蓝牙经典 HFP 协议定义详解esp_hf_defs 常量、枚举与数据结构完全指南【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读本文围绕 ESP-IDF 中蓝牙经典Classic Bluetooth免提协议Hands-Free Profile, HFP的公共定义头文件展开系统讲解 HFP 涉及的连接状态、通话管理、音频控制、网络状态上报等核心常量、枚举与数据结构并结合 esp_hf_defs.h 源码与hfp_hf、hfp_ag两个官方示例说明每个定义在实际开发中的语义与用法。读完本文你将能够准确理解 HFP 客户端HF与音频网关AG通信时所有 AT 事件与状态机字段的含义并能在自己的蓝牙免提应用中正确使用这些类型。一、文档定位与作用本文所对应的官方 API 参考文档为 esp_hf_defs.rst它是 ESP-IDF 蓝牙经典 HFP 协议族Hands-Free Client 与 Hands-Free Audio Gateway的定义层文档其核心内容通过include-build-file:: inc/esp_hf_defs.inc直接由头文件 esp_hf_defs.h 自动生成。与 esp_hf_client_api.hHF 客户端 API、esp_hf_ag_api.h音频网关 API不同esp_hf_defs.h本身不包含任何函数声明它只负责定义两类东西HFP 协议层面的状态机枚举——如连接状态、音频连接状态、通话状态、呼叫保持状态等AT 命令与结果码相关的枚举与宏——如CIND、CLCC、CHLD、BTRH、CME等 AT 指令涉及的取值。也就是说无论你编写 HF 客户端相当于耳机侧还是 AG相当于手机侧应用回调事件中携带的所有状态字段最终都要对照这一定义文件来解析。它是理解 HFP 事件回调的字典。二、两个官方示例HFP 定义的实际应用场景文档明确给出了两个开箱即用的示例它们分别演示了上述定义的两种消费方式2.1 hfp_hf免提客户端示例examples/bluetooth/bluedroid/classic_bt/hfp_hf 演示如何使用Hands-Free Client 组件与实现了免提音频网关HF-AG的设备例如智能手机通信。该示例会把音频数据回送给 AG 设备因此连接后你能听到自己的声音。在示例的 bt_app_hf.c 回调处理中esp_hf_client_connection_state_t、esp_hf_client_audio_state_t、esp_hf_client_call_state_t等事件参数正是基于esp_hf_defs.h中定义的状态语义进行日志打印的。例如建立服务级连接后打印--connection state slc_connected, peer feats 0x16e, chld_feats 0x0其中slc_connected对应的正是下文将要介绍的ESP_HF_CONNECTION_STATE_SLC_CONNECTED。2.2 hfp_ag免提音频网关示例examples/bluetooth/bluedroid/classic_bt/hfp_ag 演示如何使用Hands-Free Audio GatewayHF-AG组件与实现了免提客户端角色的设备例如耳机通信并提供了一系列命令用于配置工程、建立连接、控制音量以及接听/拒接来电。两个示例的工程结构几乎完全对称bt_app_hf.c负责事件回调与日志、app_hf_msg_set.c维护 UART 命令表、gpio_pcm_config.c配置 PCM 音频接口。建议先运行hfp_ag网关再用hfp_hf客户端与之配对联调即可在日志中直观观察下文的各类状态枚举变化。提示示例的完整菜单配置数据通路 PCM/vHCI、编解码 CVSD/mSBC、PCM 信号角色/极性/声道模式参见两个示例各自的 README.md。三、核心枚举逐项详解3.1 连接状态RFCOMM 与服务级连接SLCtypedef enum { ESP_HF_CONNECTION_STATE_DISCONNECTED 0, /* RFCOMM 数据链路已释放 */ ESP_HF_CONNECTION_STATE_CONNECTING, /* 正在与远端设备建立 RFCOMM 数据链路 */ ESP_HF_CONNECTION_STATE_CONNECTED, /* RFCOMM 连接已建立 */ ESP_HF_CONNECTION_STATE_SLC_CONNECTED, /* 服务级连接SLC已建立 */ ESP_HF_CONNECTION_STATE_DISCONNECTING, /* 正在与远端设备断开 RFCOMM 数据链路 */ } esp_hf_connection_state_t;HFP 的连接分为两层先是底层RFCOMM 数据链路状态CONNECTING → CONNECTED随后双方通过 AT 命令握手建立服务级连接 SLCService Level Connection状态SLC_CONNECTED。从 hfp_hf README 的实际日志可以清晰看到这一跃迁过程connect I (79642) BT_HF: APP HFP event: CONNECTION_STATE_EVT I (79642) BT_HF: --connection state connected, peer feats 0x0, chld_feats 0x0 ... I (79852) BT_HF: APP HFP event: CONNECTION_STATE_EVT I (79862) BT_HF: --connection state slc_connected, peer feats 0x16e, chld_feats 0x0只有当状态到达ESP_HF_CONNECTION_STATE_SLC_CONNECTED之后拨号、音量控制、语音识别等其余 HFP 命令才可用官方文档与示例中对此有明确说明。3.2 音频连接状态与 mSBCtypedef enum { ESP_HF_AUDIO_STATE_DISCONNECTED 0, /* 音频连接已释放 */ ESP_HF_AUDIO_STATE_CONNECTING, /* 音频连接已发起 */ ESP_HF_AUDIO_STATE_CONNECTED, /* 音频连接已建立 */ ESP_HF_AUDIO_STATE_CONNECTED_MSBC, /* mSBC 音频连接已建立 */ } esp_hf_audio_state_t;HFP 的音频通道建立在 SCO/eSCO 链路上。该枚举用于区分普通 CVSD 音频连接CONNECTED与宽带语音 mSBC 连接CONNECTED_MSBC。示例日志展示了典型过程connect audio I (117232) BT_HF: APP HFP event: AUDIO_STATE_EVT I (117232) BT_HF: --audio state connecting E (117262) BT_BTM: btm_sco_connected, handle 181 I (117262) BT_HF: APP HFP event: AUDIO_STATE_EVT I (117262) BT_HF: --audio state connected根据示例说明以下场景会自动建立音频连接接听来电、启用语音识别、拨出电话以下场景会断开音频连接拒接来电、关闭语音识别。3.3 来电相关状态CIND 指示器CIND是 AG 上报的通话状态指示器集合esp_hf_defs.h为每个指示器单独定义了枚举枚举取值含义esp_hf_call_status_tNO_CALLS0/CALL_IN_PROGRESS1是否有通话正在进行活动或保持esp_hf_call_setup_status_tIDLE0/INCOMING1/OUTGOING_DIALING2/OUTGOING_ALERTING3呼叫建立阶段esp_hf_call_held_status_tNONE0/HELD_AND_ACTIVE1/HELD2呼叫保持状态esp_hf_network_state_tNOT_AVAILABLE0/AVAILABLE1网络服务可用性esp_hf_roaming_status_tINACTIVE0/ACTIVE1漫游状态这些枚举直接对应CIEV事件上报esp_hf_ciev_report_type_ttypedef enum { ESP_HF_IND_TYPE_CALL 1, /* call 指示器 */ ESP_HF_IND_TYPE_CALLSETUP, /* callsetup 指示器 */ ESP_HF_IND_TYPE_SERVICE, /* service 指示器 */ ESP_HF_IND_TYPE_SIGNAL, /* 信号强度指示器范围 0-5 */ ESP_HF_IND_TYPE_ROAM, /* 漫游指示器 */ ESP_HF_IND_TYPE_BATTCHG, /* 电量指示器范围 0-5 */ ESP_HF_IND_TYPE_CALLHELD /* callheld 指示器 */ } esp_hf_ciev_report_type_t;在hfp_hf示例中建立 SLC 后 AG 会依次推送全部指示器对应日志为I (79792) BT_HF: --Call indicator NO call in progress I (79802) BT_HF: --Call setup indicator NONE I (79812) BT_HF: --NETWORK STATE available I (79822) BT_HF: -- signal strength: 4 I (79832) BT_HF: --ROAMING: inactive I (79842) BT_HF: --battery level 3 I (79852) BT_HF: --Call held indicator NONE held服务类型由esp_hf_service_type_t描述HOME0表示归属地、ROAMING1表示漫游。3.4 当前通话列表CLCC 相关枚举CLCC用于列出当前通话一组枚举完整刻画每条通话的属性typedef enum { ESP_HF_CURRENT_CALL_STATUS_ACTIVE 0, /* 活动 */ ESP_HF_CURRENT_CALL_STATUS_HELD 1, /* 保持 */ ESP_HF_CURRENT_CALL_STATUS_DIALING 2, /* 拨号中仅呼出 */ ESP_HF_CURRENT_CALL_STATUS_ALERTING 3, /* 振铃中仅呼出 */ ESP_HF_CURRENT_CALL_STATUS_INCOMING 4, /* 来电仅呼入 */ ESP_HF_CURRENT_CALL_STATUS_WAITING 5, /* 等待中仅呼入 */ ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD 6, /* 被响应保持BTRH */ } esp_hf_current_call_status_t; typedef enum { ESP_HF_CURRENT_CALL_DIRECTION_OUTGOING 0, /* 呼出 */ ESP_HF_CURRENT_CALL_DIRECTION_INCOMING 1, /* 呼入 */ } esp_hf_current_call_direction_t; typedef enum { ESP_HF_CURRENT_CALL_MPTY_TYPE_SINGLE 0, /* 非多方通话成员 */ ESP_HF_CURRENT_CALL_MPTY_TYPE_MULTI 1, /* 多方通话成员 */ } esp_hf_current_call_mpty_type_t; typedef enum { ESP_HF_CURRENT_CALL_MODE_VOICE 0, /* 语音呼叫 */ ESP_HF_CURRENT_CALL_MODE_DATA 1, /* 数据呼叫 */ ESP_HF_CURRENT_CALL_MODE_FAX 2, /* 传真呼叫 */ } esp_hf_current_call_mode_t; typedef enum { ESP_HF_CALL_ADDR_TYPE_UNKNOWN 0x81, /* 未知地址类型 */ ESP_HF_CALL_ADDR_TYPE_INTERNATIONAL 0x91, /* 国际地址 */ } esp_hf_call_addr_type_t;注意ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD与BTRH响应与保持机制相关联而地址类型取值沿用了 GSM/ETSI 对电话号码类型的编码0x81 未知、0x91 国际。示例中查询当前通话列表命令qc的典型输出为I (354582) BT_HF: APP HFP event: CLCC_EVT I (354582) BT_HF: --Current call: idx 1, dir incoming, state active, mpty single, number 186xxxx55493.5 呼叫保持与三方通话CHLD 命令typedef enum { ESP_HF_CHLD_TYPE_REL 0, /* 0 结束所有保持通话或向等待通话返回忙音 */ ESP_HF_CHLD_TYPE_REL_ACC, /* 1 结束所有活动通话并接听等待/保持通话 */ ESP_HF_CHLD_TYPE_HOLD_ACC, /* 2 保持所有活动通话并接听等待/保持通话 */ ESP_HF_CHLD_TYPE_MERGE, /* 3 将所有保持通话加入电话会议 */ ESP_HF_CHLD_TYPE_MERGE_DETACH, /* 4 连接两路通话并断开用户与二者的连接 */ ESP_HF_CHLD_TYPE_REL_X, /* 1x 仅结束指定通话 */ ESP_HF_CHLD_TYPE_PRIV_X, /* 2x 与指定通话建立私有咨询模式 */ } esp_hf_chld_type_t;该枚举完整映射了 HFP 规范中ATCHLD的全部取值覆盖挂断、接听、保持、合并会议、指定通话操作五类场景。AG 侧通过chld_feats位域向上报支持哪些CHLD操作。3.6 响应与保持BTRHtypedef enum { ESP_HF_BTRH_STATUS_HELD 0, /* 来电已在 AG 侧被保持 */ ESP_HF_BTRH_STATUS_ACCEPTED, /* 被保持的来电已在 AG 侧被接听 */ ESP_HF_BTRH_STATUS_REJECTED, /* 被保持的来电已在 AG 侧被拒接 */ } esp_hf_btrh_status_t; typedef enum { ESP_HF_BTRH_CMD_HOLD 0, /* 将来电置于保持 */ ESP_HF_BTRH_CMD_ACCEPT 1, /* 接听被保持的来电 */ ESP_HF_BTRH_CMD_REJECT 2, /* 拒接被保持的来电 */ } esp_hf_btrh_cmd_t;esp_hf_btrh_cmd_t是客户端HF通过ATBTRH发送的指令esp_hf_btrh_status_t是网关AG返回的状态。在hfp_hf示例中对应命令rh btrh参数 0/1/2 分别表示保持当前通话、接听保持的通话、结束保持的通话。3.7 音量控制typedef enum { ESP_HF_VOLUME_CONTROL_TARGET_SPK 0, /* 扬声器 */ ESP_HF_VOLUME_CONTROL_TARGET_MIC, /* 麦克风 */ } esp_hf_volume_control_target_t; typedef enum { ESP_HF_VOLUME_TYPE_SPK 0, /* 扬声器 */ ESP_HF_VOLUME_TYPE_MIC /* 麦克风 */ } esp_hf_volume_type_t;两个枚举分别用于下发音量增益命令ESP_HF_VOLUME_CONTROL_TARGET_*和解析VGS/VGM上报事件ESP_HF_VOLUME_TYPE_*。示例命令格式为vu tgt vol其中tgt取值 0扬声器/1麦克风vol为 0–15 的整数vu 0 9 → AG 侧日志--Volume Target: SPEAKER, Volume 9 vu 1 9 → AG 侧日志--Volume Target: MICROPHONE, Volume 93.8 语音识别、响铃与 NRECtypedef enum { ESP_HF_VR_STATE_DISABLED 0, /* 语音识别关闭 */ ESP_HF_VR_STATE_ENABLED, /* 语音识别开启 */ } esp_hf_vr_state_t; typedef enum { ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED 0, /* 免提设备不提供带内铃声 */ ESP_HF_IN_BAND_RINGTONE_PROVIDED, /* 免提设备提供带内铃声 */ } esp_hf_in_band_ring_state_t; typedef enum { ESP_HF_NREC_STOP 0, /* 停止 NREC */ ESP_HF_NREC_START /* 启动 NREC */ } esp_hf_nrec_t;esp_hf_vr_state_t对应BVRA客户端可用vron/vroff命令开启/关闭 AG 的语音识别开启时通常伴随音频连接建立示例日志中Start voice recognition后即出现audio state connected。esp_hf_in_band_ring_state_t对应BSIR指示来电时是否由 AG 通过 SCO 链路下发带内铃声。示例建立 SLC 后打印--inband ring state Provided。esp_hf_nrec_t对应NREC控制回声消除/降噪NREC的启停。3.9 其他状态枚举esp_hf_prof_state_t初始化状态机取值ESP_HF_INIT_SUCCESS / ESP_HF_INIT_ALREADY / ESP_HF_INIT_FAIL / ESP_HF_DEINIT_SUCCESS / ESP_HF_DEINIT_ALREADY / ESP_HF_DEINIT_FAIL供esp_hf_client_init()/esp_hf_ag_init()等接口返回。esp_hf_call_waiting_status_tCCWA呼叫等待状态INACTIVE/ACTIVE。esp_hf_subscriber_service_type_tCNUM电话号码的服务类型UNKNOWN0/VOICE4/FAX5。示例rs命令输出--subscriber type unknown, number 186xxxx5549即对应此枚举。esp_hf_wbs_config_t宽带语音编解码配置WBS_NONE/WBS_NO/WBS_YES与菜单Component config -- Bluetooth -- Bluedroid Options -- Wide Band Speech对应。四、AT 响应码与 CME 扩展错误4.1 通用 AT 响应码typedef enum { ESP_HF_AT_RESPONSE_CODE_OK 0, /* 命令执行成功 */ ESP_HF_AT_RESPONSE_CODE_ERR, /* 命令未被接受 */ ESP_HF_AT_RESPONSE_CODE_NO_CARRIER, /* 连接终止 */ ESP_HF_AT_RESPONSE_CODE_BUSY, /* 检测到忙音 */ ESP_HF_AT_RESPONSE_CODE_NO_ANSWER, /* 连接建立超时 */ ESP_HF_AT_RESPONSE_CODE_DELAYED, /* 延迟 */ ESP_HF_AT_RESPONSE_CODE_BLACKLISTED, /* 被列入黑名单 */ ESP_HF_AT_RESPONSE_CODE_CME, /* CME 错误 */ } esp_hf_at_response_code_t; typedef enum { ESP_HF_AT_RESPONSE_ERROR 0, /* AT 命令响应出错 */ ESP_HF_AT_RESPONSE_OK /* AT 命令响应成功 */ } esp_hf_at_response_t;示例中每次 AT 操作完成后都会收到AT_RESPONSE事件日志--AT response event, code 0, cme 0表示esp_hf_at_response_t为ESP_HF_AT_RESPONSE_OK且无 CME 错误。当code为ESP_HF_AT_RESPONSE_CODE_CME时需要通过下文的esp_hf_cme_err_t进一步解析cme字段。4.2 扩展音频网关错误结果码CME ERRORtypedef enum { ESP_HF_CME_AG_FAILURE 0, /* AG 故障 */ ESP_HF_CME_NO_CONNECTION_TO_PHONE 1, /* 无电话连接 */ ESP_HF_CME_OPERATION_NOT_ALLOWED 3, /* 操作不允许 */ ESP_HF_CME_OPERATION_NOT_SUPPORTED 4, /* 操作不支持 */ ESP_HF_CME_PH_SIM_PIN_REQUIRED 5, /* 需要 PH-SIM PIN */ ESP_HF_CME_SIM_NOT_INSERTED 10, /* 未插入 SIM 卡 */ ESP_HF_CME_SIM_PIN_REQUIRED 11, /* 需要 SIM PIN */ ESP_HF_CME_SIM_PUK_REQUIRED 12, /* 需要 SIM PUK */ ESP_HF_CME_SIM_FAILURE 13, /* SIM 故障 */ ESP_HF_CME_SIM_BUSY 14, /* SIM 忙 */ ESP_HF_CME_INCORRECT_PASSWORD 16, /* 密码错误 */ ESP_HF_CME_SIM_PIN2_REQUIRED 17, /* 需要 SIM PIN2 */ ESP_HF_CME_SIM_PUK2_REQUIRED 18, /* 需要 SIM PUK2 */ ESP_HF_CME_MEMORY_FULL 20, /* 存储已满 */ ESP_HF_CME_INVALID_INDEX 21, /* 非法索引 */ ESP_HF_CME_MEMORY_FAILURE 23, /* 存储故障 */ ESP_HF_CME_TEXT_STRING_TOO_LONG 24, /* 文本串过长 */ ESP_HF_CME_INVALID_CHARACTERS_IN_TEXT_STRING 25, /* 文本串含非法字符 */ ESP_HF_CME_DIAL_STRING_TOO_LONG 26, /* 拨号串过长 */ ESP_HF_CME_INVALID_CHARACTERS_IN_DIAL_STRING 27, /* 拨号串含非法字符 */ ESP_HF_CME_NO_NETWORK_SERVICE 30, /* 无网络服务 */ ESP_HF_CME_NETWORK_TIMEOUT 31, /* 网络超时 */ ESP_HF_CME_NETWORK_NOT_ALLOWED 32, /* 网络不允许仅限紧急呼叫 */ } esp_hf_cme_err_t;esp_hf_cme_err_t覆盖了 HFP/3GPP 定义的扩展错误码全集0–32是与 SIM、网络、存储、拨号串相关的错误定位依据。在调试拨号失败无法读取订阅信息等场景时应优先检查该枚举的取值。五、音频数据缓冲结构typedef struct { uint16_t buff_size; /* 缓冲区大小 */ uint16_t data_len; /* 音频数据长度不得大于缓冲区大小 */ uint8_t *data; /* 音频数据起始指针 */ } esp_hf_audio_buff_t;esp_hf_audio_buff_t是 HFP 音频数据在应用层与协议栈之间传递的载体在 vHCIHCI 数据通路模式下SCO 音频数据经由蓝牙控制器 → vHCI → Bluedroid 主机栈到达应用层时即通过该结构体承载。使用要点必须先填充buff_size并分配data指向的内存填充数据后更新data_len且必须满足data_len buff_size收发方向均为数据指针 长度模式便于零拷贝接入编解码器。六、mSBC 宽带语音的固定编解码参数HFP 的 mSBC 使用一组固定编码参数esp_hf_defs.h以宏形式给出方便应用层初始化音频管线#define ESP_HF_MSBC_CHANNEL_MODE Mono /* 声道模式单声道 */ #define ESP_HF_MSBC_SAMPLING_RATE 16 kHz /* 采样率16 kHz */ #define ESP_HF_MSBC_ALLOCATION_METHOD Loudness/* 分配方法响度 */ #define ESP_HF_MSBC_SUBBANDS 8 /* 子带数 */ #define ESP_HF_MSBC_BLOCK_LENGTH 15 /* 块长度 */ #define ESP_HF_MSBC_BITPOOL 26 /* 比特池 */ #define ESP_HF_MSBC_ENCODED_FRAME_SIZE 57 /* mSBC 编码后的帧大小字节 */mSBC 属于 SBC 编码的宽带16 kHz 采样变体帧结构固定8 个子带、每块 15 字节、bitpool 26每帧编码后恰好 57 字节。这些宏同时被 Bluedroid 主机栈软件编码器与示例应用使用是实现vHCI 数据通路 Wide Band Speech时对接编解码器的直接依据。需要特别说明编解码选择与数据通路的关系来自 hfp_hf/hfp_ag 示例 README数据通路为 PCM只能使用 CVSD编解码由硬件完成即使打开Wide Band Speech也无法使用 mSBC因为 mSBC 由 Bluedroid 主机栈以软件方式实现数据通路为 vHCI 且打开Wide Band Speech编解码在 Bluedroid 中完成实际使用 mSBC数据通路为 vHCI 但关闭Wide Band Speech编解码由硬件完成实际使用 CVSD。数据通路在menuconfig中分别通过两处配置决定须在编译烧录前完成Component config -- Bluetooth controller -- BR/EDR Sync(SCO/eSCO) default data path -- PCM/HCIComponent config -- Bluetooth -- Bluedroid Options -- Hands Free/Handset Profile -- audio(SCO) data path -- PCM/HCI七、实践要点与故障排查7.1 正确的初始化顺序根据 hfp_hf README 的 Troubleshooting 部分使用 HFP 必须遵循先调用esp_hf_client_register_callback()或 AG 侧esp_hf_ag_register_callback()注册用户回调再调用esp_hf_client_init()或esp_hf_ag_init()完成初始化之后才能建立服务级连接连接目标地址可直接硬编码在示例的bt_app.c中例如esp_bd_addr_t peer_addr {0xb4, 0xe6, 0x2d, 0xeb, 0x09, 0x93};。初始化返回的esp_hf_prof_state_t会明确区分首次成功ESP_HF_INIT_SUCCESS与重复初始化ESP_HF_INIT_ALREADY便于做幂等保护。7.2 命令可用性前提只有 HFP 服务完成初始化且SLC 已建立ESP_HF_CONNECTION_STATE_SLC_CONNECTED之后拨号d num/rd/dm index、应答ac、拒接rc、音量vu、语音识别vron/vroff、查询运营商qop、查询订阅信息rs、查询通话列表qc、DTMFk dtmf等命令才可用。此外并非所有 AG 设备都支持命令表中的全部 AT 功能遇到CME ERROR时应结合esp_hf_cme_err_t判断是不支持ESP_HF_CME_OPERATION_NOT_SUPPORTED 4还是其他原因。八、源码阅读指引如需深入源码验证上述定义的使用方式可按以下路径继续阅读定义头文件本体esp_hf_defs.h与本文对应的权威来源HF 客户端 API 与事件枚举esp_hf_client_api.h音频网关 API 与事件枚举esp_hf_ag_api.h客户端示例实现hfp_hf/main/bt_app_hf.c事件回调与状态打印、hfp_hf/main/app_hf_msg_set.c命令表音频网关示例实现hfp_ag/main/bt_app_hf.c中文版文档esp_hf_defs.rst与英文版同步维护结语esp_hf_defs.h虽然只包含常量、枚举与结构体却是连接 HFP 协议规范与 ESP-IDF 事件回调的桥梁连接状态机esp_hf_connection_state_t、esp_hf_audio_state_t、通话指示器esp_hf_call_status_t、esp_hf_call_setup_status_t、esp_hf_call_held_status_t、通话列表esp_hf_current_call_*、呼叫保持esp_hf_chld_type_t、响应保持esp_hf_btrh_*、AT 错误码esp_hf_at_response_code_t、esp_hf_cme_err_t以及 mSBC 固定参数共同构成了开发蓝牙免提应用时最常查阅的协议字典。配合hfp_hf/hfp_ag两个官方示例开发者可以快速在真实链路上验证每一个状态枚举的实际行为。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 插件、强制选项与开发服务器定制)
