ESP-BLE-MESH 全量功能清单：从入网到远程运维，一文对照源码与示例定位全部能力

ESP-BLE-MESH 全量功能清单：从入网到远程运维，一文对照源码与示例定位全部能力

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

本文以 ESP-IDF 的 esp_ble_mesh 组件官方功能清单为线索，对照源码拆解 ESP-BLE-MESH 的蓝牙 Mesh 能力：支持哪些特性、哪些处于预览（Preview）阶段、每项特性的源码与可运行示例在哪里，帮助快速完成选型与上手。

📋 能力总览：功能域 × 源码落点对照表

先给结论：ESP-BLE-MESH 实现了 Mesh 1.0.1 的全部标准能力（配网、中继、Friend/低功耗、Proxy、全量标准模型），并向前兼容了 Mesh v1.1 的远程配网、定向转发等特性；其中仅设备固件升级（Device Firmware Update, DFU）四项模型标注为预览。协议栈基于 Zephyr Bluetooth Mesh 主机协议栈移植（底层抽象集中在 common/ 目录），对外 API 按 core、models、v1.1 三层暴露。

🔗 生命周期深挖：入网、通信、持久化、运维各环节如何定位

首次入网：Provisioner 如何把设备安全带进 Mesh

入网环节要解决的问题是：一台没有网络密钥（NetKey）的未配网设备，如何安全地获得身份并加入网络。官方示例中，手机 App 扫描到未配网节点、发起配网、完成组配置的全过程可参见下图：

• PB-ADV（Provisioning over Advertising）：走广播信道完成配网，无需建立 GATT 连接，是最常用的方式（佐证：core/prov_node.c）。
• PB-GATT（Provisioning over GATT）：走 GATT 连接完成配网，适配 Proxy 场景（佐证：core/prov_pvnr.c）。
• PB-Remote（远程配网承载）：Mesh v1.1 新增，Provisioner 借助已入网的 Remote Provisioning Server 触达远处设备（佐证：v1.1/api/core/rpr_model_api.c）。
• OOB 认证（Out-of-Band Authentication）：支持 No OOB、Static OOB、Output/Input OOB，用于防中间人攻击（佐证：core/prov_common.c）。
• 基于证书的配网（Certificate-based Provisioning）：以证书完成强身份验证（佐证：Kconfig 项 BLE_MESH_CERT_BASED_PROV）。
• 增强型配网认证（Enhanced Provisioning Authentication, EPA）：Mesh v1.1 的更强认证模式（佐证：Kconfig 项 BLE_MESH_PROV_EPA）。
• 快速配网（Fast Provisioning）：乐鑫私有扩展，官方口径为 60 秒内配网多达 100 台设备（佐证：core/fast_prov.c）。

关键开关集中在 Kconfig.in，例如：

CONFIG_BLE_MESH_PB_ADV=y CONFIG_BLE_MESH_PROV_EPA=y CONFIG_BLE_MESH_V11_SUPPORT=y

源码上，节点侧逻辑在 core/prov_node.c，Provisioner 侧在 core/prov_pvnr.c，公共的密钥派生与认证流程在 core/prov_common.c，多 Provisioner 实例管理在 core/pvnr_mgmt.c。要验证这条链路，直接跑 provisioner 示例，按配套教程逐步执行 PB-ADV 配网即可。

组网通信：Relay、Friend/低功耗与 Proxy 的转发路径

组网环节回答的问题是：一条消息如何低成本、可靠地从某个节点到达另一个节点，尤其是当两端相距多跳或一方处于深睡时。

