The latest development version of this page may be more current than this released 2.3-beta.1 version.

Access Layer

The Access Layer is the application’s interface to the Bluetooth Mesh network. The Access Layer provides mechanisms fortg compartmentalizing the node behavior into elements and models, which are implemented by the application.

Mesh Models

The functionality of a mesh node is represented by models. A model implements a single behavior the node supports, like being a light, a sensor or a thermostat. The mesh models are grouped into elements. Each element is assigned its own unicast address, and may only contain one of each type of model. Conventionally, each element represents a single aspect of the mesh node behavior. For instance, a node that contains a sensor, two lights and a power outlet would spread this functionality across four elements, with each element instantiating all the models required for a single aspect of the supported behavior.

The node’s element and model structure is specified in the node composition data, which is passed to bt_mesh_init() during initialization. The Bluetooth SIG have defined a set of foundation models (see Mesh Models) and a set of models for implementing common behavior in the Bluetooth Mesh Model Specification. All models not specified by the Bluetooth SIG are vendor models, and must be tied to a company ID.

Mesh models have several parameters that can be configured either through initialization of the mesh stack or with the Configuration Server:

Opcode list

The opcode list contains all message opcodes the model can receive, as well as the minimum acceptable payload length and the callback to pass them to. Models can support any number of opcodes, but each opcode can only be listed by one model in each element.

The full opcode list must be passed to the model structure in the composition data, and cannot be changed at runtime. The end of the opcode list is determined by the special BT_MESH_MODEL_OP_END entry. This entry must always be present in the opcode list, unless the list is empty. In that case, BT_MESH_MODEL_NO_OPS should be used instead to correctly define the opcode list.

AppKey List

The AppKey list contains all the application keys on which the model can receive messages on. Only messages encrypted with application keys in the AppKey list will be passed to the model.

The maximum number of supported application keys each model can hold is configured with the CONFIG_BT_MESH_MODEL_KEY_COUNT configuration option. The contents of the AppKey list is managed by the Configuration Server.

Subscription List

A model will process all messages addressed to the unicast address of their element (given that the utilized application key is present in the AppKey list). Additionally, the model will process packets addressed to any group or virtual address in its subscription list. This allows a single message to address multiple nodes throughout the mesh network.

The maximum number of supported addresses in the subscription list each model can hold is configured with the CONFIG_BT_MESH_MODEL_GROUP_COUNT configuration option. The contents of the subscription list is managed by the Configuration Server.

Model Publication

The models may send messages in two ways:

By specifying a set of message parameters in a bt_mesh_msg_ctx, and calling bt_mesh_model_send().
By setting up a bt_mesh_model_pub structure and calling bt_mesh_model_publish().

When publishing messages with bt_mesh_model_publish(), the model will use the publication parameters configured by the Configuration Server. This is the recommended way to send unprompted model messages, as it passes the responsibility of selecting message parameters to the network administrator, who may have a better understanding of the mesh network than individual nodes.

To support publishing with the publication parameters, the model must allocate a packet buffer for publishing, and pass it to bt_mesh_model_pub.msg. The configuration server can also set up periodic publishing of messages. To support this, the model must populate the bt_mesh_model_pub.update callback. The bt_mesh_model_pub.update callback is invoked when a message is published, allowing the model to change the payload to reflect its current state.

By setting bt_mesh_model_pub.retr_update to 1, the model can configure the bt_mesh_model_pub.update callback to be triggered on every retransmission. This can, for example, be used by models that make use of a Delay parameter, which can be adjusted for every retransmission. The bt_mesh_model_pub_is_retransmission() function can be used to differentiate a first publication and a retransmission. The BT_MESH_PUB_MSG_TOTAL and BT_MESH_PUB_MSG_NUM macros can be used to return the total number of transmissions and the retransmission number within one publication interval.

Extended Models

The Bluetooth Mesh specification allows the mesh models to extend each other. When one model extends another, it inherits that model’s functionality, and extension can be used to construct complex models out of simple ones, leveraging the existing model functionality to avoid defining new opcodes. Models may extend any number of models from any element. When one model extends another in the same element, the two models will share subscription lists. The mesh stack implements this by merging the subscription lists of the two models into one, combining the number of subscriptions the models can have in total. Models may extend models that extend others, creating an “extension tree”. All models in the extension tree share a subscription list for each element they span.

Model extensions are done by calling bt_mesh_model_extend() during initialization. A model can only be extended by one other model,and extensions cannot be cyclic. Note that binding of node states and other relationships between the models must be defined by the model implementations.

The model extension concept adds some overhead in the Access Layer packet processing and must be explicitly enabled with CONFIG_BT_MESH_MODEL_EXTENSIONS to have any effect.

