The latest development version of this page may be more current than this released 3.7.0 version.

Firmware Update Client

The Firmware Update Client is responsible for distributing firmware updates through the mesh network. The Firmware Update Client uses the BLOB Transfer Client as a transport for its transfers.

API reference

group bt_mesh_dfu_cli

API for the Bluetooth Mesh Firmware Update Client model.

Defines

BT_MESH_DFU_CLI_INIT(_handlers)

Initialization parameters for the Firmware Uppdate Client model.

See also

bt_mesh_dfu_cli_cb.

Parameters:

_handlers – Handler callback structure.

BT_MESH_MODEL_DFU_CLI(_cli)

Firmware Update Client model Composition Data entry.

Parameters:

_cli – Pointer to a Firmware Uppdate Client model instance.

Typedefs

typedef enum bt_mesh_dfu_iter (*bt_mesh_dfu_img_cb_t)(struct bt_mesh_dfu_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t idx, uint8_t total, const struct bt_mesh_dfu_img *img, void *cb_data)

DFU image callback.

The image callback is called for every DFU image on the Target node when calling bt_mesh_dfu_cli_imgs_get.

Param cli:: Firmware Update Client model instance.
Param ctx:: Message context of the received message.
Param idx:: Image index.
Param total:: Total number of images on the Target node.
Param img:: Image information for the given image index.
Param cb_data:: Callback data.
Retval BT_MESH_DFU_ITER_STOP:: Stop iterating through the image list and return from bt_mesh_dfu_cli_imgs_get.
Retval BT_MESH_DFU_ITER_CONTINUE:: Continue iterating through the image list if any images remain.

Functions

int bt_mesh_dfu_cli_send(struct bt_mesh_dfu_cli *cli, const struct bt_mesh_blob_cli_inputs *inputs, const struct bt_mesh_blob_io *io, const struct bt_mesh_dfu_cli_xfer *xfer)

Start distributing a DFU.

Starts distribution of the firmware in the given slot to the list of DFU Target nodes in ctx. The transfer runs in the background, and its end is signalled through the bt_mesh_dfu_cli_cb::ended callback.

Note

The BLOB Transfer Client transfer inputs targets list must point to a list of bt_mesh_dfu_target nodes.

Parameters:

cli – Firmware Update Client model instance.
inputs – BLOB Transfer Client transfer inputs.
io – BLOB stream to read BLOB from.
xfer – Firmware Update Client transfer parameters.

Returns:

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

int bt_mesh_dfu_cli_suspend(struct bt_mesh_dfu_cli *cli)

Suspend a DFU transfer.

Parameters:

cli – Firmware Update Client instance.

Returns:

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

int bt_mesh_dfu_cli_resume(struct bt_mesh_dfu_cli *cli)

Resume the suspended transfer.

Parameters:

cli – Firmware Update Client instance.

Returns:

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

int bt_mesh_dfu_cli_cancel(struct bt_mesh_dfu_cli *cli, struct bt_mesh_msg_ctx *ctx)

Cancel a DFU transfer.

Will cancel the ongoing DFU transfer, or the transfer on a specific Target node if ctx is valid.

Parameters:

cli – Firmware Update Client model instance.
ctx – Message context, or NULL to cancel the ongoing DFU transfer.

Returns:

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

int bt_mesh_dfu_cli_apply(struct bt_mesh_dfu_cli *cli)

Apply the completed DFU transfer.

A transfer can only be applied after it has ended successfully. The Firmware Update Client’s applied callback is called at the end of the apply procedure.

Parameters:

cli – Firmware Update Client model instance.

Returns:

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

int bt_mesh_dfu_cli_confirm(struct bt_mesh_dfu_cli *cli)

Confirm that the active transfer has been applied on the Target nodes.

A transfer can only be confirmed after it has been applied. The Firmware Update Client’s confirmed callback is called at the end of the confirm procedure.

Target nodes that have reported the effect as BT_MESH_DFU_EFFECT_UNPROV are expected to not respond to the query, and will fail if they do.

Parameters:

cli – Firmware Update Client model instance.

Returns:

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

uint8_t bt_mesh_dfu_cli_progress(struct bt_mesh_dfu_cli *cli)

Get progress as a percentage of completion.

Parameters:

cli – Firmware Update Client model instance.

Returns:

The progress of the current transfer in percent, or 0 if no transfer is active.

bool bt_mesh_dfu_cli_is_busy(struct bt_mesh_dfu_cli *cli)

Check whether a DFU transfer is in progress.

Parameters:

cli – Firmware Update Client model instance.

Returns:

true if the BLOB Transfer Client is currently participating in a transfer, false otherwise.

int bt_mesh_dfu_cli_imgs_get(struct bt_mesh_dfu_cli *cli, struct bt_mesh_msg_ctx *ctx, bt_mesh_dfu_img_cb_t cb, void *cb_data, uint8_t max_count)

Perform a DFU image list request.

Requests the full list of DFU images on a Target node, and iterates through them, calling the cb for every image.

The DFU image list request can be used to determine which image index the Target node holds its different firmwares in.

Waits for a response until the procedure timeout expires.

Parameters:

