1.. _bluetooth_mesh_dfu_srv:
2
3Firmware Update Server
4######################
5
6The Firmware Update Server model implements the Target node functionality of the
7:ref:`bluetooth_mesh_dfu` subsystem. It extends the :ref:`bluetooth_mesh_blob_srv`, which it uses to
8receive the firmware image binary from the Distributor node.
9
10Together with the extended BLOB Transfer Server model, the Firmware Update Server model implements
11all the required functionality for receiving firmware updates over the mesh network, but does not
12provide any functionality for storing, applying or verifying the images.
13
14Firmware images
15***************
16
17The Firmware Update Server holds a list of all the updatable firmware images on the device. The full
18list shall be passed to the server through the ``_imgs`` parameter in
19:c:macro:`BT_MESH_DFU_SRV_INIT`, and must be populated before the Bluetooth Mesh subsystem is
20started. Each firmware image in the image list must be independently updatable, and should have its
21own firmware ID.
22
23For instance, a device with an upgradable bootloader, an application and a peripheral chip with
24firmware update capabilities could have three entries in the firmware image list, each with their
25own separate firmware ID.
26
27Receiving transfers
28*******************
29
30The Firmware Update Server model uses a BLOB Transfer Server model on the same element to transfer
31the binary image. The interaction between the Firmware Update Server, BLOB Transfer Server and
32application is described below:
33
34.. figure:: images/dfu_srv.svg
35   :align: center
36   :alt: Bluetooth Mesh Firmware Update Server transfer
37
38   Bluetooth Mesh Firmware Update Server transfer
39
40Transfer check
41==============
42
43The transfer check is an optional pre-transfer check the application can perform on incoming
44firmware image metadata. The Firmware Update Server performs the transfer check by calling the
45:c:member:`check <bt_mesh_dfu_srv_cb.check>` callback.
46
47The result of the transfer check is a pass/fail status return and the expected
48:c:enum:`bt_mesh_dfu_effect`. The DFU effect return parameter will be communicated back to the
49Distributor, and should indicate what effect the firmware update will have on the mesh state of the
50device.
51
52.. _bluetooth_mesh_dfu_srv_comp_data_and_models_metadata:
53
54Composition Data and Models Metadata
55------------------------------------
56
57If the transfer will cause the device to change its Composition Data or become
58unprovisioned, this should be communicated through the effect parameter of the metadata check.
59
60When the transfer will cause the Composition Data to change, and the
61:ref:`bluetooth_mesh_models_rpr_srv` is supported, the Composition Data of the new firmware image
62will be represented by Composition Data Pages 128, 129, and 130. The Models Metadata of the new
63firmware image will be represented by Models Metadata Page 128. Composition Data Pages 0, 1 and 2,
64and Models Metadata Page 0, will represent the Composition Data and the Models Metadata of the old
65firmware image until the device is reprovisioned with Node Provisioning Protocol Interface (NPPI)
66procedures using the :ref:`bluetooth_mesh_models_rpr_cli`.
67
68The application must call functions :c:func:`bt_mesh_comp_change_prepare` and
69:c:func:`bt_mesh_models_metadata_change_prepare` to store the existing Composition Data and Models
70Metadata pages before booting into the firmware with the updated Composition Data and Models
71Metadata. The old Composition Data will then be loaded into Composition Data Pages 0, 1 and 2,
72while the Composition Data in the new firmware will be loaded into Composition Data Pages 128, 129
73and 130. The Models Metadata for the old image will be loaded into Models Metadata Page 0, and the
74Models Metadata for the new image will be loaded into Models Metadata Page 128.
75
76Limitation:
77
78* It is not possible to change the Composition Data of the device and keep the device provisioned
79  and working with the old firmware after the new firmware image is applied.
80
81Start
82=====
83
84The Start procedure prepares the application for the incoming transfer. It'll contain information
85about which image is being updated, as well as the update metadata.
86
87The Firmware Update Server :c:member:`start <bt_mesh_dfu_srv_cb.start>` callback must return a
88pointer to the BLOB Writer the BLOB Transfer Server will send the BLOB to.
89
90BLOB transfer
91=============
92
93After the setup stage, the Firmware Update Server prepares the BLOB Transfer Server for the incoming
94transfer. The entire firmware image is transferred to the BLOB Transfer Server, which passes the
95image to its assigned BLOB Writer.
96
97At the end of the BLOB transfer, the Firmware Update Server calls its
98:c:member:`end <bt_mesh_dfu_srv_cb.end>` callback.
99
100Image verification
101==================
102
103After the BLOB transfer has finished, the application should verify the image in any way it can to
104ensure that it is ready for being applied.  Once the image has been verified, the application calls
105:c:func:`bt_mesh_dfu_srv_verified`.
106
107If the image can't be verified, the application calls :c:func:`bt_mesh_dfu_srv_rejected`.
108
109Applying the image
110==================
111
112Finally, if the image was verified, the Distributor may instruct the Firmware Update Server to apply
113the transfer. This is communicated to the application through the :c:member:`apply
114<bt_mesh_dfu_srv_cb.apply>` callback. The application should swap the image and start running with
115the new firmware. The firmware image table should be updated to reflect the new firmware ID of the
116updated image.
117
118When the transfer applies to the mesh application itself, the device might have to reboot as part of
119the swap. This restart can be performed from inside the apply callback, or done asynchronously.
120After booting up with the new firmware, the firmware image table should be updated before the
121Bluetooth Mesh subsystem is started.
122
123The Distributor will read out the firmware image table to confirm that the transfer was successfully
124applied. If the metadata check indicated that the device would become unprovisioned, the Target node
125is not required to respond to this check.
126
127API reference
128*************
129
130.. doxygengroup:: bt_mesh_dfu_srv
131