BLOB Transfer Client#

Provides BT Mesh BLOB (binary large object) Transfer Client functionality, defined in mesh specification. The BLOB Transfer Client model is used by a higher-layer application to transfer a BLOB to one or more BLOB Transfer Servers. The higher-layer application provides the inputs to the procedures executed by the client. This component is prepared for integration into SOC applications.

Modules#

sl_btmesh_blob_transfer_client_progress_t

sl_btmesh_blob_transfer_client_server_failed_t

sl_btmesh_blob_transfer_client_notification_t

Typedefs#

typedef void(*

sl_btmesh_blob_transfer_client_notify_cb_t)(const sl_btmesh_blob_transfer_client_notification_t *const notification)

Callback function type for BLOB transfer client notifications.

Functions#

SL_ENUM(sl_btmesh_blob_transfer_client_notification_kind_t)

BLOB Transfer Client Kind.

SL_ENUM(sl_btmesh_blob_transfer_client_result_t)

BLOB Transfer Client Result.

sl_status_t

sl_btmesh_blob_transfer_client_setup(uint16_t elem_index, sl_bt_uuid_64_t blob_id, uint32_t blob_size, uint16_t appkey_index, uint8_t ttl, uint16_t timeout_base, uint16_t group_address, uuid_128 virtual_address, uint16_t multicast_threshold, size_t servers_len, const uint8_t *servers)

sl_status_t

sl_btmesh_blob_transfer_client_setup_data_provider_array(uint16_t elem_index, const uint8_t *array, uint32_t length)

sl_status_t

sl_btmesh_blob_transfer_client_setup_data_provider_blob_storage(uint16_t elem_index, const sl_bt_uuid_64_t *blob_id)

sl_status_t

sl_btmesh_blob_transfer_client_set_params(uint16_t elem_index, uint16_t separation_time_ms, uint16_t retry_time_local_ms, uint16_t retry_time_push_ms, uint16_t retry_time_pull_ms, uint16_t retry_max_local, uint16_t retry_threshold_remote)

sl_status_t

sl_btmesh_blob_transfer_client_start(uint16_t elem_index, sl_btmesh_mbt_client_transfer_mode_t transfer_mode, sl_btmesh_blob_transfer_client_notify_cb_t notify)

void

sl_btmesh_blob_transfer_client_cancel(uint16_t elem_index)

sl_status_t

sl_btmesh_blob_transfer_client_abort(uint16_t elem_index)

sl_status_t

sl_btmesh_blob_transfer_client_on_aborted(uint16_t elem_index)

sl_status_t

sl_btmesh_blob_transfer_client_on_suspended(uint16_t elem_index)

sl_status_t

sl_btmesh_blob_transfer_client_on_resumed(uint16_t elem_index)

void

sl_btmesh_blob_transfer_client_on_event(const sl_btmesh_msg_t *const evt)

uint8_t

sl_btmesh_blob_transfer_client_calculate_block_size_log(uint32_t blob_size, uint8_t block_size_log_min, uint8_t block_size_log_max, uint16_t block_count_max, uint16_t max_chunk_size_min, uint16_t max_chunks_min)

uint16_t

sl_btmesh_blob_transfer_client_calculate_chunk_size(uint8_t block_size_log, uint16_t max_chunk_size_min, uint16_t max_chunks_min, uint16_t nw_pdu_size)

const char *

sl_btmesh_blob_transfer_client_transfer_mode_to_string(sl_btmesh_mbt_client_transfer_mode_t transfer_mode)

const char *

sl_btmesh_blob_transfer_client_mbt_phase_to_string(sl_btmesh_mbt_server_phase_t mbt_phase)

const char *

sl_btmesh_blob_transfer_client_mbt_status_to_string(sl_btmesh_mbt_server_status_t mbt_status)

uint16_t

sl_btmesh_blob_transfer_client_get_max_servers(void)

Macros#

#define

SL_BTMESH_BLOB_TRANSFER_CLIENT_INVALID_BLOCK_SIZE_LOG 0xFF

Invalid value for the binary logarithm of the block size.

Typedef Documentation#

sl_btmesh_blob_transfer_client_notify_cb_t#

