Recovery library implements an API that allows you to configure the different supported recovery commands and the reboot into recovery mode.

This library is installed in the toolchain provided by Digi Embedded Yocto, so you can use it to develop your own custom application with support to trigger recovery commands. See Application development.

Recovery library functionality is only available for devices with a single boot partition table. The recovery API is not applicable for dual boot partition table.

See Storage layout.

Using the library

To use the library you need to:

  1. Include the recovery header file in your application.

    #include <recovery.h>

  2. Link against the recovery static library already included in the pre-compiled toolchain.

    The library provides a pkg-config file recovery.pc, installed in the toolchain. To configure the proper compilation flags and linked libraries, add the following lines into your makefile:

    CFLAGS += $(shell pkg-config --cflags recovery)
LDLIBS += $(shell pkg-config --libs --static recovery)

Implemented functions

These are the functions implemented on the current release:

Function Description

int update_firmware(const char *swu_path)

Configures recovery commands to update the firmware using the package specified in swu_path. It returns 0 on success, -1 on failure.

To start the update process you must call the reboot_recovery() function after this one.

int update_image_set_firmware(const char *swu_path, const char *swu_image_set)

Configures recovery commands to update the firmware of a swu image set, swu_image_set, using the package specified in swu_path. It returns 0 on success, -1 on failure.

To start the update process you must call the reboot_recovery() function after this one.

int reboot_recovery(unsigned int reboot_timeout)

Reboots into recovery mode after reboot_timeout seconds. It returns -1 on failure, otherwise it does not return, the system reboots.

The configured recovery commands will be applied after booting in recovery mode.

int wipe_update_partition(void)

Configures recovery commands to wipe and format the update partition. It returns 0 on success, -1 on failure.

To start the wipe process you must call reboot_recovery() function after this one.

Example code

The following excerpt (not directly compilable) demonstrates how to use the library:

#include <recovery.h>

int main(int argc, char *argv[])
{
	int ret = 0;
	unsigned char need_reboot = 0;

	/* Read and parse command line */
	parse_options(argc, argv);

	/*
	 * Variables after parsing command line:
	 *
	 * swu_package:		path to the software update package
	 * wipe_update:		boolean flag to wipe or not the 'update' partition
	 * reboot_timeout:	time to wait to perform the reboot
	 */

	if (swu_package) {
		/* Configure recovery commands to update the firmware */
		ret = update_firmware(swu_package);
		if (ret) {
			printf("Error: update_firmware\n");
			goto out;
		}
		need_reboot++;
	}

	if (wipe_update) {
		/* Configure recovery commands to format 'update' partition */
		ret = wipe_update_partition();
		if (ret) {
			printf("Error: wipe_update_partition\n");
			goto out;
		}
		need_reboot++;
	}

	if (need_reboot > 0) {
		/* Reboot to recovery */
		ret = reboot_recovery(reboot_timeout);
		if (ret) {
			printf("Error: reboot_recovery\n");
			goto out;
		}
	}

	printf("\nNo recovery commands configured.\n");
out:
	return ret;
}