385f8e127d
Do not pass options to doxygengroup to rationalize usage and be less dependent on Breathe. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
98 lines
4.2 KiB
ReStructuredText
98 lines
4.2 KiB
ReStructuredText
.. _bluetooth_mesh_blob_srv:
|
|
|
|
BLOB Transfer Server
|
|
####################
|
|
|
|
The Binary Large Object (BLOB) Transfer Server model implements reliable receiving of large binary
|
|
objects. It serves as the backend of the :ref:`bluetooth_mesh_dfu_srv`, but can also be used for
|
|
receiving other binary images.
|
|
|
|
BLOBs
|
|
*****
|
|
|
|
As described in :ref:`bluetooth_mesh_blob`, the binary objects transferred by the BLOB Transfer
|
|
models are divided into blocks, which are divided into chunks. As the transfer is controlled by the
|
|
BLOB Transfer Client model, the BLOB Transfer Server must allow blocks to come in any order. The
|
|
chunks within a block may also come in any order, but all chunks in a block must be received before
|
|
the next block is started.
|
|
|
|
The BLOB Transfer Server keeps track of the received blocks and chunks, and will process each block
|
|
and chunk only once. The BLOB Transfer Server also ensures that any missing chunks are resent by the
|
|
BLOB Transfer Client.
|
|
|
|
Usage
|
|
*****
|
|
|
|
The BLOB Transfer Server is instantiated on an element with a set of event handler callbacks:
|
|
|
|
.. code-block:: C
|
|
|
|
static const struct bt_mesh_blob_srv_cb blob_cb = {
|
|
/* Callbacks */
|
|
};
|
|
|
|
static struct bt_mesh_blob_srv blob_srv = {
|
|
.cb = &blob_cb,
|
|
};
|
|
|
|
static const struct bt_mesh_model models[] = {
|
|
BT_MESH_MODEL_BLOB_SRV(&blob_srv),
|
|
};
|
|
|
|
A BLOB Transfer Server is capable of receiving a single BLOB transfer at a time. Before the BLOB
|
|
Transfer Server can receive a transfer, it must be prepared by the user. The transfer ID must be
|
|
passed to the BLOB Transfer Server through the :c:func:`bt_mesh_blob_srv_recv` function before the
|
|
transfer is started by the BLOB Transfer Client. The ID must be shared between the BLOB Transfer
|
|
Client and the BLOB Transfer Server through some higher level procedure, like a vendor specific
|
|
transfer management model.
|
|
|
|
Once the transfer has been set up on the BLOB Transfer Server, it's ready for receiving the BLOB.
|
|
The application is notified of the transfer progress through the event handler callbacks, and the
|
|
BLOB data is sent to the BLOB stream.
|
|
|
|
The interaction between the BLOB Transfer Server, BLOB stream and application is shown below:
|
|
|
|
.. figure:: images/blob_srv.svg
|
|
:align: center
|
|
:alt: BLOB Transfer Server model interaction
|
|
|
|
BLOB Transfer Server model interaction
|
|
|
|
Transfer suspension
|
|
*******************
|
|
|
|
The BLOB Transfer Server keeps a running timer during the transfer, that is reset on every received
|
|
message. If the BLOB Transfer Client does not send a message before the transfer timer expires, the
|
|
transfer is suspended by the BLOB Transfer Server.
|
|
|
|
The BLOB Transfer Server notifies the user of the suspension by calling the :c:member:`suspended
|
|
<bt_mesh_blob_srv_cb.suspended>` callback. If the BLOB Transfer Server is in the middle of receiving
|
|
a block, this block is discarded.
|
|
|
|
The BLOB Transfer Client may resume a suspended transfer by starting a new block transfer. The BLOB
|
|
Transfer Server notifies the user by calling the :c:member:`resume <bt_mesh_blob_srv_cb.resume>`
|
|
callback.
|
|
|
|
Transfer recovery
|
|
*****************
|
|
|
|
The state of the BLOB transfer is stored persistently. If a reboot occurs, the BLOB Transfer Server
|
|
will attempt to recover the transfer. When the Bluetooth Mesh subsystem is started (for instance by
|
|
calling :c:func:`bt_mesh_init`), the BLOB Transfer Server will check for aborted transfers, and call
|
|
the :c:member:`recover <bt_mesh_blob_srv_cb.recover>` callback if there is any. In the recover
|
|
callback, the user must provide a BLOB stream to use for the rest of the transfer. If the recover
|
|
callback doesn't return successfully or does not provide a BLOB stream, the transfer is abandoned.
|
|
If no recover callback is implemented, transfers are always abandoned after a reboot.
|
|
|
|
After a transfer is successfully recovered, the BLOB Transfer Server enters the suspended state. It
|
|
will stay suspended until the BLOB Transfer Client resumes the transfer, or the user cancels it.
|
|
|
|
.. note::
|
|
The BLOB Transfer Client sending the transfer must support transfer recovery for the transfer to
|
|
complete. If the BLOB Transfer Client has already given up the transfer, the BLOB Transfer Server
|
|
will stay suspended until the application calls :c:func:`bt_mesh_blob_srv_cancel`.
|
|
|
|
API reference
|
|
*************
|
|
|
|
.. doxygengroup:: bt_mesh_blob_srv
|