sl_btmesh_blob_transfer_client_notify_cb_t )(const sl_btmesh_blob_transfer_client_notification_t *const notification)

Callback function type for BLOB transfer client notifications.

Parameters

Type	Direction	Argument Name	Description
	[in]	notification	Pointer to the notification structure containing details about the event or update.

This callback is invoked to notify the application about events or updates related to the BLOB transfer client. The notification details are provided through the sl_btmesh_blob_transfer_client_notification_t structure.

Function Documentation#

SL_ENUM#

SL_ENUM (sl_btmesh_blob_transfer_client_notification_kind_t )

BLOB Transfer Client Kind.

Parameters

Type	Direction	Argument Name	Description
sl_btmesh_blob_transfer_client_notification_kind_t	N/A

SL_ENUM#

SL_ENUM (sl_btmesh_blob_transfer_client_result_t )

BLOB Transfer Client Result.

Parameters

Type	Direction	Argument Name	Description
sl_btmesh_blob_transfer_client_result_t	N/A

sl_btmesh_blob_transfer_client_setup#

sl_status_t sl_btmesh_blob_transfer_client_setup (uint16_t elem_index, sl_bt_uuid_64_t blob_id, uint32_t blob_size, uint16_t appkey_index, uint8_t ttl, uint16_t timeout_base, uint16_t group_address, uuid_128 virtual_address, uint16_t multicast_threshold, size_t servers_len, const uint8_t * servers)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	The client model element index.
sl_bt_uuid_64_t	[in]	blob_id	The ID of the BLOB.
uint32_t	[in]	blob_size	The size of the BLOB.
uint16_t	[in]	appkey_index	Index of the application key to be used for communicating with the servers
uint8_t	[in]	ttl	The TTL to use when communicating with the servers.
uint16_t	[in]	timeout_base	If a Server does not respond within this time frame, it will be marked as inactive.
uint16_t	[in]	group_address	The group address to used if the `multicast_threshold` is exceeded. Zero to only use unicast.
uuid_128	[in]	virtual_address	Virtual address in case virtual addresses are used
uint16_t	[in]	multicast_threshold	If the number of servers for any step exceeds this number, the group address will be used. Otherwise, servers will be looped through one by one.
size_t	[in]	servers_len	Length of data in servers
const uint8_t *	[in]	servers	List of MBT server addresses, represented as little endian two byte sequences.

Set up a new BLOB transfer.

Note

This shall not be called when the Distribution Server initiates the BLOB transfer because BT Mesh stack sets up the BLOB transfer inside the BT Mesh stack automatically.

Returns

Result of the BLOB Transfer setup

Return values

SL_STATUS_OK: if successful. Error code otherwise.
SL_STATUS_INVALID_STATE: if not Idle

sl_btmesh_blob_transfer_client_setup_data_provider_array#

sl_status_t sl_btmesh_blob_transfer_client_setup_data_provider_array (uint16_t elem_index, const uint8_t * array, uint32_t length)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index
const uint8_t *	[in]	array	Pointer to an array which stores the BLOB data
uint32_t	[in]	length	Length of the array

Set up an array data provider for a new BLOB transfer.

The BLOB transfer client reads the BLOB data from this array during chunk transfer.

Returns

Result of the Data Provider setup

Return values

SL_STATUS_OK: if successful
SL_STATUS_INVALID_STATE: Data Provider setup called in non-idle state
SL_STATUS_INVALID_PARAMETER: BLOB size inconsistency between the

sl_btmesh_blob_transfer_client_setup_data_provider_blob_storage#

sl_status_t sl_btmesh_blob_transfer_client_setup_data_provider_blob_storage (uint16_t elem_index, const sl_bt_uuid_64_t * blob_id)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index
const sl_bt_uuid_64_t *	[in]	blob_id	Pointer to the BLOB id

Set up a BLOB storage data provider for a new BLOB transfer.

The BLOB Transfer Client reads the BLOB data from the BLOB storage based on the passed BLOB id.

Note

The BLOB id used to identify the BLOB data in the BLOB storage (on the client side) is likely not the same as the BLOB id used during the BLOB transfer to the servers.