Model Data Storage

Mesh models may have data associated with each model instance that needs to be stored persistently. The Access API provides a mechanism for storing this data, leveraging the internal model instance encoding scheme. Models can store one user defined data entry per instance by calling bt_mesh_model_data_store(). To be able to read out the data the next time the device reboots, the model’s bt_mesh_model_cb.settings_set callback must be populated. This callback gets called when model specific data is found in the persistent storage. The model can retrieve the data by calling the read_cb passed as a parameter to the callback. See the settings_api() module documentation for details.

When model data changes frequently, storing it on every change may lead to increased wear of flash. To reduce the wear, the model can postpone storing of data by calling bt_mesh_model_data_store_schedule(). The stack will schedule a work item with delay defined by the CONFIG_BT_MESH_STORE_TIMEOUT option. When the work item is running, the stack will call the bt_mesh_model_cb.pending_store callback for every model that has requested storing of data. The model can then call bt_mesh_model_data_store() to store the data.

If CONFIG_BT_MESH_SETTINGS_WORKQ is enabled, the bt_mesh_model_cb.pending_store callback is called from a dedicated thread. This allows the stack to process other incoming and outgoing messages while model data is being stored. It is recommended to use this option and the bt_mesh_model_data_store_schedule() function when large amount of data needs to be stored.

Composition Data

The Composition Data provides information about a mesh device. A device’s Composition Data holds information about the elements on the device, the models that it supports, and other features. The Composition Data is split into different pages, where each page contains specific feature information about the device. In order to access this information, the user may use the Configuration Server model or, if supported, the Large Composition Data Server model.

Composition Data Page 0

Composition Data Page 0 provides the fundemental information about a device, and is mandatory for all mesh devices. It contains the element and model composition, the supported features, and manufacturer information.

Composition Data Page 1

Composition Data Page 1 provides information about the relationships between models, and is mandatory for all mesh devices. A model may extend and/or correspond to one or more models. A model can extend another model by calling bt_mesh_model_extend(), or correspond to another model by calling bt_mesh_model_correspond(). CONFIG_BT_MESH_MODEL_EXTENSION_LIST_SIZE specifies how many model relations can be stored in the composition on a device, and this number should reflect the number of bt_mesh_model_extend() and bt_mesh_model_correspond() calls.

Composition Data Page 2

Composition Data Page 2 provides information for supported mesh profiles. Mesh profile specifications define product requirements for devices that want to support a specific Bluetooth SIG defined profile. Currently supported profiles can be found in section 3.12 in Bluetooth SIG Assigned Numbers. Composition Data Page 2 is only mandatory for devices that claim support for one or more mesh profile(s).

Composition Data Pages 128, 129 and 130

Composition Data Pages 128, 129 and 130 mirror Composition Data Pages 0, 1 and 2 respectively. They are used to represent the new content of the mirrored pages when the Composition Data will change after a firmware update. See Composition Data and Models Metadata for details.

Delayable messages

The delayable message functionality is enabled with Kconfig option CONFIG_BT_MESH_ACCESS_DELAYABLE_MSG. This is an optional functionality that implements specification recommendations for messages that are transmitted by a model in a response to a received message( also called response messages).

Response messages should be sent with the following random delays:

Between 20 and 50 milliseconds if the received message was sent to a unicast address
Between 20 and 500 milliseconds if the received message was sent to a group or virtual address

The delayable message functionality is triggered if the bt_mesh_msg_ctx.rnd_delay flag is set. The feature message functionality stores messages in the local memory while they are waiting for the random delay expiration.

If the transport layer doesn’t have sufficient memory to send a message at the moment the random delay expires, the message is postponed for another 10 milliseconds. If the transport layer cannot send a message for any other reason, the delayable message functionality raises the bt_mesh_send_cb.start callback with a transport layer error code.

If the delayable message functionality cannot find enough free memory to store an incoming message, it will send messages with delay close to expiration to free memory.

Pending or resetting the mesh stack will delete messages that have not been sent and trigger the bt_mesh_send_cb.start callback with an error code.

Delayable Publications

The delayable publication feature implements the specification recommendations for message publication delays in the following cases:

Between 20 to 500 milliseconds when the Bluetooth Mesh stack starts or when the publication is triggered by the bt_mesh_model_publish() function
Between 20 to 50 milliseconds for periodically published messages

This feature is optional and enabled with the CONFIG_BT_MESH_DELAYABLE_PUBLICATION Kconfig option. When enabled, each model can enable or disable the delayable publication by setting the bt_mesh_model_pub.delayable bit field to 1 or 0 correspondingly. This bit field can be changed at any time.

