doc: bluetooth: mesh: Improve CDP128+ docs #64325
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
3 times, most recently
from
a56c099
to
47e1a66
Compare
omkar3141
reviewed
Oct 26, 2023
omkar3141
reviewed
Oct 26, 2023
omkar3141
reviewed
Oct 26, 2023
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
from
47e1a66
to
5f7a0a1
Compare
zephyrbot
requested review from
asbjornsabo,
hermabe,
jhedberg,
sjanc,
Thalley and
Vudentz
mia-ko
suggested changes
Oct 31, 2023
Comment on lines
217
to
223
| Composition Data Page 128, 129 and 130 | ||
| -------------------------------------- | ||
|
|
||
| These pages mirror Composition Data Page 0, 1 and 2, and 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. |
There was a problem hiding this comment.
Suggested change
| Composition Data Page 128, 129 and 130 | |
| -------------------------------------- | |
| These pages mirror Composition Data Page 0, 1 and 2, and 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. | |
| 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 changes after a firmware update. See :ref:`bluetooth_mesh_dfu_srv_comp_data_and_models_metadata` for details. |
There was a problem hiding this comment.
No, not "changes". When it changes, they are back to being the same data. They represent the incoming data after the new firmware is on the device but the device is still running with the old composition data (until reprovisioned). Meaning when the data "will change" (but is not changing yet and has not changed yet)
Comment on lines
214
to
215
| :c:enum:`BT_MESH_DFU_EFFECT_COMP_CHANGE`, the application must call | ||
| :c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` to |
There was a problem hiding this comment.
Suggested change
| :c:enum:`BT_MESH_DFU_EFFECT_COMP_CHANGE`, the application must call | |
| :c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` to | |
| :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 |
| 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 | ||
| :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 |
There was a problem hiding this comment.
Suggested change
| prepare the composition data page and models metadata page contents before applying the new | |
| prepare the Composition Data Page and Models Metadata Page contents before applying the new |
|
|
||
| .. _bluetooth_mesh_dfu_srv_comp_data_and_models_metadata: | ||
|
|
||
| Composition Data and Models Metadata |
There was a problem hiding this comment.
We have instances of composition data and Composition Data. I checked the spec and it seems like Composition Data (capitalized) is the one they go for. Maybe we should too then?
The more thorough round could be done in another task, maybe along with Bluetooth Mesh change.
| unprovisioned, this should be communicated through the effect parameter of the metadata check. | ||
|
|
||
| When the transfer will cause the composition data to change and | ||
| :ref:`bluetooth_mesh_models_rpr_srv` is supported, the composition data of the new firmware image | ||
| will be represented by Composition Data Page 128, 129 and 130, and the models metadata of the new |
There was a problem hiding this comment.
Is models metadata also supposed to be capitalized? In the spec, I only found instances with state attached to it (i.e. Models Metadata state), but assuming you would still keep it capitalized even if referring to it without mentioning state every time.
Comment on lines
60
to
73
| When the transfer will cause the composition data to change and | ||
| :ref:`bluetooth_mesh_models_rpr_srv` is supported, the composition data of the new firmware image | ||
| will be represented by Composition Data Page 128, 129 and 130, and the models metadata of the new | ||
| firmware image will be represented by Models Metadata Page 128. Composition Data Page 0, 1 and 2, | ||
| and Models Metadata Page 0 will represent the composition data and models metadata of the old | ||
| firmware image, until the device is reprovisioned using the Node Provisioning Protocol Interface | ||
| Procedures using the :ref:`bluetooth_mesh_models_rpr_cli`. The application must call | ||
| :c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` in | ||
| order 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 Page 0, 1 and 2, while the composition data in the new firmware | ||
| will be loaded into Composition Data Page 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. |
There was a problem hiding this comment.
Suggested change
| When the transfer will cause the composition data to change and | |
| :ref:`bluetooth_mesh_models_rpr_srv` is supported, the composition data of the new firmware image | |
| will be represented by Composition Data Page 128, 129 and 130, and the models metadata of the new | |
| firmware image will be represented by Models Metadata Page 128. Composition Data Page 0, 1 and 2, | |
| and Models Metadata Page 0 will represent the composition data and models metadata of the old | |
| firmware image, until the device is reprovisioned using the Node Provisioning Protocol Interface | |
| Procedures using the :ref:`bluetooth_mesh_models_rpr_cli`. The application must call | |
| :c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` in | |
| order 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 Page 0, 1 and 2, while the composition data in the new firmware | |
| will be loaded into Composition Data Page 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. | |
| 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. |
Comment on lines
75
to
78
| Limitation: | ||
|
|
||
| * It is currently not possible to change the composition data of the device and keep the device | ||
| provisioned and working with the old firmware after the firmware image is applied. |
There was a problem hiding this comment.
Suggested change
| Limitation: | |
| * It is currently not possible to change the composition data of the device and keep the device | |
| provisioned and working with the old firmware after the firmware image is applied. | |
| 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. |
Andrewpini
previously approved these changes
Nov 1, 2023
There was a problem hiding this comment.
Looks good to me. Assuming that you will fix @mia-ko comments, I'm approving this PR 👍
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
from
5f7a0a1
to
a43d7f6
Compare
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
from
a43d7f6
to
1ca03c1
Compare
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
from
1ca03c1
to
05d6be7
Compare
Andrewpini
previously approved these changes
Nov 1, 2023
mia-ko
suggested changes
Nov 1, 2023
| 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`. |
There was a problem hiding this comment.
Suggested change
| Procedures using the :ref:`bluetooth_mesh_models_rpr_cli`. | |
| procedures using the :ref:`bluetooth_mesh_models_rpr_cli`. |
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]>
ludvigsj
force-pushed
the
develop/mesh_improve_cdp_docs
branch
from
05d6be7
to
115ac5f
Compare
mia-ko
approved these changes
Nov 1, 2023
Andrewpini
approved these changes
Nov 1, 2023
alxelax
approved these changes
Nov 1, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.