Returns

Result of the Data Provider setup

Return values

SL_STATUS_OK: if successful
SL_STATUS_INVALID_STATE: Data Provider setup called in non-idle state
SL_STATUS_NOT_FOUND: BLOB is not found in the BLOB storage
SL_STATUS_INVALID_PARAMETER: BLOB size inconsistency between the

sl_btmesh_blob_transfer_client_set_params#

sl_status_t sl_btmesh_blob_transfer_client_set_params (uint16_t elem_index, uint16_t separation_time_ms, uint16_t retry_time_local_ms, uint16_t retry_time_push_ms, uint16_t retry_time_pull_ms, uint16_t retry_max_local, uint16_t retry_threshold_remote)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index
uint16_t	[in]	separation_time_ms	Minimum separation time between two chunks in the same block, in milliseconds
uint16_t	[in]	retry_time_local_ms	Local retry time of message transmission requests during query info, transfer start, block start, block query, chunk transfer and transfer cancel procedures. Local retry time is used when the BT Mesh stack rejects sending BLOB Transfer messages due to a recoverable error, so BT Mesh stack API returns with recoverable error code, for example due to lack of memory. Local retry time shall be greater than zero.
uint16_t	[in]	retry_time_push_ms	Retry time of message transmissions during push transfer. The transfer start, block start, block query and transfer cancel procedures use this retry time during push transfer to send the procedure specific message again if at least one receiver haven't responded when retry timeout is reached. The query info procedure use this retry time value when the push transfer mode is selected explicitly by upper layer or both transfer modes (push & pull) are allowed by the upper layer.
uint16_t	[in]	retry_time_pull_ms	Retry time of message transmissions during pull transfer. The transfer start, block start, block query and transfer cancel procedures use this retry time during pull transfer to send the procedure specific message again if at least one receiver haven't responded when this retry timeout is reached.The query info procedure use this retry time when the pull transfer mode is selected explicitly by upper layer.
uint16_t	[in]	retry_max_local	Local max retries of message transmission requests during query info, transfer start, block start, block query chunk transfer and transfer cancel procedures. Max local retry is used when the BT Mesh stack rejects sending BLOB Transfer messages due to a recoverable error, so BT Mesh stack API returns with recoverable error code, for example due to lack of memory
uint16_t	[in]	retry_threshold_remote	Retry threshold of frequent message transmissions during query info, transfer start, block start, block query and transfer cancel procedures before infrequent message transmission is activated with doubled retry time.

Set up additional parameters for new BLOB transfers

The separation and retry parameters are set for all future BLOB Transfers until the next reset (stored in RAM). On reset, the respective default separation and retry parameters are set based on the component configuration at component initialization time.

Note

This function is separated from sl_btmesh_blob_transfer_client_setup because the sl_btmesh_blob_transfer_client_setup shall not be called when Firmware Distribution Server initiates the BLOB transfer because BT Mesh stack sets up the BLOB transfer inside the BT Mesh stack automatically.

Returns

Result of the parameter setup

Return values

SL_STATUS_OK: if successful
SL_STATUS_INVALID_STATE: Parameter setup called in non-idle state
SL_STATUS_INVALID_PARAMETER: One or more parameters are invalid

sl_btmesh_blob_transfer_client_start#

sl_status_t sl_btmesh_blob_transfer_client_start (uint16_t elem_index, sl_btmesh_mbt_client_transfer_mode_t transfer_mode, sl_btmesh_blob_transfer_client_notify_cb_t notify)

Parameters

Type Direction Argument Name Description

uint16_t

[in]

elem_index

Client model element index

sl_btmesh_mbt_client_transfer_mode_t

[in]

transfer_mode

Allowed transfer mode

sl_btmesh_blob_transfer_client_notify_cb_t

[in]

notify

Function pointer to a notification callback function which is called in the following cases:

BLOB Transfer completed
BLOB Transfer failed
BLOB Transfer canceled
BLOB Transfer progress changes
BLOB Transfer Server failed

It is valid to pass NULL as notify parameter. If the callback function is null then no notification is initiated. If transfer_mode is set to sl_btmesh_mbt_client_mbt_transfer_mode_both then the BLOB transfer client selects the transfer mode based on the result of query information. If one transfer mode is supported by all receiving nodes only then that transfer mode is selected otherwise push mode is selected. If transfer_mode is set to sl_btmesh_mbt_client_mbt_transfer_mode_push or sl_btmesh_mbt_client_mbt_transfer_mode_pull then that is used as transfer mode.

Starts a previously set up BLOB Transfer.

Returns

SL_STATUS_OK if successful. Error code otherwise

Return values

SL_STATUS_INVALID_PARAMETER: Invalid transfer mode
SL_STATUS_INVALID_STATE: BLOB Transfer Client busy with another transfer
SL_STATUS_INVALID_CONFIGURATION: No data provider was specified

sl_btmesh_blob_transfer_client_cancel#

void sl_btmesh_blob_transfer_client_cancel (uint16_t elem_index)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index

Cancels an ongoing BLOB Transfer.

sl_btmesh_blob_transfer_client_abort#

sl_status_t sl_btmesh_blob_transfer_client_abort (uint16_t elem_index)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index

Aborts an ongoing BLOB Transfer.

Note

This function is not to be used when the MBT client is interfaced by a higher layer component (e.g. distribution server).

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_blob_transfer_client_on_aborted#

sl_status_t sl_btmesh_blob_transfer_client_on_aborted (uint16_t elem_index)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index

Informs BLOB Transfer Client SDK component that the transfer in MBT Client model of BT Mesh stack was aborted.

Note

This function shall be used only when the MBT client is interfaced by a higher layer component (e.g. distribution server). The MBT Client model can be aborted by higher layer models in the BT Mesh stack which is not reported in MBT Client model events so it shall be reported by calling this API.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_blob_transfer_client_on_suspended#

sl_status_t sl_btmesh_blob_transfer_client_on_suspended (uint16_t elem_index)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index

Informs BLOB Transfer Client SDK component that the transfer in MBT Client model of BT Mesh stack was suspended.

Note

This function shall be used only when the MBT client is interfaced by a higher layer component (e.g. distribution server). The MBT Client model can be suspended by higher layer models in the BT Mesh stack which is not reported in MBT Client model events so it shall be reported by calling this API.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_blob_transfer_client_on_resumed#

sl_status_t sl_btmesh_blob_transfer_client_on_resumed (uint16_t elem_index)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	elem_index	Client model element index

Informs BLOB Transfer Client SDK component that the transfer in MBT Client model of BT Mesh stack was resumed.

Note

This function shall be used only when the MBT client is interfaced by a higher layer component (e.g. distribution server). The MBT Client model can be resumed by higher layer models in the BT Mesh stack which is not reported in MBT Client model events so it shall be reported by calling this API.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_btmesh_blob_transfer_client_on_event#

void sl_btmesh_blob_transfer_client_on_event (const sl_btmesh_msg_t *const evt)

Parameters

Type	Direction	Argument Name	Description
const sl_btmesh_msg_t *const	[in]	evt	Pointer to incoming event.

Handle BLOB Transfer Client events.

This function is called automatically after enabling the component.

sl_btmesh_blob_transfer_client_calculate_block_size_log#

uint8_t sl_btmesh_blob_transfer_client_calculate_block_size_log (uint32_t blob_size, uint8_t block_size_log_min, uint8_t block_size_log_max, uint16_t block_count_max, uint16_t max_chunk_size_min, uint16_t max_chunks_min)

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	blob_size	Size of the BLOB
uint8_t	[in]	block_size_log_min	Min allowed binary logarithm of the block size
uint8_t	[in]	block_size_log_max	Max allowed binary logarithm of the block size
uint16_t	[in]	block_count_max	Max allowed number of blocks
uint16_t	[in]	max_chunk_size_min	Max allowed chunk size in the current transfer
uint16_t	[in]	max_chunks_min	Max allowed number of chunks per block in the current transfer

Calculates the binary logarithm of the block size for the current BLOB transfer from the provided parameters which are the result of the Retrieve Capabilities procedure of the BLOB Transfer.