API Reference

group bt_mesh_access

Access layer.

Group addresses

BT_MESH_ADDR_UNASSIGNED: unassigned

BT_MESH_ADDR_ALL_NODES: all-nodes

BT_MESH_ADDR_RELAYS: all-relays

BT_MESH_ADDR_FRIENDS: all-friends

BT_MESH_ADDR_PROXIES: all-proxies

BT_MESH_ADDR_DFW_NODES: all-directed-forwarding-nodes

BT_MESH_ADDR_IP_NODES: all-ipt-nodes

BT_MESH_ADDR_IP_BR_ROUTERS: all-ipt-border-routers

Predefined key indexes

BT_MESH_KEY_UNUSED: Key unused

BT_MESH_KEY_ANY: Any key index

BT_MESH_KEY_DEV: Device key

BT_MESH_KEY_DEV_LOCAL: Local device key

BT_MESH_KEY_DEV_REMOTE: Remote device key

BT_MESH_KEY_DEV_ANY: Any device key

Foundation Models

BT_MESH_MODEL_ID_CFG_SRV: Configuration Server

BT_MESH_MODEL_ID_CFG_CLI: Configuration Client

BT_MESH_MODEL_ID_HEALTH_SRV: Health Server

BT_MESH_MODEL_ID_HEALTH_CLI: Health Client

BT_MESH_MODEL_ID_REMOTE_PROV_SRV: Remote Provisioning Server

BT_MESH_MODEL_ID_REMOTE_PROV_CLI: Remote Provisioning Client

BT_MESH_MODEL_ID_PRIV_BEACON_SRV: Private Beacon Server

BT_MESH_MODEL_ID_PRIV_BEACON_CLI: Private Beacon Client

BT_MESH_MODEL_ID_SAR_CFG_SRV: SAR Configuration Server

BT_MESH_MODEL_ID_SAR_CFG_CLI: SAR Configuration Client

BT_MESH_MODEL_ID_OP_AGG_SRV: Opcodes Aggregator Server

BT_MESH_MODEL_ID_OP_AGG_CLI: Opcodes Aggregator Client

BT_MESH_MODEL_ID_LARGE_COMP_DATA_SRV: Large Composition Data Server

BT_MESH_MODEL_ID_LARGE_COMP_DATA_CLI: Large Composition Data Client

BT_MESH_MODEL_ID_SOL_PDU_RPL_SRV: Solicitation PDU RPL Configuration Client

BT_MESH_MODEL_ID_SOL_PDU_RPL_CLI: Solicitation PDU RPL Configuration Server

BT_MESH_MODEL_ID_ON_DEMAND_PROXY_SRV: Private Proxy Server

BT_MESH_MODEL_ID_ON_DEMAND_PROXY_CLI: Private Proxy Client

Models from the Mesh Model Specification

BT_MESH_MODEL_ID_GEN_ONOFF_SRV: Generic OnOff Server

BT_MESH_MODEL_ID_GEN_ONOFF_CLI: Generic OnOff Client

BT_MESH_MODEL_ID_GEN_LEVEL_SRV: Generic Level Server

BT_MESH_MODEL_ID_GEN_LEVEL_CLI: Generic Level Client

BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV: Generic Default Transition Time Server

BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI: Generic Default Transition Time Client

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV: Generic Power OnOff Server

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV: Generic Power OnOff Setup Server

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI: Generic Power OnOff Client

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV: Generic Power Level Server

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV: Generic Power Level Setup Server

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI: Generic Power Level Client

BT_MESH_MODEL_ID_GEN_BATTERY_SRV: Generic Battery Server

BT_MESH_MODEL_ID_GEN_BATTERY_CLI: Generic Battery Client

BT_MESH_MODEL_ID_GEN_LOCATION_SRV: Generic Location Server

BT_MESH_MODEL_ID_GEN_LOCATION_SETUPSRV: Generic Location Setup Server

BT_MESH_MODEL_ID_GEN_LOCATION_CLI: Generic Location Client

BT_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV: Generic Admin Property Server

BT_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV: Generic Manufacturer Property Server

BT_MESH_MODEL_ID_GEN_USER_PROP_SRV: Generic User Property Server

BT_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV: Generic Client Property Server

BT_MESH_MODEL_ID_GEN_PROP_CLI: Generic Property Client

BT_MESH_MODEL_ID_SENSOR_SRV: Sensor Server

BT_MESH_MODEL_ID_SENSOR_SETUP_SRV: Sensor Setup Server

BT_MESH_MODEL_ID_SENSOR_CLI: Sensor Client

BT_MESH_MODEL_ID_TIME_SRV: Time Server

