Chapter 2. API Reference
App rollback
The main purpose of the application rollback is to keep the device working after the update. This feature allows
you to roll back to the previous working application in case a new application has critical errors. When the rollback
process is enabled and an OTA update provides a new version of the app, one of three things can happen:
• The application works fine, esp_ota_mark_app_valid_cancel_rollback() marks the running
application with the state ESP_OTA_IMG_VALID. There are no restrictions on booting this application.
• The application has critical errors and further work is not possible, a rollback to the previous application is re-
quired, esp_ota_mark_app_invalid_rollback_and_reboot() marks the running application
with the state ESP_OTA_IMG_INVALID and reset. This application will not be selected by the bootloader
for boot and will boot the previously working application.
• If the CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set, and a reset occurs without calling
either function then the application is rolled back.
Note: The state is not written to the binary image of the application it is written to the otadata partition. The
partition contains a ota_seq counter which is a pointer to the slot (ota_0, ota_1, …) from which the application
will be selected for boot.
App OTA State States control the process of selecting a boot app:
States Restriction of selecting a boot app in bootloader
ESP_OTA_IMG_VALIDNone restriction. Will be selected.
ESP_OTA_IMG_UNDEFINEDNone restriction. Will be selected.
ESP_OTA_IMG_INVALIDWill not be selected.
ESP_OTA_IMG_ABORTEDWill not be selected.
ESP_OTA_IMG_NEWIf CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set it will
be selected only once. In bootloader the state immediately changes to
ESP_OTA_IMG_PENDING_VERIFY.
ESP_OTA_IMG_PENDING_VERIFYIf CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is set it will not be se-
lected and the state will change to ESP_OTA_IMG_ABORTED.
If CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is not enabled (by default), then
the use of the following functions esp_ota_mark_app_valid_cancel_rollback() and
esp_ota_mark_app_invalid_rollback_and_reboot() are optional, and ESP_OTA_IMG_NEW and
ESP_OTA_IMG_PENDING_VERIFY states are not used.
An option in Kconfig CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE allows you to track the first
boot of a new application. In this case, the application must confirm its operability by calling
esp_ota_mark_app_valid_cancel_rollback() function, otherwise the application will be rolled back
upon reboot. It allows you to control the operability of the application during the boot phase. Thus, a new application
has only one attempt to boot successfully.
Rollback Process The description of the rollback process when CON-
FIG_BOOTLOADER_APP_ROLLBACK_ENABLE option is enabled:
• The new application successfully downloaded and esp_ota_set_boot_partition() function makes
this partition bootable and sets the state ESP_OTA_IMG_NEW. This state means that the application is new
and should be monitored for its first boot.
• Reboot esp_restart().
• The bootloader checks for the ESP_OTA_IMG_PENDING_VERIFY state if it is set, then it will be written
to ESP_OTA_IMG_ABORTED.
• The bootloader selects a new application to boot so that the state is not set as ESP_OTA_IMG_INVALID or
ESP_OTA_IMG_ABORTED.
• The bootloader checks the selected application for ESP_OTA_IMG_NEW state if it is set, then it will
be written to ESP_OTA_IMG_PENDING_VERIFY. This state means that the application requires con-
firmation of its operability, if this does not happen and a reboot occurs, this state will be overwritten to
Espressif Systems 1017
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General