This document introduces ESP-BLE-MESH architecture overview, ESP-BLE-MESH architecture implementation as well as ESP-BLE-MESH auxiliary routines.
- ESP-BLE-MESH Architecture Overview
- Describes the five major parts of ESP-BLE-MESH architecture and the functionality of each part.
- ESP-BLE-MESH Architecture Implementation
- Describes the basic functions of ESP-BLE-MESH files, the correspondence between files and ESP-BLE-MESH architecture, and the interface for calling among files.
- ESP-BLE-MESH Auxiliary Routines
- Describe the auxiliary routines of ESP-BLE-MESH, such as Mesh network management, Mesh features, etc.
1. ESP-BLE-MESH Architecture Overview
-------------------------------------
Currently ESP-BLE-MESH has implemented most functions of Mesh Profile and all the Client Models defined in Mesh Model specification. Those missing functions/models are under development and will be provided soon. ESP-BLE-MESH architecture has been granted the official Bluetooth `certification <https://launchstudio.bluetooth.com/ListingDetails/76255>`__.
- Includes ``Advertising Bearer`` and ``GATT Bearer``. The bearer layer is crucial to ESP-BLE-MESH protocol stack which is built on Bluetooth Low-Energy technology, because the protocol stack must make use of the bearer layer to transmit data via the BLE advertising channel and connection channel.
-``Applications``
- Based on ESP-BLE-MESH protocol stack and ``Mesh Models``.
- By calling API and handling Event, ``Applications`` interact with ``Mesh Networking`` and ``Mesh Provisioning`` in ESP-BLE-MESH protocol stack, as well as a series of Models provided by ``Mesh Models``.
- Access Layer not only defines the format of application data, but also defines and controls the encryption and decryption of the data packets conducted by Upper Transport Layer.
* - Upper Transport Layer
- Upper Transport Layer encrypts, decrypts, and authenticates application data to and from the access layer; it also handles special messages called "transport control messages", including messages related to "friendship" and heartbeat messages.
* - Lower Transport Layer
- Lower Transport Layer handles segmentation and reassembly of PDU.
* - Network Layer
- Network Layer defines the address type and format of the network messages, and implements the relay function of the device.
1.1.2 Mesh Provisioning
^^^^^^^^^^^^^^^^^^^^^^^
``Mesh Provisioning`` in the protocol stack architecture implements the following functions:
- Provisioning of unprovisioned devices.
- Allocation of Mesh network resources (unicast address, IV Index, NetKey, etc.).
- Four authentication methods support during provisioning.
- For more features, please see :doc:`ble-mesh-feature-list`.
The implementation of ``Mesh Provisioning`` functions is based on hierarchy structure. Functions of each layer are shown in Table 1.2:
- Provisioning PDUs from different layers are handled using provisioning protocol.
* - Generic Provisioning PDU/Proxy PDU
- The Provisioning PDUs are transmitted to an unprovisioned device using a Generic Provisioning layer or Proxy protocol layer.
* - PB-ADV/PB-GATT
- These layers define how the Provisioning PDUs are transmitted as transactions that can be segmented and reassembled.
* - Advertising/Provisioning Service
- The provisioning bearers define how sessions are established such that the transactions from the generic provisioning layer can be delivered to a single device.
1.1.3 Mesh Models
^^^^^^^^^^^^^^^^^
``Mesh Models`` in the protocol stack architecture implements the following functions:
- Model Layer implements models used to standardize the operation of typical user scenarios, including Generic Client/Server Models, Sensor Client/Server Models, Time and Scenes Client/Server Models, Lighting Client/Server Models and several vendor models.
* - Foundation Model Layer
- Foundation Model Layer implements models related to ESP-BLE-MESH configuration, management, self diagnosis, etc.
1.2 Mesh Network Management
---------------------------
``Network Management`` implements the following functions:
- Node removal procedure is used to remove a node from the network.
- IV Index recovery procedure is used to recover a node's IV Index.
- IV update procedure is used to update the nodes' IV Index.
- Key refresh procedure is used to update the nodes' NetKey, AppKey, etc.
- Network creation procedure is used to create a mesh network.
- NVS storage is used to store node's networking information.
1.3 Mesh Features
-----------------
``Features`` includes the following options:
- Low Power feature is used to reduce node's power consumption.
- Friend feature is used to store messages for Low Power nodes.
- Relay feature is used to relay/forward Network PDUs received by a node over the advertising bearer.
- Proxy Server/Client are two node roles in proxy protocol, which enable nodes to send and receive Network PDUs, mesh beacons, proxy configuration messages and Provisioning PDUs over a connection-oriented bearer.
1.4 Mesh Bearer Layer
---------------------
``Bearers`` in the protocol stack architecture are responsible for passing of data between ESP-BLE-MESH protocol stack and Bluetooth Low Energy Core.
``Bearers`` can be taken as a carrier layer based on Bluetooth Low Energy Core, which implements the function of receiving and transmitting data for the ESP-BLE-MESH protocol stack.
..list-table:: Table 1.3 Mesh Bearers Description
:widths:40 150
:header-rows:1
* - Layer
- Function
* - GATT Bearer
- The GATT Bearer uses the Proxy protocol to transmit and receive ``Proxy PDUs`` between two devices over a GATT connection.
* - Advertising Bearer
- When using the Advertising Bearer, a mesh packet shall be sent in the Advertising Data of a ``Bluetooth Low Energy advertising PDU`` using the Mesh Message AD Type.
1.5 Mesh Applications
---------------------
The ``Applications`` in the protocol stack architecture implement the corresponding functions by calling the API provided by the ESP-BLE-MESH protocol stack and processing the Event reported by the protocol stack. There are some common applications, such as gateway, lighting and etc.
- Call the provisioning-related API for provisioning.
- Call the model-related API to send messages.
- Call the device-attributes-related API to get local information about the device.
- Application layer processes Event
The application layer is designed based on events, which take parameters to the application layer. Events are mainly divided into two categories.
- The events completed by calling API.
- Such as nodes sending messages.
- The events that the protocol stack actively reports to the application layer.
- The Event that the protocol stack actively reports.
- The Event that Model actively reports.
- The event is reported by the callback function registered by the application layer, and the callback function also contains the corresponding processing of the event.
Interaction between ``API / Event`` and ESP-BLE-MESH protocol stack
- API used by user mainly calls functions provided by ``Mesh Networking``, ``Mesh Provisioning`` and ``Mesh Models``.
- The interaction between ``API / Event`` and the protocol stack does not operate across the hierarchy of the protocol stack. For example, API does not call functions related to ``Network Layer``.
2. ESP-BLE-MESH Architecture Implementation
-------------------------------------------
The design and implementation of ESP-BLE-MESH architecture is based on layers and modules. In details, Section 2.1 (Mesh Networking Implementation), Section 2.2 (Mesh Provisioning Implementation) and Section 2.3 (Mesh Bearers Implementation) are based on layers, and Section 2.4 (Mesh Models Implementation) is on modules.
-**Layer-based Approach**: With Layer-based approach, the architecture is designed according to the layers specified in the Mesh Profile Specification. Each layer has its unique files which include APIs of this layer and etc. The specific design is shown in Figure 2.1.
-**Module-based Approach**: Every file implements an independent function that can be called by other programs.
The design of ESP-BLE-MESH architecture uses layer-based approach. The sequence of layers which data packets are processed through is fixed, i.e., the processing of packets will form a ``message flow``. Thus, we could see flows of messages from the Protocol Stack Interface Diagram in Figure 2.1.
2.1 Mesh Protocol Stack Implementation
--------------------------------------
2.1.1 Mesh Networking Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The list of files and the functions implemented in each file in ``Mesh Networking`` are shown in Table 2.1:
Mesh Models are used to implement the specific functions of model in nodes. Server model is used to maintain node status. Client model is used to obtain and modify node state.
Portability is fully considered in the implementation of Mesh Bearers. When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify :component_file:`adapter.c <bt/esp_ble_mesh/core/bluedroid_host/adapter.c>` (example of :component_file:`NimBLE version <bt/esp_ble_mesh/core/nimble_host/adapter.c>`).
:component_file:`adapter.c <bt/esp_ble_mesh/core/bluedroid_host/adapter.c>` is the implementation of ``Advertising Bearer`` and ``GATT Bearer`` in Mesh Networking framework.
We have provided a series of application examples for customer development, and users can develop products based on :ref:`esp-ble-mesh-examples`.
3. Auxiliary Routine
---------------------
Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The design of the auxiliary routine generally implement the truncation of code through :ref:`CONFIG_BLE_MESH`.
3.1 Features
^^^^^^^^^^^^
- Low Power
- Friend
- Relay
- Proxy Client/Server
3.2 Network Management
^^^^^^^^^^^^^^^^^^^^^^
- Node Removal procedure
- IV Index Recovery procedure
- IV Update procedure
- Key Refresh procedure
- Network Creation procedure
- NVS Storage
3.3 Auxiliary Routine Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When adopting the design of independent module, the two main factors should be considered:
- The module can not be implemented hierarchically, and it can be completely independent, which means it does not rely on the implementation of other modules.
- The functions in the module will be used repeatedly, so it is reasonable to design it into a module. Independent module is shown in Table 3.1:
