1.. _bluetooth_mesh_blob_cli:
2
3BLOB Transfer Client
4####################
5
6The Binary Large Object (BLOB) Transfer Client is the sender of the BLOB transfer. It supports
7sending BLOBs of any size to any number of Target nodes, in both Push BLOB Transfer Mode and Pull
8BLOB Transfer Mode.
9
10Usage
11*****
12
13Initialization
14==============
15
16The BLOB Transfer Client is instantiated on an element with a set of event handler callbacks:
17
18.. code-block:: C
19
20   static const struct bt_mesh_blob_cli_cb blob_cb = {
21         /* Callbacks */
22   };
23
24   static struct bt_mesh_blob_cli blob_cli = {
25         .cb = &blob_cb,
26   };
27
28   static const struct bt_mesh_model models[] = {
29         BT_MESH_MODEL_BLOB_CLI(&blob_cli),
30   };
31
32Transfer context
33================
34
35Both the transfer capabilities retrieval procedure and the BLOB transfer uses an instance of a
36:c:struct:`bt_mesh_blob_cli_inputs` to determine how to perform the transfer. The BLOB Transfer Client
37Inputs structure must at least be initialized with a list of targets, an application key and a time
38to live (TTL) value before it is used in a procedure:
39
40.. code-block:: c
41
42   static struct bt_mesh_blob_target targets[3] = {
43           { .addr = 0x0001 },
44           { .addr = 0x0002 },
45           { .addr = 0x0003 },
46   };
47   static struct bt_mesh_blob_cli_inputs inputs = {
48           .app_idx = MY_APP_IDX,
49           .ttl = BT_MESH_TTL_DEFAULT,
50   };
51
52   sys_slist_init(&inputs.targets);
53   sys_slist_append(&inputs.targets, &targets[0].n);
54   sys_slist_append(&inputs.targets, &targets[1].n);
55   sys_slist_append(&inputs.targets, &targets[2].n);
56
57Note that all BLOB Transfer Servers in the transfer must be bound to the chosen application key.
58
59
60Group address
61-------------
62
63The application may additionally specify a group address in the context structure. If the group is
64not :c:macro:`BT_MESH_ADDR_UNASSIGNED`, the messages in the transfer will be sent to the group
65address, instead of being sent individually to each Target node. Mesh Manager must ensure that all
66Target nodes having the BLOB Transfer Server model subscribe to this group address.
67
68Using group addresses for transferring the BLOBs can generally increase the transfer speed, as the
69BLOB Transfer Client sends each message to all Target nodes at the same time. However, sending
70large, segmented messages to group addresses in Bluetooth Mesh is generally less reliable than
71sending them to unicast addresses, as there is no transport layer acknowledgment mechanism for
72groups. This can lead to longer recovery periods at the end of each block, and increases the risk of
73losing Target nodes. Using group addresses for BLOB transfers will generally only pay off if the
74list of Target nodes is extensive, and the effectiveness of each addressing strategy will vary
75heavily between different deployments and the size of the chunks.
76
77Transfer timeout
78----------------
79
80If a Target node fails to respond to an acknowledged message within the BLOB Transfer Client's time
81limit, the Target node is dropped from the transfer. The application can reduce the chances of this
82by giving the BLOB Transfer Client extra time through the context structure. The extra time may be
83set in 10-second increments, up to 182 hours, in addition to the base time of 20 seconds. The wait
84time scales automatically with the transfer TTL.
85
86Note that the BLOB Transfer Client only moves forward with the transfer in following cases:
87
88* All Target nodes have responded.
89* A node has been removed from the list of Target nodes.
90* The BLOB Transfer Client times out.
91
92Increasing the wait time will increase this delay.
93
94BLOB transfer capabilities retrieval
95====================================
96
97It is generally recommended to retrieve BLOB transfer capabilities before starting a transfer. The
98procedure populates the transfer capabilities from all Target nodes with the most liberal set of
99parameters that allows all Target nodes to participate in the transfer. Any Target nodes that fail
100to respond, or respond with incompatible transfer parameters, will be dropped.
101
102Target nodes are prioritized according to their order in the list of Target nodes. If a Target node
103is found to be incompatible with any of the previous Target nodes, for instance by reporting a
104non-overlapping block size range, it will be dropped. Lost Target nodes will be reported through the
105:c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
106
107The end of the procedure is signalled through the :c:member:`caps <bt_mesh_blob_cli_cb.caps>`
108callback, and the resulting capabilities can be used to determine the block and chunk sizes required
109for the BLOB transfer.
110
111BLOB transfer
112=============
113
114The BLOB transfer is started by calling :c:func:`bt_mesh_blob_cli_send` function, which (in addition
115to the aforementioned transfer inputs) requires a set of transfer parameters and a BLOB stream
116instance. The transfer parameters include the 64-bit BLOB ID, the BLOB size, the transfer mode, the
117block size in logarithmic representation and the chunk size. The BLOB ID is application defined, but
118must match the BLOB ID the BLOB Transfer Servers have been started with.
119
120The transfer runs until it either completes successfully for at least one Target node, or it is
121cancelled. The end of the transfer is communicated to the application through the :c:member:`end
122<bt_mesh_blob_cli_cb.end>` callback. Lost Target nodes will be reported through the
123:c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback.
124
125API reference
126*************
127
128.. doxygengroup:: bt_mesh_blob_cli
129