The mesh stack consists of a number of subsystems that are interfaced through a set of API modules, and are involved in the Mesh network data flow. The API modules hide the complexity of their subsystems. The functionality provided in the API is sufficient to make a functioning mesh device, so that there is no need to bypass the API.

Basic architecture of the mesh stack in the nRF5 SDK for Mesh

The mesh stack's structure corresponds to the structure of the Bluetooth Mesh Specification and follows the same naming conventions:

Models: The Bluetooth Mesh models present and implement device behavior.
Access: The Bluetooth Mesh access layer organizes models and communication.
DSM: The Device State Manager stores addresses and encryption keys for usage in the models.
Core: The Core Bluetooth Mesh layer takes care of encryption and message relaying.
Provisioning: The Bluetooth Mesh provisioning protocol is used for adding devices to the network.
Bearer: The Bearer layer takes care of low-level radio operation.
DFU: The Device Firmware Upgrade module cooperates with a bootloader to enable firmware upgrades through the mesh.
Mesh Stack (not pictured): Top level functionality for initializing and starting the stack.
Serial (not pictured): Application-level serialization of the Mesh API allows the mesh to be controlled by a separate host device.

Check the official Bluetooth Mesh glossary for definitions of the most important Mesh-related terms used in this documentation. You can also read Basic Bluetooth Mesh concepts for a concise introduction to the Bluetooth Mesh.

Mesh network data flow

The following figure demonstrates how the data packets flow between mesh nodes and their layers within the mesh stack structure.

Basic data flow within a mesh network in the nRF5 SDK for Mesh

For example, after a light switch is pressed on the source node, the following process takes place:

Source
1. The application calls the light switch model's publish function
2. The model includes an on/off message in a publishing packet with an opcode and sends it to the access layer.
3. The access layer fetches the necessary publish parameters, like destination address, encryption keys and time to live value (TTL value), and passes the packet to the transport layer, the highest of the core layers.
4. The transport layer then encrypts the message with the selected application key, and splits the message into segments if necessary. Each segment is passed to the network layer, which attaches a network header with a sequence number and encrypts the packet with the network key before passing it to the bearer.
5. The bearer includes the network message in an advertisement packet, and schedules a time slot for the packet to be broadcasted.
Relays
1. The broadcast is received by all mesh nodes within range, and is passed from their bearer layers to their network layers.
2. The network packet is decrypted, and if the receiving node is not its destination, the packet's TTL value is decreased by one, before being re-encrypted with the same network key and passed back to the bearer to be relayed.
Destination
1. Once the packet is relayed to the destination light bulb node, its network layer will decrypt the packet and pass it to the transport layer.
2. Once all transport layer segments are received in this manner, the assembled message is decrypted with an application key, and passed on to the access layer.
3. The access layer checks the opcode, application key and destination address, and passes the message to all eligible models.
4. If one of these models is a light bulb model, the model parses the contents of the message, and notifies the application to turn on or off the light bulb.

The light bulb model may respond to acknowledge the transmission, following the same procedure back to the light switch node, which can notify the application that the on/off message was received.

Models

API: Mesh Models

The models define the behavior and communication formats of all data that is transmitted across the mesh. Equivalent to Bluetooth Low Energy's GATT services, the Mesh Models are independent, immutable implementations of specific behaviors or services. All mesh communication happens through models, and any application that exposes its behavior through the mesh must channel the communication through one or more models.

The Bluetooth Mesh Specification defines a set of immutable models for typical usage scenarios, but vendors are also free to implement their own models.

You can read more about models, including how to implement your own models, in Mesh models.

Access

API: Access

The access layer controls the device's model composition. It holds references to:

models that are present on the device,
messages these models accept,
configuration of these models.

As the device receives mesh messages, the access layer finds which models the messages are for and forwards them to the model implementations.

Device State Manager

API: Device State Manager

The Device State Manager stores the encryption keys and addresses used by the mesh stack. When models get assigned application keys and publish addresses through configuration server, the Device State Manager stores the raw values and provides handles to these values. The models can use the handles when referencing these values.

The Device State Manager stores its data in persistent storage, which it can recover on bootup.

Mesh Core

API: Core

Consisting of a network and a transport layer, the Mesh Core module provides the mesh-specific transport for the messages.

The transport layer provides in-network security by encrypting mesh packets with application keys and splitting them into smaller segments that can go on air. The transport layer re-assembles incoming packet segments and presents the full mesh message to the access layer.

The network layer encrypts each transport layer packet segment with a network key and populates the source and destination address fields. When receiving a mesh packet, the network layer decrypts the message, inspects the source and destination addresses, and decides whether the packet is intended for this device and whether the network layer should relay it.

The Mesh Core provides protection against malicious behavior and attacks against the mesh network through two-layer encryption, replay protection, and packet header obfuscation.

Provisioning

API: Provisioning

Provisioning is the act of adding a device to a mesh network. The Provisioning module takes care of both sides of this process, by implementing a provisioner role (the network owner) and a provisionee role (the device to add).

For detailed information about the provisioning process, see Implementing provisioning.

The mesh stack provides two ways to provision a device:

Provisioning directly through the PB-ADV/PB-GATT provisioning bearer, which can only happen between a provisioner and a provisionee that are within radio range of each other.
Provisioning through remote provisioning, which implements two mesh models that together create a tunnel through the mesh, allowing the provisioner to add devices from a distance, with the help of a PB-ADV proxy device.

Note: The remote provisioning is a Nordic proprietary feature that cannot be used with devices from other vendors.

The Remote Provisioning example demonstrates remote provisioning. The light switch example shows the provisioner and provisionee side of PB-ADV as a first step to establishing the network.

Bearer

API: Bearer

The Bearer is the low-level radio controller that provides an asynchronous interface to the radio packet sending and receiving for the upper layers. It enforces Bluetooth low energy compliance for packet formats and timing, and operates directly on radio hardware through the SoftDevice Timeslot API.

The Bearer is an internal module that normally does not need to be accessed by the application.

DFU

API: DFU

The Device Firmware Upgrade module provides firmware update capabilities over the mesh by cooperating with a bootloader. It is capable of concurrent, authenticated firmware transfers to all devices in a network, without halting the application.

Note

The mesh DFU is a Nordic proprietary feature that cannot be used with devices from other vendors.
DFU procedure is not compatible with the Bluetooth low energy secure DFU procedure used in the nRF5 SDK.

For more information about DFU, see the DFU protocol section, including information about how to run Mesh DFU.

Mesh Stack

API: Mesh stack

The Mesh Stack module is a thin wrapper around the top-level mesh modules that makes it easy to get started using the mesh. It takes care of mesh initialization and enabling. It also contains functions for storing and erasing provisioning and state related data.

Serial

API: Serial

The Serial module provides full serialization of the mesh API, allowing other devices to control the nRF5 mesh device through a UART interface. Intended for network gateways and similar complex applications, the serial interface provides a way to access the mesh through a Nordic device, without making it the unit's main controller.

The mesh serial interface is based on the nRF8001 ACI serial interface and optionally supports SLIP-encoded operation. The serial protocol can be run as a stand-alone application (see serial example) or alongside a normal mesh application.

For an overview of the serial packet format, commands, and events, as well as the related Interactive PyACI script, the Serial interface section.