Bluetooth Mesh BLOB Transfer Server Model#

Bluetooth Mesh BLOB Transfer Server Model.

The Bluetooth Mesh BLOB Transfer (MBT) Server model is used to receive binary large objects (BLOBs) over a Bluetooth Mesh network from a MBT Client.

There are two different modes in which the transfer may be performed: Push BLOB Transfer mode and Pull BLOB Transfer mode. The MBT Server may support both, or only one of these modes. The MBT Server API usage flow is identical in both transfer modes.

A Low Power Node (LPN) typically only supports the Pull BLOB Transfer mode, as that mode makes it possible for the MBT Server to throttle the transfer speed. This is necessary for ensuring that no more chunks than the Friend node can store in its Friend Queue are transmitted at once. While an LPN is receiving a transfer, the application needs to make sure that messages are polled from the Friend node at least every 30 seconds. If the LPN's Poll Timeout is larger than this, the application may call sl_btmesh_lpn_poll to satisfy this requirement.

The MBT Server model is normally used as a transport in a higher-layer model, e.g., the Firmware Update models. Please refer to the documentation of such a model for more information on how to interact with the MBT Server API in that context.

Modules#

sl_btmesh_evt_mbt_server_state_changed

sl_btmesh_evt_mbt_server_transfer_start_req

sl_btmesh_evt_mbt_server_block_start

sl_btmesh_evt_mbt_server_chunk

sl_btmesh_evt_mbt_server_block_complete

sl_btmesh_evt_mbt_server_transfer_cancel

sl_btmesh_evt_mbt_server_partial_block_report_tx_complete

Enumerations#

enum
sl_btmesh_mbt_server_status_t {
sl_btmesh_mbt_server_status_success = 0x0
sl_btmesh_mbt_server_status_invalid_block_number = 0x1
sl_btmesh_mbt_server_status_wrong_block_size = 0x2
sl_btmesh_mbt_server_status_wrong_chunk_size = 0x3
sl_btmesh_mbt_server_status_invalid_state = 0x4
sl_btmesh_mbt_server_status_invalid_parameter = 0x5
sl_btmesh_mbt_server_status_wrong_object_id = 0x6
sl_btmesh_mbt_server_status_storage_limit = 0x7
sl_btmesh_mbt_server_status_unsupported_transfer_mode = 0x8
sl_btmesh_mbt_server_status_internal_error = 0x9
sl_btmesh_mbt_server_status_information_unavailable = 0xa
sl_btmesh_mbt_server_status_malformed_message = 0xfe
sl_btmesh_mbt_server_status_timeout = 0xff
}

The MBT Status codes.

enum
sl_btmesh_mbt_server_phase_t {
sl_btmesh_mbt_server_phase_inactive = 0x0
sl_btmesh_mbt_server_phase_idle = 0x1
sl_btmesh_mbt_server_phase_waiting_for_block = 0x2
sl_btmesh_mbt_server_phase_waiting_for_chunks = 0x3
sl_btmesh_mbt_server_phase_complete = 0x4
sl_btmesh_mbt_server_phase_suspended = 0x5
}

The MBT Server Phase.

Functions#

sl_status_t
sl_btmesh_mbt_server_init(uint16_t elem_index, uint8_t min_block_size_log, uint8_t max_block_size_log, uint16_t max_chunks_per_block, uint16_t max_chunk_size, uint32_t max_blob_size, uint8_t supported_transfer_modes, uint16_t pull_mode_chunks_to_request, uint16_t pull_mode_retry_interval_ms, uint16_t pull_mode_retry_count)
sl_status_t
sl_btmesh_mbt_server_start(uint16_t elem_index, sl_bt_uuid_64_t blob_id, uint16_t timeout_10s, uint8_t ttl)
sl_status_t
sl_btmesh_mbt_server_get_transfer_status(uint16_t elem_index, uint8_t *state, sl_bt_uuid_64_t *blob_id, uint32_t *blob_size, uint16_t *block_number, size_t max_blocks_missing_mask_size, size_t *blocks_missing_mask_len, uint8_t *blocks_missing_mask)
sl_status_t
sl_btmesh_mbt_server_transfer_complete(uint16_t elem_index)
sl_status_t
sl_btmesh_mbt_server_abort(uint16_t elem_index)
sl_status_t
sl_btmesh_mbt_server_set_pull_mode_parameters(uint16_t elem_index, uint16_t pull_mode_retry_interval_ms, uint16_t pull_mode_retry_count)
sl_status_t
sl_btmesh_mbt_server_transfer_start_rsp(uint16_t elem_index, uint8_t status)

Macros#

Enumeration Documentation#

sl_btmesh_mbt_server_status_t#

sl_btmesh_mbt_server_status_t

The MBT Status codes.

Enumerator
sl_btmesh_mbt_server_status_success

(0x0) The Client message was successfully received by the Server.

sl_btmesh_mbt_server_status_invalid_block_number

(0x1) The Block number is higher than the total number of blocks indicates.

sl_btmesh_mbt_server_status_wrong_block_size

(0x2) The Block Size is outside of the boundaries specified by the Server's Min and Max Block Size Log capabilities.

