Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: bluetooth: mesh: Improve CDP128+ docs #64325

Merged
merged 1 commit into from
Nov 2, 2023
Merged

doc: bluetooth: mesh: Improve CDP128+ docs #64325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 16 additions & 13 deletions doc/connectivity/bluetooth/api/mesh/access.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
*************
Expand Down
7 changes: 6 additions & 1 deletion doc/connectivity/bluetooth/api/mesh/dfu.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 29 additions & 1 deletion doc/connectivity/bluetooth/api/mesh/dfu_srv.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

------------------------------------

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.

alxelax marked this conversation as resolved.
Show resolved Hide resolved
Start
=====

Expand Down