Bluetooth: Mesh: Restructure doc

Adds a deeper hierarchy to the Bluetooth Mesh documentation by moving
the modules in separate pages with a brief description of the concepts
in each module.

Adds the full list of specification defined Health model faults.

Signed-off-by: Trond Einar Snekvik <[email protected]>

Author: trond-snekvik

doc/reference/bluetooth/mesh.rst

@@ -1,59 +1,21 @@
 .. _bluetooth_mesh:
 
-
-
 Bluetooth Mesh Profile
 ######################
 
+The Bluetooth Mesh Profile adds secure wireless multi-hop communication for
+Bluetooth Low Energy. This module implements the
+`Bluetooth Mesh Profile Specification v1.0.1 <https://www.bluetooth.com/specifications/mesh-specifications/>`_.
 
+Read more about Bluetooth Mesh on the
+`Bluetooth SIG Website <https://www.bluetooth.com/bluetooth-resources/?tags=mesh>`_.
 
-API Reference
-**************
-
-Mesh Profile
-============
-
-.. doxygengroup:: bt_mesh
-   :project: Zephyr
-
-Bluetooth Mesh Access Layer
-===========================
-
-.. doxygengroup:: bt_mesh_access
-   :project: Zephyr
-
-Bluetooth Mesh Configuration Client Model
-=========================================
-
-.. doxygengroup:: bt_mesh_cfg_cli
-   :project: Zephyr
-
-Bluetooth Mesh Configuration Server Model
-=========================================
-
-.. doxygengroup:: bt_mesh_cfg_srv
-   :project: Zephyr
-
-Bluetooth Mesh Health Client Model
-==================================
-
-.. doxygengroup:: bt_mesh_health_cli
-   :project: Zephyr
-
-Bluetooth Mesh Health Server Model
-==================================
-
-.. doxygengroup:: bt_mesh_health_srv
-   :project: Zephyr
-
-Bluetooth Mesh Provisioning
-===========================
-
-.. doxygengroup:: bt_mesh_prov
-   :project: Zephyr
+.. toctree::
+   :maxdepth: 1
 
-Bluetooth Mesh Proxy
-====================
+   mesh/core.rst
+   mesh/access.rst
+   mesh/models.rst
+   mesh/provisioning.rst
+   mesh/proxy.rst
 
-.. doxygengroup:: bt_mesh_proxy
-   :project: Zephyr

doc/reference/bluetooth/mesh/access.rst

@@ -0,0 +1,147 @@
+.. _bluetooth_mesh_access:
+
+Access
+######
+
+The Bluetooth Mesh access layer is the application's interface to the 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 :cpp: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 :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 :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 :cpp:type:`bt_mesh_msg_ctx`,
+  and calling :cpp:func:`bt_mesh_model_send()`.
+* By setting up a :cpp:type:`bt_mesh_model_pub` structure and calling
+  :cpp:func:`bt_mesh_model_publish()`.
+
+When publishing messages with :cpp: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
+:cpp:var:`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 :cpp:var:`bt_mesh_model_pub::update` callback. The
+:cpp:var:`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.
+
+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 :cpp: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
+: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
+:cpp:func:`bt_mesh_model_data_store()`. To be able to read out the data the
+next time the device reboots, the model's
+:cpp:var:`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` module documentation for
+details.
+
+API reference
+*************
+
+.. doxygengroup:: bt_mesh_access
+   :project: Zephyr
+   :members:

doc/reference/bluetooth/mesh/cfg_cli.rst

@@ -0,0 +1,28 @@
+.. _bluetooth_mesh_models_cfg_cli:
+
+Configuration Client
+####################
+
+Configuration Client model is a foundation model defined by the Bluetooth Mesh
+specification. It provides functionality for configuring most parameters of a
+mesh node, including encryption keys, model configuration and feature
+enabling.
+
+The Configuration Client model communicates with a
+:ref:`bluetooth_mesh_models_cfg_srv` model using the device key of the target
+node. The Configuration Client model may communicate with servers on other
+nodes or self-configure through the local Configuration Server model.
+
+All configuration functions in the Configuration Client API have ``net_idx``
+and ``addr`` as their first parameters. These should be set to the network
+index and primary unicast address that the target node was provisioned with.
+
+The Configuration Client model is optional, but should be instantiated on the
+first element if it is present in the composition data.
+
+API reference
+*************
+
+.. doxygengroup:: bt_mesh_cfg_cli
+   :project: Zephyr
+   :members:

doc/reference/bluetooth/mesh/cfg_srv.rst

