Defining Bluetooth Mesh Models

Interoperability is a benefit of standardization across every layer of the entire communications stack — from the physical layer, dealing with the analogue world of radio at the bottom, to user-level behaviors that products may exhibit at the top. The Bluetooth® Mesh specifications define those product behaviors in terms of granular, standard building blocks called models. Bluetooth Mesh models are the building blocks for interoperable Bluetooth Mesh products and the means by which diverse requirements can be met in smart buildings and smart venues around the world.

The following excerpt from this paper, Bluetooth Mesh Models – A Technical Overview, defines Bluetooth Mesh models and helps you understand their behaviors and functions. 

What is a Bluetooth Mesh Model?

As noted in the Bluetooth^® Mesh glossary of terms, a model,

The glossary and the Bluetooth Mesh Technology Overview are recommended reading if any of these terms are new to you.

Essentially, models are specifications for standard software components that, when included in a product, determine what it can do as a mesh device. Models are self-contained components and products will incorporate several of them. Collectively, from a network’s point of view, models make the device what it is.

State

Models contain states. States are data items that indicate the condition of the device, such as on/off or high/low. States may be simple, containing only a single value, or composite, containing multiple fields, similar to a struct in programming languages like C.

In some cases, there are relationships defined between state items. These relationships are called state bindings. A state binding indicates that if one of the states in the relationship changes, then the other one needs to have its value recalculated. Sometimes state bindings are conditional and may be enabled or disabled by some other state. Developers must implement the required logic for any state bindings that are defined for the models they are using and ensure that logic is executed whenever required.

Conversely, where state bindings are not explicitly defined in the Bluetooth^® Mesh Model Specification, states must act independently. For example, if the generic on/off state indicates that a device is currently off, increasing the generic level state should have no user-discernible effect. Switching the device on by setting the generic on/off state to 1 should not only switch the device on, but it should begin functioning at the level that has been set. This can be readily understood if you consider a rotary dimmer switch that is rotated to change the level of the lights in the room but can also be pressed to switch them on or off. You can rotate the control when the lights are off and nothing will appear to happen, but if you then press the switch, with it in the same rotated position, the lights will come on at the selected level of brightness.

Categories of Model

Models are classified as being either clients, which do not contain state, or servers, which do. State is the term used for a data item which represents the condition that some aspect of a device is in, such as whether it is on or off or what level it is turned up to.

Some server models are associated with another server model with a name that is similar but includes “SetUp” in it. For example, the Sensor Server model has an associated Sensor Setup Server model. SetUp server models are technically no different to other server models in that they contain a state and produce and consume particular types of messages. Their purpose is to allow the separation of a model’s configuration settings from the main model state items so that distinct access control policies can be applied. It is common to allow a network administrator to configure a model’s associated settings via its SetUp Server model but not allow standard users to do this.

Model Communication and Behaviors

Models talk to each other by sending and receiving messages. There are numerous types of message, and these are defined as part of the specification for each model so that it is clear what types of message a model can produce and what types of message it can receive and understand.

Messages either communicate a state value to other devices or they change a state value, eliciting a response, often visible, from a device.

Models defined by the Bluetooth Special Interest Group (SIG) in the Bluetooth Mesh Model Specification are known as Bluetooth SIG models. Vendors may define their own models too, and these are known as vendor models. Vendor models should be used with caution and only when there is no possible way to use Bluetooth SIG models to meet the requirements.

Models can have specified dependencies on other models. A model may extend another model, a process whereby the first model adds states to the second model. A model may also require that a model which extends it be present. Models that do not extend other models are known as root models.

Software Developers and Bluetooth Mesh Models

Object Orientation

Software developers should find it easy to imagine model specifications as being akin to classes in the object-oriented (OO) software engineering paradigm and model implementations in code inside a device as an instance of the model or object.

The Bluetooth^® Mesh specifications do not stipulate any particular approach to implementing models in code; that’s left to the developer and the programming language and APIs in use. But models do lend themselves to an object-oriented approach, and the specification even talks about one model extending another, a concept that is also reminiscent of OO.

SDK Variations

