1.. _bluetooth_mesh_access: 2 3Access layer 4############ 5 6The access layer is the application's interface to the Bluetooth Mesh network. 7The access layer provides mechanisms for compartmentalizing the node behavior 8into elements and models, which are implemented by the application. 9 10Mesh models 11*********** 12 13The functionality of a mesh node is represented by models. A model implements 14a single behavior the node supports, like being a light, a sensor or a 15thermostat. The mesh models are grouped into *elements*. Each element is 16assigned its own unicast address, and may only contain one of each type of 17model. Conventionally, each element represents a single aspect of the mesh 18node behavior. For instance, a node that contains a sensor, two lights and a 19power outlet would spread this functionality across four elements, with each 20element instantiating all the models required for a single aspect of the 21supported behavior. 22 23The node's element and model structure is specified in the node composition 24data, which is passed to :c:func:`bt_mesh_init` during initialization. The 25Bluetooth SIG have defined a set of foundation models (see 26:ref:`bluetooth_mesh_models`) and a set of models for implementing common 27behavior in the `Bluetooth Mesh Model Specification 28<https://www.bluetooth.com/specifications/mesh-specifications/>`_. All models 29not specified by the Bluetooth SIG are vendor models, and must be tied to a 30Company ID. 31 32Mesh models have several parameters that can be configured either through 33initialization of the mesh stack or with the 34:ref:`bluetooth_mesh_models_cfg_srv`: 35 36Opcode list 37=========== 38 39The opcode list contains all message opcodes the model can receive, as well as 40the minimum acceptable payload length and the callback to pass them to. Models 41can support any number of opcodes, but each opcode can only be listed by one 42model in each element. 43 44The full opcode list must be passed to the model structure in the composition 45data, and cannot be changed at runtime. The end of the opcode list is 46determined by the special :c:macro:`BT_MESH_MODEL_OP_END` entry. This entry 47must always be present in the opcode list, unless the list is empty. In that 48case, :c:macro:`BT_MESH_MODEL_NO_OPS` should be used in place of a proper 49opcode list definition. 50 51AppKey list 52=========== 53 54The AppKey list contains all the application keys the model can receive 55messages on. Only messages encrypted with application keys in the AppKey list 56will be passed to the model. 57 58The maximum number of supported application keys each model can hold is 59configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_KEY_COUNT` configuration 60option. The contents of the AppKey list is managed by the 61:ref:`bluetooth_mesh_models_cfg_srv`. 62 63Subscription list 64================= 65 66A model will process all messages addressed to the unicast address of their 67element (given that the utilized application key is present in the AppKey 68list). Additionally, the model will process packets addressed to any group or 69virtual address in its subscription list. This allows nodes to address 70multiple nodes throughout the mesh network with a single message. 71 72The maximum number of supported addresses in the Subscription list each model 73can hold is configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_GROUP_COUNT` 74configuration option. The contents of the subscription list is managed by the 75:ref:`bluetooth_mesh_models_cfg_srv`. 76 77Model publication 78================= 79 80The models may send messages in two ways: 81 82* By specifying a set of message parameters in a :c:struct:`bt_mesh_msg_ctx`, 83 and calling :c:func:`bt_mesh_model_send`. 84* By setting up a :c:struct:`bt_mesh_model_pub` structure and calling 85 :c:func:`bt_mesh_model_publish`. 86 87When publishing messages with :c:func:`bt_mesh_model_publish`, the model 88will use the publication parameters configured by the 89:ref:`bluetooth_mesh_models_cfg_srv`. This is the recommended way to send 90unprompted model messages, as it passes the responsibility of selecting 91message parameters to the network administrator, which likely knows more about 92the mesh network than the individual nodes will. 93 94To support publishing with the publication parameters, the model must allocate 95a packet buffer for publishing, and pass it to 96:c:member:`bt_mesh_model_pub.msg`. The Config Server may also set up period 97publication for the publication message. To support this, the model must 98populate the :c:member:`bt_mesh_model_pub.update` callback. The 99:c:member:`bt_mesh_model_pub.update` callback will be called right before the 100message is published, allowing the model to change the payload to reflect its 101current state. 102 103By setting :c:member:`bt_mesh_model_pub.retr_update` to 1, the model can 104configure the :c:member:`bt_mesh_model_pub.update` callback to be triggered 105on every retransmission. This can, for example, be used by models that make 106use of a Delay parameter, which can be adjusted for every retransmission. 107The :c:func:`bt_mesh_model_pub_is_retransmission` function can be 108used to differentiate a first publication and a retransmission. 109The :c:macro:`BT_MESH_PUB_MSG_TOTAL` and :c:macro:`BT_MESH_PUB_MSG_NUM` macros 110can be used to return total number of transmissions and the retransmission 111number within one publication interval. 112 113Extended models 114=============== 115 116The Bluetooth Mesh specification allows the mesh models to extend each other. 117When a model extends another, it inherits that model's functionality, and 118extension can be used to construct complex models out of simple ones, 119leveraging the existing model functionality to avoid defining new opcodes. 120Models may extend any number of models, from any element. When one model 121extends another in the same element, the two models will share subscription 122lists. The mesh stack implements this by merging the subscription lists of the 123two models into one, combining the number of subscriptions the models can have 124in total. Models may extend models that extend others, creating an "extension 125tree". All models in an extension tree share a single subscription list per 126element it spans. 127 128Model extensions are done by calling :c:func:`bt_mesh_model_extend` during 129initialization. A model can only be extended by one other model, and 130extensions cannot be circular. Note that binding of node states and other 131relationships between the models must be defined by the model implementations. 132 133The model extension concept adds some overhead in the access layer packet 134processing, and must be explicitly enabled with 135:kconfig:option:`CONFIG_BT_MESH_MODEL_EXTENSIONS` to have any effect. 136 137Model data storage 138================== 139 140Mesh models may have data associated with each model instance that needs to be 141stored persistently. The access API provides a mechanism for storing this 142data, leveraging the internal model instance encoding scheme. Models can store 143one user defined data entry per instance by calling 144:c:func:`bt_mesh_model_data_store`. To be able to read out the data the 145next time the device reboots, the model's 146:c:member:`bt_mesh_model_cb.settings_set` callback must be populated. This 147callback gets called when model specific data is found in the persistent 148storage. The model can retrieve the data by calling the ``read_cb`` passed as 149a parameter to the callback. See the :ref:`settings_api` module documentation for 150details. 151 152When model data changes frequently, storing it on every change may lead to 153increased wear of flash. To reduce the wear, the model can postpone storing of 154data by calling :c:func:`bt_mesh_model_data_store_schedule`. The stack will 155schedule a work item with delay defined by the 156:kconfig:option:`CONFIG_BT_MESH_STORE_TIMEOUT` option. When the work item is 157running, the stack will call the :c:member:`bt_mesh_model_cb.pending_store` 158callback for every model that has requested storing of data. The model can 159then call :c:func:`bt_mesh_model_data_store` to store the data. 160 161If :kconfig:option:`CONFIG_BT_MESH_SETTINGS_WORKQ` is enabled, the 162:c:member:`bt_mesh_model_cb.pending_store` callback is called from a dedicated 163thread. This allows the stack to process other incoming and outgoing messages 164while model data is being stored. It is recommended to use this option and the 165:c:func:`bt_mesh_model_data_store_schedule` function when large amount of data 166needs to be stored. 167 168Composition Data 169================ 170 171The Composition Data provides information about a mesh device. 172A device's Composition Data holds information about the elements on the 173device, the models that it supports, and other features. The Composition 174Data is split into different pages, where each page contains specific feature 175information about the device. In order to access this information, the user 176may use the :ref:`bluetooth_mesh_models_cfg_srv` model or, if supported, 177the :ref:`bluetooth_mesh_lcd_srv` model. 178 179Composition Data Page 0 180----------------------- 181 182Composition Data Page 0 provides the fundamental information about a device, and 183is mandatory for all mesh devices. It contains the element and model composition, 184the supported features, and manufacturer information. 185 186Composition Data Page 1 187----------------------- 188 189Composition Data Page 1 provides information about the relationships between models, 190and is mandatory for all mesh devices. A model may extend and/or correspond to one 191or more models. A model can extend another model by calling :c:func:`bt_mesh_model_extend`, 192or correspond to another model by calling :c:func:`bt_mesh_model_correspond`. 193:kconfig:option:`CONFIG_BT_MESH_MODEL_EXTENSION_LIST_SIZE` specifies how many model 194relations can be stored in the composition on a device, and this number should reflect the 195number of :c:func:`bt_mesh_model_extend` and :c:func:`bt_mesh_model_correspond` calls. 196 197Composition Data Page 2 198----------------------- 199 200Composition Data Page 2 provides information for supported mesh profiles. Mesh profile 201specifications define product requirements for devices that want to support a specific 202Bluetooth SIG defined profile. Currently supported profiles can be found in section 2033.12 in `Bluetooth SIG Assigned Numbers 204<https://www.bluetooth.com/specifications/assigned-numbers/uri-scheme-name-string-mapping/>`_. 205Composition Data Page 2 is only mandatory for devices that claim support for one or more 206mesh profile(s). 207 208Composition Data Pages 128, 129 and 130 209--------------------------------------- 210 211Composition Data Pages 128, 129 and 130 mirror Composition Data Pages 0, 1 and 2 respectively. 212They are used to represent the new content of the mirrored pages when the Composition Data will 213change after a firmware update. See :ref:`bluetooth_mesh_dfu_srv_comp_data_and_models_metadata` 214for details. 215 216Delayable messages 217================== 218 219The delayable message functionality is enabled with Kconfig option 220:kconfig:option:`CONFIG_BT_MESH_ACCESS_DELAYABLE_MSG`. 221This is an optional functionality that implements specification recommendations for 222messages that are transmitted by a model in a response to a received message, also called 223response messages. 224 225Response messages should be sent with the following random delays: 226 227* Between 20 and 50 milliseconds if the received message was sent 228 to a unicast address 229* Between 20 and 500 milliseconds if the received message was sent 230 to a group or virtual address 231 232The delayable message functionality is triggered if the :c:member:`bt_mesh_msg_ctx.rnd_delay` 233flag is set. 234The delayable message functionality stores messages in the local memory while they are 235waiting for the random delay expiration. 236 237If the transport layer doesn't have sufficient memory to send a message at the moment 238the random delay expires, the message is postponed for another 10 milliseconds. 239If the transport layer cannot send a message for any other reason, the delayable message 240functionality raises the :c:member:`bt_mesh_send_cb.start` callback with a transport layer 241error code. 242 243If the delayable message functionality cannot find enough free memory to store an incoming 244message, it will send messages with delay close to expiration to free memory. 245 246When the mesh stack is suspended or reset, messages not yet sent are removed and 247the :c:member:`bt_mesh_send_cb.start` callback is raised with an error code. 248 249.. note:: 250 When a model sends several messages in a row, it may happen that the messages are not sent in 251 the order they were passed to the access layer. This is because some messages can be delayed 252 for a longer time than the others. 253 254 Disable the randomization by setting the :c:member:`bt_mesh_msg_ctx.rnd_delay` to ``false``, 255 when a set of messages originated by the same model needs to be sent in a certain order. 256 257Delayable publications 258====================== 259 260The delayable publication functionality implements the specification recommendations for message 261publication delays in the following cases: 262 263* Between 20 to 500 milliseconds when the Bluetooth Mesh stack starts or when the publication is 264 triggered by the :c:func:`bt_mesh_model_publish` function 265* Between 20 to 50 milliseconds for periodically published messages 266 267This feature is optional and enabled with the :kconfig:option:`CONFIG_BT_MESH_DELAYABLE_PUBLICATION` 268Kconfig option. When enabled, each model can enable or disable the delayable publication by setting 269the :c:member:`bt_mesh_model_pub.delayable` bit field to ``1`` or ``0`` correspondingly. This bit 270field can be changed at any time. 271 272API reference 273************* 274 275.. doxygengroup:: bt_mesh_access 276
