Access layer

The access layer is the application’s interface to the Bluetooth 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 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 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.

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

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 fundamental 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 delayable 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.

When the mesh stack is suspended or reset, messages not yet sent are removed and the bt_mesh_send_cb.start callback is raised with an error code.

Note

When a model sends several messages in a row, it may happen that the messages are not sent in the order they were passed to the access layer. This is because some messages can be delayed for a longer time than the others.

Disable the randomization by setting the bt_mesh_msg_ctx.rnd_delay to false, when a set of messages originated by the same model needs to be sent in a certain order.

Delayable publications

The delayable publication functionality 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.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

BT_MESH_MODEL_NONE

Helper to define an empty model array.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

BT_MESH_MODEL_CNT_CB(_id, _op, _pub, _user_data, _keys, _grps, _cb)

Composition data SIG model entry with callback functions with specific number of keys & groups.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

Parameters:

• _id – Model ID.

• _op – Array of model opcode handlers.

• _pub – Model publish parameters.

• _user_data – User data for the model.

• _keys – Number of keys that can be bound to the model. Shall not exceed CONFIG_BT_MESH_MODEL_KEY_COUNT .

• _grps – Number of addresses that the model can be subscribed to. Shall not exceed CONFIG_BT_MESH_MODEL_GROUP_COUNT .

• _cb – Callback structure, or NULL to keep no callbacks.

BT_MESH_MODEL_CNT_VND_CB(_company, _id, _op, _pub, _user_data, _keys, _grps, _cb)

Composition data vendor model entry with callback functions with specific number of keys & groups.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

Parameters:

• _company – Company ID.

• _id – Model ID.

• _op – Array of model opcode handlers.

• _pub – Model publish parameters.

• _user_data – User data for the model.

• _keys – Number of keys that can be bound to the model. Shall not exceed CONFIG_BT_MESH_MODEL_KEY_COUNT .

• _grps – Number of addresses that the model can be subscribed to. Shall not exceed CONFIG_BT_MESH_MODEL_GROUP_COUNT .

• _cb – Callback structure, or NULL to keep no callbacks.

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

Composition data SIG model entry with callback functions.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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_METADATA_CB(_id, _op, _pub, _user_data, _cb, _metadata)

Composition data SIG model entry with callback functions and metadata.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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.

• _metadata – Metadata structure. Used if CONFIG_BT_MESH_LARGE_COMP_DATA_SRV is enabled.

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

Composition data vendor model entry with callback functions.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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_VND_METADATA_CB(_company, _id, _op, _pub, _user_data, _cb, _metadata)

Composition data vendor model entry with callback functions and metadata.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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.

• _metadata – Metadata structure. Used if CONFIG_BT_MESH_LARGE_COMP_DATA_SRV is enabled.

BT_MESH_MODEL(_id, _op, _pub, _user_data)

Composition data SIG model entry.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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.

This macro uses compound literal feature of C99 standard and thus is available only from C, not C++.

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.

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.

Returns:

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

BT_MESH_TRANSMIT_COUNT(transmit)

Decode transmit count from a transmit value.

Parameters:

• transmit – Encoded transmit count & interval value.

Returns:

Transmission count (actual transmissions is N + 1).

BT_MESH_TRANSMIT_INT(transmit)

Decode transmit interval from a transmit value.

Parameters:

• transmit – Encoded transmit count & interval value.

Returns:

Transmission interval in milliseconds.

BT_MESH_PUB_TRANSMIT(count, int_ms)

Encode Publish Retransmit count & interval steps.

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.

Returns:

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

BT_MESH_PUB_TRANSMIT_COUNT(transmit)

Decode Publish Retransmit count from a given value.

Parameters:

• transmit – Encoded Publish Retransmit count & interval value.

Returns:

Retransmission count (actual transmissions is N + 1).

BT_MESH_PUB_TRANSMIT_INT(transmit)

Decode Publish Retransmit interval from a given value.

Parameters:

• transmit – Encoded Publish Retransmit count & interval value.

Returns:

Transmission interval in milliseconds.

BT_MESH_PUB_MSG_TOTAL(pub)

Get total number of messages within one publication interval including initial publication.

Parameters:

• pub – Model publication context.

Returns:

total number of messages.

BT_MESH_PUB_MSG_NUM(pub)

Get message number within one publication interval.

Meant to be used inside bt_mesh_model_pub::update.

Parameters:

• pub – Model publication context.

Returns:

message number starting from 1.

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_MODELS_METADATA_ENTRY(_len, _id, _data)

Initialize a Models Metadata entry structure in a list.

Parameters:

• _len – Length of the metadata entry.

• _id – ID of the Models Metadata entry.

• _data – Pointer to a contiguous memory that contains the metadata.

BT_MESH_MODELS_METADATA_NONE

Helper to define an empty Models metadata array.

BT_MESH_MODELS_METADATA_END

End of the Models Metadata list.

Must always be present.

BT_MESH_TTL_DEFAULT

Special TTL value to request using configured default TTL.

BT_MESH_TTL_MAX

Maximum allowed TTL value.

Functions

int bt_mesh_model_send(const 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.

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.

Returns:

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

int bt_mesh_model_publish(const 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.

Parameters:

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

Returns:

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

static inline bool bt_mesh_model_pub_is_retransmission(const struct bt_mesh_model *model)

Check if a message is being retransmitted.

Meant to be used inside the bt_mesh_model_pub::update callback.

Parameters:

• model – Mesh Model that supports publication.

Returns:

true if this is a retransmission, false if this is a first publication.

const struct bt_mesh_elem *bt_mesh_model_elem(const struct bt_mesh_model *mod)

Get the element that a model belongs to.

Parameters:

• mod – Mesh model.

Returns:

Pointer to the element that the given model belongs to.

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

Find a SIG model.

Parameters:

• elem – Element to search for the model in.

• id – Model ID of the model.

Returns:

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.

const 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.

Parameters:

• elem – Element to search for the model in.

• company – Company ID of the model.

• id – Model ID of the model.

Returns:

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.

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.

Parameters:

• mod – Mesh model.

Returns:

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

int bt_mesh_model_data_store(const 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.

Parameters:

• mod – Mesh model.

• vnd – This is a vendor model.

• name – Name/key of the settings item. Only SETTINGS_MAX_DIR_DEPTH bytes will be used at most.

• data – Model data to store, or NULL to delete any model data.

• data_len – Length of the model data.

Returns:

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

void bt_mesh_model_data_store_schedule(const struct bt_mesh_model *mod)

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

This function triggers the bt_mesh_model_cb::pending_store callback for the corresponding model after delay defined by CONFIG_BT_MESH_STORE_TIMEOUT .

The delay is global for all models. Once scheduled, the callback can not be re-scheduled until previous schedule completes.

Parameters:

• mod – Mesh model.

int bt_mesh_model_extend(const struct bt_mesh_model *extending_mod, const 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.

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

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

If CONFIG_BT_MESH_COMP_PAGE_1 is enabled, it is not allowed to call this function before the bt_mesh_model_cb::init callback is called for both models, except if it is called as part of the final callback.

Parameters:

• extending_mod – Mesh model that is extending the base model.

• base_mod – The model being extended.

Return values:

0 – Successfully extended the base_mod model.

int bt_mesh_model_correspond(const struct bt_mesh_model *corresponding_mod, const struct bt_mesh_model *base_mod)

Let a model correspond to another.

Mesh models may correspond to each other, which means that if one is present, other must be present too. A Mesh model may correspond to any number of models, in any element. All models connected together via correspondence form single Correspondence Group, which has it’s unique Correspondence ID. Information about Correspondence is used to construct Composition Data Page 1.

This function must be called on already initialized base_mod. Because this function is designed to be called in corresponding_mod initializer, this means that base_mod shall be initialized before corresponding_mod is.

Parameters:

• corresponding_mod – Mesh model that is corresponding to the base model.

• base_mod – The model being corresponded to.

Return values:

• 0 – Successfully saved correspondence to the base_mod model.

• -ENOMEM – There is no more space to save this relation.

• -ENOTSUP – Composition Data Page 1 is not supported.

bool bt_mesh_model_is_extended(const struct bt_mesh_model *model)

Check if model is extended by another model.

Parameters:

• model – The model to check.

Return values:

true – If model is extended by another model, otherwise false

int bt_mesh_comp_change_prepare(void)

Indicate that the composition data will change on next bootup.

Tell the config server that the composition data is expected to change on the next bootup, and the current composition data should be backed up.

Returns:

Zero on success or (negative) error code otherwise.

int bt_mesh_models_metadata_change_prepare(void)

Indicate that the metadata will change on next bootup.

Tell the config server that the models metadata is expected to change on the next bootup, and the current models metadata should be backed up.

Returns:

Zero on success or (negative) error code otherwise.

int bt_mesh_comp2_register(const struct bt_mesh_comp2 *comp2)

Register composition data page 2 of the device.

Register Mesh Profiles information (Ref section 3.12 in Bluetooth SIG Assigned Numbers) for composition data page 2 of the device.

Note

There must be at least one record present in comp2

Parameters:

• comp2 – Pointer to composition data page 2.

Returns:

Zero on success or (negative) error code otherwise.

struct bt_mesh_elem

#include <access.h>

Abstraction that describes a Mesh Element.

Public Members

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.

const struct bt_mesh_model *const models

The list of SIG models in this element.

const struct bt_mesh_model *const vnd_models

The list of vendor models in this element.

struct bt_mesh_elem_rt_ctx

#include <access.h>

Mesh Element runtime information.

Public Members

uint16_t addr

Unicast Address.

Set at runtime during provisioning.

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 ssize_t len

Message length.

If the message has variable length then this value indicates minimum message length and should be positive. Handler function should verify precise length based on the contents of the message. If the message has fixed length then this value should be negative. Use BT_MESH_LEN_* macros when defining this value.

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

Handler function for this opcode.

Param model:

Model instance receiving the message.

Param ctx:

Message context for the message.

Param buf:

Message buffer containing the message payload, not including the opcode.

Return:

Zero on success or (negative) error code otherwise.

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

const struct bt_mesh_model *mod

The model the context belongs to.

Initialized by the stack.

uint16_t addr

Publish Address.

const uint8_t *uuid

Label UUID if Publish Address is Virtual Address.

uint16_t key

Publish AppKey Index.

uint16_t cred

Friendship Credentials Flag.

uint16_t send_rel

Force reliable sending (segment acks)

uint16_t fast_period

Use FastPeriodDivisor.

uint16_t retr_update

Call update callback on every retransmission.

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 count

Transmissions left.

uint8_t delayable

Use random delay for publishing.

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)(const 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.

When bt_mesh_model_pub::retr_update is set to 1, the callback will be called on every retransmission.

Param mod:

The Model the Publication Context belongs to.

Return:

Zero on success or (negative) error code otherwise.

struct k_work_delayable timer

Publish Period Timer.

Only for stack-internal use.

struct bt_mesh_models_metadata_entry

#include <access.h>

Models Metadata Entry struct.

The struct should primarily be created using the BT_MESH_MODELS_METADATA_ENTRY macro.

struct bt_mesh_model_cb

#include <access.h>

Model callback functions.

Public Members

int (*const settings_set)(const 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 also

settings_handler::h_set

Param model:

Model to set the persistent data of.

Param name:

Name/key of the settings item.

Param len_rd:

The size of the data found in the backend.

Param read_cb:

Function provided to read the data from the backend.

Param cb_arg:

Arguments for the read function provided by the backend.

Return:

0 on success, error otherwise.

int (*const start)(const 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.

Param model:

Model this callback belongs to.

Return:

0 on success, error otherwise.

int (*const init)(const 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.

Param model:

Model to be initialized.

Return:

0 on success, error otherwise.

void (*const reset)(const 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.

Param model:

Model this callback belongs to.

void (*const pending_store)(const struct bt_mesh_model *model)

Callback used to store pending model’s user data.

Triggered by bt_mesh_model_data_store_schedule.

To store the user data, call bt_mesh_model_data_store.

Param model:

Model this callback belongs to.

struct bt_mesh_mod_id_vnd

#include <access.h>

Vendor model ID.

Public Members

uint16_t company

Vendor’s company ID.

uint16_t id

Model ID.

struct bt_mesh_model

#include <access.h>

Abstraction that describes a Mesh Model instance.

Public Members

const uint16_t id

SIG model ID.

const struct bt_mesh_mod_id_vnd vnd

Vendor model ID.

struct bt_mesh_model_pub *const pub

Model Publication.

uint16_t *const keys

AppKey List.

uint16_t *const groups

Subscription List (group or virtual addresses)

const uint8_t **const uuids

List of Label UUIDs the model is subscribed to.

const struct bt_mesh_model_op *const op

Opcode handler list.

const struct bt_mesh_model_cb *const cb

Model callback structure.

struct bt_mesh_model_rt_ctx

#include <access.h>

Public Members

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.

Param duration:

The duration of the full transmission.

Param err:

Error occurring during sending.

Param 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.

Param err:

Error occurring during sending.

Param 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.

const struct bt_mesh_elem *elem

List of elements.

struct bt_mesh_comp2_record

#include <access.h>

Composition data page 2 record.

Public Members

uint16_t id

Mesh profile ID.

uint8_t x

Major version.

uint8_t y

Minor version.

uint8_t z

Z version.

struct bt_mesh_comp2_record.[anonymous] version

Mesh Profile Version.

uint8_t elem_offset_cnt

Element offset count.

const uint8_t *elem_offset

Element offset list.

uint16_t data_len

Length of additional data.

const void *data

Additional data.

struct bt_mesh_comp2

#include <access.h>

Node Composition data page 2.

Public Members

size_t record_cnt

The number of Mesh Profile records on a device.

const struct bt_mesh_comp2_record *record

List of records.