feat(ble_mesh): Support Bluetooth Mesh Protocol v1.1 (Preview)

2025-09-30 19:19:21 +00:00 · 2023-08-28 16:09:37 +08:00
parent fd451f5856
commit 5bab168b0e
271 changed files with 32403 additions and 7253 deletions
--- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst
+++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst
@@ -390,7 +390,7 @@ When adopting the design of independent module, the two main factors should be c
    - ESP-BLE-MESH Proxy Server related functionalities
  * - :component_file:`proxy_client.c <bt/esp_ble_mesh/core/proxy_client.c>`
    - ESP-BLE-MESH Proxy Client related functionalities
-  * - :component_file:`settings.c <bt/esp_ble_mesh/core/settings.c>`
+  * - :component_file:`settings.c <bt/esp_ble_mesh/core/storage/settings.c>`
    - ESP-BLE-MESH NVS storage functionality
  * - :component_file:`main.c <bt/esp_ble_mesh/core/main.c>`
    - ESP-BLE-MESH stack initialize, stack enable, node removal related functionalities
--- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
+++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
@@ -568,7 +568,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m

    The **count** value is provided to the Proxy node which is provisioned by the App so as to determine when to start Proxy advertising in advance.

-4.5 When will Configuration Client Model of the node running :example:`fast_prov_server <bluetooth/esp_ble_mesh/fast_provision/fast_prov_server>` example start to work?
+4.5 When will Configuration Client Model of the node running :example:`fast_prov_server <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_server>` example start to work?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled.
--- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
+++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
@@ -7,13 +7,12 @@ Supported Features
 Mesh Core
 """""""""

-* Provisioning: Node Role
-    * PB-ADV and PB-GATT
-    * OOB Authentication
-
-* Provisioning: Provisioner Role
-    * PB-ADV and PB-GATT
+* Provisioning:
+    * PB-ADV, PB-GATT and PB-Remote
    * OOB Authentication
+    * Certificate-based Provisioning
+    * Remote Provisioning
+    * Enhanced Provisioning Authentication

 * Networking
    * Relay
@@ -24,6 +23,10 @@ Mesh Core
    * Low Power
    * Proxy Server
    * Proxy Client
+    * Directed Forwarding
+    * Private Beacon
+    * Subnet Bridge
+    * Minor Enhancements

 * Multiple Client Models Run Simultaneously
    * Support multiple client models send packets to different nodes simultaneously
@@ -40,6 +43,24 @@ Mesh Models
    * Configuration Client model
    * Health Server model
    * Health Client model
+    * Remote Provisioning Server model
+    * Remote Provisioning Client model
+    * Directed Forwarding Configuration Server model
+    * Directed Forwarding Configuration Client model
+    * Bridge Configuration Server model
+    * Bridge Configuration Client model
+    * Mesh Private Beacon Server model
+    * Mesh Private Beacon Client model
+    * On-Demend Private Proxy Server model
+    * On-Demend Private Proxy Client model
+    * SAR Configuration Server model
+    * SAR Configuration Client model
+    * Solicitation PDU RPL Configuration Server model
+    * Solicitation PDU RPL Configuration Client model
+    * Opcodes Aggregator Server model
+    * Opcodes Aggregator Client model
+    * Large Composition Data Server model
+    * Large Composition Data Client model

 * Generic client models
    * Generic OnOff Client
@@ -120,9 +141,9 @@ Mesh Applications
    * :example_file:`Tutorial <bluetooth/esp_ble_mesh/provisioner/tutorial/BLE_Mesh_Provisioner_Example_Walkthrough.md>`
    * :example:`Example <bluetooth/esp_ble_mesh/provisioner>`
 * ESP-BLE-MESH Fast Provisioning
-    * :example_file:`Fast Provisioning Client Model Tutorial <bluetooth/esp_ble_mesh/fast_provision/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>`
-    * :example_file:`Fast Provisioning Server Model Tutorial <bluetooth/esp_ble_mesh/fast_provision/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>`
-    * :example:`Example <bluetooth/esp_ble_mesh/fast_provision>`
+    * :example_file:`Fast Provisioning Client Model Tutorial <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>`
+    * :example_file:`Fast Provisioning Server Model Tutorial <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>`
+    * :example:`Example <bluetooth/esp_ble_mesh/fast_provisioning>`
    * `Demo Video <https://dl.espressif.com/BLE/public/ESP32_BLE_Mesh_Fast_Provision.mp4>`__
 * ESP-BLE-MESH and Wi-Fi Coexistence
    * :example_file:`Tutorial <bluetooth/esp_ble_mesh/wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>`
--- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
+++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
@@ -219,10 +219,14 @@ ESP-BLE-MESH Examples

 * :example_file:`ESP-BLE-MESH Provisioner <bluetooth/esp_ble_mesh/provisioner/tutorial/BLE_Mesh_Provisioner_Example_Walkthrough.md>` - shows how a device can act as an ESP-BLE-MESH Provisioner to provision devices. The Provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model, see :example:`example code <bluetooth/esp_ble_mesh/provisioner>`.

-* ESP-BLE-MESH Fast Provisioning - :example_file:`Client <bluetooth/esp_ble_mesh/fast_provision/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example_file:`Server <bluetooth/esp_ble_mesh/fast_provision/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/fast_provision/fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/fast_provision/fast_prov_server>`.
+* ESP-BLE-MESH Fast Provisioning - :example_file:`Client <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example_file:`Server <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_server>`.

 * :example_file:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/wifi_coexist>`.

+* ESP-BLE-MESH Remote Provisioning(v1.1) - :example_file:`Client, Server and device <bluetooth/esp_ble_mesh/remote_provisioning/tutorial/BLE_Mesh_Remote_Provisioning_Example_Walkthrough.md>` - this example is used to demonstrate the new remote provisioning feature introduced in the Mesh Protocol v1.1, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>`, :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>` and :example:`example device code <bluetooth/esp_ble_mesh/remote_provisioning/unprov_dev>`.
+
+* ESP-BLE-MESH Directed Forwarding(v1.1) - :example_file:`Client and Server <bluetooth/esp_ble_mesh/directed_forwarding/tutorial/BLE_Mesh_Directed_Forwarding_Example_Walkthrough.md>` - this example is used to demonstrate the new directed forwarding feature introduced in the Mesh Protocol v1.1. Only nodes along the path will forward the directed messages, while other nodes will not actively participate in forwarding, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>` and :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>`.
+

 .. _esp-ble-mesh-demo-videos:

@@ -262,7 +266,9 @@ Bluetooth SIG Documentation
 ---------------------------

 - `BLE Mesh Core Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429633>`_
+- `BLE Mesh Protocol v1.1 Specification(draft) <https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=554899>`_
 - `BLE Mesh Model Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429634>`_
+- `BLE Mesh Model v1.1 Specification(draft) <https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=557081>`_
 - `An Intro to Bluetooth Mesh Part 1 <https://www.bluetooth.com/blog/an-intro-to-bluetooth-mesh-part1>`_ / `Part 2 <https://www.bluetooth.com/blog/an-intro-to-bluetooth-mesh-part2>`__
 - `The Fundamental Concepts of Bluetooth Mesh Networking, Part 1 <https://www.bluetooth.com/blog/the-fundamental-concepts-of-bluetooth-mesh-networking-part-1>`_ / `Part 2 <https://www.bluetooth.com/blog/the-fundamental-concepts-of-bluetooth-mesh-networking-part-2>`__
 - `Bluetooth Mesh Networking: Friendship <https://www.bluetooth.com/blog/bluetooth-mesh-networking-series-friendship>`_
--- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst
+++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst
@@ -95,7 +95,10 @@ ESP-BLE-MESH Terminology
    - PB-ADV transfers packets generated during the provisioning process over the advertising channels. This way can only be used for provisioning when provisioner and unprovisioned device both support PB-ADV.
  * - PB-GATT
    - PB-GATT is a provisioning bearer used to provision a device using Proxy PDUs to encapsulate Provisioning PDUs within the Mesh Provisioning Service.
-    - PB-GATT uses connection channels to transfer packets generated during the provisioning process. If an unprovisioned device wants to be provisioned through this method, it needs to implement the related Mesh Provisioning Service. Unprovisioned devices which do not implement such service cannot be provisioned into mesh network through PB-GATT bearer.
+    - PB-GATT uses connection channels to transfer packets generated during the provisioning process. If an unprovisioned device wants to be provisioned through this method, it needs to implement the related Mesh Provisioning Service. Unprovisioned devices which don't implement such service cannot be provisioned into mesh network through PB-GATT bearer.
+  * - PB-Remote
+    - The PB-Remote provisioning bearer uses the existing mesh network to provision an unprovisioned device that is not within immediate radio range of the Provisioner.
+    - PB-Remote uses the PB-ADV bearer or the PB-GATT bearer for the last hop to the unprovisioned device.
  * - Provisioning
    - Provisioning is a process of adding an unprovisioned device to a mesh network, managed by a Provisioner.
    - The process of provisioning turns the "unprovisioned device" into a "node", making it a member of the ESP-BLE-MESH network.
@@ -114,6 +117,9 @@ ESP-BLE-MESH Terminology
  * - No OOB
    - No Out-of-Band
    - Authentication method of No OOB: Set the value of the Static OOB field to 0. Using this way is like not authenticating the unprovisioned devices.
+  * - Certificate-based Provisioning
+    - Certificate-based Out-of-Band
+    - The certificate-based provisioning feature makes use of Public Key Infrastructure to authenticate unprovisioned device's public key and UUID information.


 .. _ble-mesh-terminology-address:
@@ -154,10 +160,12 @@ ESP-BLE-MESH Terminology
  * - Application Key (AppKey)
    - Application keys are used to secure communications at the upper transport layer.
    - Application key is used for decryption of application data before delivering application data to application layer and encryption of them during the delivery of application layer. Some nodes in the network have a specific purpose and can restrict access to potentially sensitive data based on the needs of the application. With specific application keys, these nodes are associated with specific applications. Generally speaking, the fields using different application keys include security (access control of buildings, machine rooms and CEO offices), lighting (plant, exterior building and sidewalks) and HVAC systems. Application keys are bound to Network keys. This means application keys are only used in a context of a Network key they are bound to. An application key shall only be bound to a single Network key.
-  * - Master Security Material
-    - The master security material is derived from the network key (NetKey) and can be used by other nodes in the same network. Messages encrypted with master security material can be decoded by any node in the same network.
-    - The corresponding friendship messages encrypted with the friendship security material: 1. Friend Poll, 2. Friend Update, 3. Friend Subscription List, add/delete/confirm, 4. The Stored Messages" sent by friend nodes to Low Power node. The corresponding friendship messages encrypted with the master security material: 1. Friend Clear, 2. Friend Clear Confirm. Based on the setup of the applications, the messages sent from the Low Power node to the friend nodes will be encrypted with the friendship security material or master security material, with the former being used by the messages transmitted between Low Power node and friend nodes and the latter being used by other network messages.
-
+  * - Flooding Security Material
+    - The flooding security material is derived from the network key (NetKey) and can be used by other nodes in the same network. Messages encrypted with flooding security material can be decoded by any node in the same network.
+    - The corresponding friendship messages encrypted with the friendship security material: 1. Friend Poll, 2. Friend Update, 3. Friend Subscription List, add/delete/confirm, 4. The Stored Messages" sent by friend nodes to Low Power node. The corresponding friendship messages encrypted with the flooding security material: 1. Friend Clear, 2. Friend Clear Confirm. Based on the setup of the applications, the messages sent from the Low Power node to the friend nodes will be encrypted with the friendship security material or flooding security material, with the former being used by the messages transmitted between Low Power node and friend nodes and the latter being used by other network messages.
+  * - Directed Security Material
+    - The directed security material is derived from the network key (NetKey) and can be used by other nodes in the directed forwarding path.
+    - The messages that need to be forwarded through the directed forwarding path need to be encrypted with the directed security material. Messages encrypted with directed security material can be decoded by any node in the same directed forwarding path.

 .. _ble-mesh-terminology-message:

@@ -197,6 +205,60 @@ ESP-BLE-MESH Terminology
  * - Health Client Model
    - The model is used to represent an element that can control and monitor the health of a node.
    - The Health Client Model uses messages to control the state maintained by the Health Server Model. The model can get the self-test information of other nodes through the message "Health Fault Get".
+  * - Remote Provisioning Server model
+    - The model is used to support the functionality of provisioning a remote device over the mesh network and to perform the Node Provisioning Protocol Interface procedures.
+    - The Remote Provisioning Server model is a root model and a main model that does not extend any other models.
+  * - Remote Provisioning Client model
+    - The model is used to support the functionality of provisioning devices into a mesh network by interacting with a mesh node that supports the Remote Provisioning Server model.
+    - The Remote Provisioning Client is a root model and a main model that does not extend any other models. The Remote Provisioning Client may operate on states defined by the Remote Provisioning Server model using Remote Provisioning messages.
+  * - Directed Forwarding Configuration Server model
+    - The model is used to support the configuration of the directed forwarding functionality of a node.
+    - The Directed Forwarding Configuration Server model is a main model that extends the Configuration Server model.
+  * - Directed Forwarding Configuration Client model
+    - The model is used to support the functionality of a node that can configure the directed forwarding functionality of another node.
+    - The Directed Forwarding Configuration Client model is a root model and a main model that does not extend any other models. The Directed Forwarding Configuration Client model may operate on states defined by the Directed Forwarding Configuration Server model using Directed Forwarding Configuration messages.
+  * - Bridge Configuration Server model
+    - The model is used to support the configuration of the subnet bridge functionality of a node.
+    - The Bridge Configuration Server model is a main model that extends the Configuration Server model.
+  * - Bridge Configuration Client model
+    - The model is used to support the functionality of a node that can configure the subnet bridge functionality of another node.
+    - The Bridge Configuration Client model is a root model and a main model that does not extend any other models. The Bridge Configuration Client model may operate on states defined by the Bridge Configuration Server model using Bridge messages.
+  * - Mesh Private Beacon Server model
+    - The model is used to support the configuration of the Mesh Private beacons functionality of a node.
+    - The Mesh Private Beacon Server model is a main model that extends the Configuration Server model.
+  * - Mesh Private Beacon Client model
+    - The model is used to support the functionality of a node that can configure the Mesh Private beacons functionality of another node.
+    - The Mesh Private Beacon Client model is a root model and a main model that does not extend any other models. The Mesh Private Beacon Client model may operate on states defined by the Mesh Private Beacon Server model using Mesh Private Beacon messages.
+  * - On-Demend Private Proxy Server model
+    - The model is used to support the configuration of the advertising with Private Network Identity type functionality of a node.
+    - The On-Demand Private Proxy Server model is a main model that extends the Mesh Private Beacon Server model and corresponds with the Solicitation PDU RPL Configuration Server model.
+  * - On-Demend Private Proxy Client model
+    - The model is used to support the functionality of a node that can configure the advertising with Private Network Identity type functionality of another node.
+    - The On-Demand Private Proxy Client model is a root model and a main model that does not extend any other models. The On-Demand Private Proxy Client model may operate on states defined by the On-Demand Private Proxy Server model using On-Demand Private Proxy messages.
+  * - SAR Configuration Server model
+    - The model is used to support the configuration of the segmentation and reassembly behavior of a node.
+    - The SAR Configuration Server model is a root model and a main model that does not extend any other models.
+  * - SAR Configuration Client model
+    - The SAR Configuration Client model is used to support the functionality of configuring the behavior of the lower transport layer of a node that supports the SAR Configuration Server model.
+    - The SAR Configuration Client model is a root model and a main model that does not extend any other models. The SAR Configuration Client model may operate on states defined by the SAR Configuration Server model using SAR Configuration messages.
+  * - Solicitation PDU RPL Configuration Server model
+    - The Solicitation PDU RPL Configuration Server model is used to support the functionality of removing items from the solicitation replay protection list of a node.
+    - The Solicitation PDU RPL Configuration Server model corresponds with the On-Demand Private Proxy Server model.
+  * - Solicitation PDU RPL Configuration Client model
+    - The model is used to support the functionality of removing addresses from the solicitation replay protection list of a node that supports the Solicitation PDU RPL Configuration Server model.
+    - The Solicitation PDU RPL Configuration Client model is a root model and a main model that does not extend any other models. The Solicitation PDU RPL Configuration Client model may be used to remove items from a solicitation replay protection list of a peer node by using Solicitation PDU RPL Configuration messages.
+  * - Opcodes Aggregator Server model
+    - The model is used to support the functionality of processing a sequence of access layer messages.
+    - The Opcodes Aggregator Server model is a root model that does not extend any other models.
+  * - Opcodes Aggregator Client model
+    - The model is used to support the functionality of dispatching a sequence of access layer messages to nodes supporting the Opcodes Aggregator Server model.
+    - The Opcodes Aggregator Client model is a root model and a main model that does not extend any other models.
+  * - Large Composition Data Server model
+    - The model is used to support the functionality of exposing pages of Composition Data that do not fit in a Config Composition Data Status message and to expose metadata of the model instances.
+    - The Large Composition Data Server is a main model that extends the Configuration Server model.
+  * - Large Composition Data Client model
+    - The model is used to support the functionality of reading pages of Composition Data that do not fit in a Config Composition Data Status message and reading the metadata of the model instances.
+    - The Large Composition Data Client model is a root model that does not extend any other models. The Large Composition Data Client model may operate on states defined by the Large Composition Data Server model using Large Composition Data messages.


 .. _ble-mesh-terminology-network-management: