1.. _bluetooth_mesh_blob_srv:
2
3BLOB Transfer Server
4####################
5
6The Binary Large Object (BLOB) Transfer Server model implements reliable receiving of large binary
7objects. It serves as the backend of the :ref:`bluetooth_mesh_dfu_srv`, but can also be used for
8receiving other binary images.
9
10BLOBs
11*****
12
13As described in :ref:`bluetooth_mesh_blob`, the binary objects transferred by the BLOB Transfer
14models are divided into blocks, which are divided into chunks. As the transfer is controlled by the
15BLOB Transfer Client model, the BLOB Transfer Server must allow blocks to come in any order. The
16chunks within a block may also come in any order, but all chunks in a block must be received before
17the next block is started.
18
19The BLOB Transfer Server keeps track of the received blocks and chunks, and will process each block
20and chunk only once. The BLOB Transfer Server also ensures that any missing chunks are resent by the
21BLOB Transfer Client.
22
23Usage
24*****
25
26The BLOB Transfer Server is instantiated on an element with a set of event handler callbacks:
27
28.. code-block:: C
29
30   static const struct bt_mesh_blob_srv_cb blob_cb = {
31       /* Callbacks */
32   };
33
34   static struct bt_mesh_blob_srv blob_srv = {
35       .cb = &blob_cb,
36   };
37
38   static const struct bt_mesh_model models[] = {
39       BT_MESH_MODEL_BLOB_SRV(&blob_srv),
40   };
41
42A BLOB Transfer Server is capable of receiving a single BLOB transfer at a time. Before the BLOB
43Transfer Server can receive a transfer, it must be prepared by the user. The transfer ID must be
44passed to the BLOB Transfer Server through the :c:func:`bt_mesh_blob_srv_recv` function before the
45transfer is started by the BLOB Transfer Client. The ID must be shared between the BLOB Transfer
46Client and the BLOB Transfer Server through some higher level procedure, like a vendor specific
47transfer management model.
48
49Once the transfer has been set up on the BLOB Transfer Server, it's ready for receiving the BLOB.
50The application is notified of the transfer progress through the event handler callbacks, and the
51BLOB data is sent to the BLOB stream.
52
53The interaction between the BLOB Transfer Server, BLOB stream and application is shown below:
54
55.. figure:: images/blob_srv.svg
56   :align: center
57   :alt: BLOB Transfer Server model interaction
58
59   BLOB Transfer Server model interaction
60
61Transfer suspension
62*******************
63
64The BLOB Transfer Server keeps a running timer during the transfer, that is reset on every received
65message. If the BLOB Transfer Client does not send a message before the transfer timer expires, the
66transfer is suspended by the BLOB Transfer Server.
67
68The BLOB Transfer Server notifies the user of the suspension by calling the :c:member:`suspended
69<bt_mesh_blob_srv_cb.suspended>` callback. If the BLOB Transfer Server is in the middle of receiving
70a block, this block is discarded.
71
72The BLOB Transfer Client may resume a suspended transfer by starting a new block transfer. The BLOB
73Transfer Server notifies the user by calling the :c:member:`resume <bt_mesh_blob_srv_cb.resume>`
74callback.
75
76Transfer recovery
77*****************
78
79The state of the BLOB transfer is stored persistently. If a reboot occurs, the BLOB Transfer Server
80will attempt to recover the transfer. When the Bluetooth Mesh subsystem is started (for instance by
81calling :c:func:`bt_mesh_init`), the BLOB Transfer Server will check for aborted transfers, and call
82the :c:member:`recover <bt_mesh_blob_srv_cb.recover>` callback if there is any. In the recover
83callback, the user must provide a BLOB stream to use for the rest of the transfer. If the recover
84callback doesn't return successfully or does not provide a BLOB stream, the transfer is abandoned.
85If no recover callback is implemented, transfers are always abandoned after a reboot.
86
87After a transfer is successfully recovered, the BLOB Transfer Server enters the suspended state. It
88will stay suspended until the BLOB Transfer Client resumes the transfer, or the user cancels it.
89
90.. note::
91   The BLOB Transfer Client sending the transfer must support transfer recovery for the transfer to
92   complete. If the BLOB Transfer Client has already given up the transfer, the BLOB Transfer Server
93   will stay suspended until the application calls :c:func:`bt_mesh_blob_srv_cancel`.
94
95API reference
96*************
97
98.. doxygengroup:: bt_mesh_blob_srv
99   :project: Zephyr
100   :members:
101