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