Common model types

All models in the Bluetooth® Mesh model specification share some common data types, which are collected in a single header file. These include transitions, common IDs and other types that are rarely actively used.

Each Bluetooth Mesh model can also contain its own common types, listed in the respective documentation pages.

The following section defines types that are common for all models.

API documentation

Header file: 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_data is 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.

enum bt_mesh_rgb_ch

RGB color channels

Values:

enumerator BT_MESH_RGB_CH_RED

enumerator BT_MESH_RGB_CH_GREEN

enumerator BT_MESH_RGB_CH_BLUE

enumerator BT_MESH_RGB_CHANNELS

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 trans is 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.

Public Members

uint32_t time

Transition time value in milliseconds

uint32_t delay

Message execution delay in milliseconds

struct bt_mesh_tid_ctx

#include <model_types.h>

Transaction ID context, storing information about the previous transaction in model spec messages.

Public Members

uint16_t src

Source address.

uint16_t dst

Destination address.

uint64_t timestamp

System uptime of the transaction.

uint8_t tid

Transaction ID.