From 115ac5f6e2a7dd53d1dac6bbeffb3c3780adac3d Mon Sep 17 00:00:00 2001 From: Ludvig Jordet Date: Tue, 24 Oct 2023 16:43:42 +0200 Subject: [PATCH] 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 --- .../bluetooth/api/mesh/access.rst | 29 ++++++++++-------- doc/connectivity/bluetooth/api/mesh/dfu.rst | 7 ++++- .../bluetooth/api/mesh/dfu_srv.rst | 30 ++++++++++++++++++- 3 files changed, 51 insertions(+), 15 deletions(-) diff --git a/doc/connectivity/bluetooth/api/mesh/access.rst b/doc/connectivity/bluetooth/api/mesh/access.rst index 151e74add28624..2af8e6a03b8a0d 100644 --- a/doc/connectivity/bluetooth/api/mesh/access.rst +++ b/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,11 +202,9 @@ 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 @@ -216,8 +212,15 @@ Bluetooth SIG defined profile. Currently supported profiles can be found in sect 3.12 in `Bluetooth SIG Assigned Numbers `_. 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 ************* diff --git a/doc/connectivity/bluetooth/api/mesh/dfu.rst b/doc/connectivity/bluetooth/api/mesh/dfu.rst index a929f8a53fc55e..46d3cfb6dc384f 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu.rst +++ b/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 diff --git a/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst b/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst index b78d4ce2c1d96a..2642dec8cc95bc 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst +++ b/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 =====