doc: bluetooth: mesh: ug restructuring

- Reorganizing under overview section
- Splitting concepts/overview from how-to
- Adding/moving some info from library sections

Signed-off-by: Mia Koen <mia.koen@nordicsemi.no>

doc/_utils/redirects.py

@@ -303,12 +303,15 @@
     ("protocols/bt/ble/radio_notification_conn_cb", "libraries/bluetooth_services/radio_notification_conn_cb"),
     ("ug_bt_mesh", "protocols/bt/bt_mesh/index"), # Bluetooth Mesh (landing)
     ("protocols/bt_mesh/index", "protocols/bt/bt_mesh/index"),
-    ("ug_bt_mesh_supported_features", "protocols/bt/bt_mesh/supported_features"), # Supported Bluetooth Mesh features
-    ("protocols/bt_mesh/supported_features", "protocols/bt/bt_mesh/supported_features"),
-    ("ug_bt_mesh_concepts", "protocols/bt/bt_mesh/concepts"), # Bluetooth Mesh concepts
-    ("protocols/bt_mesh/concepts", "protocols/bt/bt_mesh/concepts"),
-    ("ug_bt_mesh_architecture", "protocols/bt/bt_mesh/architecture"), # Bluetooth Mesh stack architecture
-    ("protocols/bt_mesh/architecture", "protocols/bt/bt_mesh/architecture"),
+    ("ug_bt_mesh_supported_features", "protocols/bt/bt_mesh/overview/index"), # Supported Bluetooth Mesh features (file removed; part of the overview index page now)
+    ("protocols/bt_mesh/supported_features", "protocols/bt/bt_mesh/overview/index"),
+    ("protocols/bt/bt_mesh/supported_features", "protocols/bt/bt_mesh/overview/index"),
+    ("ug_bt_mesh_concepts", "protocols/bt/bt_mesh/overview/topology"), # Bluetooth Mesh concepts
+    ("protocols/bt_mesh/concepts", "protocols/bt/bt_mesh/overview/topology"),
+    ("protocols/bt/bt_mesh/concepts", "protocols/bt/bt_mesh/overview/topology"),
+    ("ug_bt_mesh_architecture", "protocols/bt/bt_mesh/overview/architecture"), # Bluetooth Mesh stack architecture
+    ("protocols/bt_mesh/architecture", "protocols/bt/bt_mesh/overview/architecture"),
+    ("protocols/bt/bt_mesh/architecture", "protocols/bt/bt_mesh/overview/architecture"),
     ("ug_bt_mesh_configuring", "protocols/bt/bt_mesh/configuring"), # Configuring Bluetooth Mesh in nRF Connect SDK
     ("protocols/bt_mesh/configuring", "protocols/bt/bt_mesh/configuring"),
     ("ug_bt_mesh_model_config_app", "protocols/bt/bt_mesh/model_config_app"), # Configuring mesh models using the nRF Mesh mobile app
@@ -319,12 +322,15 @@
     ("protocols/bt_mesh/node_removal", "protocols/bt/bt_mesh/node_removal"),
     ("ug_bt_mesh_vendor_model", "protocols/bt/bt_mesh/vendor_model/index"), # Creating a new model (landing)
     ("protocols/bt_mesh/vendor_model/index", "protocols/bt/bt_mesh/vendor_model/index"),
-    ("ug_bt_mesh_vendor_model_dev_overview", "protocols/bt/bt_mesh/vendor_model/index"), # Vendor model development overview
-    ("protocols/bt_mesh/vendor_model/dev_overview", "protocols/bt/bt_mesh/vendor_model/index"),
+    ("ug_bt_mesh_vendor_model_dev_overview", "protocols/bt/bt_mesh/vendor_model/dev_overview"), # Vendor model development overview
+    ("protocols/bt_mesh/vendor_model/dev_overview", "protocols/bt/bt_mesh/vendor_model/dev_overview"),
     ("ug_bt_mesh_vendor_model_chat_sample_walk_through", "protocols/bt/bt_mesh/vendor_model/chat_sample_walk_through"), # Chat sample walk-through
     ("protocols/bt_mesh/vendor_model/chat_sample_walk_through", "protocols/bt/bt_mesh/vendor_model/chat_sample_walk_through"),
