1.. _bluetooth_mesh_blob:
2
3BLOB Transfer models
4####################
5
6The Binary Large Object (BLOB) Transfer models implement the Bluetooth Mesh Binary Large Object
7Transfer Model specification version 1.0 and provide functionality for sending large binary objects
8from a single source to many Target nodes over the Bluetooth Mesh network. It is the underlying
9transport method for the :ref:`bluetooth_mesh_dfu`, but may be used for other object transfer
10purposes. The implementation is in experimental state.
11
12The BLOB Transfer models support transfers of continuous binary objects of up to 4 GB (2 \ :sup:`32`
13bytes). The BLOB transfer protocol has built-in recovery procedures for packet losses, and sets up
14checkpoints to ensure that all targets have received all the data before moving on. Data transfer
15order is not guaranteed.
16
17BLOB transfers are constrained by the transfer speed and reliability of the underlying mesh network.
18Under ideal conditions, the BLOBs can be transferred at a rate of up to 1 kbps, allowing a 100 kB
19BLOB to be transferred in 10-15 minutes. However, network conditions, transfer capabilities and
20other limiting factors can easily degrade the data rate by several orders of magnitude. Tuning the
21parameters of the transfer according to the application and network configuration, as well as
22scheduling it to periods with low network traffic, will offer significant improvements on the speed
23and reliability of the protocol. However, achieving transfer rates close to the ideal rate is
24unlikely in actual deployments.
25
26There are two BLOB Transfer models:
27
28.. toctree::
29   :maxdepth: 1
30
31   blob_srv
32   blob_cli
33
34The BLOB Transfer Client is instantiated on the sender node, and the BLOB Transfer Server is
35instantiated on the receiver nodes.
36
37Concepts
38********
39
40The BLOB transfer protocol introduces several new concepts to implement the BLOB transfer.
41
42
43BLOBs
44=====
45
46BLOBs are binary objects up to 4 GB in size, that can contain any data the application would like to
47transfer through the mesh network. The BLOBs are continuous data objects, divided into blocks and
48chunks to make the transfers reliable and easy to process. No limitations are put on the contents or
49structure of the BLOB, and applications are free to define any encoding or compression they'd like
50on the data itself.
51
52The BLOB transfer protocol does not provide any built-in integrity checks, encryption or
53authentication of the BLOB data. However, the underlying encryption of the Bluetooth Mesh protocol
54provides data integrity checks and protects the contents of the BLOB from third parties using
55network and application level encryption.
56
57Blocks
58------
59
60The binary objects are divided into blocks, typically from a few hundred to several thousand bytes
61in size. Each block is transmitted separately, and the BLOB Transfer Client ensures that all BLOB
62Transfer Servers have received the full block before moving on to the next. The block size is
63determined by the transfer's ``block_size_log`` parameter, and is the same for all blocks in the
64transfer except the last, which may be smaller. For a BLOB stored in flash memory, the block size is
65typically a multiple of the flash page size of the Target devices.
66
67Chunks
68------
69
70Each block is divided into chunks. A chunk is the smallest data unit in the BLOB transfer, and must
71fit inside a single Bluetooth Mesh access message excluding the opcode (379 bytes or less). The
72mechanism for transferring chunks depends on the transfer mode.
73
74When operating in Push BLOB Transfer Mode, the chunks are sent as unacknowledged packets from the
75BLOB Transfer Client to all targeted BLOB Transfer Servers. Once all chunks in a block have been
76sent, the BLOB Transfer Client asks each BLOB Transfer Server if they're missing any chunks, and
77resends them. This is repeated until all BLOB Transfer Servers have received all chunks, or the BLOB
78Transfer Client gives up.
79
80When operating in Pull BLOB Transfer Mode, the BLOB Transfer Server will request a small number of
81chunks from the BLOB Transfer Client at a time, and wait for the BLOB Transfer Client to send them
82before requesting more chunks. This repeats until all chunks have been transferred, or the BLOB
83Transfer Server gives up.
84
85Read more about the transfer modes in :ref:`bluetooth_mesh_blob_transfer_modes` section.
86
87.. _bluetooth_mesh_blob_stream:
88
89BLOB streams
90============
91
92In the BLOB Transfer models' APIs, the BLOB data handling is separated from the high-level transfer
93handling. This split allows reuse of different BLOB storage and transfer strategies for different
94applications. While the high level transfer is controlled directly by the application, the BLOB data
95itself is accessed through a *BLOB stream*.
96
97The BLOB stream is comparable to a standard library file stream. Through opening, closing, reading
98and writing, the BLOB Transfer model gets full access to the BLOB data, whether it's kept in flash,
99RAM, or on a peripheral. The BLOB stream is opened with an access mode (read or write) before it's
100used, and the BLOB Transfer models will move around inside the BLOB's data in blocks and chunks,
101using the BLOB stream as an interface.
102
103Interaction
104-----------
105
106Before the BLOB is read or written, the stream is opened by calling its
107:c:member:`open <bt_mesh_blob_io.open>` callback. When used with a BLOB Transfer Server, the BLOB
108stream is always opened in write mode, and when used with a BLOB Transfer Client, it's always opened
109in read mode.
110
111For each block in the BLOB, the BLOB Transfer model starts by calling
112:c:member:`block_start <bt_mesh_blob_io.block_start>`. Then, depending on the access mode, the BLOB
113stream's :c:member:`wr <bt_mesh_blob_io.wr>` or :c:member:`rd <bt_mesh_blob_io.rd>` callback is
114called repeatedly to move data to or from the BLOB. When the model is done processing the block, it
115calls :c:member:`block_end <bt_mesh_blob_io.block_end>`. When the transfer is complete, the BLOB
116stream is closed by calling :c:member:`close <bt_mesh_blob_io.close>`.
117
118Implementations
119---------------
120
121The application may implement their own BLOB stream, or use the implementations provided by Zephyr:
122
123.. toctree::
124   :maxdepth: 2
125
126   blob_flash
127
128
129Transfer capabilities
130=====================
131
132Each BLOB Transfer Server may have different transfer capabilities. The transfer capabilities of
133each device are controlled through the following configuration options:
134
135* :kconfig:option:`CONFIG_BT_MESH_BLOB_SIZE_MAX`
136* :kconfig:option:`CONFIG_BT_MESH_BLOB_BLOCK_SIZE_MIN`
137* :kconfig:option:`CONFIG_BT_MESH_BLOB_BLOCK_SIZE_MAX`
138* :kconfig:option:`CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX`
139
140The :kconfig:option:`CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX` option is also used by the BLOB Transfer
141Client and affects memory consumption by the BLOB Transfer Client model structure.
142
143To ensure that the transfer can be received by as many servers as possible, the BLOB Transfer Client
144can retrieve the capabilities of each BLOB Transfer Server before starting the transfer. The client
145will transfer the BLOB with the highest possible block and chunk size.
146
147.. _bluetooth_mesh_blob_transfer_modes:
148
149Transfer modes
150==============
151
152BLOBs can be transferred using two transfer modes, Push BLOB Transfer Mode and Pull BLOB Transfer
153Mode. In most cases, the transfer should be conducted in Push BLOB Transfer Mode.
154
155In Push BLOB Transfer Mode, the send rate is controlled by the BLOB Transfer Client, which will push
156all the chunks of each block without any high level flow control. Push BLOB Transfer Mode supports
157any number of Target nodes, and should be the default transfer mode.
158
159In Pull BLOB Transfer Mode, the BLOB Transfer Server will "pull" the chunks from the BLOB Transfer
160Client at its own rate. Pull BLOB Transfer Mode can be conducted with multiple Target nodes, and is
161intended for transferring BLOBs to Target nodes acting as :ref:`bluetooth_mesh_lpn`. When operating
162in Pull BLOB Transfer Mode, the BLOB Transfer Server will request chunks from the BLOB Transfer
163Client in small batches, and wait for them all to arrive before requesting more chunks. This process
164is repeated until the BLOB Transfer Server has received all chunks in a block. Then, the BLOB
165Transfer Client starts the next block, and the BLOB Transfer Server requests all chunks of that
166block.
167
168
169.. _bluetooth_mesh_blob_timeout:
170
171Transfer timeout
172================
173
174The timeout of the BLOB transfer is based on a Timeout Base value. Both client and server use the
175same Timeout Base value, but they calculate timeout differently.
176
177The BLOB Transfer Server uses the following formula to calculate the BLOB transfer timeout::
178
179  10 * (Timeout Base + 1) seconds
180
181
182For the BLOB Transfer Client, the following formula is used::
183
184  (10000 * (Timeout Base + 2)) + (100 * TTL) milliseconds
185
186where TTL is time to live value set in the transfer.
187
188API reference
189*************
190
191This section contains types and defines common to the BLOB Transfer models.
192
193.. doxygengroup:: bt_mesh_blob
194   :project: Zephyr
195   :members:
196