doc: bluetooth: mesh: Improve CDP128+ docs

Improves the documentation about how CDP 128, 129 and 130, as well as
Models Metadata Page 128 are created, as well as which functions the
application will have to call to store the correct contents in the
pages.

Signed-off-by: Ludvig Jordet <[email protected]>

doc/connectivity/bluetooth/api/mesh/access.rst

@@ -185,17 +185,15 @@ information about the device. In order to access this information, the user
 may use the :ref:`bluetooth_mesh_models_cfg_srv` model or, if supported,
 the :ref:`bluetooth_mesh_lcd_srv` model.
 
-Composition Data Page 0 and 128
--------------------------------
+Composition Data Page 0
+-----------------------
 
 Composition Data Page 0 provides the fundemental information about a device, and
 is mandatory for all mesh devices. It contains the element and model composition,
-the supported features, and manufacturer information. Composition Data Page 128
-mirrors Page 0 and is used to represent the new content of the Composition Data
-Page 0 after a device firmware update.
+the supported features, and manufacturer information.
 
-Composition Data Page 1 and 129
--------------------------------
+Composition Data Page 1
+-----------------------
 
 Composition Data Page 1 provides information about the relationships between models,
 and is mandatory for all mesh devices. A model may extend and/or correspond to one
@@ -204,20 +202,25 @@ or correspond to another model by calling :c:func:`bt_mesh_model_correspond`.
 :kconfig:option:`CONFIG_BT_MESH_MODEL_EXTENSION_LIST_SIZE` specifies how many model
 relations can be stored in the composition on a device, and this number should reflect the
 number of :c:func:`bt_mesh_model_extend` and :c:func:`bt_mesh_model_correspond` calls.
-Composition Data Page 129 mirrors Page 1 and is used to represent the new content of
-the Composition Data Page 1 after a device firmware update.
 
-Composition Data Page 2 and 130
--------------------------------
+Composition Data Page 2
+-----------------------
 
 Composition Data Page 2 provides information for supported mesh profiles. Mesh profile
 specifications define product requirements for devices that want to support a specific
 Bluetooth SIG defined profile. Currently supported profiles can be found in section
 3.12 in `Bluetooth SIG Assigned Numbers
 <https://www.bluetooth.com/specifications/assigned-numbers/uri-scheme-name-string-mapping/>`_.
 Composition Data Page 2 is only mandatory for devices that claim support for one or more
-mesh profile(s). Composition Data Page 130 mirrors Page 2 and is used to represent the
-new content of the Composition Data Page 2 after a device firmware update.
+mesh profile(s).
+
+Composition Data Pages 128, 129 and 130
+---------------------------------------
+
+Composition Data Pages 128, 129 and 130 mirror Composition Data Pages 0, 1 and 2 respectively.
+They are used to represent the new content of the mirrored pages when the Composition Data will
+change after a firmware update. See :ref:`bluetooth_mesh_dfu_srv_comp_data_and_models_metadata`
+for details.
 
 API reference
 *************

doc/connectivity/bluetooth/api/mesh/dfu.rst

@@ -210,7 +210,12 @@ re-provisioned. The complete list of available options is defined in :c:enum:`bt
 
 When the Target node receives the Firmware Update Firmware Metadata Check message, the Firmware
 Update Server model calls the :c:member:`bt_mesh_dfu_srv_cb.check` callback, the application can
-then process the metadata and provide the effect value.
+then process the metadata and provide the effect value. If the effect is
+:c:enum:`BT_MESH_DFU_EFFECT_COMP_CHANGE`, the application must call functions
+:c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` to
+prepare the Composition Data Page and Models Metadata Page contents before applying the new
+firmware image. See :ref:`bluetooth_mesh_dfu_srv_comp_data_and_models_metadata` for more
+information.
 
 
 DFU procedures

doc/connectivity/bluetooth/api/mesh/dfu_srv.rst

@@ -47,9 +47,37 @@ firmware image metadata. The Firmware Update Server performs the transfer check
 The result of the transfer check is a pass/fail status return and the expected
 :c:type:`bt_mesh_dfu_effect`. The DFU effect return parameter will be communicated back to the
 Distributor, and should indicate what effect the firmware update will have on the mesh state of the
-device. If the transfer will cause the device to change its Composition Data or become
+device.
+
+.. _bluetooth_mesh_dfu_srv_comp_data_and_models_metadata:
+
+Composition Data and Models Metadata
+------------------------------------
+
+If the transfer will cause the device to change its Composition Data or become
 unprovisioned, this should be communicated through the effect parameter of the metadata check.
 
+When the transfer will cause the Composition Data to change, and the
+:ref:`bluetooth_mesh_models_rpr_srv` is supported, the Composition Data of the new firmware image
+will be represented by Composition Data Pages 128, 129, and 130. The Models Metadata of the new
+firmware image will be represented by Models Metadata Page 128. Composition Data Pages 0, 1 and 2,
+and Models Metadata Page 0, will represent the Composition Data and the Models Metadata of the old
+firmware image until the device is reprovisioned with Node Provisioning Protocol Interface (NPPI)
+procedures using the :ref:`bluetooth_mesh_models_rpr_cli`.
+
+The application must call functions :c:func:`bt_mesh_comp_change_prepare` and
+:c:func:`bt_mesh_models_metadata_change_prepare` to store the existing Composition Data and Models
+Metadata pages before booting into the firmware with the updated Composition Data and Models
+Metadata. The old Composition Data will then be loaded into Composition Data Pages 0, 1 and 2,
+while the Composition Data in the new firmware will be loaded into Composition Data Pages 128, 129
+and 130. The Models Metadata for the old image will be loaded into Models Metadata Page 0, and the
+Models Metadata for the new image will be loaded into Models Metadata Page 128.
+
+Limitation:
+
+* It is not possible to change the Composition Data of the device and keep the device provisioned
+  and working with the old firmware after the new firmware image is applied.
+
 Start
 =====