sl_btmesh_mbt_server_status_wrong_chunk_size

(0x3) The Chunk Size is too large for the Server to accept, or so small that the Block's total chunks number would exceed the Server's Max Chunks capability.

sl_btmesh_mbt_server_status_invalid_state

(0x4) The Server is in a state where it cannot process the message.

sl_btmesh_mbt_server_status_invalid_parameter

(0x5) A parameter in the message is outside of its valid range.

sl_btmesh_mbt_server_status_wrong_object_id

(0x6) The Server is not expecting to receive this BLOB ID.

sl_btmesh_mbt_server_status_storage_limit

(0x7) Not enough space to store the BLOB.

sl_btmesh_mbt_server_status_unsupported_transfer_mode

(0x8) Transfer Mode not supported.

sl_btmesh_mbt_server_status_internal_error

(0x9) Internal error occurred.

sl_btmesh_mbt_server_status_information_unavailable

(0xa) The requested information is not available. A Block Get was sent, but no Block is active.

sl_btmesh_mbt_server_status_malformed_message

(0xfe) A malformed message was received.

sl_btmesh_mbt_server_status_timeout

(0xff) Timeout occurred.


Definition at line 11160 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_phase_t#

sl_btmesh_mbt_server_phase_t

The MBT Server Phase.

Enumerator
sl_btmesh_mbt_server_phase_inactive

(0x0) The Server has not been given a BLOB ID to expect.

sl_btmesh_mbt_server_phase_idle

(0x1) The Server has a BLOB ID to expect, but is not (yet) receiving the BLOB.

sl_btmesh_mbt_server_phase_waiting_for_block

(0x2) The Server is waiting for the next Block Start message.

sl_btmesh_mbt_server_phase_waiting_for_chunks

(0x3) The Server is waiting for Chunk messages.

sl_btmesh_mbt_server_phase_complete

(0x4) The Server has received the full BLOB.

sl_btmesh_mbt_server_phase_suspended

(0x5) The Server has timed out and gone to Suspended phase.


Definition at line 11261 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

Function Documentation#

sl_btmesh_mbt_server_init#

sl_status_t sl_btmesh_mbt_server_init (uint16_t elem_index, uint8_t min_block_size_log, uint8_t max_block_size_log, uint16_t max_chunks_per_block, uint16_t max_chunk_size, uint32_t max_blob_size, uint8_t supported_transfer_modes, uint16_t pull_mode_chunks_to_request, uint16_t pull_mode_retry_interval_ms, uint16_t pull_mode_retry_count)
Parameters
[in]elem_index

The server model element index.

[in]min_block_size_log

The minimum supported block size as an exponent n in 2^n. Range: 6 - 32.

[in]max_block_size_log

The maximum supported block size as an exponent n in 2^n. Must be less than or equal to max_chunks_per_block * max_chunk_size. Range: 6 - 32.

[in]max_chunks_per_block

The maximum number of chunks into which a block can be broken down.

[in]max_chunk_size

The maximum supported chunk size. Range: 8 - 241.

[in]max_blob_size

The maximum supported BLOB size.

[in]supported_transfer_modes

A bitfield of supported transfer modes. At least one must be supported.

  • Bit 0: Push BLOB Transfer mode

  • Bit 1: Pull BLOB Transfer mode

[in]pull_mode_chunks_to_request

In Pull BLOB Transfer mode, how many chunks to request at a time. Can be set to zero if this transfer mode is not supported.

[in]pull_mode_retry_interval_ms

In Pull BLOB Transfer mode, retry requesting chunks with this interval in milliseconds. Can be set to zero if this transfer mode is not supported.

[in]pull_mode_retry_count

In Pull BLOB Transfer mode, retry requesting chunks this many times before giving up. Note that if the timeout set by sl_btmesh_mbt_server_start occurs before the retry attempts are exhausted, no more retries will be attempted. Can be set to zero if this transfer mode is not supported.

Initialize the MBT Server.

Note that the configuration parameters min_block_size_log, max_chunks_per_block and max_blob_size have memory usage implications. The server needs to store 1 bit of information per chunk, so every additional 8 chunks supported add 1 byte of RAM usage. Each potential block needs 1 bit of information, so the server must allocate 1 byte of RAM for every 8 potential blocks. Supporting small blocks and large objects, or large blocks and small chunks, will use more memory. The values should be chosen to conservatively satisfy the use cases of the node if RAM usage is of concern.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11543 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_start#

sl_status_t sl_btmesh_mbt_server_start (uint16_t elem_index, sl_bt_uuid_64_t blob_id, uint16_t timeout_10s, uint8_t ttl)
Parameters
[in]elem_index

The server model element index.

[in]blob_id

The ID of the BLOB.

[in]timeout_10s

If no messages are received from the MBT Client within this time frame, the transfer will be suspended.

[in]ttl

The time-to-live value to use when communicating with the MBT Client. Valid values: 0, range:[2-127] and 255.

Start receiving a BLOB.

This is used to declare a BLOB to the MBT Server for receiving. The blob_id identifies the expected BLOB. The MBT Server will wait for the MBT Client to start the transfer, which is indicated by sl_btmesh_evt_mbt_server_transfer_start_req.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 11576 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_get_transfer_status#