• 中继（Relay）：入网节点对组播消息做多跳转发，扩展网络覆盖（佐证：core/net.c）。
• 分段与重组（SAR）：超过单包 MTU 的长消息自动拆分、在对端重组（佐证：core/transport.c，参数见 Kconfig 项 BLE_MESH_TX_SEG_MSG_COUNT）。
• 密钥刷新（Key Refresh）：怀疑网络密钥泄露后刷新 NetKey 的完整流程（佐证：core/prov_node.c）。
• IV 更新（IV Update）：周期性更新 IV Index，保证网络长期运行的消息新鲜性（佐证：core/local.c）。
• 好友节点（Friend）：常电节点为低功耗节点缓存消息（佐证：core/friend.c）。
• 低功耗节点（LPN）：周期性休眠，唤醒后主动向 Friend 取消息（佐证：core/lpn.c，总开关 BLE_MESH_LOW_POWER）。
• Proxy Server / Proxy Client：把 GATT 连接域与 Mesh 广播域打通，让不支持 Mesh 广播的 BLE 设备接入（佐证：core/proxy_server.c、core/proxy_client.c）。
• 定向转发（Directed Forwarding）：Mesh v1.1 特性，仅路径上的节点转发定向消息，其余节点不参与，降低无关节点的功耗（佐证：directed_forwarding 示例）。
• 私有信标（Private Beacon）：Mesh v1.1 特性，信标内容随机化以增强隐私（佐证：core/beacon.c）。
• 子网桥接（Subnet Bridge）：Mesh v1.1 特性，跨子网转发消息，上限由 Kconfig 项 BLE_MESH_SUBNET_COUNT 控制（佐证：Kconfig.in）。
• 小型增强项（Minor Enhancements）：规范中其余零星增强点的合集（佐证：core/ 目录整体）。

这些路径的公共入口在 core/net.c（入网/转发决策）与 core/transport.c（分段、访问控制与转发控制）中，v1.1 的转发增强通过 BLE_MESH_V11_SUPPORT 统一开启。想亲手观察定向转发的行为差异，参考 directed_forwarding 示例中 df_client 与 df_server 的对照结果。

本地持久化：重启后从 NVS 恢复已入网状态

持久化环节解决"断电重启后是否要重新配网"的问题：答案是否定的，配网结果与网络配置会被写回 NVS。

• NVS 存储（NVS Storing）：节点配网信息（NetKey、地址、Elements）与模型配置信息全部落盘，上电自动恢复（佐证：core/storage/settings_nvs.c）。
• 节点唯一标识生成：为节点生成并持久化 UID（佐证：core/storage/settings_uid.c）。
• 容量上限配置：子网数、AppKey 数、模型键数、组地址数等均有独立 Kconfig 上限（佐证：BLE_MESH_SUBNET_COUNT、BLE_MESH_APP_KEY_COUNT 等项）。

实现集中在 core/storage/ 目录下的 settings.c（统一读写接口）、settings_nvs.c（NVS 后端）与 settings_uid.c（UID 后端）三个文件，API 侧对应 api/core/ 下的 esp_ble_mesh_local_data_operation_api.h。整体分层与数据流向在 ble-mesh-architecture.rst 中有图示说明，可配合 provisioner 示例中反复删档重配的实验观察落盘行为。

远程运维：v1.1 新特性与固件升级从哪里入手

运维环节解决的是"设备已批量入网后，如何不改现场就能调整网络行为、更新固件"的问题，Mesh v1.1 把这部分能力做成了独立模型。

• 多 Client Model 并发运行：多个 Client Model 同时向不同节点发包，Client 与 Server 模型之间互不阻塞（佐证：models/ 目录与 btc/ 的模型公共层 btc_ble_mesh_model_common.c）。
• Remote Provisioning Server/Client：通过已入网节点远程给远处设备配网（佐证：v1.1/api/core/rpr_model_api.c）。
• Directed Forwarding / Bridge / Private Beacon / On-Demand Private Proxy / SAR / SRPL / Opcodes Aggregator / Large Composition Data 配置模型：八组 v1.1 配置类模型的 Server/Client 成对提供（佐证：v1.1/api/core/ 下 df_model_api.c、brc_model_api.c、prb_model_api.c、odp_model_api.c、sar_model_api.c、srpl_model_api.c、agg_model_api.c、cm_data_api.c）。
• 设备固件升级（DFU，预览）：Firmware Update Client/Server 负责升级流程，Firmware Distribution Client/Server 支持经多个节点接力分发固件镜像（佐证：v1.1/dfu/ 目录）。

