Access¶

The Bluetooth Mesh access layer is the application’s interface to the mesh network. The access layer provides mechanisms for 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 Foundation 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 in place of a proper opcode list definition.

AppKey list¶

The AppKey list contains all the application keys 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 nodes to address multiple nodes throughout the mesh network with a single message.

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, which likely knows more about the mesh network than the individual nodes will.

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 Config Server may also set up period publication for the publication message. To support this, the model must populate the bt_mesh_model_pub.update callback. The bt_mesh_model_pub.update callback will be called right before the message is published, allowing the model to change the payload to reflect its current state.

Extended models¶

The Bluetooth Mesh specification allows the Mesh models to extend each other. When a 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 an extension tree share a single subscription list per element it spans.

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 circular. 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 module documentation for details.

API reference¶

group bt_mesh_access

Bluetooth Mesh Access Layer.

Defines

BT_MESH_ADDR_UNASSIGNED¶

BT_MESH_ADDR_ALL_NODES¶

BT_MESH_ADDR_PROXIES¶

BT_MESH_ADDR_FRIENDS¶

BT_MESH_ADDR_RELAYS¶

BT_MESH_KEY_UNUSED¶

BT_MESH_KEY_ANY¶

BT_MESH_KEY_DEV¶

BT_MESH_KEY_DEV_LOCAL¶

BT_MESH_KEY_DEV_REMOTE¶

BT_MESH_KEY_DEV_ANY¶

BT_MESH_ADDR_IS_UNICAST(addr)¶

BT_MESH_ADDR_IS_GROUP(addr)¶

BT_MESH_ADDR_IS_VIRTUAL(addr)¶

BT_MESH_ADDR_IS_RFU(addr)¶

BT_MESH_IS_DEV_KEY(key)¶

BT_MESH_APP_SEG_SDU_MAX¶: Maximum payload size of an access message (in octets).

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_ID_CFG_SRV¶

BT_MESH_MODEL_ID_CFG_CLI¶

BT_MESH_MODEL_ID_HEALTH_SRV¶

BT_MESH_MODEL_ID_HEALTH_CLI¶

BT_MESH_MODEL_ID_GEN_ONOFF_SRV¶

BT_MESH_MODEL_ID_GEN_ONOFF_CLI¶

BT_MESH_MODEL_ID_GEN_LEVEL_SRV¶

BT_MESH_MODEL_ID_GEN_LEVEL_CLI¶

BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV¶

BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI¶

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV¶

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV¶

BT_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI¶

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV¶

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV¶

BT_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI¶

BT_MESH_MODEL_ID_GEN_BATTERY_SRV¶

BT_MESH_MODEL_ID_GEN_BATTERY_CLI¶

BT_MESH_MODEL_ID_GEN_LOCATION_SRV¶

BT_MESH_MODEL_ID_GEN_LOCATION_SETUPSRV¶

BT_MESH_MODEL_ID_GEN_LOCATION_CLI¶

BT_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV¶

BT_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV¶

BT_MESH_MODEL_ID_GEN_USER_PROP_SRV¶

BT_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV¶

BT_MESH_MODEL_ID_GEN_PROP_CLI¶

BT_MESH_MODEL_ID_SENSOR_SRV¶

BT_MESH_MODEL_ID_SENSOR_SETUP_SRV¶

BT_MESH_MODEL_ID_SENSOR_CLI¶

BT_MESH_MODEL_ID_TIME_SRV¶

BT_MESH_MODEL_ID_TIME_SETUP_SRV¶

BT_MESH_MODEL_ID_TIME_CLI¶

BT_MESH_MODEL_ID_SCENE_SRV¶

BT_MESH_MODEL_ID_SCENE_SETUP_SRV¶

BT_MESH_MODEL_ID_SCENE_CLI¶

BT_MESH_MODEL_ID_SCHEDULER_SRV¶

BT_MESH_MODEL_ID_SCHEDULER_SETUP_SRV¶