There are a number of SDKs (software developer kit) for developing mesh firmware. Some are from Bluetooth^® module vendors that are specific to creating code for their modules. Others, such as the Zephyr RTOS SDK, are hardware agnostic and allow for the creation of firmware for numerous different target boards. At this time, Zephyr supports 100 different target boards.

Whatever SDK you use, the principals involved in implementing mesh firmware will be the same. In this post, code created with the Zephyr SDK will be presented as a way of illustrating points from a developer’s point of view.

// models – an array of specific model definitions

static struct bt_mesh_model sig_models[] = {

BT_MESH_MODEL_CFG_SRV&(cfg_srv),

BT_MESH_MODEL_CFG_CLI(&cfg_cli),

BT_MESH_MODEL_HEALTH_SRV(&health_srv, &health_pub),

BT_MESH_MODEL(BT_MESH_MODEL_ID_GEN_ONOFF_SRV, generic_ onoff_op,

&generic_onoff_pub, NULL),

BT_MESH_MODEL(BT_MESH_MODEL_ID_GEN_LEVEL_SRV, generic_level_op,

&generic_level_pub, NULL)};

// elements – contains arrays of SIG models and vendor models (none in this case)

static struct bt_mesh_elem elements[] = {

BT_MESH_ELEM(0, sig_models, BT_MESH_MODEL_NONE),

};

// node composition – contains an array of elements

static const struct bt_mesh_comp comp = {

.elem = elements,

.elem_count = ARRAY_SIZE(elements),

};

Node Composition

One of the first key tasks a mesh firmware developer must undertake is to define their product’s mesh node composition. This means defining in code how many elements the node has and what models each of the elements contains. The node diagram above shows the relationships between the node, its elements, the models contained within elements, and the items of state that each model contains.

Details will vary across SDKs, but using the Zephyr SDK node composition involves creating a series of arrays, each of which contains structs defined by macros that the SDK provides. It might look something like the example above that shows four models belonging to an element, which is the sole element of the node.

Properties

There are two forms that data items can take in a Bluetooth^® Mesh model.

State values are members of particular models and have a value with a meaning that the specification defines. They are not self-describing, and the state a message relates to is inferred from the opcode of the message.

Properties, on the other hand, are instances of characteristics to be interpreted in a given context.

Characteristics are also used with GATT. A characteristic defines the fields its value consists of, such as permissible values and their meaning and, in the case of GATT, includes an explicit type identifier in the form of a UUID (universally unique identifier). When used in GATT, characteristics are members of services, and the service that owns a characteristic provides a context within which to interpret and work with the characteristic. For example, the Alert Level characteristic can be a member of either the Link Loss service or the Immediate Alert service. The meaning of the characteristic varies depending on which service it is a member of, and this is defined in the GATT service specification.

Bluetooth Mesh does not use GATT services. Instead, properties provide context for interpreting a related characteristic,

Properties are explicitly identified by a Property ID. In a model where a property is in use, the property ID and property value comprise the value of a state. For example, the sensor data state contains one or more pairs of property ID and a corresponding sensor value.

Properties allow the same model to be used with a wide range of data types, which, in the case of models like the sensor server model, is hugely advantageous since any type of sensor data can be handled and interpreted with respect to any context, provided a suitable property has been defined. Without this approach to describing and encapsulating data, many different types of sensor models would be required, or the sensor server model would need to have a large number of states for each of the different types of sensor data it might need to support.

Client and Server Decoupling

When implementing models, it is important to respect the fact that client models and server models must know nothing about each other’s implementation details. For example, a server should not need to know or choose to exploit knowledge of the specific values that a client might be able to send. Each is a black box to the other.

Coding Models

Apart from specifying which models belong to each element in node composition, what else do developers need to do to incorporate the models that have been selected for their product? In some cases, nothing at all. Some models like the health server model are mandatory (in the primary element of a node, which all nodes have), and the SDK may provide a complete implementation, which is easily incorporated in the node’s composition.

In most other cases, a number of other steps will be necessary:

#define BT_MESH_MODEL_OP_GENERIC_ONOFF_GET BT_MESH_MODEL_OP_2(0x82, 0x01)

#define BT_MESH_MODEL_OP_GENERIC_ONOFF_SET BT_MESH_MODEL_OP_2(0x82, 0x02)