@@ -0,0 +1,25 @@
+.. _bluetooth_mesh_models_cfg_srv:
+
+Configuration Server
+####################
+
+Configuration Server model is a foundation model defined by the Bluetooth Mesh
+specification. The Configuration Server model controls most parameters of the
+mesh node. It does not have an API of its own, but relies on a
+:ref:`bluetooth_mesh_models_cfg_cli` to control it.
+
+The application can configure the initial parameters of the Configuration
+Server model through the :cpp:type:`bt_mesh_cfg_srv` instance passed to
+:c:macro:`BT_MESH_MODEL_CFG_SRV`. Note that if the mesh node stored changes to
+this configuration in the settings subsystem, the initial values may be
+overwritten upon loading.
+
+The Configuration Server model is mandatory on all Bluetooth Mesh nodes, and
+should be instantiated in the first element.
+
+API reference
+*************
+
+.. doxygengroup:: bt_mesh_cfg_srv
+   :project: Zephyr
+   :members:

doc/reference/bluetooth/mesh/core.rst

@@ -0,0 +1,29 @@
+.. _bluetooth_mesh_core:
+
+Core API
+########
+
+The Bluetooth Mesh Core API provides functionality for managing the general
+Bluetooth Mesh state.
+
+Low Power Node
+**************
+
+The Low Power Node (LPN) role allows battery powered devices to participate in
+a mesh network as a leaf node. An LPN interacts with the mesh network through
+a Friend node, which is responsible for relaying any messages directed to the
+LPN. The LPN saves power by keeping its radio turned off, and only wakes up to
+either send messages or poll the Friend node for any incoming messages.
+
+The radio control and polling is managed automatically by the mesh stack, but
+the LPN API allows the application to trigger the polling at any time through
+:cpp:func:`bt_mesh_lpn_poll()`. The LPN operation parameters, including poll
+interval, poll event timing and Friend requirements is controlled through the
+:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.
+
+API reference
+**************
+
+.. doxygengroup:: bt_mesh
+   :project: Zephyr
+   :members:

doc/reference/bluetooth/mesh/health_cli.rst

@@ -0,0 +1,25 @@
+.. _bluetooth_mesh_models_health_cli:
+
+Health Client
+#############
+
+The Health Client model interacts with a Health Server model to read out
+diagnostics and control the node's attention state.
+
+All message passing functions in the Health Client API have ``net_idx`` and
+``addr`` as their first parameters. These should be set to the network index
+and primary unicast address that the target node was provisioned with.
+
+The Health Client model is optional, and may be instantiated in any element.
+However, if a Health Client model is instantiated in an element other than the
+first, an instance must also be present in the first element.
+
+See :ref:`bluetooth_mesh_health_faults` for a list of specification defined
+fault values.
+
+API reference
+*************
+
+.. doxygengroup:: bt_mesh_health_cli
+   :project: Zephyr
+   :members:

doc/reference/bluetooth/mesh/health_srv.rst

@@ -0,0 +1,65 @@
+.. _bluetooth_mesh_models_health_srv:
+
+Health Server
+#############
+
+The Health Server model provides attention callbacks and node diagnostics for
+:ref:`bluetooth_mesh_models_health_cli` models. It is primarily used to report
+faults in the mesh node and map the mesh nodes to their physical location.
+
+Faults
+******
+
+The Health Server model may report a list of faults that have occurred in the
+device's lifetime. Typically, the faults are events or conditions that may
+alter the behavior of the node, like power outages or faulty peripherals.
+Faults are split into warnings and errors. Warnings indicate conditions that
+are close to the limits of what the node is designed to withstand, but not
+necessarily damaging to the device. Errors indicate conditions that are
+outside of the node's design limits, and may have caused invalid behavior or
+permanent damage to the device.
+
+Fault values ``0x01`` to ``0x7f`` are reserved for the Bluetooth Mesh
+specification, and the full list of specification defined faults are available
+in :ref:`bluetooth_mesh_health_faults`. Fault values ``0x80`` to ``0xff`` are
+vendor specific. The list of faults are always reported with a company ID to
+help interpreting the vendor specific faults.
+
+.. _bluetooth_mesh_models_health_srv_attention:
+
+Attention state
+***************
+
+The attention state is used to make the device call attention to itself
+through some physical behavior like blinking, playing a sound or vibrating.
+The attention state may be used during provisioning to let the user know which
+device they're provisioning, as well as through the Health models at runtime.
+
+The attention state is always assigned a timeout in the range of one to 255
+seconds when enabled. The Health Server API provides two callbacks for the
+application to run their attention calling behavior:
+:cpp:var:`bt_mesh_health_srv_cb::attn_on` is called at the beginning of the
+attention period, :cpp:var:`bt_mesh_health_srv_cb::attn_off` is called at
+the end.
+
+The remaining time for the attention period may be queried through
+:cpp:var:`bt_mesh_health_srv::attn_timer`.
+
+API reference
+*************
+
+.. doxygengroup:: bt_mesh_health_srv
+   :project: Zephyr
+   :members:
+
+
+.. _bluetooth_mesh_health_faults:
+
+Bluetooth Mesh Health Faults
+============================
+
+Fault values defined by the Bluetooth Mesh specification.
+
+.. doxygengroup:: bt_mesh_health_faults
+   :project: Zephyr
+