Lines Matching full:the
6 The access layer is the application's interface to the Bluetooth Mesh network.
7 The access layer provides mechanisms for compartmentalizing the node behavior
8 into elements and models, which are implemented by the application.
13 The functionality of a mesh node is represented by models. A model implements
14 a single behavior the node supports, like being a light, a sensor or a
15 thermostat. The mesh models are grouped into *elements*. Each element is
17 model. Conventionally, each element represents a single aspect of the mesh
20 element instantiating all the models required for a single aspect of the
23 The node's element and model structure is specified in the node composition
24 data, which is passed to :c:func:`bt_mesh_init` during initialization. The
27 behavior in the `Bluetooth Mesh Model Specification
29 not specified by the Bluetooth SIG are vendor models, and must be tied to a
33 initialization of the mesh stack or with the
39 The opcode list contains all message opcodes the model can receive, as well as
40 the minimum acceptable payload length and the callback to pass them to. Models
44 The full opcode list must be passed to the model structure in the composition
45 data, and cannot be changed at runtime. The end of the opcode list is
46 determined by the special :c:macro:`BT_MESH_MODEL_OP_END` entry. This entry
47 must always be present in the opcode list, unless the list is empty. In that
54 The AppKey list contains all the application keys the model can receive
55 messages on. Only messages encrypted with application keys in the AppKey list
56 will be passed to the model.
58 The maximum number of supported application keys each model can hold is
59 configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_KEY_COUNT` configuration
60 option. The contents of the AppKey list is managed by the
66 A model will process all messages addressed to the unicast address of their
67 element (given that the utilized application key is present in the AppKey
68 list). Additionally, the model will process packets addressed to any group or
70 multiple nodes throughout the mesh network with a single message.
72 The maximum number of supported addresses in the Subscription list each model
73 can hold is configured with the :kconfig:option:`CONFIG_BT_MESH_MODEL_GROUP_COUNT`
74 configuration option. The contents of the subscription list is managed by the
80 The models may send messages in two ways:
87 When publishing messages with :c:func:`bt_mesh_model_publish`, the model
88 will use the publication parameters configured by the
89 :ref:`bluetooth_mesh_models_cfg_srv`. This is the recommended way to send
90 unprompted model messages, as it passes the responsibility of selecting
91 message parameters to the network administrator, which likely knows more about
92 the mesh network than the individual nodes will.
94 To support publishing with the publication parameters, the model must allocate
96 :c:member:`bt_mesh_model_pub.msg`. The Config Server may also set up period
97 publication for the publication message. To support this, the model must
98 populate 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
100 message is published, allowing the model to change the payload to reflect its
103 By setting :c:member:`bt_mesh_model_pub.retr_update` to 1, the model can
104 configure the :c:member:`bt_mesh_model_pub.update` callback to be triggered
107 The :c:func:`bt_mesh_model_pub_is_retransmission` function can be
109 The :c:macro:`BT_MESH_PUB_MSG_TOTAL` and :c:macro:`BT_MESH_PUB_MSG_NUM` macros
110 can be used to return total number of transmissions and the retransmission
116 The Bluetooth Mesh specification allows the mesh models to extend each other.
119 leveraging the existing model functionality to avoid defining new opcodes.
121 extends another in the same element, the two models will share subscription
122 lists. The mesh stack implements this by merging the subscription lists of the
123 two models into one, combining the number of subscriptions the models can have
131 relationships between the models must be defined by the model implementations.
133 The model extension concept adds some overhead in the access layer packet
141 stored persistently. The access API provides a mechanism for storing this
142 data, leveraging the internal model instance encoding scheme. Models can store
144 :c:func:`bt_mesh_model_data_store`. To be able to read out the data the
145 next time the device reboots, the model's
147 callback gets called when model specific data is found in the persistent
148 storage. The model can retrieve the data by calling the ``read_cb`` passed as
149 a parameter to the callback. See the :ref:`settings_api` module documentation for
153 increased wear of flash. To reduce the wear, the model can postpone storing of
154 data by calling :c:func:`bt_mesh_model_data_store_schedule`. The stack will
155 schedule a work item with delay defined by the
156 :kconfig:option:`CONFIG_BT_MESH_STORE_TIMEOUT` option. When the work item is
157 running, the stack will call the :c:member:`bt_mesh_model_cb.pending_store`
158 callback for every model that has requested storing of data. The model can
159 then call :c:func:`bt_mesh_model_data_store` to store the data.
161 If :kconfig:option:`CONFIG_BT_MESH_SETTINGS_WORKQ` is enabled, the
163 thread. This allows the stack to process other incoming and outgoing messages
164 while model data is being stored. It is recommended to use this option and the
171 The Composition Data provides information about a mesh device.
172 A device's Composition Data holds information about the elements on the
173 device, the models that it supports, and other features. The Composition
175 information about the device. In order to access this information, the user
176 may use the :ref:`bluetooth_mesh_models_cfg_srv` model or, if supported,
177 the :ref:`bluetooth_mesh_lcd_srv` model.
182 Composition Data Page 0 provides the fundamental information about a device, and
183 is mandatory for all mesh devices. It contains the element and model composition,
184 the supported features, and manufacturer information.
189 Composition Data Page 1 provides information about the relationships between models,
194 relations can be stored in the composition on a device, and this number should reflect the
212 They are used to represent the new content of the mirrored pages when the Composition Data will
219 The delayable message functionality is enabled with Kconfig option
225 Response messages should be sent with the following random delays:
227 * Between 20 and 50 milliseconds if the received message was sent
229 * Between 20 and 500 milliseconds if the received message was sent
232 The delayable message functionality is triggered if the :c:member:`bt_mesh_msg_ctx.rnd_delay`
234 The delayable message functionality stores messages in the local memory while they are
235 waiting for the random delay expiration.
237 If the transport layer doesn't have sufficient memory to send a message at the moment
238 the random delay expires, the message is postponed for another 10 milliseconds.
239 If the transport layer cannot send a message for any other reason, the delayable message
240 functionality raises the :c:member:`bt_mesh_send_cb.start` callback with a transport layer
243 If the delayable message functionality cannot find enough free memory to store an incoming
246 When the mesh stack is suspended or reset, messages not yet sent are removed and
247 the :c:member:`bt_mesh_send_cb.start` callback is raised with an error code.
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.
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.
260 The delayable publication functionality implements the specification recommendations for message
261 publication delays in the following cases:
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
267 This feature is optional and enabled with the :kconfig:option:`CONFIG_BT_MESH_DELAYABLE_PUBLICATION`
268 Kconfig option. When enabled, each model can enable or disable the delayable publication by setting
269 the :c:member:`bt_mesh_model_pub.delayable` bit field to ``1`` or ``0`` correspondingly. This bit