BT_MESH_MODEL_ID_SCHEDULER_CLI¶

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV¶

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV¶

BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI¶

BT_MESH_MODEL_ID_LIGHT_CTL_SRV¶

BT_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV¶

BT_MESH_MODEL_ID_LIGHT_CTL_CLI¶

BT_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV¶

BT_MESH_MODEL_ID_LIGHT_HSL_SRV¶

BT_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV¶

BT_MESH_MODEL_ID_LIGHT_HSL_CLI¶

BT_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV¶

BT_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV¶

BT_MESH_MODEL_ID_LIGHT_XYL_SRV¶

BT_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV¶

BT_MESH_MODEL_ID_LIGHT_XYL_CLI¶

BT_MESH_MODEL_ID_LIGHT_LC_SRV¶

BT_MESH_MODEL_ID_LIGHT_LC_SETUPSRV¶

BT_MESH_MODEL_ID_LIGHT_LC_CLI¶

BT_MESH_MODEL_OP_1(b0)¶

BT_MESH_MODEL_OP_2(b0, b1)¶

BT_MESH_MODEL_OP_3(b0, cid)¶

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.

BT_MESH_MODEL_NONE¶: Helper to define an empty model array

BT_MESH_MIC_SHORT¶: Length of a short Mesh MIC.

BT_MESH_MIC_LONG¶: Length of a long Mesh MIC.

BT_MESH_MODEL_OP_LEN(_op)¶

Helper to determine the length of an opcode.

Parameters

_op: Opcode.

BT_MESH_MODEL_BUF_LEN(_op, _payload_len)¶

Helper for model message buffer length.

Returns the length of a Mesh model message buffer, including the opcode length and a short MIC.

Parameters

_op: Opcode of the message.
_payload_len: Length of the model payload.

BT_MESH_MODEL_BUF_LEN_LONG_MIC(_op, _payload_len)¶

Helper for model message buffer length.

Returns the length of a Mesh model message buffer, including the opcode length and a long MIC.

Parameters

_op: Opcode of the message.
_payload_len: Length of the model payload.

BT_MESH_MODEL_BUF_DEFINE(_buf, _op, _payload_len)¶

Define a Mesh model message buffer using NET_BUF_SIMPLE_DEFINE.

Parameters

_buf: Buffer name.
_op: Opcode of the message.
_payload_len: Length of the model message payload.

BT_MESH_MODEL_CB(_id, _op, _pub, _user_data, _cb)¶

Composition data SIG model entry with callback functions.

Parameters

_id: Model ID.
_op: Array of model opcode handlers.
_pub: Model publish parameters.
_user_data: User data for the model.
_cb: Callback structure, or NULL to keep no callbacks.

BT_MESH_MODEL_VND_CB(_company, _id, _op, _pub, _user_data, _cb)¶

Composition data vendor model entry with callback functions.

Parameters

_company: Company ID.
_id: Model ID.
_op: Array of model opcode handlers.
_pub: Model publish parameters.
_user_data: User data for the model.
_cb: Callback structure, or NULL to keep no callbacks.

BT_MESH_MODEL(_id, _op, _pub, _user_data)¶

Composition data SIG model entry.

Parameters

_id: Model ID.
_op: Array of model opcode handlers.
_pub: Model publish parameters.
_user_data: User data for the model.

BT_MESH_MODEL_VND(_company, _id, _op, _pub, _user_data)¶

Composition data vendor model entry.

Parameters

_company: Company ID.
_id: Model ID.
_op: Array of model opcode handlers.
_pub: Model publish parameters.
_user_data: User data for the model.

BT_MESH_TRANSMIT(count, int_ms)¶

Encode transmission count & interval steps.

Return

Mesh transmit value that can be used e.g. for the default values of the configuration model data.

Parameters

count: Number of retransmissions (first transmission is excluded).
int_ms: Interval steps in milliseconds. Must be greater than 0, less than or equal to 320, and a multiple of 10.

