Bluetooth mesh models

In the Bluetooth mesh solution, models are used to define the functionality of nodes. Each model represents a set of states and behaviors and defines messages that are used to interact with the model states.

One example of a model is the Configuration Model, which is a mandatory model in all Bluetooth mesh devices. This model represents the configuration of a node (in the form of various states) and provides messages to set or retrieve configuration parameters (behavior).

In addition to the foundation models defined in the Bluetooth mesh model specification, the nRF5 SDK for Mesh provides unique models for performing functionalities on the nodes in a Bluetooth mesh network.

You can also create your own models. For details, see Creating new models.

Check the official Bluetooth mesh glossary for definitions of the most important mesh-related terms used in this documentation.

Table of contents

• Models in the nRF5 SDK for Mesh
  • Pointers as arguments to model callbacks
  • Segmentation forcing
  • Large MIC size

---

Models in the nRF5 SDK for Mesh

See the following list for the complete overview of models implemented in the nRF5 SDK for Mesh.

Note

Links under names indicate models with documentation pages.

• Generic models
  • Default Transition Time model
    • Source files: <InstallFolder>/models/model_spec/generic_dtt
    • API reference
  • OnOff model
    • Source files: <InstallFolder>/models/model_spec/generic_onoff
    • API reference
  • Level model
    • Source files: <InstallFolder>/models/model_spec/generic_level
    • API reference
  • Power OnOff model
    • Source files: <InstallFolder>/models/model_spec/generic_ponoff
    • API reference
• Foundation models
  • Health model
    • Source files: <InstallFolder>/models/foundation/health
    • API reference
  • Configuration model
    • Source files: <InstallFolder>/models/foundation/config
    • API reference
• Scenes models
  • Scenes model
    • Source files: <InstallFolder>/models/model_spec/scene
    • API reference
• Sensor models
  • Sensor model
    • Source files: <InstallFolder>/models/model_spec/sensor
    • API reference
• Light models
  • Light Lightness models
    • Source files: <InstallFolder>/models/model_spec/light_lightness
    • API reference
  • Light CTL models
    • Source files: <InstallFolder>/models/model_spec/light_ctl
    • API reference
  • Light LC models
    • Source files: <InstallFolder>/models/model_spec/light_lc
    • API reference
• Proprietary models
  • PB-remote model
    • Source files: <InstallFolder>/models/proprietary/pb_remote
    • API reference
• Vendor models
  • Simple OnOff model
    • Source files: <InstallFolder>/models/vendor/simple_on_off
    • API reference
  • RSSI monitor models (RSSI model and RSSI util model)
    • Source files: <InstallFolder>/models/vendor/rssi_monitor
    • API reference

For the complete overview of available Bluetooth mesh model APIs, see Mesh Models in the API Reference section.

Pointers as arguments to model callbacks

Models in the nRF5 SDK for Mesh communicate with the application through a number of callback functions implemented by the application. Many of these, especially get callbacks, supply a data pointer as one of the arguments from the model.

These pointers are to be regarded as local (stack) variables, and will go out of scope once the callback chain returns. For this reason, do not be store or dereference these pointers outside the scope of the callback implementation. If the data is needed outside this scope, make sure that the application copies the data.

Segmentation forcing

The model implementation in the nRF5 SDK for Mesh provides the ability to apply segmentation behavior for model messages even if these messages are fit in a single transport layer payload. Use the force_segmented boolean for this purpose.

However, this approach has its advantages and disadvantages. On the one hand, forcing segmentation improves the reliability of communication. The Bluetooth mesh stack will apply the Segment Acknowledgement message to confirm every model message.

On the other hand, this approach will cause poor latency, because the confirmation stage requires time. Moreover, a model might get the NRF_ERROR_NO_MEM status back from the stack for the next transaction. This can happen if a model sends more messages that require SAR, but the application does not take into account notifications about the completion of the previous SAR messages.

Large MIC size

The model implementation in the nRF5 SDK for Mesh provides the ability to use the 8-byte Message Integrity Check (MIC) for messages. Use transmic_size for this purpose.

When using this MIC, it is important to check that the model data still fits in the transport payload. If a model message cannot be fit in a single transport payload, the segmentation mechanism will be applied automatically.