ESP-IDF Bluetooth LE API Reference 全面指南GAP / GATT / BluFi 架构与实战【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本指南以 ESP-IDF 官方 API 参考文档 Bluetooth Low Energy 为主线系统梳理 ESP-IDF 中 Bluetooth LEBLE协议栈的 API 组成从设备发现与连接的GAP、属性与特征建模的GATT 定义到外设/主机两种角色下的GATT Server 与 GATT Client再到通过 BLE 通道完成 Wi-Fi 配网的BluFi。读完本文你将掌握每个 API 模块的职责边界、对应头文件与示例工程的位置并能基于仓库内的源码与示例快速定位到具体的 BLE 开发实现。Bluetooth Low EnergyBluetooth LE是面向低功耗无线通信设计的协议广泛用于可穿戴设备、传感器和智能家居等物联网产品。在 ESP-IDF 中BLE 协议栈提供了两个可选的主机实现Bluedroid位于components/bt/host/bluedroid与NimBLE位于examples/bluetooth/nimble等 NimBLE 目录二者共享上层的 GAP/GATT API 设计理念。本文聚焦于 API 参考层面讲解其组织方式、每个模块的功能、示例与底层实现入口。BLE API 的总体组织方式根据 bt_le.rst 的说明ESP-IDF 的 Bluetooth LE API 被划分为以下几个部分API 模块文档核心职责Bluetooth Low Energy GAPesp_gap_ble.rst广播Advertising、扫描Scanning、连接管理、安全操作Bluetooth Low Energy GATT Defineesp_gatt_defs.rstGATT 操作中使用的公共数据类型与常量属性、特征、UUIDBluetooth Low Energy GATT Serveresp_gatts.rst向远端客户端暴露服务与特征外设 peripheral 角色Bluetooth Low Energy GATT Clientesp_gattc.rst发现并访问远端服务器上的服务主机 central 角色Bluetooth Low Energy BluFiesp_blufi.rst通过 Bluetooth LE 完成 Wi-Fi 配网与配置其中BluFi仅在芯片支持时可用对应文档中SOC_BLUFI_SUPPORTED条件其余四个模块为通用组成部分。每个部分通常都包含Overview概述、Application Examples应用示例和API ReferenceAPI 参考三类内容分别说明用途、主要功能、用法示例与详细 API 文档。在开始阅读各模块文档之前建议先阅读 API Guides 中的 Bluetooth Low Energy 使用指南其中包含概念讲解与教程API Reference 则用于查询具体的函数、枚举与回调参数。GAP设备发现、连接与安全GAPGeneric Access Profile是 BLE 的通用访问规范负责设备在链路层之上的广播、扫描、连接建立与安全参数管理等基础能力。ESP-IDF 的 GAP API 完整定义在头文件 esp_gap_ble_api.h 中文档见 esp_gap_ble.rst。从源码结构看GAP 相关能力覆盖以下典型操作广播Advertising通过esp_ble_gap_set_device_name()、esp_ble_gap_config_adv_data()配置广播数据随后调用esp_ble_gap_start_advertising()启动广播扫描Scanning调用esp_ble_gap_set_scan_params()配置扫描参数用esp_ble_gap_start_scanning()开启扫描扫描结果通过事件回调返回连接管理广播方与扫描方建立连接后连接状态的维护与断开通过 GAP 事件通知安全操作包括配对、绑定、加密、密钥管理等是 GATT 数据安全传输的前提。GAP 文档中列出的两个安全示例是理解安全流程的最佳起点gatt_security_client以 GATT 客户端身份使用 ESP BLE 安全 API与对端设备建立安全连接并对通信进行加密gatt_security_server以 GATT 服务端身份使用 ESP BLE 安全 API与对端设备建立安全连接并对通信进行加密。这两个示例分别从主机与从机两个角度演示了 BLE 的配对绑定与加密流程是学习 ESP-IDF BLE 安全机制的标准参考工程。GATT 定义属性、特征与 UUID 的公共类型GATTGeneric Attribute Profile建立在属性协议之上用属性Attribute组织数据。GATT 操作涉及服务Service、特征Characteristic、描述符Descriptor、UUID、权限Permission与属性Property等众多类型这些公共数据类型与常量统一收拢在头文件 esp_gatt_defs.h 中文档见 esp_gatt_defs.rst。从源码看该头文件定义了 GATT 层的关键基础类型例如esp_gatt_perm_ttypedef uint16_t表示 GATT 属性权限attribute permissions控制属性可读、可写、加密读写等访问级别esp_gatt_char_prop_ttypedef uint8_t表示特征属性characteristic properties如广播、读、写、通知Notify、指示Indicate等能力位服务 IDservice id、UUID 结构体、GATT 状态码status等类型供 GATT Server 与 GATT Client 两端的 API 共同引用。GATT 定义是 GATT Server 与 GATT Client 的公共基础层——两端在描述服务、特征以及处理回调结果时都复用同一套类型定义从而保证协议栈内部数据语义的一致性。GATT Server以属性表或逐条添加方式暴露服务GATT Server 让设备以外设peripheral角色向远端客户端暴露服务与特征API 定义于头文件 esp_gatts_api.h文档见 esp_gatts.rst。GATT Server 的使用流程通常包含以下步骤调用esp_ble_gatts_register_callback()注册 GATTS 事件回调如gatts_event_handler调用esp_ble_gatts_app_register()注册应用app注册完成事件ESP_GATTS_REG_EVT返回gatts_if接口句柄创建服务可以通过esp_ble_gatts_create_attr_tab()使用属性表批量创建也可以通过esp_ble_gatts_create_service()等接口逐条添加属性服务创建完成后调用esp_ble_gatts_start_service()启动服务使客户端可以发现并连接启动广播等待 GATT 客户端连接并交换数据。文档提供了两个互补的示例工程gatt_server_service_table演示如何通过属性表attribute table创建 GATT 服务开发者无需逐条添加属性适合服务结构固定的场景gatt_server演示如何逐条添加属性来创建 GATT 服务然后启动广播等待 GATT 客户端连接并交换数据适合需要精细控制每个属性的场景。在 gatt_server 示例源码 中可以看到完整的实现脉络gatts_event_handler()统一处理全部 GATTS 事件ESP_GATTS_REG_EVT分支中保存gatts_if并调用esp_ble_gatts_create_attr_tab()创建属性表多个 profile 共享一个回调通过app_id区分服务创建完成后在对应事件分支中调用esp_ble_gatts_start_service()启动服务。这种一个 profile 对应一个 app_id 与一个 gatts_if的写法是官方推荐的工程模式。GATT Client服务发现、连接与通知注册GATT Client 让设备以主机central角色发现并访问远端服务器上的服务API 定义于头文件 esp_gattc_api.h文档见 esp_gattc.rst。典型的 GATT Client 流程如下通过扫描或已知地址找到目标设备调用esp_ble_gattc_open()建立与 GATT Server 的连接连接成功后ESP_GATTC_OPEN_EVT调用esp_ble_gattc_search_service()按 UUID 搜索远程服务在服务发现完成事件中获取特征句柄调用esp_ble_gattc_register_for_notify()注册通知Notification从而接收服务端的主动数据推送通过读写操作与对端交换数据。文档列出的示例工程覆盖了单连接、多连接与双角色共存等典型场景gatt_client创建 GATT 客户端连接一个 GATT 服务器开启服务器的通知功能并发现其服务gattc_multi_connect创建 GATT 客户端同时连接多个 GATT 服务器分别开启通知并发现各自的服务演示多连接管理gattc_gatts_coex在同一设备上同时创建 GATT 服务与 GATT 客户端演示 GATT 客户端与 GATT 服务器共存coexistence——创建服务、启动广播并在 GATT 客户端与设备之间交换数据ble_amsBluedroid 版本与 ble_amsNimBLE 版本在各自协议栈上扮演 Apple Media ServiceAMS客户端连接 iOS 设备通过 GATT 接收媒体元数据并发送远程播放控制命令展示了基于 GATT 的跨厂商协议应用。在 gatt_client 示例源码 中可以看到ESP_GATTC_OPEN_EVT事件触发后调用esp_ble_gattc_search_service()按过滤 UUID 搜索服务服务发现完成后遍历特征结果并调用esp_ble_gattc_register_for_notify()注册通知。需要说明的是BluFi 同样基于 GATT 服务实现其协议栈内部注册了专用的 GATT 服务用于承载 Wi-Fi 配置数据。BluFi基于 GATT 的 Wi-Fi 配网协议BluFi 是一个基于 GATT profile 的协议用于通过蓝牙通道配置 ESP32 系列芯片的 Wi-Fi连接/断开 AP、设置 SoftAP 等。其 API 定义于头文件 esp_blufi_api.h文档见 esp_blufi.rst。BluFi 模块仅在芯片 SOC 支持时SOC_BLUFI_SUPPORTED才编译进文档与固件。按照 esp_blufi.rst 的说明使用 BluFi 需要重点关注两类事项profile 事件处理profile 会向上层发送事件应用需要根据事件指示完成相应操作例如收到 Wi-Fi 连接请求后调用esp_blufi_send_wifi_conn_report()上报连接状态安全参考实现开发者可以编写自己的安全函数例如对称加解密函数与校验和函数甚至可以自定义密钥交换/协商流程实现完全自主的安全策略。从源码结构看BluFi 的安全机制通过esp_blufi_sec_t结构体注入包含以下回调negotiate_data_handler协商数据处理器用于协商共享密钥negotiate share keyencrypt_func/decrypt_func使用协商出的共享密钥对数据做加/解密checksum_func校验和FCS计算函数。应用在初始化时通过esp_blufi_register_callbacks()注册esp_blufi_callbacks_t回调集合再调用esp_blufi_profile_init()初始化 profile。官方示例 bluetooth/blufi 演示了完整的配网流程在 blufi_security.c 中实现了基于 AES 的加解密与校验函数在 blufi_example_main.c 中处理 Wi-Fi 配置事件并上报连接结果在 blufi_init.c 中完成 BLE 协议栈与 BluFi profile 的初始化。这三个文件共同构成了一个事件处理 安全实现 初始化的可复用模板。结合示例的快速上手路径综合上述五个模块一份完整的 BLE 应用例如通过手机 App 配网的智能设备通常需要串联以下能力初始化与注册初始化 Bluedroid/NimBLE 协议栈注册 GAP 与 GATT 回调GAP 层设置设备名称与广播数据启动广播等待手机连接或启动扫描发现目标设备GATT Server 层用属性表或逐条添加创建 Wi-Fi 配置服务与数据服务启动服务GATT Client 层按需作为主机访问其他 BLE 外设注册通知接收数据BluFi 层按需芯片支持时实现自定义安全回调通过 BLE 通道下发 Wi-Fi SSID/密码并上报配网结果。每个阶段的示例工程位置如下可直接作为开发起点GAP 安全examples/bluetooth/bluedroid/ble/gatt_security_client、examples/bluetooth/bluedroid/ble/gatt_security_serverGATT Serverexamples/bluetooth/bluedroid/ble/gatt_server、examples/bluetooth/bluedroid/ble/gatt_server_service_tableGATT Clientexamples/bluetooth/bluedroid/ble/gatt_client、examples/bluetooth/bluedroid/ble/gattc_multi_connect、examples/bluetooth/bluedroid/coex/gattc_gatts_coexAMS 客户端examples/bluetooth/bluedroid/ble/ble_ams、examples/bluetooth/nimble/ble_amsBluFi 配网examples/bluetooth/blufi对应 API 头文件统一位于components/bt/host/bluedroid/api/include/api/GAP/GATT 系列与components/bt/common/api/include/api/BluFi 系列查阅 API 细节时可直接在这些头文件中检索函数声明、枚举与回调结构体。需要进一步了解 BLE 使用概念与协议栈选型时可参考 API Guides 中的 Bluetooth Low Energy 索引 与 BluFi 使用指南。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF Bluetooth LE API Reference 全面指南：GAP / GATT / BluFi 架构与实战
ESP-IDF Bluetooth LE API Reference 全面指南GAP / GATT / BluFi 架构与实战【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本指南以 ESP-IDF 官方 API 参考文档 Bluetooth Low Energy 为主线系统梳理 ESP-IDF 中 Bluetooth LEBLE协议栈的 API 组成从设备发现与连接的GAP、属性与特征建模的GATT 定义到外设/主机两种角色下的GATT Server 与 GATT Client再到通过 BLE 通道完成 Wi-Fi 配网的BluFi。读完本文你将掌握每个 API 模块的职责边界、对应头文件与示例工程的位置并能基于仓库内的源码与示例快速定位到具体的 BLE 开发实现。Bluetooth Low EnergyBluetooth LE是面向低功耗无线通信设计的协议广泛用于可穿戴设备、传感器和智能家居等物联网产品。在 ESP-IDF 中BLE 协议栈提供了两个可选的主机实现Bluedroid位于components/bt/host/bluedroid与NimBLE位于examples/bluetooth/nimble等 NimBLE 目录二者共享上层的 GAP/GATT API 设计理念。本文聚焦于 API 参考层面讲解其组织方式、每个模块的功能、示例与底层实现入口。BLE API 的总体组织方式根据 bt_le.rst 的说明ESP-IDF 的 Bluetooth LE API 被划分为以下几个部分API 模块文档核心职责Bluetooth Low Energy GAPesp_gap_ble.rst广播Advertising、扫描Scanning、连接管理、安全操作Bluetooth Low Energy GATT Defineesp_gatt_defs.rstGATT 操作中使用的公共数据类型与常量属性、特征、UUIDBluetooth Low Energy GATT Serveresp_gatts.rst向远端客户端暴露服务与特征外设 peripheral 角色Bluetooth Low Energy GATT Clientesp_gattc.rst发现并访问远端服务器上的服务主机 central 角色Bluetooth Low Energy BluFiesp_blufi.rst通过 Bluetooth LE 完成 Wi-Fi 配网与配置其中BluFi仅在芯片支持时可用对应文档中SOC_BLUFI_SUPPORTED条件其余四个模块为通用组成部分。每个部分通常都包含Overview概述、Application Examples应用示例和API ReferenceAPI 参考三类内容分别说明用途、主要功能、用法示例与详细 API 文档。在开始阅读各模块文档之前建议先阅读 API Guides 中的 Bluetooth Low Energy 使用指南其中包含概念讲解与教程API Reference 则用于查询具体的函数、枚举与回调参数。GAP设备发现、连接与安全GAPGeneric Access Profile是 BLE 的通用访问规范负责设备在链路层之上的广播、扫描、连接建立与安全参数管理等基础能力。ESP-IDF 的 GAP API 完整定义在头文件 esp_gap_ble_api.h 中文档见 esp_gap_ble.rst。从源码结构看GAP 相关能力覆盖以下典型操作广播Advertising通过esp_ble_gap_set_device_name()、esp_ble_gap_config_adv_data()配置广播数据随后调用esp_ble_gap_start_advertising()启动广播扫描Scanning调用esp_ble_gap_set_scan_params()配置扫描参数用esp_ble_gap_start_scanning()开启扫描扫描结果通过事件回调返回连接管理广播方与扫描方建立连接后连接状态的维护与断开通过 GAP 事件通知安全操作包括配对、绑定、加密、密钥管理等是 GATT 数据安全传输的前提。GAP 文档中列出的两个安全示例是理解安全流程的最佳起点gatt_security_client以 GATT 客户端身份使用 ESP BLE 安全 API与对端设备建立安全连接并对通信进行加密gatt_security_server以 GATT 服务端身份使用 ESP BLE 安全 API与对端设备建立安全连接并对通信进行加密。这两个示例分别从主机与从机两个角度演示了 BLE 的配对绑定与加密流程是学习 ESP-IDF BLE 安全机制的标准参考工程。GATT 定义属性、特征与 UUID 的公共类型GATTGeneric Attribute Profile建立在属性协议之上用属性Attribute组织数据。GATT 操作涉及服务Service、特征Characteristic、描述符Descriptor、UUID、权限Permission与属性Property等众多类型这些公共数据类型与常量统一收拢在头文件 esp_gatt_defs.h 中文档见 esp_gatt_defs.rst。从源码看该头文件定义了 GATT 层的关键基础类型例如esp_gatt_perm_ttypedef uint16_t表示 GATT 属性权限attribute permissions控制属性可读、可写、加密读写等访问级别esp_gatt_char_prop_ttypedef uint8_t表示特征属性characteristic properties如广播、读、写、通知Notify、指示Indicate等能力位服务 IDservice id、UUID 结构体、GATT 状态码status等类型供 GATT Server 与 GATT Client 两端的 API 共同引用。GATT 定义是 GATT Server 与 GATT Client 的公共基础层——两端在描述服务、特征以及处理回调结果时都复用同一套类型定义从而保证协议栈内部数据语义的一致性。GATT Server以属性表或逐条添加方式暴露服务GATT Server 让设备以外设peripheral角色向远端客户端暴露服务与特征API 定义于头文件 esp_gatts_api.h文档见 esp_gatts.rst。GATT Server 的使用流程通常包含以下步骤调用esp_ble_gatts_register_callback()注册 GATTS 事件回调如gatts_event_handler调用esp_ble_gatts_app_register()注册应用app注册完成事件ESP_GATTS_REG_EVT返回gatts_if接口句柄创建服务可以通过esp_ble_gatts_create_attr_tab()使用属性表批量创建也可以通过esp_ble_gatts_create_service()等接口逐条添加属性服务创建完成后调用esp_ble_gatts_start_service()启动服务使客户端可以发现并连接启动广播等待 GATT 客户端连接并交换数据。文档提供了两个互补的示例工程gatt_server_service_table演示如何通过属性表attribute table创建 GATT 服务开发者无需逐条添加属性适合服务结构固定的场景gatt_server演示如何逐条添加属性来创建 GATT 服务然后启动广播等待 GATT 客户端连接并交换数据适合需要精细控制每个属性的场景。在 gatt_server 示例源码 中可以看到完整的实现脉络gatts_event_handler()统一处理全部 GATTS 事件ESP_GATTS_REG_EVT分支中保存gatts_if并调用esp_ble_gatts_create_attr_tab()创建属性表多个 profile 共享一个回调通过app_id区分服务创建完成后在对应事件分支中调用esp_ble_gatts_start_service()启动服务。这种一个 profile 对应一个 app_id 与一个 gatts_if的写法是官方推荐的工程模式。GATT Client服务发现、连接与通知注册GATT Client 让设备以主机central角色发现并访问远端服务器上的服务API 定义于头文件 esp_gattc_api.h文档见 esp_gattc.rst。典型的 GATT Client 流程如下通过扫描或已知地址找到目标设备调用esp_ble_gattc_open()建立与 GATT Server 的连接连接成功后ESP_GATTC_OPEN_EVT调用esp_ble_gattc_search_service()按 UUID 搜索远程服务在服务发现完成事件中获取特征句柄调用esp_ble_gattc_register_for_notify()注册通知Notification从而接收服务端的主动数据推送通过读写操作与对端交换数据。文档列出的示例工程覆盖了单连接、多连接与双角色共存等典型场景gatt_client创建 GATT 客户端连接一个 GATT 服务器开启服务器的通知功能并发现其服务gattc_multi_connect创建 GATT 客户端同时连接多个 GATT 服务器分别开启通知并发现各自的服务演示多连接管理gattc_gatts_coex在同一设备上同时创建 GATT 服务与 GATT 客户端演示 GATT 客户端与 GATT 服务器共存coexistence——创建服务、启动广播并在 GATT 客户端与设备之间交换数据ble_amsBluedroid 版本与 ble_amsNimBLE 版本在各自协议栈上扮演 Apple Media ServiceAMS客户端连接 iOS 设备通过 GATT 接收媒体元数据并发送远程播放控制命令展示了基于 GATT 的跨厂商协议应用。在 gatt_client 示例源码 中可以看到ESP_GATTC_OPEN_EVT事件触发后调用esp_ble_gattc_search_service()按过滤 UUID 搜索服务服务发现完成后遍历特征结果并调用esp_ble_gattc_register_for_notify()注册通知。需要说明的是BluFi 同样基于 GATT 服务实现其协议栈内部注册了专用的 GATT 服务用于承载 Wi-Fi 配置数据。BluFi基于 GATT 的 Wi-Fi 配网协议BluFi 是一个基于 GATT profile 的协议用于通过蓝牙通道配置 ESP32 系列芯片的 Wi-Fi连接/断开 AP、设置 SoftAP 等。其 API 定义于头文件 esp_blufi_api.h文档见 esp_blufi.rst。BluFi 模块仅在芯片 SOC 支持时SOC_BLUFI_SUPPORTED才编译进文档与固件。按照 esp_blufi.rst 的说明使用 BluFi 需要重点关注两类事项profile 事件处理profile 会向上层发送事件应用需要根据事件指示完成相应操作例如收到 Wi-Fi 连接请求后调用esp_blufi_send_wifi_conn_report()上报连接状态安全参考实现开发者可以编写自己的安全函数例如对称加解密函数与校验和函数甚至可以自定义密钥交换/协商流程实现完全自主的安全策略。从源码结构看BluFi 的安全机制通过esp_blufi_sec_t结构体注入包含以下回调negotiate_data_handler协商数据处理器用于协商共享密钥negotiate share keyencrypt_func/decrypt_func使用协商出的共享密钥对数据做加/解密checksum_func校验和FCS计算函数。应用在初始化时通过esp_blufi_register_callbacks()注册esp_blufi_callbacks_t回调集合再调用esp_blufi_profile_init()初始化 profile。官方示例 bluetooth/blufi 演示了完整的配网流程在 blufi_security.c 中实现了基于 AES 的加解密与校验函数在 blufi_example_main.c 中处理 Wi-Fi 配置事件并上报连接结果在 blufi_init.c 中完成 BLE 协议栈与 BluFi profile 的初始化。这三个文件共同构成了一个事件处理 安全实现 初始化的可复用模板。结合示例的快速上手路径综合上述五个模块一份完整的 BLE 应用例如通过手机 App 配网的智能设备通常需要串联以下能力初始化与注册初始化 Bluedroid/NimBLE 协议栈注册 GAP 与 GATT 回调GAP 层设置设备名称与广播数据启动广播等待手机连接或启动扫描发现目标设备GATT Server 层用属性表或逐条添加创建 Wi-Fi 配置服务与数据服务启动服务GATT Client 层按需作为主机访问其他 BLE 外设注册通知接收数据BluFi 层按需芯片支持时实现自定义安全回调通过 BLE 通道下发 Wi-Fi SSID/密码并上报配网结果。每个阶段的示例工程位置如下可直接作为开发起点GAP 安全examples/bluetooth/bluedroid/ble/gatt_security_client、examples/bluetooth/bluedroid/ble/gatt_security_serverGATT Serverexamples/bluetooth/bluedroid/ble/gatt_server、examples/bluetooth/bluedroid/ble/gatt_server_service_tableGATT Clientexamples/bluetooth/bluedroid/ble/gatt_client、examples/bluetooth/bluedroid/ble/gattc_multi_connect、examples/bluetooth/bluedroid/coex/gattc_gatts_coexAMS 客户端examples/bluetooth/bluedroid/ble/ble_ams、examples/bluetooth/nimble/ble_amsBluFi 配网examples/bluetooth/blufi对应 API 头文件统一位于components/bt/host/bluedroid/api/include/api/GAP/GATT 系列与components/bt/common/api/include/api/BluFi 系列查阅 API 细节时可直接在这些头文件中检索函数声明、枚举与回调结构体。需要进一步了解 BLE 使用概念与协议栈选型时可参考 API Guides 中的 Bluetooth Low Energy 索引 与 BluFi 使用指南。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考