From 9a9af61cec9970bbe9c185c0d352477ee92534ab Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 22 Oct 2020 19:41:02 +1100 Subject: [PATCH] doc: Add note about bootloader version compatibility --- docs/en/api-guides/bootloader.rst | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 6f39247945..6931815ac1 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -10,15 +10,23 @@ Bootloader performs the following functions: Bootloader is located at the address `0x1000` in the flash. -FACTORY reset ---------------------------- -The user can write a basic working firmware and load it into the factory partition. -Next, update the firmware via OTA (over the air). The updated firmware will be loaded into an OTA app partition slot and the OTA data partition is updated to boot from this partition. -If you want to be able to roll back to the factory firmware and clear the settings, then you need to set :ref:`CONFIG_BOOTLOADER_FACTORY_RESET`. -The factory reset mechanism allows to reset the device to factory settings: +Bootloader compatibility +------------------------ -- Clear one or more data partitions. -- Boot from "factory" partition. +It is recommended to update to newer :doc:`versions of ESP-IDF `: when they are released. The OTA (over the air) update process can flash new apps in the field but cannot flash a new bootloader. For this reason, the bootloader supports booting apps built from newer versions of ESP-IDF. + +The bootloader does not support booting apps from older versions of ESP-IDF. When updating ESP-IDF manually on an existing product that might need to downgrade the app to an older version, keep using the older ESP-IDF bootloader binary as well. + +Factory reset +------------- +The user can write a basic working firmware and load it into the factory app partition. + +Next, update the firmware via OTA (over the air). The updated firmware will be loaded into an OTA app partition slot and the OTA data partition is updated to boot from this partition. + +If you want to be able to roll back to the factory firmware and clear the settings, then you need to set :ref:`CONFIG_BOOTLOADER_FACTORY_RESET`. The factory reset mechanism allows to reset the device to factory settings: + +- Clear one or more data partitions. +- Boot from "factory" partition. :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` allows customers to select which data partitions will be erased when the factory reset is executed. Can specify the names of partitions through comma-delimited with optional spaces for readability. (Like this: "nvs, phy_init, nvs_custom, ..."). @@ -45,8 +53,8 @@ Partition table.:: .. _bootloader_boot_from_test_firmware: -Boot from TEST firmware ------------------------- +Boot from test app partition +---------------------------- The user can write a special firmware for testing in production, and run it as needed. The partition table also needs a dedicated partition for this testing firmware (See `partition table`). To trigger a test app you need to set :ref:`CONFIG_BOOTLOADER_APP_TEST`.