BT_MESH_TRANSMIT_COUNT(transmit)¶

Decode transmit count from a transmit value.

Return

Transmission count (actual transmissions is N + 1).

Parameters

transmit: Encoded transmit count & interval value.

BT_MESH_TRANSMIT_INT(transmit)¶

Decode transmit interval from a transmit value.

Return

Transmission interval in milliseconds.

Parameters

transmit: Encoded transmit count & interval value.

BT_MESH_PUB_TRANSMIT(count, int_ms)¶

Encode Publish Retransmit count & interval steps.

Return

Mesh transmit value that can be used e.g. for the default values of the configuration model data.

Parameters

count: Number of retransmissions (first transmission is excluded).
int_ms: Interval steps in milliseconds. Must be greater than 0 and a multiple of 50.

BT_MESH_PUB_TRANSMIT_COUNT(transmit)¶

Decode Publish Retransmit count from a given value.

Return

Retransmission count (actual transmissions is N + 1).

Parameters

transmit: Encoded Publish Retransmit count & interval value.

BT_MESH_PUB_TRANSMIT_INT(transmit)¶

Decode Publish Retransmit interval from a given value.

Return

Transmission interval in milliseconds.

Parameters

transmit: Encoded Publish Retransmit count & interval value.

BT_MESH_MODEL_PUB_DEFINE(_name, _update, _msg_len)¶

Define a model publication context.

Parameters

_name: Variable name given to the context.
_update: Optional message update callback (may be NULL).
_msg_len: Length of the publication message.

BT_MESH_TTL_DEFAULT¶: Special TTL value to request using configured default TTL

BT_MESH_TTL_MAX¶: Maximum allowed TTL value

Functions

void bt_mesh_model_msg_init(struct net_buf_simple *msg, uint32_t opcode)¶

Initialize a model message.

Clears the message buffer contents, and encodes the given opcode. The message buffer will be ready for filling in payload data.

Parameters

msg: Message buffer.
opcode: Opcode to encode.

int bt_mesh_model_send(struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, struct net_buf_simple *msg, const struct bt_mesh_send_cb *cb, void *cb_data)¶

Send an Access Layer message.

Return

0 on success, or (negative) error code on failure.

Parameters

model: Mesh (client) Model that the message belongs to.
ctx: Message context, includes keys, TTL, etc.
msg: Access Layer payload (the actual message to be sent).
cb: Optional “message sent” callback.
cb_data: User data to be passed to the callback.

int bt_mesh_model_publish(struct bt_mesh_model *model)¶

Send a model publication message.

Before calling this function, the user needs to ensure that the model publication message (bt_mesh_model_pub::msg) contains a valid message to be sent. Note that this API is only to be used for non-period publishing. For periodic publishing the app only needs to make sure that bt_mesh_model_pub::msg contains a valid message whenever the bt_mesh_model_pub::update callback is called.

Return

0 on success, or (negative) error code on failure.

Parameters

model: Mesh (client) Model that’s publishing the message.

struct bt_mesh_elem *bt_mesh_model_elem(struct bt_mesh_model *mod)¶

Get the element that a model belongs to.

Return

Pointer to the element that the given model belongs to.

Parameters

mod: Mesh model.

struct bt_mesh_model *bt_mesh_model_find(const struct bt_mesh_elem *elem, uint16_t id)¶

Find a SIG model.

Return

A pointer to the Mesh model matching the given parameters, or NULL if no SIG model with the given ID exists in the given element.

Parameters

elem: Element to search for the model in.
id: Model ID of the model.

struct bt_mesh_model *bt_mesh_model_find_vnd(const struct bt_mesh_elem *elem, uint16_t company, uint16_t id)¶

Find a vendor model.

Return

A pointer to the Mesh model matching the given parameters, or NULL if no vendor model with the given ID exists in the given element.