-    ("ug_bt_mesh_reserved_ids", "protocols/bt/bt_mesh/reserved_ids"), # Reserved vendor model IDs and opcodes
-    ("protocols/bt_mesh/reserved_ids", "protocols/bt/bt_mesh/reserved_ids"),
+    ("ug_bt_mesh_reserved_ids", "protocols/bt/bt_mesh/overview/reserved_ids"), # Reserved vendor model IDs and opcodes
+    ("protocols/bt_mesh/reserved_ids", "protocols/bt/bt_mesh/overview/reserved_ids"),
+    ("protocols/bt/bt_mesh/reserved_ids", "protocols/bt/bt_mesh/overview/reserved_ids"),
+    ("ug_bt_mesh_nlc", "protocols/bt/bt_mesh/overview/nlc"), # Networked Lighting Control profiles
+    ("protocols/bt/bt_mesh/nlc", "protocols/bt/bt_mesh/overview/nlc"),
     ("ug_esb", "protocols/esb/index"), # Enhanced ShockBurst (ESB) (landing)
     ("ug_gz", "protocols/gazell/index"), # Gazell (landing)
     ("ug_gzll", "protocols/gazell/gzll"), # Gazell Link Layer

doc/nrf/libraries/bluetooth_services/mesh.rst

@@ -1,29 +1,26 @@
 .. _bt_mesh:
 
-Bluetooth Mesh profile
-######################
+Bluetooth Mesh libraries
+########################
 
-Bluetooth® Mesh is supported for development in |NCS|, through the Zephyr :ref:`zephyr:bluetooth_mesh` implementation.
-Nordic Semiconductor's implementation of the Bluetooth Mesh allows applications to use the features provided by the Bluetooth Mesh when running on supported Nordic devices.
+Bluetooth® Mesh is supported for development in the |NCS|, through the Zephyr :ref:`zephyr:bluetooth_mesh` implementation.
+Nordic Semiconductor's implementation of the Bluetooth Mesh protocol allows applications to use the features provided by the Bluetooth Mesh when running on supported Nordic devices.
 
-The `Bluetooth Mesh profile specification`_ is developed and published by the Bluetooth® Special Interest Group (SIG).
-It is a solution that allows one-to-one, one-to-many, and many-to-many communication, using the Bluetooth Low Energy protocol to exchange messages between the nodes in the network.
-The nodes can communicate with each other as long as they are in direct radio range of each other, or there are enough devices available that are capable of listening and forwarding these messages.
+The `Bluetooth Mesh protocol specification`_ is developed and published by the Bluetooth Special Interest Group (SIG).
 See the :ref:`Bluetooth Mesh user guide <ug_bt_mesh>` for an overview of the technology, like supported features, concepts and architecture.
 
 The end-user applications (such as Luminaire control) are defined with the help of client-server Bluetooth Mesh models defined in the `Bluetooth Mesh model specification`_.
-Bluetooth Mesh libraries contain modules, including the Bluetooth Mesh models, provided by Nordic Semiconductor to aid in the development of Bluetooth Mesh-based applications.
+The Bluetooth Mesh libraries contain modules, including the Bluetooth Mesh models, provided by Nordic Semiconductor to aid in the development of Bluetooth Mesh-based applications.
 They implement default behavior of a Bluetooth Mesh device, and are used in :ref:`bt_mesh_samples`.
 
-For information on how to use the supplied libraries for Bluetooth Mesh, see :ref:`ug_bt_mesh_configuring`.
+For information on how to configure and use the supplied libraries for Bluetooth Mesh, see :ref:`ug_bt_mesh_configuring`.
 
-Information about the changes and known issues for Bluetooth Mesh in each release can be found in |NCS|'s :ref:`release_notes` and on the :ref:`known_issues` page.
+Information about the changes and known issues for Bluetooth Mesh in each release can be found in the |NCS|'s :ref:`release_notes` and on the :ref:`known_issues` page.
 
 .. toctree::
    :maxdepth: 1
    :caption: Subpages:
 
-   mesh/model_types.rst
    mesh/models.rst
    mesh/properties.rst
    mesh/dk_prov.rst

doc/nrf/libraries/bluetooth_services/mesh/model_types.rst

@@ -1,83 +1,19 @@
+.. _bt_mesh_models_common_types:
 .. _bt_mesh_models_overview:
 
-Bluetooth Mesh models overview
-##############################
+Common model types
+##################
 
 .. contents::
    :local:
    :depth: 2
 
