| .. _bluetooth_mesh_access: |
| |
| 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 :c:func:`bt_mesh_init` during initialization. The |
| Bluetooth SIG have defined a set of foundation models (see |
| :ref:`bluetooth_mesh_models`) and a set of models for implementing common |
| behavior in the `Bluetooth Mesh Model Specification |
| <https://www.bluetooth.com/specifications/mesh-specifications/>`_. 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 |
| :ref:`bluetooth_mesh_models_cfg_srv`: |
| |
| 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 :c:macro:`BT_MESH_MODEL_OP_END` entry. This entry |
| must always be present in the opcode list, unless the list is empty. In that |
| case, :c:macro:`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 :kconfig:option:`CONFIG_BT_MESH_MODEL_KEY_COUNT` configuration |
| option. The contents of the AppKey list is managed by the |
| :ref:`bluetooth_mesh_models_cfg_srv`. |
| |
| 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 :kconfig:option:`CONFIG_BT_MESH_MODEL_GROUP_COUNT` |
| configuration option. The contents of the subscription list is managed by the |
| :ref:`bluetooth_mesh_models_cfg_srv`. |
| |
| Model publication |
| ================= |
| |
| The models may send messages in two ways: |
| |
| * By specifying a set of message parameters in a :c:struct:`bt_mesh_msg_ctx`, |
| and calling :c:func:`bt_mesh_model_send`. |
| * By setting up a :c:struct:`bt_mesh_model_pub` structure and calling |
| :c:func:`bt_mesh_model_publish`. |
| |
| When publishing messages with :c:func:`bt_mesh_model_publish`, the model |
| will use the publication parameters configured by the |
| :ref:`bluetooth_mesh_models_cfg_srv`. 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 |
| :c:member:`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 :c:member:`bt_mesh_model_pub.update` callback. The |
| :c:member:`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 :c:member:`bt_mesh_model_pub.retr_update` to 1, the model can |
| configure the :c:member:`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 :c:func:`bt_mesh_model_pub_is_retransmission` function can be |
| used to differentiate a first publication and a retransmission. |
| The :c:macro:`BT_MESH_PUB_MSG_TOTAL` and :c:macro:`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 :c:func:`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 |
| :kconfig:option:`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 |
| :c:func:`bt_mesh_model_data_store`. To be able to read out the data the |
| next time the device reboots, the model's |
| :c:member:`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 :ref:`settings_api` module documentation for |
| details. |
| |
| API reference |
| ************* |
| |
| .. doxygengroup:: bt_mesh_access |