BT_MESH_MODEL_ID_TIME_SETUP_SRV: Time Setup Server

BT_MESH_MODEL_ID_TIME_CLI: Time Client

BT_MESH_MODEL_ID_SCENE_SRV: Scene Server

BT_MESH_MODEL_ID_SCENE_SETUP_SRV: Scene Setup Server

BT_MESH_MODEL_ID_SCENE_CLI: Scene Client

BT_MESH_MODEL_ID_SCHEDULER_SRV: Scheduler Server

BT_MESH_MODEL_ID_SCHEDULER_SETUP_SRV: Scheduler Setup Server

BT_MESH_MODEL_ID_SCHEDULER_CLI: Scheduler Client

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV: Light Lightness Server

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV: Light Lightness Setup Server

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI: Light Lightness Client

BT_MESH_MODEL_ID_LIGHT_CTL_SRV: Light CTL Server

BT_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV: Light CTL Setup Server

BT_MESH_MODEL_ID_LIGHT_CTL_CLI: Light CTL Client

BT_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV: Light CTL Temperature Server

BT_MESH_MODEL_ID_LIGHT_HSL_SRV: Light HSL Server

BT_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV: Light HSL Setup Server

BT_MESH_MODEL_ID_LIGHT_HSL_CLI: Light HSL Client

BT_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV: Light HSL Hue Server

BT_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV: Light HSL Saturation Server

BT_MESH_MODEL_ID_LIGHT_XYL_SRV: Light xyL Server

BT_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV: Light xyL Setup Server

BT_MESH_MODEL_ID_LIGHT_XYL_CLI: Light xyL Client

BT_MESH_MODEL_ID_LIGHT_LC_SRV: Light LC Server

BT_MESH_MODEL_ID_LIGHT_LC_SETUPSRV: Light LC Setup Server

BT_MESH_MODEL_ID_LIGHT_LC_CLI: Light LC Client

Models from the Mesh Binary Large Object Transfer Model Specification

BT_MESH_MODEL_ID_BLOB_SRV: BLOB Transfer Server

BT_MESH_MODEL_ID_BLOB_CLI: BLOB Transfer Client

Models from the Mesh Device Firmware Update Model Specification

BT_MESH_MODEL_ID_DFU_SRV: Firmware Update Server

BT_MESH_MODEL_ID_DFU_CLI: Firmware Update Client

BT_MESH_MODEL_ID_DFD_SRV: Firmware Distribution Server

BT_MESH_MODEL_ID_DFD_CLI: Firmware Distribution Client

Defines

BT_MESH_ADDR_IS_UNICAST(addr): Check if a Bluetooth Mesh address is a unicast address.

BT_MESH_ADDR_IS_GROUP(addr): Check if a Bluetooth Mesh address is a group address.

BT_MESH_ADDR_IS_FIXED_GROUP(addr): Check if a Bluetooth Mesh address is a fixed group address.

BT_MESH_ADDR_IS_VIRTUAL(addr): Check if a Bluetooth Mesh address is a virtual address.

BT_MESH_ADDR_IS_RFU(addr): Check if a Bluetooth Mesh address is an RFU address.

BT_MESH_IS_DEV_KEY(key): Check if a Bluetooth Mesh key is a device key.

BT_MESH_APP_SEG_SDU_MAX: Maximum size of an access message segment (in octets).

BT_MESH_APP_UNSEG_SDU_MAX: Maximum payload size of an unsegmented access message (in octets).

BT_MESH_RX_SEG_MAX: Maximum number of segments supported for incoming messages.

BT_MESH_TX_SEG_MAX: Maximum number of segments supported for outgoing messages.

BT_MESH_TX_SDU_MAX: Maximum possible payload size of an outgoing access message (in octets).

BT_MESH_RX_SDU_MAX: Maximum possible payload size of an incoming access message (in octets).

BT_MESH_ELEM(_loc, _mods, _vnd_mods)

Helper to define a mesh element within an array.

In case the element has no SIG or Vendor models the helper macro BT_MESH_MODEL_NONE can be given instead.

Parameters:

_loc – Location Descriptor.
_mods – Array of models.
_vnd_mods – Array of vendor models.

BT_MESH_MODEL_OP_1(b0)

BT_MESH_MODEL_OP_2(b0, b1)

BT_MESH_MODEL_OP_3(b0, cid)

BT_MESH_LEN_EXACT(len): Macro for encoding exact message length for fixed-length messages.

BT_MESH_LEN_MIN(len): Macro for encoding minimum message length for variable-length messages.

BT_MESH_MODEL_OP_END: End of the opcode list. Must always be present.

BT_MESH_MODEL_NO_OPS

Helper to define an empty opcode list.