#define BT_MESH_MODEL_OP_GENERIC_ONOFF_SET_UNACK BT_MESH_MODEL_OP_ 2(0x82, 0x03)

#define BT_MESH_MODEL_OP_GENERIC_ONOFF_STATUS BT_MESH_MODEL_OP_ 2(0x82, 0x04)

// each array member contains opcode, min msg len, handler function

static const struct bt_mesh_model_op generic_onoff_op[] = {

{BT_MESH_MODEL_OP_GENERIC_ONOFF_GET, 0, generic_onoff_get},

{BT_MESH_MODEL_OP_GENERIC_ONOFF_SET, 2, generic_onoff_set},

{BT_MESH_MODEL_OP_GENERIC_ONOFF_SET_UNACK, 2,

generic_onoff_set_unack},

BT_MESH_MODEL_OP_END,

};

1. RX Message Handler Functions

The opcodes of messages associated with each model and which the node might receive (RX) must be registered and, one or more functions for handling those message types, implemented. Here’s what that looks like in Zephyr code above.

Messages received by a model either change a state value (set) or request that the current value of a particular state be reported in a status message (get). Set messages come in two forms: those that do not require a response (unacknowledged) and those that require the new state value to be sent back in a status message. The term set is sometimes used to mean either of these two variations.

When handling state changes produced by set messages, developers must ensure that any defined and active state bindings are processed, recalculating other dependent state values as required.

2. TX Message Producer Functions

Models almost certainly need to transmit (TX) messages as well as receive them. Functions that formulate mesh messages and use the appropriate API to send messages need to be written and their execution triggered by suitable events or device interactions, such as the user pressing buttons or turning knobs. Developers will be largely concerned with the access layer part of messages rather than those fields that are related to lower layers of the stack, though there can be exceptions. It may be necessary to explicitly increment the SEQ field to avoid having devices reject messages as forming part of a suspected replay attack, or the software framework may do this automatically.

3. Bind Application Keys to Models

All mesh messages are encrypted and authenticated using AES-CCM. Header fields are also obfuscated to make network-pattern-analysis attacks difficult. Fields from upper layers of the stack are encrypted using an application key, and fields from lower in the stack are encrypted using a network key. This separates network and application security and allows nodes to perform network functions, such as the relaying of messages without needing or having the ability to decrypt the application payload of the message.

A good mesh software framework automatically secures messages through encryption and obfuscation, using the network and application keys established when the device was provisioned. But a node may have several application keys, and each must be associated with specific models through a process known as key binding. This ensures that the stack knows which application key to use with which types of message. Developers will almost certainly need to perform explicit application key binding in their code. On Zephyr, application key binding looks like this:

/* Bind to generic level server model */

err = bt_mesh_cfg_mod_app_bind(net_idx,

addr,

addr,

app_idx,

BT_MESH_MODEL_ID_GEN_LEVEL_SRV,

NULL);

net_idx and app_idx are index values that reference specific keys from the list of one or more network and application keys that a node might have been equipped with when initially provisioned and configured.

Application key binding is the basis for access control in a Bluetooth^® Mesh network. Issuing the network administrator with the application key bound to the sensor setup server model gives that user the ability to update that model’s state and configure the associated sensor server model. Other users, not in possession of this application key, cannot configure the sensor setup server.

Bluetooth Mesh Models for the Smarthome

Since January 2019, the Bluetooth Smart Home Subgroup has been working to create new Bluetooth Mesh models that will take Bluetooth Mesh into everyday smart home applications. And while these models are being developed with the smart home in mind, they will seamlessly translate to commercial and industrial smart building environments.  

The video below shows you how the Bluetooth^® Smart Home Subgroup is making intelligent and integrated smart home experiences a reality.

The Full Bluetooth Mesh Models Tour

The full paper gives you a guided tour of Bluetooth Mesh models. It outlines how the generics support the use of fundamental capabilities that many device types possess, how commercial lighting requirements are met by the lighting models, and how sensors can be used to inform other devices of environmental data that could result in automated responses.

Download Bluetooth Mesh Models – A Technical Overview, and get a comprehensive overview of Bluetooth^® Mesh models — from foundation, generic, and lighting models to sensor, scene, and time models.