Bluetooth Mesh models overview
A Bluetooth® Mesh model is a standardized component that defines a series of states and related behaviors. Models encapsulate a single feature of a mesh node, and expose this feature to the mesh network. Each mesh-based product implements several models.
States, either simple or complex, are used to indicate the condition of a device, for example whether it is on or off. Some states are bound to other, which causes them to mutually update their values.
Categorization
Each model is classified into one of the following categories:
Server – which contains states.
Client – which reads and writes the Server’s states.
Moreover, some models also include a Setup Server model instance. The two server model instances share the states of the server model, but accept different messages. This allows for a fine-grained control of the access rights for the states, as the two model instances can be bound to different application keys. Typically, the Setup Server instance provides write access to configuration parameters, such as valid parameter ranges or default values.
Both server and client models can be extended, but because client models do not have states, there is generally no reason to extend them. None of the specification client models extend other models. All server models store changes to their configuration persistently using the Settings subsystem.
Configuration
You can configure mesh models in nRF Connect SDK using Kconfig options. See Configuring and building an application for more information.
The options related to each model configuration are listed in the respective documentation pages.
Transition
States may support non-instantaneous changes.
Such states make use of bt_mesh_model_transition to specify the time it should take a server to change a state to a new value.
The transition to a new value can be postponed by the time defined in bt_mesh_model_transition.delay, and the current value of a state remains unchanged until the transition starts.
The delay should not be taken into account when calculating the remaining transition time.
Server models are taking care of publishing of status messages, when receiving a state changing message, as well as sending a response back to a client, when an acknowledged message is received.
If a state change is non-instantaneous, for example when bt_mesh_model_transition_time() returns a nonzero value, the application is responsible for publishing a new value of the state at the end of the transition.
Common types for all models
All models in the Bluetooth Mesh model specification share some common types, which are collected in a single header file. These include transitions, common IDs and other types that are rarely actively used.
Each model can also contain its own common types, listed in the respective documentation pages. For the types common to all models, see the following section.
The following types are common for all models:
API documentation
include/bluetooth/mesh/model_types.h- group bt_mesh_model_types
Collection of types exposed in the model definitions.
Defines
-
BT_MESH_MODEL_TRANSITION_TIME_MAX_MS
Maximum permissible transition time in milliseconds
-
BT_MESH_MODEL_DELAY_TIME_STEP_FACTOR_MS
Delay field step factor in milliseconds
-
BT_MESH_MODEL_DELAY_TIME_MAX_MS
Maximum permissible delay time in milliseconds
-
BT_MESH_MODEL_USER_DATA(_type, _user_data)
Utility macro for type checking of model user data.
Produces a “Comparison of distinct pointer types” warning if
_user_datais of the wrong type.This macro abuses the C language a bit, but when used in the
BT_MESH_MODEL_macros, it generates a compiler warning for a bug that is otherwise very hard to detect, and relatively easy to make:As the bt_mesh_model::user_data is a void pointer, it does not have any type checking. The mesh model implementations wrap this macro, often taking a pointer parameter to a context structure, passing it to the model user data. As the
BT_MESH_MODEL_macros are used in listing of models, users are likely to copy and paste them, but only change the suffix. If they do this, but fail to change the context pointer, the resulting misbehavior will be confusing, dangerous and potentially hard to detect.- Parameters:
_type – [in] Expected type of the user data.
_user_data – [in] User data pointer.
Enums
-
enum bt_mesh_model_status
Model status values.
Values:
-
enumerator BT_MESH_MODEL_SUCCESS
Command successfully processed.
-
enumerator BT_MESH_MODEL_ERROR_INVALID_RANGE_MIN
The provided value for range min cannot be set.
-
enumerator BT_MESH_MODEL_ERROR_INVALID_RANGE_MAX
The provided value for range max cannot be set.
-
enumerator BT_MESH_MODEL_STATUS_INVALID
Invalid status code.
-
enumerator BT_MESH_MODEL_SUCCESS
Functions
-
static inline int32_t bt_mesh_model_transition_time(const struct bt_mesh_model_transition *trans)
Get the total transition time.
- Parameters:
trans – [in] Transition time, or NULL.
- Returns:
Total time of the given transition, in milliseconds, or 0 if
transis NULL.
-
struct bt_mesh_model_transition
- #include <model_types.h>
Generic Transition parameters for the model messages.
Note
Time cannot be larger than BT_MESH_MODEL_TRANSITION_TIME_MAX_MS and delay cannot be larger than BT_MESH_MODEL_DELAY_TIME_MAX_MS.
-
struct bt_mesh_tid_ctx
- #include <model_types.h>
Transaction ID context, storing information about the previous transaction in model spec messages.
-
BT_MESH_MODEL_TRANSITION_TIME_MAX_MS