这个页面的最新开发版本可能比这个发布的 2.3-beta.2 版本新。

BLOB 传输客户端

二进制大型对象（BLOB）传输客户端是 BLOB 传输的发送方。它支持将任何大小的 BLOB 发送到任意数量的目标节点，无论是 Push BLOB 传输模式还是 Pull BLOB 转移模式。

使用

初始化

BLOB 传输客户端在具有一组事件处理程序回调的元素上实例化:

static const struct bt_mesh_blob_cli_cb blob_cb = {
      /* Callbacks */
};

static struct bt_mesh_blob_cli blob_cli = {
      .cb = &blob_cb,
};

static const struct bt_mesh_model models[] = {
      BT_MESH_MODEL_BLOB_CLI(&blob_cli),
};

传输上下文

传输功能检索过程和 BLOB 传输都使用 bt_mesh_BLOB_cli_input() 的实例来确定如何执行传输。BLOB 传输客户端输入结构在用于过程之前，必须至少用目标列表、应用程序密钥和生存时间（TTL）值进行初始化：

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);

请注意，传输中的所有 BLOB 传输服务器都必须绑定到所选的应用程序密钥。

逻辑地址

应用程序可以在上下文结构中额外指定组地址。如果组不是 BT_MESH_ADDR_UNASSIGNED ，则传输中的消息将发送到组地址，而不是单独发送到每个目标节点。Mesh Manager 必须确保具有 BLOB 传输服务器模型的所有目标节点都订阅该组地址。

使用组地址传输 BLOB 通常可以提高传输速度，因为 BLOB 传输客户端同时将每个消息发送到所有目标节点。然而，在 Bluetooth Mesh 中向组地址发送大型分段消息通常不如将它们发送到单播地址可靠，因为组没有传输层确认机制。这可能导致每个块末尾的恢复周期更长，并增加丢失目标节点的风险。使用组地址进行 BLOB 传输通常只有在目标节点列表广泛的情况下才会有回报，并且每个寻址策略的有效性在不同的部署和块的大小之间会有很大差异。

传输超时时间

如果目标节点未能在 BLOB 传输客户端的时间限制内响应确认的消息，则会从传输中删除目标节点。应用程序可以通过上下文结构为 BLOB 传输客户端提供额外的时间，从而减少这种可能性。除了20秒的基本时间外，额外时间可以以10秒为增量设置，最长可达182小时。等待时间随传输 TTL 自动调整。

请注意，BLOB 传输客户端仅在以下情况下与传输一起向前移动：

所有目标节点都已响应。
已从目标节点列表中删除节点。
BLOB 传输客户端超时。

增加等待时间将增加该延迟。

BLOB 传输功能检索

通常建议在开始传输之前检索 BLOB 传输功能。该过程使用允许所有目标节点参与传输的最自由的参数集填充来自所有目标节点的传输功能。任何未能响应或使用不兼容的传输参数响应的目标节点都将被丢弃。

根据目标节点在目标节点列表中的顺序对目标节点进行优先级排序。如果发现目标节点与任何先前的目标节点不兼容，例如通过报告不重叠的块大小范围，则将删除该节点。丢失的目标节点将通过 lost_target 回调报告。

过程的结束通过 caps 回调发出信号，生成的功能可用于确定 BLOB 传输所需的块和块大小。

BLOB 传输

BLOB 传输通过调用 bt_mesh_BLOB_cli_send 函数启动，该函数（除了前面提到的传输输入外）需要一组传输参数和 BLOB 流实例。传输参数包括64位 BLOB ID、BLOB 大小、传输模式、对数表示的块大小和块大小。BLOB ID 是应用程序定义的，但必须与启动 BLOB 传输服务器的BLOB标识匹配。

传输将一直运行，直到至少一个目标节点的传输成功完成，或者传输被取消。传输的结束通过结束回调与应用程序通信。丢失的目标节点将通过 lost_target 回调报告。

API 参考

group bt_mesh_blob_cli

Defines

BT_MESH_MODEL_BLOB_CLI(_cli)

BLOB Transfer Client model Composition Data entry.

参数:

_cli – Pointer to a Bluetooth Mesh BLOB Transfer Client model API instance.

Enums

enum bt_mesh_blob_cli_state

BLOB Transfer Client state.

Values:

enumerator BT_MESH_BLOB_CLI_STATE_NONE: No transfer is active.

enumerator BT_MESH_BLOB_CLI_STATE_CAPS_GET: Retrieving transfer capabilities.

enumerator BT_MESH_BLOB_CLI_STATE_START: Sending transfer start.

enumerator BT_MESH_BLOB_CLI_STATE_BLOCK_START: Sending block start.

enumerator BT_MESH_BLOB_CLI_STATE_BLOCK_SEND: Sending block chunks.

