blob: 53d9144713c2a54bb0d222f90fcf32607c78bfd2 [file] [log] [blame]
/*
* Copyright (c) 2020 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @file
* @defgroup bt_mesh_dfu_srv Firmware Update Server model
* @ingroup bt_mesh_dfu
* @{
* @brief API for the Bluetooth mesh Firmware Update Server model
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__
#define ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__
#include <zephyr/bluetooth/mesh/dfu.h>
#include <zephyr/bluetooth/mesh/blob_srv.h>
#include <zephyr/bluetooth/mesh/access.h>
#ifdef __cplusplus
extern "C" {
#endif
struct bt_mesh_dfu_srv;
/**
*
* @brief Initialization parameters for @ref bt_mesh_dfu_srv.
*
* @param _handlers DFU handler function structure.
* @param _imgs List of @ref bt_mesh_dfu_img managed by this Server.
* @param _img_count Number of DFU images managed by this Server.
*/
#define BT_MESH_DFU_SRV_INIT(_handlers, _imgs, _img_count) \
{ \
.blob = { .cb = &_bt_mesh_dfu_srv_blob_cb }, .cb = _handlers, \
.imgs = _imgs, .img_count = _img_count, \
}
/**
*
* @brief Firmware Update Server model entry.
*
* @param _srv Pointer to a @ref bt_mesh_dfu_srv instance.
*/
#define BT_MESH_MODEL_DFU_SRV(_srv) \
BT_MESH_MODEL_BLOB_SRV(&(_srv)->blob), \
BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_DFU_SRV, _bt_mesh_dfu_srv_op, NULL, \
_srv, &_bt_mesh_dfu_srv_cb)
/** @brief Firmware Update Server event callbacks. */
struct bt_mesh_dfu_srv_cb {
/** @brief Transfer check callback.
*
* The transfer check can be used to validate the incoming transfer
* before it starts. The contents of the metadata is implementation
* specific, and should contain all the information the application
* needs to determine whether this image should be accepted, and what
* the effect of the transfer would be.
*
* If applying the image will have an effect on the provisioning state
* of the mesh stack, this can be communicated through the @c effect
* return parameter.
*
* The metadata check can be performed both as part of starting a new
* transfer and as a separate procedure.
*
* This handler is optional.
*
* @param srv Firmware Update Server instance.
* @param img DFU image the metadata check is performed on.
* @param metadata Image metadata.
* @param effect Return parameter for the image effect on the
* provisioning state of the mesh stack.
*
* @return 0 on success, or (negative) error code otherwise.
*/
int (*check)(struct bt_mesh_dfu_srv *srv,
const struct bt_mesh_dfu_img *img,
struct net_buf_simple *metadata,
enum bt_mesh_dfu_effect *effect);
/** @brief Transfer start callback.
*
* Called when the Firmware Update Server is ready to start a new DFU transfer.
* The application must provide an initialized BLOB stream to be used
* during the DFU transfer.
*
* The following error codes are treated specially, and should be used
* to communicate these issues:
* - @c -ENOMEM: The device cannot fit this image.
* - @c -EBUSY: The application is temporarily unable to accept the
* transfer.
* - @c -EALREADY: The device has already received and verified this
* image, and there's no need to transfer it again. The Firmware Update model
* will skip the transfer phase, and mark the image as verified.
*
* This handler is mandatory.
*
* @param srv Firmware Update Server instance.
* @param img DFU image being updated.
* @param metadata Image metadata.
* @param io BLOB stream return parameter. Must be set to a
* valid BLOB stream by the callback.
*
* @return 0 on success, or (negative) error code otherwise. Return
* codes @c -ENOMEM, @c -EBUSY @c -EALREADY will be passed to
* the updater, other error codes are reported as internal
* errors.
*/
int (*start)(struct bt_mesh_dfu_srv *srv,
const struct bt_mesh_dfu_img *img,
struct net_buf_simple *metadata,
const struct bt_mesh_blob_io **io);
/** @brief Transfer end callback.
*
* This handler is optional.
*
* If the transfer is successful, the application should verify the
* firmware image, and call either @ref bt_mesh_dfu_srv_verified or
* @ref bt_mesh_dfu_srv_rejected depending on the outcome.
*
* If the transfer fails, the Firmware Update Server will be available for new
* transfers immediately after this function returns.
*
* @param srv Firmware Update Server instance.
* @param img DFU image that failed the update.
* @param success Whether the DFU transfer was successful.
*/
void (*end)(struct bt_mesh_dfu_srv *srv,
const struct bt_mesh_dfu_img *img, bool success);
/** @brief Transfer recovery callback.
*
* If the device reboots in the middle of a transfer, the Firmware Update Server
* calls this function when the Bluetooth mesh subsystem is started.
*
* This callback is optional, but transfers will not be recovered after
* a reboot without it.
*
* @param srv Firmware Update Server instance.
* @param img DFU image being updated.
* @param io BLOB stream return parameter. Must be set to a valid BLOB
* stream by the callback.
*
* @return 0 on success, or (negative) error code to abandon the
* transfer.
*/
int (*recover)(struct bt_mesh_dfu_srv *srv,
const struct bt_mesh_dfu_img *img,
const struct bt_mesh_blob_io **io);
/** @brief Transfer apply callback.
*
* Called after a transfer has been validated, and the updater sends an
* apply message to the Target nodes.
*
* This handler is optional.
*
* @param srv Firmware Update Server instance.
* @param img DFU image that should be applied.
*
* @return 0 on success, or (negative) error code otherwise.
*/
int (*apply)(struct bt_mesh_dfu_srv *srv,
const struct bt_mesh_dfu_img *img);
};
/** @brief Firmware Update Server instance.
*
* Should be initialized with @ref BT_MESH_DFU_SRV_INIT.
*/
struct bt_mesh_dfu_srv {
/** Underlying BLOB Transfer Server. */
struct bt_mesh_blob_srv blob;
/** Callback structure. */
const struct bt_mesh_dfu_srv_cb *cb;
/** List of updatable images. */
const struct bt_mesh_dfu_img *imgs;
/** Number of updatable images. */
size_t img_count;
/* Runtime state */
struct bt_mesh_model *mod;
struct {
/* Effect of transfer, @see bt_mesh_dfu_effect. */
uint8_t effect;
/* Current phase, @see bt_mesh_dfu_phase. */
uint8_t phase;
uint8_t ttl;
uint8_t idx;
uint16_t timeout_base;
uint16_t meta;
} update;
};
/** @brief Accept the received DFU transfer.
*
* Should be called at the end of a successful DFU transfer.
*
* If the DFU transfer completes successfully, the application should verify
* the image validity (including any image authentication or integrity checks),
* and call this function if the image is ready to be applied.
*
* @param srv Firmware Update Server instance.
*/
void bt_mesh_dfu_srv_verified(struct bt_mesh_dfu_srv *srv);
/** @brief Reject the received DFU transfer.
*
* Should be called at the end of a successful DFU transfer.
*
* If the DFU transfer completes successfully, the application should verify
* the image validity (including any image authentication or integrity checks),
* and call this function if one of the checks fail.
*
* @param srv Firmware Update Server instance.
*/
void bt_mesh_dfu_srv_rejected(struct bt_mesh_dfu_srv *srv);
/** @brief Cancel the ongoing DFU transfer.
*
* @param srv Firmware Update Server instance.
*/
void bt_mesh_dfu_srv_cancel(struct bt_mesh_dfu_srv *srv);
/** @brief Confirm that the received DFU transfer was applied.
*
* Should be called as a result of the @ref bt_mesh_dfu_srv_cb.apply callback.
*
* @param srv Firmware Update Server instance.
*/
void bt_mesh_dfu_srv_applied(struct bt_mesh_dfu_srv *srv);
/** @brief Check if the Firmware Update Server is busy processing a transfer.
*
* @param srv Firmware Update Server instance.
*
* @return true if a DFU procedure is in progress, false otherwise.
*/
bool bt_mesh_dfu_srv_is_busy(const struct bt_mesh_dfu_srv *srv);
/** @brief Get the progress of the current DFU procedure, in percent.
*
* @param srv Firmware Update Server instance.
*
* @return The current transfer progress in percent.
*/
uint8_t bt_mesh_dfu_srv_progress(const struct bt_mesh_dfu_srv *srv);
/** @cond INTERNAL_HIDDEN */
extern const struct bt_mesh_model_op _bt_mesh_dfu_srv_op[];
extern const struct bt_mesh_model_cb _bt_mesh_dfu_srv_cb;
extern const struct bt_mesh_blob_srv_cb _bt_mesh_dfu_srv_blob_cb;
/** @endcond */
#ifdef __cplusplus
}
#endif
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__ */
/** @} */