| .. _bluetooth_mesh_blob_cli: |
| |
| BLOB Transfer Client |
| #################### |
| |
| The Binary Large Object (BLOB) Transfer Client is the sender of the BLOB transfer. It supports |
| sending BLOBs of any size to any number of Target nodes, in both Push BLOB Transfer Mode and Pull |
| BLOB Transfer Mode. |
| |
| Usage |
| ***** |
| |
| Initialization |
| ============== |
| |
| The BLOB Transfer Client is instantiated on an element with a set of event handler callbacks: |
| |
| .. code-block:: C |
| |
| static const struct bt_mesh_blob_cli_cb blob_cb = { |
| /* Callbacks */ |
| }; |
| |
| static struct bt_mesh_blob_cli blob_cli = { |
| .cb = &blob_cb, |
| }; |
| |
| static struct bt_mesh_model models[] = { |
| BT_MESH_MODEL_BLOB_CLI(&blob_cli), |
| }; |
| |
| Transfer context |
| ================ |
| |
| Both the transfer capabilities retrieval procedure and the BLOB transfer uses an instance of a |
| :c:type:`bt_mesh_blob_cli_inputs` to determine how to perform the transfer. The BLOB Transfer Client |
| Inputs structure must at least be initialized with a list of targets, an application key and a time |
| to live (TTL) value before it is used in a procedure: |
| |
| .. code-block:: c |
| |
| static struct bt_mesh_blob_target targets[3] = { |
| { .addr = 0x0001 }, |
| { .addr = 0x0002 }, |
| { .addr = 0x0003 }, |
| }; |
| static struct bt_mesh_blob_cli_inputs inputs = { |
| .app_idx = MY_APP_IDX, |
| .ttl = BT_MESH_TTL_DEFAULT, |
| }; |
| |
| sys_slist_init(&inputs.targets); |
| sys_slist_append(&inputs.targets, &targets[0].n); |
| sys_slist_append(&inputs.targets, &targets[1].n); |
| sys_slist_append(&inputs.targets, &targets[2].n); |
| |
| Note that all BLOB Transfer Servers in the transfer must be bound to the chosen application key. |
| |
| |
| Group address |
| ------------- |
| |
| The application may additionally specify a group address in the context structure. If the group is |
| not :c:macro:`BT_MESH_ADDR_UNASSIGNED`, the messages in the transfer will be sent to the group |
| address, instead of being sent individually to each Target node. Mesh Manager must ensure that all |
| Target nodes having the BLOB Transfer Server model subscribe to this group address. |
| |
| Using group addresses for transferring the BLOBs can generally increase the transfer speed, as the |
| BLOB Transfer Client sends each message to all Target nodes at the same time. However, sending |
| large, segmented messages to group addresses in Bluetooth mesh is generally less reliable than |
| sending them to unicast addresses, as there is no transport layer acknowledgment mechanism for |
| groups. This can lead to longer recovery periods at the end of each block, and increases the risk of |
| losing Target nodes. Using group addresses for BLOB transfers will generally only pay off if the |
| list of Target nodes is extensive, and the effectiveness of each addressing strategy will vary |
| heavily between different deployments and the size of the chunks. |
| |
| Transfer timeout |
| ---------------- |
| |
| If a Target node fails to respond to an acknowledged message within the BLOB Transfer Client's time |
| limit, the Target node is dropped from the transfer. The application can reduce the chances of this |
| by giving the BLOB Transfer Client extra time through the context structure. The extra time may be |
| set in 10-second increments, up to 182 hours, in addition to the base time of 20 seconds. The wait |
| time scales automatically with the transfer TTL. |
| |
| Note that the BLOB Transfer Client only moves forward with the transfer in following cases: |
| |
| * All Target nodes have responded. |
| * A node has been removed from the list of Target nodes. |
| * The BLOB Transfer Client times out. |
| |
| Increasing the wait time will increase this delay. |
| |
| BLOB transfer capabilities retrieval |
| ==================================== |
| |
| It is generally recommended to retrieve BLOB transfer capabilities before starting a transfer. The |
| procedure populates the transfer capabilities from all Target nodes with the most liberal set of |
| parameters that allows all Target nodes to participate in the transfer. Any Target nodes that fail |
| to respond, or respond with incompatible transfer parameters, will be dropped. |
| |
| Target nodes are prioritized according to their order in the list of Target nodes. If a Target node |
| is found to be incompatible with any of the previous Target nodes, for instance by reporting a |
| non-overlapping block size range, it will be dropped. Lost Target nodes will be reported through the |
| :c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback. |
| |
| The end of the procedure is signalled through the :c:member:`caps <bt_mesh_blob_cli_cb.caps>` |
| callback, and the resulting capabilities can be used to determine the block and chunk sizes required |
| for the BLOB transfer. |
| |
| BLOB transfer |
| ============= |
| |
| The BLOB transfer is started by calling :c:func:`bt_mesh_blob_cli_send` function, which (in addition |
| to the aforementioned transfer inputs) requires a set of transfer parameters and a BLOB stream |
| instance. The transfer parameters include the 64-bit BLOB ID, the BLOB size, the transfer mode, the |
| block size in logarithmic representation and the chunk size. The BLOB ID is application defined, but |
| must match the BLOB ID the BLOB Transfer Servers have been started with. |
| |
| The transfer runs until it either completes successfully for at least one Target node, or it is |
| cancelled. The end of the transfer is communicated to the application through the :c:member:`end |
| <bt_mesh_blob_cli_cb.end>` callback. Lost Target nodes will be reported through the |
| :c:member:`lost_target <bt_mesh_blob_cli_cb.lost_target>` callback. |
| |
| API reference |
| ************* |
| |
| .. doxygengroup:: bt_mesh_blob_cli |
| :project: Zephyr |
| :members: |