Parameters

elem: Element to search for the model in.
company: Company ID of the model.
id: Model ID of the model.

static inline bool bt_mesh_model_in_primary(const struct bt_mesh_model *mod)¶

Get whether the model is in the primary element of the device.

Return

true if the model is on the primary element, false otherwise.

Parameters

mod: Mesh model.

int bt_mesh_model_data_store(struct bt_mesh_model *mod, bool vnd, const char *name, const void *data, size_t data_len)¶

Immediately store the model’s user data in persistent storage.

Return

0 on success, or (negative) error code on failure.

Parameters

mod: Mesh model.
vnd: This is a vendor model.
name: Name/key of the settings item.
data: Model data to store, or NULL to delete any model data.
data_len: Length of the model data.

int bt_mesh_model_extend(struct bt_mesh_model *mod, struct bt_mesh_model *base_mod)¶

Let a model extend another.

Mesh models may be extended to reuse their functionality, forming a more complex model. A Mesh model may extend any number of models, in any element. The extensions may also be nested, ie a model that extends another may itself be extended. Extensions may not be cyclical, and a model can only be extended by one other model.

A set of models that extend each other form a model extension tree.

All models in an extension tree share one subscription list per element. The access layer will utilize the combined subscription list of all models in an extension tree and element, giving the models extended subscription list capacity.

Parameters

mod: Mesh model.
base_mod: The model being extended.

Return Value

0: Successfully extended the base_mod model.
-EALREADY: The base_mod model is already extended.

struct bt_mesh_elem¶

#include <access.h>

Abstraction that describes a Mesh Element

Public Members

uint16_t addr¶: Unicast Address. Set at runtime during provisioning.

const uint16_t loc¶: Location Descriptor (GATT Bluetooth Namespace Descriptors)

const uint8_t model_count¶: The number of SIG models in this element

const uint8_t vnd_model_count¶: The number of vendor models in this element

struct bt_mesh_model *const models¶: The list of SIG models in this element

struct bt_mesh_model *const vnd_models¶: The list of vendor models in this element

struct bt_mesh_msg_ctx¶

#include <access.h>

Message sending context.

Public Members

uint16_t net_idx¶: NetKey Index of the subnet to send the message on.

uint16_t app_idx¶: AppKey Index to encrypt the message with.

uint16_t addr¶: Remote address.

uint16_t recv_dst¶: Destination address of a received message. Not used for sending.

int8_t recv_rssi¶: RSSI of received packet. Not used for sending.

uint8_t recv_ttl¶: Received TTL value. Not used for sending.

bool send_rel¶: Force sending reliably by using segment acknowledgement

uint8_t send_ttl¶: TTL, or BT_MESH_TTL_DEFAULT for default TTL.

struct bt_mesh_model_op¶

#include <access.h>

Model opcode handler.

Public Members

const uint32_t opcode¶: OpCode encoded using the BT_MESH_MODEL_OP_* macros

const size_t min_len¶: Minimum required message length

void (*const func)(struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, struct net_buf_simple *buf)¶

Handler function for this opcode.

Parameters

model: Model instance receiving the message.
ctx: Message context for the message.
buf: Message buffer containing the message payload, not including the opcode.

struct bt_mesh_model_pub¶

#include <access.h>

Model publication context.

The context should primarily be created using the BT_MESH_MODEL_PUB_DEFINE macro.

Public Members

struct bt_mesh_model *mod¶: The model the context belongs to. Initialized by the stack.

uint16_t addr¶: Publish Address.

uint16_t key¶: Publish AppKey Index.

uint16_t cred¶: Friendship Credentials Flag.

uint16_t send_rel¶: Force reliable sending (segment acks)

uint8_t ttl¶: Publish Time to Live.

uint8_t retransmit¶: Retransmit Count & Interval Steps.

uint8_t period¶: Publish Period.

uint8_t period_div¶: Divisor for the Period.