sl_status_t sl_btmesh_mbt_server_get_transfer_status (uint16_t elem_index, uint8_t * state, sl_bt_uuid_64_t * blob_id, uint32_t * blob_size, uint16_t * block_number, size_t max_blocks_missing_mask_size, size_t * blocks_missing_mask_len, uint8_t * blocks_missing_mask)
Parameters
[in]elem_index

The server model element index.

[out]state

The current state

  • 0: Inactive, not expecting any transfer

  • 1: Waiting for the BLOB transfer to start

  • 2: Waiting for a new block to start

  • 3: Waiting for chunks of the current block

  • 4: The BLOB has been transferred successfully

  • 5: Timeout occurred and the transfer is suspended

[out]blob_id

The ID of the BLOB.

[out]blob_size

The size of the BLOB.

[out]block_number

The index number of the current block.

[in]max_blocks_missing_mask_size

Size of output buffer passed in blocks_missing_mask

[out]blocks_missing_mask_len

On return, set to the length of output data written to blocks_missing_mask

[out]blocks_missing_mask

A bitfield indicating missing blocks. The least significant bit of the first byte in the array belongs to block zero.

Get the status of the transfer.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11606 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_transfer_complete#

sl_status_t sl_btmesh_mbt_server_transfer_complete (uint16_t elem_index)
Parameters
[in]elem_index

The server model element index.

To be called when the transfer is completed. This is only needed when implementing your vendor model that uses MBT Server. The DFU models use this API internally.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11626 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_abort#

sl_status_t sl_btmesh_mbt_server_abort (uint16_t elem_index)
Parameters
[in]elem_index

The server model element index.

Abort the ongoing transfer, if any.

Abort a transfer and clear the Server's state. Note that this function does not inform the Client that the Server has aborted the transfer.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11640 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_set_pull_mode_parameters#

sl_status_t sl_btmesh_mbt_server_set_pull_mode_parameters (uint16_t elem_index, uint16_t pull_mode_retry_interval_ms, uint16_t pull_mode_retry_count)
Parameters
[in]elem_index

The server model element index.

[in]pull_mode_retry_interval_ms

The retry interval in milliseconds (ms).

[in]pull_mode_retry_count

The retry count.

Set the retry interval and the retry count parameters in the Pull BLOB Transfer Mode. The new values will take effect at the next transfer start. The command does not modify parameters of the ongoing transfer.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11656 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_mbt_server_transfer_start_rsp#

sl_status_t sl_btmesh_mbt_server_transfer_start_rsp (uint16_t elem_index, uint8_t status)
Parameters
[in]elem_index

The server model element index.

[in]status

mesh_mbt_status_success to accept, mesh_mbt_status_internal_error and mesh_mbt_status_storage_limit to reject.

Response to the sl_btmesh_evt_mbt_server_transfer_start_req event.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11671 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

Macro Definition Documentation#

sl_btmesh_cmd_mbt_server_init_id#

#define sl_btmesh_cmd_mbt_server_init_id
Value:
0x02290028

Definition at line 11142 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_start_id#

#define sl_btmesh_cmd_mbt_server_start_id
Value:
0x00290028

Definition at line 11143 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_get_transfer_status_id#

#define sl_btmesh_cmd_mbt_server_get_transfer_status_id
Value:
0x01290028

Definition at line 11144 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_transfer_complete_id#

#define sl_btmesh_cmd_mbt_server_transfer_complete_id
Value:
0x03290028

Definition at line 11145 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_abort_id#

#define sl_btmesh_cmd_mbt_server_abort_id
Value:
0x04290028

Definition at line 11146 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_set_pull_mode_parameters_id#

#define sl_btmesh_cmd_mbt_server_set_pull_mode_parameters_id
Value:
0x05290028

Definition at line 11147 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_mbt_server_transfer_start_rsp_id#

#define sl_btmesh_cmd_mbt_server_transfer_start_rsp_id
Value:
0x06290028

Definition at line 11148 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_init_id#

#define sl_btmesh_rsp_mbt_server_init_id
Value:
0x02290028

Definition at line 11149 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_start_id#

#define sl_btmesh_rsp_mbt_server_start_id
Value:
0x00290028

Definition at line 11150 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_get_transfer_status_id#

#define sl_btmesh_rsp_mbt_server_get_transfer_status_id
Value:
0x01290028

Definition at line 11151 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_transfer_complete_id#

#define sl_btmesh_rsp_mbt_server_transfer_complete_id
Value:
0x03290028

Definition at line 11152 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_abort_id#

#define sl_btmesh_rsp_mbt_server_abort_id
Value:
0x04290028

Definition at line 11153 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_set_pull_mode_parameters_id#

#define sl_btmesh_rsp_mbt_server_set_pull_mode_parameters_id
Value:
0x05290028

Definition at line 11154 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_mbt_server_transfer_start_rsp_id#

#define sl_btmesh_rsp_mbt_server_transfer_start_rsp_id
Value:
0x06290028

Definition at line 11155 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h