1.. _bluetooth_mesh_dfu:
2
3Device Firmware Update (DFU)
4############################
5
6Bluetooth Mesh supports the distribution of firmware images across a mesh network. The Bluetooth
7mesh DFU subsystem implements the Bluetooth Mesh Device Firmware Update Model specification version
81.0.
9
10Bluetooth Mesh DFU implements a distribution mechanism for firmware images, and does not put any
11restrictions on the size, format or usage of the images. The primary design goal of the subsystem is
12to provide the qualifiable parts of the Bluetooth Mesh DFU specification, and leave the usage,
13firmware validation and deployment to the application.
14
15The DFU specification is implemented in the Zephyr Bluetooth Mesh DFU subsystem as three separate
16models:
17
18.. toctree::
19   :maxdepth: 1
20
21   dfu_srv
22   dfu_cli
23   dfd_srv
24
25Overview
26********
27
28DFU roles
29=========
30
31The Bluetooth Mesh DFU subsystem defines three different roles the mesh nodes have to assume in the
32distribution of firmware images:
33
34Target node
35   Target node is the receiver and user of the transferred firmware images. All its functionality is
36   implemented by the :ref:`bluetooth_mesh_dfu_srv` model. A transfer may be targeting any number of
37   Target nodes, and they will all be updated concurrently.
38
39Distributor
40   The Distributor role serves two purposes in the DFU process. First, it's acting as the Target
41   node in the Upload Firmware procedure, then it distributes the uploaded image to other Target
42   nodes as the Distributor. The Distributor does not select the parameters of the transfer, but
43   relies on an Initiator to give it a list of Target nodes and transfer parameters. The Distributor
44   functionality is implemented in two models, :ref:`bluetooth_mesh_dfd_srv` and
45   :ref:`bluetooth_mesh_dfu_cli`. The :ref:`bluetooth_mesh_dfd_srv` is responsible for communicating
46   with the Initiator, and the :ref:`bluetooth_mesh_dfu_cli` is responsible for distributing the
47   image to the Target nodes.
48
49Initiator
50   The Initiator role is typically implemented by the same device that implements the Bluetooth Mesh
51   :ref:`Provisioner <bluetooth_mesh_provisioning>` and :ref:`Configurator
52   <bluetooth_mesh_models_cfg_cli>` roles. The Initiator needs a full overview of the potential
53   Target nodes and their firmware, and will control (and initiate) all firmware updates. The
54   Initiator role is not implemented in the Zephyr Bluetooth Mesh DFU subsystem.
55
56.. figure:: images/dfu_roles_mesh.svg
57   :align: center
58   :alt: Graphic overview of the DFU roles mesh nodes can have during the process of image
59         distribution
60
61   DFU roles and the associated Bluetooth Mesh models
62
63Bluetooth Mesh applications may combine the DFU roles in any way they'd like, and even take on
64multiple instances of the same role by instantiating the models on separate elements. For instance,
65the Distributor and Initiator role can be combined by instantiating the
66:ref:`bluetooth_mesh_dfu_cli` on the Initiator node and calling its API directly.
67
68It's also possible to combine the Initiator and Distributor devices into a single device, and
69replace the Firmware Distribution Server model with a proprietary mechanism that will access the
70Firmware Update Client model directly, e.g. over a serial protocol.
71
72.. note::
73   All DFU models instantiate one or more :ref:`bluetooth_mesh_blob`, and may need to be spread over
74   multiple elements for certain role combinations.
75
76Stages
77======
78
79The Bluetooth Mesh DFU process is designed to act in three stages:
80
81Upload stage
82   First, the image is uploaded to a Distributor in a mesh network by an external entity, such as a
83   phone or gateway (the Initiator). During the Upload stage, the Initiator transfers the firmware
84   image and all its metadata to the Distributor node inside the mesh network. The Distributor
85   stores the firmware image and its metadata persistently, and awaits further instructions from the
86   Initiator. The time required to complete the upload process depends on the size of the image.
87   After the upload completes, the Initiator can disconnect from the network during the much more
88   time-consuming Distribution stage. Once the firmware has been uploaded to the Distributor, the
89   Initiator may trigger the Distribution stage at any time.
90
91Firmware Capability Check stage (optional)
92  Before starting the Distribution stage, the Initiator may optionally check if Target nodes can
93  accept the new firmware. Nodes that do not respond, or respond that they can't receive the new
94  firmware, are excluded from the firmware distribution process.
95
96Distribution stage
97   Before the firmware image can be distributed, the Initiator transfers the list of Target nodes
98   and their designated firmware image index to the Distributor. Next, it tells the Distributor to
99   start the firmware distributon process, which runs in the background while the Initiator and the
100   mesh network perform other duties. Once the firmware image has been transferred to the Target
101   nodes, the Distributor may ask them to apply the firmware image immediately and report back with
102   their status and new firmware IDs.
103
104Firmware images
105===============
106
107All updatable parts of a mesh node's firmware should be represented as a firmware image. Each Target
108node holds a list of firmware images, each of which should be independently updatable and
109identifiable.
110
111Firmware images are represented as a BLOB (the firmware itself) with the following additional
112information attached to it:
113
114Firmware ID
115   The firmware ID is used to identify a firmware image. The Initiator node may ask the Target nodes
116   for a list of its current firmware IDs to determine whether a newer version of the firmware is
117   available. The format of the firmware ID is vendor specific, but generally, it should include
118   enough information for an Initiator node with knowledge of the format to determine the type of
119   image as well as its version. The firmware ID is optional, and its max length is determined by
120   :kconfig:option:`CONFIG_BT_MESH_DFU_FWID_MAXLEN`.
121
122Firmware metadata
123   The firmware metadata is used by the Target node to determine whether it should accept an
124   incoming firmware update, and what the effect of the update would be. The metadata format is
125   vendor specific, and should contain all information the Target node needs to verify the image, as
126   well as any preparation the Target node has to make before the image is applied. Typical metadata
127   information can be image signatures, changes to the node's Composition Data and the format of the
128   BLOB. The Target node may perform a metadata check before accepting incoming transfers to
129   determine whether the transfer should be started. The firmware metadata can be discarded by the
130   Target node after the metadata check, as other nodes will never request the metadata from the
131   Target node. The firmware metadata is optional, and its maximum length is determined by
132   :kconfig:option:`CONFIG_BT_MESH_DFU_METADATA_MAXLEN`.
133
134   The Bluetooth Mesh DFU subsystem in Zephyr provides its own metadata format
135   (:c:struct:`bt_mesh_dfu_metadata`) together with a set of related functions that can be used by
136   an end product. The support for it is enabled using the
137   :kconfig:option:`CONFIG_BT_MESH_DFU_METADATA` option. The format of the metadata is presented in
138   the table below.
139
140+------------------------+--------------+----------------------------------------+
141| Field                  | Size (Bytes) | Description                            |
142+========================+==============+========================================+
143| New firmware version   | 8 B          | 1 B: Major version                     |
144|                        |              | 1 B: Minor version                     |
145|                        |              | 2 B: Revision                          |
146|                        |              | 4 B: Build number                      |
147+------------------------+--------------+----------------------------------------+
148| New firmware size      | 3 B          | Size in bytes for a new firmware       |
149+------------------------+--------------+----------------------------------------+
150| New firmware core type | 1 B          | Bit field:                             |
151|                        |              | Bit 0: Application core                |
152|                        |              | Bit 1: Network core                    |
153|                        |              | Bit 2: Applications specific BLOB.     |
154|                        |              | Other bits: RFU                        |
155+------------------------+--------------+----------------------------------------+
156| Hash of incoming       | 4 B          | Lower 4 octets of AES-CMAC             |
157| composition data       | (Optional)   | (app-specific-key, composition data).  |
158|                        |              | This field is present, if Bit 0 is set |
159|                        |              | in the New firmware core type field.   |
160+------------------------+--------------+----------------------------------------+
161| New number of elements | 2 B          | Number of elements on the node         |
162|                        | (Optional)   | after firmware is applied.             |
163|                        |              | This field is present, if Bit 0 is set |
164|                        |              | in the New firmware core type field.   |
165+------------------------+--------------+----------------------------------------+
166| Application-specific   | <variable>   | Application-specific data to allow     |
167| data for new firmware  | (Optional)   | application to execute some            |
168|                        |              | vendor-specific behaviors using        |
169|                        |              | this data before it can respond        |
170|                        |              | with a status message.                 |
171+------------------------+--------------+----------------------------------------+
172
173  .. note::
174
175      The AES-CMAC algorithm serves as a hashing function with a fixed key and is not used for
176      encryption in Bluetooth Mesh DFU metadata. The resulting hash is not secure since the key is
177      known.
178
179Firmware URI
180   The firmware URI gives the Initiator information about where firmware updates for the image can
181   be found. The URI points to an online resource the Initiator can interact with to get new
182   versions of the firmware. This allows Initiators to perform updates for any node in the mesh
183   network by interacting with the web server pointed to in the URI. The URI must point to a
184   resource using the ``http`` or ``https`` schemes, and the targeted web server must behave
185   according to the Firmware Check Over HTTPS procedure defined by the specification. The firmware
186   URI is optional, and its max length is determined by
187   :kconfig:option:`CONFIG_BT_MESH_DFU_URI_MAXLEN`.
188
189   .. note::
190
191      The out-of-band distribution mechanism is not supported.
192
193.. _bluetooth_mesh_dfu_firmware_effect:
194
195Firmware effect
196---------------
197
198A new image may have the Composition Data Page 0 different from the one allocated on a Target node.
199This may have an effect on the provisioning data of the node and how the Distributor finalizes the
200DFU. Depending on the availability of the Remote Provisioning Server model on the old and new image,
201the device may either boot up unprovisioned after applying the new firmware or require to be
202re-provisioned. The complete list of available options is defined in :c:enum:`bt_mesh_dfu_effect`:
203
204:c:enumerator:`BT_MESH_DFU_EFFECT_NONE`
205   The device stays provisioned after the new firmware is programmed. This effect is chosen if the
206   composition data of the new firmware doesn't change.
207:c:enumerator:`BT_MESH_DFU_EFFECT_COMP_CHANGE_NO_RPR`
208   This effect is chosen when the composition data changes and the device doesn't support the remote
209   provisioning. The new composition data takes place only after re-provisioning.
210:c:enumerator:`BT_MESH_DFU_EFFECT_COMP_CHANGE`
211   This effect is chosen when the composition data changes and the device supports the remote
212   provisioning. In this case, the device stays provisioned and the new composition data takes place
213   after re-provisioning using the Remote Provisioning models.
214:c:enumerator:`BT_MESH_DFU_EFFECT_UNPROV`
215  This effect is chosen if the composition data in the new firmware changes, the device doesn't
216  support the remote provisioning, and the new composition data takes effect after applying the
217  firmware.
218
219When the Target node receives the Firmware Update Firmware Metadata Check message, the Firmware
220Update Server model calls the :c:member:`bt_mesh_dfu_srv_cb.check` callback, the application can
221then process the metadata and provide the effect value. If the effect is
222:c:enumerator:`BT_MESH_DFU_EFFECT_COMP_CHANGE`, the application must call functions
223:c:func:`bt_mesh_comp_change_prepare` and :c:func:`bt_mesh_models_metadata_change_prepare` to
224prepare the Composition Data Page and Models Metadata Page contents before applying the new
225firmware image. See :ref:`bluetooth_mesh_dfu_srv_comp_data_and_models_metadata` for more
226information.
227
228
229DFU procedures
230**************
231
232The DFU protocol is implemented as a set of procedures that must be performed in a certain order.
233
234The Initiator controls the Upload stage of the DFU protocol, and all Distributor side handling of
235the upload subprocedures is implemented in the :ref:`bluetooth_mesh_dfd_srv`.
236
237The Distribution stage is controlled by the Distributor, as implemented by the
238:ref:`bluetooth_mesh_dfu_cli`. The Target node implements all handling of these procedures in the
239:ref:`bluetooth_mesh_dfu_srv`, and notifies the application through a set of callbacks.
240
241.. figure:: images/dfu_stages_procedures_mesh.svg
242   :align: center
243   :alt: Overview of DFU stages and procedures
244
245   DFU stages and procedures as seen from the Distributor
246
247Uploading the firmware
248======================
249
250The Upload Firmware procedure uses the :ref:`bluetooth_mesh_blob` to transfer the firmware image
251from the Initiator to the Distributor. The Upload Firmware procedure works in two steps:
252
2531. The Initiator generates a BLOB ID, and sends it to the Distributor's Firmware Distribution Server
254   along with the firmware information and other input parameters of the BLOB transfer. The Firmware
255   Distribution Server stores the information, and prepares its BLOB Transfer Server for the
256   incoming transfer before it responds with a status message to the Initiator.
257#. The Initiator's BLOB Transfer Client model transfers the firmware image to the Distributor's BLOB
258   Transfer Server, which stores the image in a predetermined flash partition.
259
260When the BLOB transfer finishes, the firmware image is ready for distribution. The Initiator may
261upload several firmware images to the Distributor, and ask it to distribute them in any order or at
262any time. Additional procedures are available for querying and deleting firmware images from the
263Distributor.
264
265The following Distributor's capabilities related to firmware images can be configured using the
266configuration options:
267
268* :kconfig:option:`CONFIG_BT_MESH_DFU_SLOT_CNT`: Amount of image slots available on the device.
269* :kconfig:option:`CONFIG_BT_MESH_DFD_SRV_SLOT_MAX_SIZE`: Maximum allowed size for each image.
270* :kconfig:option:`CONFIG_BT_MESH_DFD_SRV_SLOT_SPACE`: Available space for all images.
271
272Populating the Distributor's receivers list
273===========================================
274
275Before the Distributor can start distributing the firmware image, it needs a list of Target nodes to
276send the image to. The Initiator gets the full list of Target nodes either by querying the potential
277targets directly, or through some external authority. The Initiator uses this information to
278populate the Distributor's receivers list with the address and relevant firmware image index of each
279Target node. The Initiator may send one or more Firmware Distribution Receivers Add messages to
280build the Distributor's receivers list, and a Firmware Distribution Receivers Delete All message to
281clear it.
282
283The maximum number of receivers that can be added to the Distributor is configured through the
284:kconfig:option:`CONFIG_BT_MESH_DFD_SRV_TARGETS_MAX` configuration option.
285
286Initiating the distribution
287===========================
288
289Once the Distributor has stored a firmware image and received a list of Target nodes, the Initiator
290may initiate the distribution procedure. The BLOB transfer parameters for the distribution are
291passed to the Distributor along with an update policy. The update policy decides whether the
292Distributor should request that the firmware is applied on the Target nodes or not. The Distributor
293stores the transfer parameters and starts distributing the firmware image to its list of Target
294nodes.
295
296Firmware distribution
297---------------------
298
299The Distributor's Firmware Update Client model uses its BLOB Transfer Client model's broadcast
300subsystem to communicate with all Target nodes. The firmware distribution is performed with the
301following steps:
302
3031. The Distributor's Firmware Update Client model generates a BLOB ID and sends it to each Target
304   node's Firmware Update Server model, along with the other BLOB transfer parameters, the Target
305   node firmware image index and the firmware image metadata. Each Target node performs a metadata
306   check and prepares their BLOB Transfer Server model for the transfer, before sending a status
307   response to the Firmware Update Client, indicating if the firmware update will have any effect on
308   the Bluetooth Mesh state of the node.
309#. The Distributor's BLOB Transfer Client model transfers the firmware image to all Target nodes.
310#. Once the BLOB transfer has been received, the Target nodes' applications verify that the firmware
311   is valid by performing checks such as signature verification or image checksums against the image
312   metadata.
313#. The Distributor's Firmware Update Client model queries all Target nodes to ensure that they've
314   all verified the firmware image.
315
316If the distribution procedure completed with at least one Target node reporting that the image has
317been received and verified, the distribution procedure is considered successful.
318
319.. note::
320   The firmware distribution procedure only fails if *all* Target nodes are lost. It is up to the
321   Initiator to request a list of failed Target nodes from the Distributor and initiate additional
322   attempts to update the lost Target nodes after the current attempt is finished.
323
324Suspending the distribution
325---------------------------
326
327The Initiator can also request the Distributor to suspend the firmware distribution. In this case,
328the Distributor will stop sending any messages to Target nodes. When the firmware distribution is
329resumed, the Distributor will continue sending the firmware from the last successfully transferred
330block.
331
332Applying the firmware image
333===========================
334
335If the Initiator requested it, the Distributor can initiate the Apply Firmware on Target Node
336procedure on all Target nodes that successfully received and verified the firmware image. The Apply
337Firmware on Target Node procedure takes no parameters, and to avoid ambiguity, it should be
338performed before a new transfer is initiated. The Apply Firmware on Target Node procedure consists
339of the following steps:
340
3411. The Distributor's Firmware Update Client model instructs all Target nodes that have verified the
342   firmware image to apply it. The Target nodes' Firmware Update Server models respond with a status
343   message before calling their application's ``apply`` callback.
344#. The Target node's application performs any preparations needed before applying the transfer, such
345   as storing a snapshot of the Composition Data or clearing its configuration.
346#. The Target node's application swaps the current firmware with the new image and updates its
347   firmware image list with the new firmware ID.
348#. The Distributor's Firmware Update Client model requests the full list of firmware images from
349   each Target node, and scans through the list to make sure that the new firmware ID has replaced
350   the old.
351
352.. note::
353   During the metadata check in the distribution procedure, the Target node may have reported that
354   it will become unprovisioned after the firmware image is applied. In this case, the Distributor's
355   Firmware Update Client model will send a request for the full firmware image list, and expect no
356   response.
357
358Cancelling the distribution
359===========================
360
361The firmware distribution can be cancelled at any time by the Initiator. In this case, the
362Distributor starts the cancelling procedure by sending a cancelling message to all Target nodes. The
363Distributor waits for the response from all Target nodes. Once all Target nodes have replied, or the
364request has timed out, the distribution procedure is cancelled. After this the distribution
365procedure can be started again from the ``Firmware distribution`` section.
366
367
368API reference
369*************
370
371This section lists the types common to the Device Firmware Update mesh models.
372
373.. doxygengroup:: bt_mesh_dfd
374
375.. doxygengroup:: bt_mesh_dfu
376
377.. doxygengroup:: bt_mesh_dfu_metadata
378