uint8_t fast_period¶: Use FastPeriodDivisor

uint8_t count¶: Retransmissions left.

uint32_t period_start¶: Start of the current period.

struct net_buf_simple *msg¶

Publication buffer, containing the publication message.

This will get correctly created when the publication context has been defined using the BT_MESH_MODEL_PUB_DEFINE macro.

BT_MESH_MODEL_PUB_DEFINE(name, update, size);

int (*update)(struct bt_mesh_model *mod)¶

Callback for updating the publication buffer.

When set to NULL, the model is assumed not to support periodic publishing. When set to non-NULL the callback will be called periodically and is expected to update bt_mesh_model_pub::msg with a valid publication message.

If the callback returns non-zero, the publication is skipped and will resume on the next periodic publishing interval.

Return

Zero on success or (negative) error code otherwise.

Parameters

mod: The Model the Publication Context belogs to.

struct k_delayed_work timer¶: Publish Period Timer. Only for stack-internal use.

struct bt_mesh_model_cb¶

#include <access.h>

Model callback functions.

Public Members

int (*const settings_set)(struct bt_mesh_model *model, const char *name, size_t len_rd, settings_read_cb read_cb, void *cb_arg)¶

Set value handler of user data tied to the model.

See

settings_handler::h_set

Return

0 on success, error otherwise.

Parameters

model: Model to set the persistent data of.
name: Name/key of the settings item.
len_rd: The size of the data found in the backend.
read_cb: Function provided to read the data from the backend.
cb_arg: Arguments for the read function provided by the backend.

int (*const start)(struct bt_mesh_model *model)¶

Callback called when the mesh is started.

This handler gets called after the node has been provisioned, or after all mesh data has been loaded from persistent storage.

When this callback fires, the mesh model may start its behavior, and all Access APIs are ready for use.

Return

0 on success, error otherwise.

Parameters

model: Model this callback belongs to.

int (*const init)(struct bt_mesh_model *model)¶

Model init callback.

Called on every model instance during mesh initialization.

If any of the model init callbacks return an error, the Mesh subsystem initialization will be aborted, and the error will be returned to the caller of bt_mesh_init.

Return

0 on success, error otherwise.

Parameters

model: Model to be initialized.

void (*const reset)(struct bt_mesh_model *model)¶

Model reset callback.

Called when the mesh node is reset. All model data is deleted on reset, and the model should clear its state.

Note

If the model stores any persistent data, this needs to be erased manually.

Parameters

model: Model this callback belongs to.

struct bt_mesh_model¶

#include <access.h>

Abstraction that describes a Mesh Model instance

Public Members

struct bt_mesh_model_pub *const pub¶: Model Publication

uint16_t keys[CONFIG_BT_MESH_MODEL_KEY_COUNT]¶: AppKey List

uint16_t groups[CONFIG_BT_MESH_MODEL_GROUP_COUNT]¶: Subscription List (group or virtual addresses)

const struct bt_mesh_model_op *const op¶: Opcode handler list

const struct bt_mesh_model_cb *const cb¶: Model callback structure.

void *user_data¶: Model-specific user data

struct bt_mesh_send_cb¶

#include <access.h>

Callback structure for monitoring model message sending

Public Members

void (*start)(uint16_t duration, int err, void *cb_data)¶

Handler called at the start of the transmission.

Parameters

duration: The duration of the full transmission.
err: Error occurring during sending.
cb_data: Callback data, as passed to the send API.

void (*end)(int err, void *cb_data)¶

Handler called at the end of the transmission.

Parameters

err: Error occurring during sending.
cb_data: Callback data, as passed to the send API.

struct bt_mesh_comp¶

#include <access.h>

Node Composition

Public Members

uint16_t cid¶: Company ID

uint16_t pid¶: Product ID

uint16_t vid¶: Version ID

size_t elem_count¶: The number of elements in this device.

struct bt_mesh_elem *elem¶: List of elements.