cli – Firmware Update Client model instance.
ctx – Message context.
cb – Callback to call for each image index.
cb_data – Callback data to pass to cb.
max_count – Max number of images to return.

Returns:

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

int bt_mesh_dfu_cli_metadata_check(struct bt_mesh_dfu_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t img_idx, const struct bt_mesh_dfu_slot *slot, struct bt_mesh_dfu_metadata_status *rsp)

Perform a metadata check for the given DFU image slot.

The metadata check procedure allows the Firmware Update Client to check if a Target node will accept a transfer of this DFU image slot, and what the effect would be.

Waits for a response until the procedure timeout expires.

Parameters:

cli – Firmware Update Client model instance.
ctx – Message context.
img_idx – Target node’s image index to check.
slot – DFU image slot to check for.
rsp – Metadata status response buffer.

Returns:

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

int bt_mesh_dfu_cli_status_get(struct bt_mesh_dfu_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_dfu_target_status *rsp)

Get the status of a Target node.

Parameters:

cli – Firmware Update Client model instance.
ctx – Message context.
rsp – Response data buffer.

Returns:

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

int32_t bt_mesh_dfu_cli_timeout_get(void)

Get the current procedure timeout value.

Returns:: The configured procedure timeout.

void bt_mesh_dfu_cli_timeout_set(int32_t timeout)

Set the procedure timeout value.

Parameters:

timeout – The new procedure timeout.

struct bt_mesh_dfu_target

#include <dfu_cli.h>

DFU Target node.

Public Members

struct bt_mesh_blob_target blob: BLOB Target node.

uint8_t img_idx: Image index on the Target node.

uint8_t effect: Expected DFU effect, see bt_mesh_dfu_effect.

uint8_t status: Current DFU status, see bt_mesh_dfu_status.

uint8_t phase: Current DFU phase, see bt_mesh_dfu_phase.

struct bt_mesh_dfu_metadata_status

#include <dfu_cli.h>

Metadata status response.

Public Members

uint8_t idx: Image index.

enum bt_mesh_dfu_status status: Status code.

enum bt_mesh_dfu_effect effect: Effect of transfer.

struct bt_mesh_dfu_target_status

#include <dfu_cli.h>

DFU Target node status parameters.

Public Members

enum bt_mesh_dfu_status status: Status of the previous operation.

enum bt_mesh_dfu_phase phase: Phase of the current DFU transfer.

enum bt_mesh_dfu_effect effect: The effect the update will have on the Target device’s state.

uint64_t blob_id: BLOB ID used in the transfer.

uint8_t img_idx: Image index to transfer.

uint8_t ttl: TTL used in the transfer.

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_dfu_cli_cb

#include <dfu_cli.h>

Firmware Update Client event callbacks.

Public Members

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

BLOB transfer is suspended.

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

Param cli:: Firmware Update Client model instance.

void (*ended)(struct bt_mesh_dfu_cli *cli, enum bt_mesh_dfu_status reason)

DFU ended.

Called when the DFU transfer ends, either because all Target nodes were lost or because the transfer was completed successfully.

Param cli:: Firmware Update Client model instance.
Param reason:: Reason for ending.

void (*applied)(struct bt_mesh_dfu_cli *cli)

DFU transfer applied on all active Target nodes.

Called at the end of the apply procedure started by bt_mesh_dfu_cli_apply.

Param cli:: Firmware Update Client model instance.

void (*confirmed)(struct bt_mesh_dfu_cli *cli)

DFU transfer confirmed on all active Target nodes.

Called at the end of the apply procedure started by bt_mesh_dfu_cli_confirm.

Param cli:: Firmware Update Client model instance.

void (*lost_target)(struct bt_mesh_dfu_cli *cli, struct bt_mesh_dfu_target *target)

DFU Target node was lost.

A DFU Target node was dropped from the receivers list. The Target node’s status is set to reflect the reason for the failure.

Param cli:: Firmware Update Client model instance.
Param target:: DFU Target node that was lost.

struct bt_mesh_dfu_cli

#include <dfu_cli.h>

Firmware Update Client model instance.

Should be initialized with BT_MESH_DFU_CLI_INIT.

Public Members

const struct bt_mesh_dfu_cli_cb *cb: Callback structure.

struct bt_mesh_blob_cli blob: Underlying BLOB Transfer Client.

struct bt_mesh_dfu_cli_xfer_blob_params

#include <dfu_cli.h>

BLOB parameters for Firmware Update Client transfer:

Public Members

uint16_t chunk_size

Base chunk size.

May be smaller for the last chunk.

struct bt_mesh_dfu_cli_xfer

#include <dfu_cli.h>

Firmware Update Client transfer parameters:

Public Members

uint64_t blob_id: BLOB ID to use for this transfer, or 0 to set it randomly.

const struct bt_mesh_dfu_slot *slot: DFU image slot to transfer.

enum bt_mesh_blob_xfer_mode mode: Transfer mode (Push (Push BLOB Transfer Mode) or Pull (Pull BLOB Transfer Mode))

const struct bt_mesh_dfu_cli_xfer_blob_params *blob_params: BLOB parameters to be used for the transfer, or NULL to retrieve Target nodes’ capabilities before sending a firmware.