-A Bluetooth® Mesh model is a standardized component that defines a series of states and related behaviors.
-Models encapsulate a single feature of a mesh node, and expose this feature to the mesh network.
-Each mesh-based product implements several models.
-
-States, either simple or complex, are used to indicate the condition of a device, for example whether it is on or off.
-Some states are bound to other, which causes them to mutually update their values.
-
-.. _bt_mesh_models_categorization:
-
-Categorization
-**************
-
-Each model is classified into one of the following categories:
-
-* Server -- which contains states.
-* Client -- which reads and writes the Server's states.
-
-Moreover, some models also include a *Setup Server* model instance.
-The two server model instances share the states of the server model, but accept different messages.
-This allows for a fine-grained control of the access rights for the states, as the two model instances can be bound to different application keys.
-Typically, the Setup Server instance provides write access to configuration parameters, such as valid parameter ranges or default values.
-
-Both server and client models can be extended, but because client models do not have states, there is generally no reason to extend them.
-None of the specification client models extend other models.
-All server models store changes to their configuration persistently using the :ref:`zephyr:settings_api` subsystem.
-
-.. _bt_mesh_models_configuration:
-
-Configuration
-*************
-
-You can configure mesh models in |NCS| using Kconfig options.
-See :ref:`configure_application` for more information.
-
-The options related to each model configuration are listed in the respective documentation pages.
-
-.. _bt_mesh_models_transition:
-
-Transition
-**********
-
-States may support non-instantaneous changes.
-Such states make use of :c:struct:`bt_mesh_model_transition` to specify the time it should take a server to change a state to a new value.
-
-The transition to a new value can be postponed by the time defined in :c:member:`bt_mesh_model_transition.delay`, and the current value of a state remains unchanged until the transition starts.
-The delay should not be taken into account when calculating the remaining transition time.
-
-Server models are taking care of publishing of status messages, when receiving a state changing message, as well as sending a response back to a client, when an acknowledged message is received.
-If a state change is non-instantaneous, for example when :c:func:`bt_mesh_model_transition_time` returns a nonzero value, the application is responsible for publishing a new value of the state at the end of the transition.
-
-.. _bt_mesh_models_common_blocking_api_rule:
-
-Common rule for the model's blocking API
-****************************************
-
-Some client APIs can be called as blocking if the response buffer is set to non-NULL.
-Blocking calls must only be made from threads where they do not disrupt Zephyr’s system services.
-Thus, do not make blocking calls in interrupt handlers, such as button handlers, or kernel services, such as system work queue handlers.
-
-.. _bt_mesh_models_common_types:
-
-Common types for all models
-***************************
-
-All models in the Bluetooth Mesh model specification share some common types, which are collected in a single header file.
+All models in the Bluetooth® Mesh model specification share some common data types, which are collected in a single header file.
 These include transitions, common IDs and other types that are rarely actively used.
 
-Each model can also contain its own common types, listed in the respective documentation pages.
-For the types common to all models, see the following section.
+Each Bluetooth Mesh model can also contain its own common types, listed in the respective documentation pages.
 
-The following types are common for all models:
+The following section defines types that are common for all models.
 
 API documentation
 =================

doc/nrf/libraries/bluetooth_services/mesh/models.rst

@@ -3,15 +3,20 @@
 Bluetooth Mesh models
 #####################
 
-Nordic Semiconductor provides a variety of model implementations from the `Bluetooth Mesh model specification`_ and their API documentation, as well as vendor-specific models.
+Nordic Semiconductor provides a variety of Bluetooth® Mesh model implementations and their API documentation as defined by the `Bluetooth Mesh model specification`_, as well as vendor-specific models.
+In addition, Zephyr implements foundation models defined by the `Bluetooth Mesh protocol specification`_, Binary Large Object (BLOB) Transfer models and Device Firmware Update (DFU) models (see :ref:`zephyr:bluetooth_mesh_models`).
 
-For more information about these and other models, see also `Bluetooth Mesh model overview`_.
+Find more information about the models in the :ref:`model overview <ug_bt_mesh_overview_models>` section.
+Also of interest might be `Bluetooth Mesh model overview`_, a paper on the Bluetooth technology website giving a technical overview of the Bluetooth Mesh models.
+
+Below is an overview of all model implementations available in the |NCS|.
 
 .. toctree::
    :maxdepth: 1
    :caption: Subpages:
    :glob:
 
+   model_types.rst
    gen_onoff.rst
    gen_lvl.rst
    gen_dtt.rst

doc/nrf/links.txt

@@ -959,7 +959,8 @@
 .. _`PRD and DPD`: https://www.bluetooth.com/download/prd_dpd_resolutions/
 .. _`Create a subset of a design`: https://qualification.support.bluetooth.com/hc/en-us/articles/27694580618637-Create-a-Subset-of-a-Design
 
-.. _`Bluetooth Mesh model specification`:
+.. _`Bluetooth Mesh model specification`: https://www.bluetooth.com/specifications/specs/mesh-model-1-1/
+.. _`Bluetooth Mesh protocol specification`: https://www.bluetooth.com/specifications/specs/mesh-protocol/
 .. _`Bluetooth Mesh profile specification`: https://www.bluetooth.com/specifications/specs/
 .. _`Bluetooth NLC profile specifications`: https://www.bluetooth.com/specifications/specs/