enumerator BT_MESH_BLOB_CLI_STATE_BLOCK_CHECK: Checking block status.

enumerator BT_MESH_BLOB_CLI_STATE_XFER_CHECK: Checking transfer status.

enumerator BT_MESH_BLOB_CLI_STATE_CANCEL: Cancelling transfer.

enumerator BT_MESH_BLOB_CLI_STATE_SUSPENDED: Transfer is suspended.

enumerator BT_MESH_BLOB_CLI_STATE_XFER_PROGRESS_GET: Checking transfer progress.

Functions

int bt_mesh_blob_cli_caps_get(struct bt_mesh_blob_cli *cli, const struct bt_mesh_blob_cli_inputs *inputs)

Retrieve transfer capabilities for a list of Target nodes.

Queries the availability and capabilities of all Target nodes, producing a cumulative set of transfer capabilities for the Target nodes, and returning it through the bt_mesh_blob_cli_cb::caps callback.

Retrieving the capabilities may take several seconds, depending on the number of Target nodes and mesh network performance. The end of the procedure is indicated through the bt_mesh_blob_cli_cb::caps callback.

This procedure is not required, but strongly recommended as a preparation for a transfer to maximize performance and the chances of success.

参数:

cli – BLOB Transfer Client instance.
inputs – Statically allocated BLOB Transfer Client transfer inputs.

返回:

0 on success, or (negative) error code otherwise.

int bt_mesh_blob_cli_send(struct bt_mesh_blob_cli *cli, const struct bt_mesh_blob_cli_inputs *inputs, const struct bt_mesh_blob_xfer *xfer, const struct bt_mesh_blob_io *io)

Perform a BLOB transfer.

Starts sending the transfer to the Target nodes. Only Target nodes with a status of BT_MESH_BLOB_SUCCESS will be considered.

The transfer will keep going either until all Target nodes have been dropped, or the full BLOB has been sent.

The BLOB transfer may take several minutes, depending on the number of Target nodes, size of the BLOB and mesh network performance. The end of the transfer is indicated through the bt_mesh_blob_cli_cb::end callback.

A Client only supports one transfer at the time.

参数:

cli – BLOB Transfer Client instance.
inputs – Statically allocated BLOB Transfer Client transfer inputs.
xfer – Statically allocated transfer parameters.
io – BLOB stream to read the transfer from.

返回:

0 on success, or (negative) error code otherwise.

int bt_mesh_blob_cli_suspend(struct bt_mesh_blob_cli *cli)

Suspend the active transfer.

参数:: cli – BLOB Transfer Client instance.
返回:: 0 on success, or (negative) error code otherwise.

int bt_mesh_blob_cli_resume(struct bt_mesh_blob_cli *cli)

Resume the suspended transfer.

参数:: cli – BLOB Transfer Client instance.
返回:: 0 on success, or (negative) error code otherwise.

void bt_mesh_blob_cli_cancel(struct bt_mesh_blob_cli *cli)

Cancel an ongoing transfer.

参数:: cli – BLOB Transfer Client instance.

int bt_mesh_blob_cli_xfer_progress_get(struct bt_mesh_blob_cli *cli, const struct bt_mesh_blob_cli_inputs *inputs)

Get the progress of BLOB transfer.

This function can only be used if the BLOB Transfer Client is currently not performing a BLOB transfer. To get progress of the active BLOB transfer, use the bt_mesh_blob_cli_xfer_progress_active_get function.

参数:

cli – BLOB Transfer Client instance.
inputs – Statically allocated BLOB Transfer Client transfer inputs.

返回:

0 on success, or (negative) error code otherwise.

uint8_t bt_mesh_blob_cli_xfer_progress_active_get(struct bt_mesh_blob_cli *cli)

Get the current progress of the active transfer in percent.

参数:: cli – BLOB Transfer Client instance.
返回:: The current transfer progress, or 0 if no transfer is active.

bool bt_mesh_blob_cli_is_busy(struct bt_mesh_blob_cli *cli)

Get the current state of the BLOB Transfer Client.

参数:: cli – BLOB Transfer Client instance.
返回:: true if the BLOB Transfer Client is currently participating in a transfer or retrieving the capabilities and false otherwise.

struct bt_mesh_blob_target_pull

Target node’s Pull mode (Pull BLOB Transfer Mode) context used while sending chunks to the Target node.

Public Members

int64_t block_report_timestamp: Timestamp when the Block Report Timeout Timer expires for this Target node.

uint8_t missing[DIV_ROUND_UP(CONFIG_BT_MESH_BLOB_CHUNK_COUNT_MAX, 8)]: Missing chunks reported by this Target node.

struct bt_mesh_blob_target

BLOB Transfer Client Target node.

Public Members

sys_snode_t n: Linked list node

uint16_t addr: Target node address.

struct bt_mesh_blob_target_pull *pull: Target node’s Pull mode context. Needs to be initialized when sending a BLOB in Pull mode.