配置类模型的 API 统一放在 v1.1/api/core/ 下按模型一文件一模块，与 1.0 的 api/ 目录并列；DFU 的底层状态机独立在 v1.1/dfu/。完整链路可在 remote_provisioning 示例中验证，它提供 rpr_client、rpr_server、unprov_dev 三个角色的完整配网与转发演示。

🧩 模型与子系统支持矩阵

Foundation 模型、标准模型的 Client 与 Server 合并登记如下（模型总数以官方功能清单为准，合计 Foundation 24 个、标准 Client 17 个、标准 Server 34 个、DFU 4 个预览模型）：

🧪 预览与实验特性：使用前先核对版本

• DFU 四项模型（预览 Preview）：Firmware Update Client/Server 与 Firmware Distribution Client/Server 在官方功能清单中均明确标注 (Preview)，源码位于 v1.1/dfu/，正式使用前请核对 ESP-IDF 版本说明与发布注记。
• Mesh v1.1 特性集整体：由 Kconfig 项 BLE_MESH_V11_SUPPORT 统一开关，默认开启，其 help 文本同样带 (Preview) 标记；远程配网、定向转发、私有信标、子网桥接等 v1.1 能力都在此开关之下。
• 实验性广播选项：BLE_MESH_USE_BLE_50、BLE_MESH_EXT_ADV、BLE_MESH_LONG_PACKET 均依赖 BLE_MESH_EXPERIMENTAL（实验性总开关）才可见；BLE_MESH_HCI_5_0 的说明中自称是 temporary solution（临时方案）。
• 提醒：预览与实验特性的 API、行为可能随版本调整，接入量产项目前请以官方版本说明为准。

🚀 上手路径：按目标选示例

• 体验最基础的开关控制→ onoff_models（onoff_server 演示 Configuration Server + Generic OnOff Server 组合，onoff_client 演示客户端控制），配套教程见 BLE_Mesh_Node_OnOff_Client_Example_Walkthrough.md。
• 自己写一个配网端→ provisioner 示例（含 Configuration Client 与 Generic OnOff Client），教程在示例目录的 tutorial/ 下。
• 工厂批量配网→ fast_provisioning（fast_prov_client + fast_prov_server，官方口径 60 秒配 100 台），参考 BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md。
• 上报传感器数据→ sensor_models（sensor_client 配在 Provisioner 上，sensor_server + Sensor Setup Server 配在节点上）。
• 定义私有 Opcode 与属性→ vendor_models；若要对接天猫精灵生态，另有 aligenie_demo 示例。
• 体验 v1.1 远程配网与定向转发→ remote_provisioning（rpr_client/rpr_server/unprov_dev 三角色）与 directed_forwarding（df_client/df_server），两个示例共用 BLE_MESH_V11_SUPPORT 开关。
• 同一设备跑 Wi-Fi 与 Mesh→ wifi_coexist（esp32h2 不支持，其余芯片可用）。

📚 选型提示与延伸阅读

• ble-mesh-feature-list.rst：官方功能清单原文，本文能力总览表的核对基准。
• ble-mesh-index.rst：总览页，含快速入门、示例索引与 FAQ 入口。
• ble-mesh-architecture.rst：架构说明，理解分层与数据流向后再读源码效率更高。
• ble-mesh-faq.rst：配网失败、低功耗异常、Wi-Fi 共存等问题排查优先查这里。
• ble-mesh-terminology.rst：术语表，Element、Model、NetKey 等概念的标准定义。
• api/core/include：对外 API 头文件目录，配网、组网、低功耗、本地数据操作、Proxy 五大组接口都在这里。

结语

ESP-BLE-MESH 的能力面覆盖了三条主线：Mesh 1.0.1 的基础配网、中继、Friend/低功耗、Proxy 与全量标准模型；Mesh v1.1 的远程配网、定向转发、私有信标、子网桥接等九组新模型；以及预览阶段的设备固件升级链路。配合 NVS 持久化、多 Client 并发与快速配网扩展，它适合作为照明控制、传感组网与带 Wi-Fi 共存的边缘网关场景的选型基础。对预览特性与实验性广播选项保持版本核对习惯，即可从原型验证平滑走到量产。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf