DFU target¶
The DFU target library provides a common API for the following types of firmware upgrades:
An MCUboot style upgrade
A modem delta upgrade.
A full modem firmware upgrade.
Use this library in your component to do different types of firmware upgrades against a single interface.
When initializing the DFU target library, you must provide information about the type of firmware upgrade.
To do so automatically, send the first fragment of the firmware to the function dfu_target_img_type().
This function can identify all supported firmware upgrade types.
The result of this call can then be given as input to the dfu_target_init() function.
Note
After starting a DFU procedure for a given target, you cannot initialize a new DFU procedure with a different firmware file for the same target, until the DFU procedure has completed successfully or the device has been restarted.
Supported DFU targets¶
Every supported DFU target must implement the set of functions defined in subsys/dfu/src/dfu_target.c.
The following sections describe the DFU targets that are currently supported.
MCUboot style upgrades¶
This type of firmware upgrade can be used for application updates and updates to the upgradable bootloader.
It writes the data given to the dfu_target_write() function into the secondary slot specified by MCUboot’s flash memory partitions.
For application updates, the new image replaces the existing application. For bootloader updates, the new firmware is placed in the non-active partition (slot 0 or slot 1, see Upgradable bootloader).
Note
When updating the bootloader, you must ensure that the provided bootloader firmware is linked against the correct partition. This is handled automatically by the FOTA download library.
When the complete transfer is done, call the dfu_target_done() function to mark the firmware as ready to be booted.
On the next reboot, the device will run the new firmware.
Note
To maintain the writing progress in case the device reboots, enable the configuration options CONFIG_SETTINGS and CONFIG_DFU_TARGET_STREAM_SAVE_PROGRESS.
The MCUboot target then uses the Settings subsystem in Zephyr to store the current progress used by the dfu_target_write() function across power failures and device resets.
Modem delta upgrades¶
This type of firmware upgrade opens a socket into the modem and passes the data given to the dfu_target_write() function through the socket.
The modem stores the data in the memory location for firmware patches.
If there is already a firmware patch stored in the modem, the library requests the modem to delete the old firmware patch, to make space for the new patch.
When the complete transfer is done, call the dfu_target_done() function to request the modem to apply the patch, and to close the socket.
On the next reboot, the modem will try to apply the patch.
Full modem upgrades¶
Note
An external flash memory device of minimum 2MB is required for this target.
This type of firmware upgrade supports updating the modem firmware using the serialized firmware bundled in the zip file of the modem firmware release. This DFU target will download the serialized modem firmware to an external flash memory, which is required for this type of upgrade. Once the modem firmware has been downloaded, the library will use Full modem firmware update from flash device to write the firmware to the modem.
Configuration¶
You can disable support for specific DFU targets with the following parameters:
API documentation¶
include/dfu/dfu_target.hsubsys/dfu/dfu_target/src/-
group
dfu_target DFU Target.
Typedefs
-
typedef void (*
dfu_target_callback_t)(enum dfu_target_evt_id evt_id)¶
Enums
Functions
-
int
dfu_target_img_type(const void *const buf, size_t len)¶ Find the image type for the buffer of bytes recived. Used to determine what dfu target to initialize.
- Return
Positive identifier for a supported image type or a negative error code identicating reason of failure.
- Parameters
[in] buf: A buffer of bytes which are the start of an binary firmware image.[in] len: The length of the provided buffer.
-
int
dfu_target_init(int img_type, size_t file_size, dfu_target_callback_t cb)¶ Initialize the resources needed for the specific image type DFU target.
If a target update is in progress, and the same target is given as input, then calling the ‘init()’ function of that target is skipped.
To allow continuation of an aborted DFU procedure, call the ‘dfu_target_offset_get’ function after invoking this function.
- Return
0 for a supported image type or a negative error code identicating reason of failure.
- Parameters
[in] img_type: Image type identifier.[in] file_size: Size of the current file being downloaded.[in] cb: Callback function in case the DFU operation requires additional proceedures to be called.
-
int
dfu_target_offset_get(size_t *offset)¶ Get offset of the firmware upgrade.
- Return
0 if success, otherwise negative value if unable to get the offset
- Parameters
[out] offset: Returns the offset of the firmware upgrade.
-
int
dfu_target_write(const void *const buf, size_t len)¶ Write the given buffer to the initialized DFU target.
- Return
Positive identifier for a supported image type or a negative error code identicating reason of failure.
- Parameters
[in] buf: A buffer of bytes which contains part of an binary firmware image.[in] len: The length of the provided buffer.
-
int
dfu_target_done(bool successful)¶ Deinitialize the resources that were needed for the current DFU target.
- Return
0 for an successful deinitialization or a negative error code identicating reason of failure.
- Parameters
[in] successful: Indicate whether the process completed successfully or was aborted.
-
int
dfu_target_reset(void)¶ Deinitialize the resources that were needed for the current DFU target if any and resets the current dfu target.
- Return
0 for an successful deinitialization and reset or a negative error code identicating reason of failure.
-
struct
dfu_target¶ - #include <dfu_target.h>
Functions which needs to be supported by all DFU targets.
-
typedef void (*