uint8_t status: BLOB transfer status, see bt_mesh_blob_status.

struct bt_mesh_blob_xfer_info

BLOB transfer information.

If phase is BT_MESH_BLOB_XFER_PHASE_INACTIVE, the fields below phase are not initialized. If phase is BT_MESH_BLOB_XFER_PHASE_WAITING_FOR_START, the fields below id are not initialized.

Public Members

enum bt_mesh_blob_status status: BLOB transfer status.

enum bt_mesh_blob_xfer_mode mode: BLOB transfer mode.

enum bt_mesh_blob_xfer_phase phase: BLOB transfer phase.

uint64_t id: BLOB ID.

uint32_t size: BLOB size in octets.

uint8_t block_size_log: Logarithmic representation of the block size.

uint16_t mtu_size: MTU size in octets.

const uint8_t *missing_blocks: Bit field indicating blocks that were not received.

struct bt_mesh_blob_cli_inputs

BLOB Transfer Client transfer inputs.

Public Members

sys_slist_t targets: Linked list of Target nodes. Each node should point to bt_mesh_blob_target::n.

uint16_t app_idx: AppKey index to send with.

uint16_t group: Group address destination for the BLOB transfer, or BT_MESH_ADDR_UNASSIGNED to send every message to each Target node individually.

uint8_t ttl: Time to live value of BLOB transfer messages.

uint16_t timeout_base

Additional response time for the Target nodes, in 10-second increments.

The extra time can be used to give the Target nodes more time to respond to messages from the Client. The actual timeout will be calculated according to the following formula:

*  timeout = 20 seconds + (10 seconds * timeout_base) + (100 ms * TTL)
*

If a Target node fails to respond to a message from the Client within the configured transfer timeout, the Target node is dropped.

struct bt_mesh_blob_cli_caps

Transfer capabilities of a Target node.

Public Members

size_t max_size: Max BLOB size.

uint8_t min_block_size_log: Logarithmic representation of the minimum block size.

uint8_t max_block_size_log: Logarithmic representation of the maximum block size.

uint16_t max_chunks: Max number of chunks per block.

uint16_t max_chunk_size: Max chunk size.

uint16_t mtu_size: Max MTU size.

enum bt_mesh_blob_xfer_mode modes: Supported transfer modes.

struct bt_mesh_blob_cli_cb

Event handler callbacks for the BLOB Transfer Client model.

All handlers are optional.

Public Members

void (*caps)(struct bt_mesh_blob_cli *cli, const struct bt_mesh_blob_cli_caps *caps)

Capabilities retrieval completion callback.

Called when the capabilities retrieval procedure completes, indicating that a common set of acceptable transfer parameters have been established for the given list of Target nodes. All compatible Target nodes have status code BT_MESH_BLOB_SUCCESS.

Param cli:: BLOB Transfer Client instance.
Param caps:: Safe transfer capabilities if the transfer capabilities of at least one Target node has satisfied the Client, or NULL otherwise.

void (*lost_target)(struct bt_mesh_blob_cli *cli, struct bt_mesh_blob_target *target, enum bt_mesh_blob_status reason)

Target node loss callback.

Called whenever a Target node has been lost due to some error in the transfer. Losing a Target node is not considered a fatal error for the Client until all Target nodes have been lost.

Param cli:: BLOB Transfer Client instance.
Param target:: Target node that was lost.
Param reason:: Reason for the Target node loss.

void (*suspended)(struct bt_mesh_blob_cli *cli)

Transfer is suspended.

Called when the transfer is suspended due to response timeout from all Target nodes.

Param cli:: BLOB Transfer Client instance.

void (*end)(struct bt_mesh_blob_cli *cli, const struct bt_mesh_blob_xfer *xfer, bool success)

Transfer end callback.

Called when the transfer ends.

Param cli:: BLOB Transfer Client instance.
Param xfer:: Completed transfer.
Param success:: Status of the transfer. Is true if at least one Target node received the whole transfer.

void (*xfer_progress)(struct bt_mesh_blob_cli *cli, struct bt_mesh_blob_target *target, const struct bt_mesh_blob_xfer_info *info)

Transfer progress callback.

The content of info is invalidated upon exit from the callback. Therefore it needs to be copied if it is planned to be used later.

Param cli:: BLOB Transfer Client instance.
Param target:: Target node that responded to the request.
Param info:: BLOB transfer information.

void (*xfer_progress_complete)(struct bt_mesh_blob_cli *cli)

End of Get Transfer Progress procedure.

Called when all Target nodes have responded or the procedure timed-out.

Param cli:: BLOB Transfer Client instance.

struct bt_mesh_blob_cli

BLOB Transfer Client model instance.

Public Members

const struct bt_mesh_blob_cli_cb *cb: Event handler callbacks