The parameters passed represent the aggregated capabilities of the BLOB transfer client and every BLOB transfer server which participates in the current transfer.

The default implementation calculates the greatest possible block size from the parameters. If another implementation is required then the strong symbol definition shall be provided for this function with the implementation in the application code.

Returns

Binary logarithm of the selected block size for the current transfer

Return values

SL_BTMESH_BLOB_TRANSFER_CLIENT_INVALID_BLOCK_SIZE_LOG: Invalid parameters

sl_btmesh_blob_transfer_client_calculate_chunk_size#

uint16_t sl_btmesh_blob_transfer_client_calculate_chunk_size (uint8_t block_size_log, uint16_t max_chunk_size_min, uint16_t max_chunks_min, uint16_t nw_pdu_size)

Parameters

Type	Direction	Argument Name	Description
uint8_t	[in]	block_size_log	The selected binary logarithm of the block size during previous phase of the BLOB transfer
uint16_t	[in]	max_chunk_size_min	Max allowed chunk size in the current transfer
uint16_t	[in]	max_chunks_min	Max allowed number of chunks per block in the current transfer
uint16_t	[in]	nw_pdu_size	Size of Network PDU. If the Silicon Labs BT Mesh over advertisement extension proprietary feature is turned on then it can be greater than 29 bytes.

Calculates the chunk size for the next block in the current BLOB transfer from the previously selected binary logarithm of the block size and from the result of the Retrieve Capabilities procedure of the BLOB Transfer.

If the configurable preferred chunk size is supported by all BLOB Transfer Servers then the default chunk size calculation algorithm selects it as chunk size of the block otherwise the chunk size is set to the closest value which fills all segments of the chunk. If another implementation is required then the strong symbol definition shall be provided for this function with the implementation in the application code.

Returns

Chunk size for next block in the current BLOB transfer

sl_btmesh_blob_transfer_client_transfer_mode_to_string#

const char * sl_btmesh_blob_transfer_client_transfer_mode_to_string (sl_btmesh_mbt_client_transfer_mode_t transfer_mode)

Parameters

Type	Direction	Argument Name	Description
sl_btmesh_mbt_client_transfer_mode_t	[in]	transfer_mode	transfer mode

Provides string representation of transfer mode

It is guaranteed that this function returns a valid string even in case of invalid transfer mode.

Note

The to_string functions are used for log calls only in this component. If the logging is disabled then the linker can eliminate these functions.

Returns

String representation of transfer mode

Return values

INVALID: if the transfer mode is invalid

sl_btmesh_blob_transfer_client_mbt_phase_to_string#

const char * sl_btmesh_blob_transfer_client_mbt_phase_to_string (sl_btmesh_mbt_server_phase_t mbt_phase)

Parameters

Type	Direction	Argument Name	Description
sl_btmesh_mbt_server_phase_t	[in]	mbt_phase	MBT phase

Provides string representation of MBT phase

It is guaranteed that this function returns a valid string even in case of invalid MBT phase.

Note

The to_string functions are used for log calls only in this component. If the logging is disabled then the linker can eliminate these functions.

Returns

String representation of MBT phase

Return values

INVALID: if the MBT phase is invalid

sl_btmesh_blob_transfer_client_mbt_status_to_string#

const char * sl_btmesh_blob_transfer_client_mbt_status_to_string (sl_btmesh_mbt_server_status_t mbt_status)

Parameters

Type	Direction	Argument Name	Description
sl_btmesh_mbt_server_status_t	[in]	mbt_status	MBT status

Provides string representation of MBT status

It is guaranteed that this function returns a valid string even in case of invalid MBT status.

Note

The to_string functions are used for log calls only in this component. If the logging is disabled then the linker can eliminate these functions.

Returns

String representation of MBT status

Return values

INVALID: if the MBT status is invalid

sl_btmesh_blob_transfer_client_get_max_servers#

uint16_t sl_btmesh_blob_transfer_client_get_max_servers (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Provides the maximum number of MBT servers the client is configured to handle

Returns

Value of SL_BTMESH_BLOB_TRANSFER_CLIENT_MAX_SERVERS_CFG_VAL