ESP-IDF ESP-BLE-MESH API 参考完全指南：从 Provisioning 到 Mesh 1.1 新特性

ESP-IDF ESP-BLE-MESH API 参考完全指南从 Provisioning 到 Mesh 1.1 新特性【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP-BLE-MESH 是乐鑫 ESP-IDF 官方蓝牙 Mesh 协议栈实现基于 Zephyr Bluetooth Mesh stack 构建支持设备配网Provisioning、节点控制以及 Proxy、Relay、Low Power、Friend 等全部核心节点特性。本文以 docs/en/api-reference/bluetooth/esp-ble-mesh.rst 为骨架结合仓库内的架构文档、术语表、特性清单与真实源码完整梳理 ESP-BLE-MESH 的 API 体系Definitions、Core API、Models API 以及 Mesh Protocol v1.1 新增的 10 组件并给出源码级实现证据与可运行的示例入口。读完本文你将能够根据需求快速定位对应的头文件与 API理解 Node/Provisioner 两种角色的开发模型并掌握从配网到模型收发消息的完整链路。版本提示当前仓库中 ESP-BLE-MESH v1.1 相关代码为预览版本涉及 Mesh Protocol v1.1 的结构体、宏与 API 在后续版本中可能发生变更请以实际发布的 SDK 为准。一、ESP-BLE-MESH 是什么借助 ESP-BLE-MESH 的丰富特性开发者可以针对多种场景构建受管泛洪式managed floodingMesh 网络典型场景包括照明、传感器网络等。Bluetooth® Mesh 是一种多对多m:m设备通信技术专为大规模设备网络而优化设备可以将数据中继relay给不在源设备直接射频范围内的其他设备从而让网络覆盖很大的物理区域、容纳大量节点非常适合楼宇自动化、传感器网络等需要成百上千台设备可靠安全通信的 IoT 方案。需要特别强调的是Bluetooth Mesh 不是一种无线通信技术而是一种组网技术它依赖 Bluetooth Low EnergyBLE这一无线通信协议栈来承载数据。ESP-BLE-MESH 的 bearer 层正是建立在 BLE 的广播通道与连接通道之上。在 ESP-BLE-MESH 网络中存在两种核心角色未配网设备Unprovisioned Device还不是 Mesh 网络成员的设备例如照明设备、温控设备、制造设备、电动门等。节点Node完成配网后的设备。节点能够在网络中发送、接收或中继消息并可选择支持一个或多个子网。配网器Provisioner具备将设备加入 Mesh 网络能力的节点负责把未配网设备配网成节点并配置节点的各项特性。该过程通常通过产品厂商提供的 App 完成可运行在网关、智能手机、平板或其他载体上。一块 ESP32 要加入并工作在 ESP-BLE-MESH 网络中必须先经过配网Provisioning。配网后作为未配网设备的 ESP32 加入网络并成为节点可与其他节点无论是否在射频范围内通信。二、核心术语速查角色、组成、特性、地址与安全理解 API 之前建议先掌握 docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst 中定义的基础概念它们直接对应esp_ble_mesh_defs.h中的结构体字段与消息语义。2.1 角色Role术语官方定义详细说明Relay Node支持 Relay 特性且该特性已启用的节点可接收并重发 Mesh 消息使其继续传递每条消息最多可跳 126 次hop足以支撑广域传输Proxy Node支持 Proxy 特性且已启用的节点在广播 bearer 与 GATT bearer 之间转发消息移动 App 通常必须通过 Proxy 节点才能接入 Mesh 网络Friend Node支持 Friend 特性、已启用并与 Low Power 节点建立友情的节点作为 LPN 的备份暂存发往 LPN 的消息与安全更新在 LPN 需要时移交Low Power Node (LPN)支持 Low Power 特性并与 Friend 节点建立友情的节点通过轮询polling从 Friend 节点获取消息从而大幅降低接收机占空比与功耗Provisioner具备将设备加入 Mesh 网络能力的节点通过 App网关、手机、平板等载体完成配网与节点配置2.2 组成Composition术语说明State元素暴露的条件值如亮度、颜色、开关状态状态值变化会引发设备物理状态变化Model定义节点基本功能所需状态、控制消息、消息处理动作分 SIG Model 与 Vendor Model 两类Element设备内的可寻址实体每个元素拥有一个单播地址和若干 Model同一元素内 Model 不可重复Composition Data State包含节点信息、所含元素及支持的模型Provisioner 通过读取它来进一步配置设备2.3 特性Features特性说明Low Power仅在配合 Friend 特性时生效显著降低接收机占空比存在多个 Friend 节点时通过算法选择最合适的Friend为 LPN 暂存消息启用后可能带来更多功耗与内存消耗Relay经广播 bearer 接收并重传消息使消息可在节点间多次跳跃、覆盖整个网络节点只中继自己子网的消息对分段消息不等待完整报文、收到即转发Proxy在 GATT 与广播 bearer 间转发使无广播 bearer 的设备如手机可接入网络2.4 地址类型Address类型说明Unassigned Address值0x0000表示元素尚未配置或未分配单播地址建议作为用户代码设置地址前的初值Unicast Address配网时由 Provisioner 为每个元素分配的唯一地址可出现在消息源/目的地址字段Virtual Address表示一组目的地址逻辑上对应 128 位 Label UUID第 15、14 位分别为 1、0低 14 位为哈希值16384 个Group Address编程进零个或多个元素的多播地址all-proxies/all-friends/all-relays/all-nodes分别由启用对应功能节点的主元素处理2.5 安全与消息Device KeyDevKey每个节点唯一的特殊应用密钥仅节点与 Configuration Client 知道用于加密配置消息Provisioner 与节点之间的配置报文。Application KeyAppKey用于上层传输层Upper Transport Layer加解密应用数据AppKey 绑定到单个 NetKey只在所绑定 NetKey 的上下文中使用。Flooding Security Material由 NetKey 派生同网内任意节点可解密友情消息Friend Poll、Friend Update、Stored Messages 等使用友情安全材料加密Friend Clear 等使用泛洪安全材料加密。Directed Security Material由 NetKey 派生供定向转发路径上的节点使用只有同一路径上的节点可解密。Segmentation/Reassembly下层传输层自动分段大消息未分段消息最多 15 字节其中 4 字节 transMIC有效 11 字节分段时首几包每包 12 有效字节、最后一包 8 字节。Unacknowledged/Acknowledged按接收端是否需要响应分为两类消息发送端应设置最大重传次数。三、API 参考总体结构esp-ble-mesh.rst 将 ESP-BLE-MESH API 划分为四大块与仓库components/bt/esp_ble_mesh/的目录结构一一对应ESP-BLE-MESH Definitions由 esp_ble_mesh_defs.h 一个头文件承载。ESP-BLE-MESH Core API Reference对应 api/core 下的 7 组核心 API。ESP-BLE-MESH Models API Reference对应 api/models 下的 6 类模型 API。ESP-BLE-MESH (v1.1) Core API Reference对应 v1.1/api/core 下的 10 个新组件 API预览。四、ESP-BLE-MESH DefinitionsDefinitions 部分只有一个头文件 esp_ble_mesh_defs.h它集中定义了 ESP-BLE-MESH 的全部基础数据类型包括所有 Model 的 ID 及对应消息 opcode例如 Generic OnOff、Lighting、Sensor、Time and Scenes 各模型的 Client/Server 消息码。Model、Element 与 Composition Data 的结构体用于描述节点组成与能力上报。Node/Provisioner 配网所用的结构体配网参数、认证信息、OOB 数据等。消息收发transmit/receive用的结构体esp_ble_mesh_msg_ctx_t、esp_ble_mesh_opus_t等通用上下文与载荷。事件类型及事件参数协议栈主动上报给应用层的事件枚举与回调参数结构体。该头文件是所有上层 API 的共同基础无论开发 Node 还是 Provisioner 应用都应首先阅读。五、ESP-BLE-MESH Core API六大组成部分Core API 用于初始化协议栈、配网、发送/发布消息等官方文档将其划分为六个部分。下面逐一给出对应的源码文件与核心函数。5.1 协议栈初始化Stack Initialization对应 esp_ble_mesh_common_api.c 与头文件 esp_ble_mesh_common_api.h。核心入口esp_err_t esp_ble_mesh_init(esp_ble_mesh_prov_t *prov, esp_ble_mesh_comp_t *comp);prov配网参数Provisioning 参数含认证方式、OOB 数据、Provisioning 回调等。comp节点组成数据元素与模型注册表。协议栈的使能、卸载与节点移除等底层逻辑实现在 core/main.c。5.2 本地数据信息读取Local Data Operation对应 esp_ble_mesh_local_data_operation_api.h用于读取/操作节点本地信息典型函数包括esp_err_t esp_ble_mesh_node_add_local_net_key(const uint8_t net_key[16], uint16_t net_idx); esp_err_t esp_ble_mesh_node_add_local_app_key(const uint8_t app_key[16], uint16_t net_idx, uint16_t app_idx); esp_err_t esp_ble_mesh_node_bind_app_key_to_local_model(uint16_t element_addr, uint16_t company_id, uint16_t model_id, uint16_t app_idx);即向本地节点添加 NetKey/AppKey并将 AppKey 绑定到本地模型——这与 nRF Mesh App 中Model Bind AppKey的操作相对应。本地状态管理实现在 core/local.c。5.3 与 BLE 共存Coexist with BLE对应 esp_ble_mesh_ble_api.c 与 esp_ble_mesh_ble_api.h提供 ESP-BLE-MESH 与普通 BLE 功能共存的接口例如节点同时提供 BLE 外设服务与 Mesh 代理服务。上层适配逻辑分别位于 core/bluedroid_host/adapter.cBluedroid 版本与 core/nimble_host/adapter.cNimBLE 版本。5.4 低功耗操作Low Power Operation持续更新对应 esp_ble_mesh_low_power_api.h封装 Low Power 节点LPN行为如设置轮询超时、Friend 建立参数等。底层实现在 core/lpn.cFriend 侧对应 core/friend.c。官方文档标注该部分为Updating状态说明相关 API 仍处于演进中。5.5 发送/发布消息、添加本地 AppKey 等Networking对应 esp_ble_mesh_networking_api.h是日常开发使用频率最高的一组接口包括节点本地复位esp_ble_mesh_node_local_reset(void)Provisioner 节点管理esp_ble_mesh_provisioner_set_node_name、esp_ble_mesh_provisioner_store_node_comp_data、esp_ble_mesh_provisioner_delete_node_with_uuid/addrProvisioner 密钥管理esp_ble_mesh_provisioner_add_local_app_key、esp_ble_mesh_provisioner_update_local_app_key、esp_ble_mesh_provisioner_bind_app_key_to_local_model、esp_ble_mesh_provisioner_add/update_local_net_key心跳Heartbeatesp_ble_mesh_provisioner_recv_heartbeat、esp_ble_mesh_provisioner_set_heartbeat_filter_type/infoSettings 管理esp_ble_mesh_provisioner_open_settings_with_index/uid、close_settings_with_index/uid、delete_settings_with_index/uidv1.1 配网记录与链路管理配合 PB-Remoteesp_ble_mesh_provisioner_send_prov_records_get、send_prov_record_req、send_prov_invite、send_link_close底层网络层实现位于 core/net.c消息收发与分段重组位于 core/transport.c。5.6 Node/Provisioner 配网Provisioning对应 esp_ble_mesh_provisioning_api.c 与 esp_ble_mesh_provisioning_api.h。节点侧核心接口esp_err_t esp_ble_mesh_node_prov_enable(esp_ble_mesh_prov_bearer_t bearers); // 使能配网 bearerPB-ADV / PB-GATT esp_err_t esp_ble_mesh_node_prov_disable(esp_ble_mesh_prov_bearer_t bearers); esp_err_t esp_ble_mesh_node_set_oob_pub_key(uint8_t pub_key_x[32], uint8_t pub_key_y[32], uint8_t *private_key); esp_err_t esp_ble_mesh_node_input_number(uint32_t number); // Input OOB 认证输入 esp_err_t esp_ble_mesh_node_input_string(const char *string);实现上Node 侧配网逻辑位于 core/prov_node.cProvisioner 侧位于 core/prov_pvnr.c共同提供 PB-ADV 与 PB-GATT 两种 bearer 支持。5.7 GATT Proxy Server对应 esp_ble_mesh_proxy_api.h管理 GATT Proxy Server 的使能与去使能含身份广播模式用于 Private Network Identity 等场景。实现位于 core/proxy_server.c客户端侧对应 core/proxy_client.c。六、ESP-BLE-MESH Models API六类模型Models API 对应 api/models 目录官方文档将模型划分为六类每类均含 Client/Server 两侧 API模型类别源码文件说明Configuration Client/Serveresp_ble_mesh_config_model_api.c配置节点状态NetKey/AppKey 列表、Model 绑定、Key Refresh 等实现位于 core/cfg_cli.c 与 core/cfg_srv.cHealth Client/Serveresp_ble_mesh_health_model_api.c节点自诊断、故障读取Health Fault Get实现位于 core/health_cli.c 与 core/health_srv.cGeneric Client/Serveresp_ble_mesh_generic_model_api.c通用开关/电平/电池/位置/属性等实现位于 models/client/generic_client.c 与 models/server/generic_server.cSensor Client/Serveresp_ble_mesh_sensor_model_api.c传感器数据采集实现位于 models/client/sensor_client.c 与 models/server/sensor_server.cTime and Scenes Client/Serveresp_ble_mesh_time_scene_model_api.c时间、场景、定时器Scheduler模型Lighting Client/Serveresp_ble_mesh_lighting_model_api.c灯光亮度/色温/HSL/XYL/Ctl 等实现位于 models/client/lighting_client.c 与 models/server/lighting_server.c此外各 Client 模型的公共操作封装在 models/client/client_common.cSIG 模型与厂商模型的完整清单可查阅 docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rstGeneric 共 8 个 Client 模型、Sensor 1 个等。注意官方文档注明 Server 模型相关定义正在持续更新将很快发布补充。七、ESP-BLE-MESH v1.1 Core APIMesh 1.1 新特性预览Mesh Protocol v1.1 的 API 集中在 v1.1/api/core官方文档列出 10 个组件仓库还额外提供 DFU设备固件升级API。整个 v1.1 部分均为预览版本相关结构体、宏与 API 可能变更。组件头文件核心 API 示例Remote Provisioning远程配网PB-Remoteesp_ble_mesh_rpr_model_api.hesp_ble_mesh_rpr_client_send、esp_ble_mesh_rpr_client_action、esp_ble_mesh_rpr_server_set_uuid_matchDirected Forwarding定向转发esp_ble_mesh_df_model_api.hesp_ble_mesh_df_client_get_state、esp_ble_mesh_df_client_set_stateSubnet Bridge Configuration子网桥接esp_ble_mesh_brc_model_api.hesp_ble_mesh_brc_client_sendMesh Private Beacon私密信标esp_ble_mesh_prb_model_api.hesp_ble_mesh_prb_client_sendOn-Demand Private Proxy按需私密代理esp_ble_mesh_odp_model_api.hesp_ble_mesh_odp_client_sendSAR Configuration分段重组配置esp_ble_mesh_sar_model_api.hesp_ble_mesh_sar_client_sendSolicitation PDU RPL Configurationesp_ble_mesh_srpl_model_api.hesp_ble_mesh_srpl_client_sendOpcodes Aggregator操作码聚合器esp_ble_mesh_agg_model_api.hesp_ble_mesh_agg_client_sendLarge Composition Data大组成数据esp_ble_mesh_lcd_model_api.hesp_ble_mesh_lcd_client_sendComposition and Metadata组成与元数据esp_ble_mesh_cm_data_api.h—此外v1.1 目录下还提供设备固件升级相关 APIesp_ble_mesh_dfu_model_api.hDFU 模型、esp_ble_mesh_dfu_slot_api.h固件槽位、esp_ble_mesh_blob_model_api.h与esp_ble_mesh_mbt_model_api.hBLOB/MBT 传输对应源码位于 v1.1/api/models。对应术语说明Remote Provisioning Server/Client、Directed Forwarding Configuration、Bridge Configuration、Mesh Private Beacon、On-Demand Private Proxy、SAR、Opcodes Aggregator、Large Composition Data 等模型可查阅 ble-mesh-terminology.rst 的 Table 8。八、架构与实现从分层设计到源码文件ble-mesh-architecture.rst 将 ESP-BLE-MESH 架构划分为五个关键部分Mesh Protocol Stack含 Mesh Networking消息处理、Mesh Provisioning配网流程、Mesh ModelsSIG 模型实现。Network Management实现节点移除、IV Index 恢复/更新、Key Refresh、网络创建、NVS 存储等管理流程。FeaturesLow Power、Friend、Relay、Proxy Client/Server。Mesh Bearer LayerAdvertising Bearer 与 GATT Bearer是建立在 BLE 之上的数据承载层。Applications基于协议栈与 Models通过调用 API 和处理 Event 与应用交互。8.1 协议栈分层Mesh Networking层功能Access Layer定义应用数据格式并控制上层传输层的加解密源码core/access.cUpper Transport Layer加解密与认证应用数据处理传输控制消息友情相关、心跳源码core/transport.cLower Transport Layer负责 PDU 的分段与重组SARNetwork Layer定义网络消息的地址类型与格式实现设备中继功能源码core/net.c广播发送任务与收包回调位于 core/adv.c。8.2 配网分层Mesh Provisioning层功能Provisioning PDUs按配网协议处理各层 PDUGeneric Provisioning PDU / Proxy PDU通过通用配网层或代理协议层把 PDU 传给未配网设备PB-ADV / PB-GATT定义 PDU 如何作为可分段重组的事务传输Advertising / Provisioning Service定义会话建立方式使事务能投递到单一设备Node 侧实现core/prov_node.cPB-ADV PB-GATT、core/proxy_server.c、core/beacon.c。Provisioner 侧实现core/prov_pvnr.cPB-ADV PB-GATT、core/proxy_client.c、core/pvnr_mgmt.cProvisioner 组网管理。8.3 辅助例程Auxiliary Routine辅助例程指协议栈中的可选功能通常通过CONFIG_BLE_MESH相关配置做代码裁剪以独立模块方式实现模块文件Low Powercore/lpn.cFriendcore/friend.cRelay / 网络创建 / IV 更新与恢复 / Key Refreshcore/net.cProxy Server / Clientcore/proxy_server.c、core/proxy_client.cNVS 存储core/storage/settings.c初始化 / 使能 / 节点移除core/main.cBearer 的可移植性已充分考虑将 ESP-BLE-MESH 移植到其他平台时只需修改 core/bluedroid_host/adapter.c或 NimBLE 版本该文件是 Advertising Bearer 与 GATT Bearer 的实现。九、应用示例从配网到开关灯官方在 docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst 中给出了完整的上手流程配套示例位于 examples/bluetooth/esp_ble_meshonoff_models/onoff_server演示 Configuration Server 模型 Generic OnOff Server 模型三个元素分别控制 RGB LED 的红/绿/蓝。onoff_models/onoff_client节点内同时包含 Configuration Server 与 Generic OnOff Client 模型。provisioner设备作为 Provisioner 配网其他设备包含 Configuration Client 与 Generic OnOff Client 模型。fast_provisioningfast_prov_client 与 fast_prov_server 演示快速配网官方宣称可在 60 秒内配网最多 100 台设备。sensor_modelsProvisioner 中的 Sensor Client 与未配网设备中的 Sensor Server / Sensor Setup Server。vendor_models自定义厂商模型Vendor Client / Vendor Server。wifi_coexistWi-Fi 与 ESP-BLE-MESH 共存不支持 esp32h2。remote_provisioningrpr_client / rpr_server / unprov_dev 演示 Mesh Protocol v1.1 的远程配网与定向转发仅路径上的节点转发定向消息其他节点不参与。9.1 最小网络搭建步骤检查硬件ESP32-DevKitC 与 ESP-WROVER-KIT 均受支持若使用 ESP32-DevKitC 需在 GPIO 25/26/27 连接 RGB LED。通过idf.py menuconfig→Example Configuration→Board selection for ESP-BLE-MESH选择开发板。配置并编译进入onoff_server示例目录执行idf.py menuconfig选择开发板然后idf.py build。烧录三个节点将同一份编译产物用idf.py flash分别烧入三块开发板上电后每块板的 RGB LED 应点亮为绿色。配网使用 nRF MeshAndroid/iOS或 EspBleMesh 等 App 扫描未配网设备经过 IDENTIFY 确认后执行 PROVISION。配网成功后 LED 熄灭App 会依次断开重连、发现 ESP-BLE-MESH GATT 服务、读取 Composition Data 并添加 AppKey。配置模型将 AppKey 绑定到各元素内的 Generic OnOff Server 模型Configuration Server 模型无需绑定因为它只用 DevKey 加密上层传输消息。操作网络通过 App 发送 Generic OnOff 命令控制各节点的 RGB LED 颜色。已知问题nRF Mesh iOS Appv1.0.4在节点含多个元素时行为不正确操作第二/第三个 Generic OnOff Server 模型的消息会发往主元素内的第一个模型需要注意。十、进一步阅读完整特性清单含 Foundation Models 全部 22 个、Generic/Sensor 等 Client 模型ble-mesh-feature-list.rst架构详解与文件映射ble-mesh-architecture.rst术语表含 PB-ADV/PB-GATT/PB-Remote、四种认证方式、证书配网、IV Update 等ble-mesh-terminology.rst开发者 FAQ配网器开发、节点开发、BLE Mesh 与 Wi-Fi 共存、快速配网等ble-mesh-faq.rst中文版文档入口docs/zh_CN 下对应章节与英文版同步维护总结ESP-BLE-MESH 的 API 体系结构清晰esp_ble_mesh_defs.h提供全部基础类型Core API 负责初始化、配网、收发与低功耗等基础设施Models API 覆盖 SIG 定义的标准模型v1.1 Core API 则带来远程配网、定向转发、子网桥接、私密信标等下一代 Mesh 能力。开发时只需对照官方文档定位对应头文件再结合 examples/bluetooth/esp_ble_mesh 下的示例即可快速起步。需要注意 v1.1 相关 API 目前仍是预览状态在正式产品化前请持续关注 SDK 版本更新。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考