Merge branch 'feature/remove_raw_ota_exmaple_v3.1' into 'release/v3.1'

Update verify and document for OTA of ESP8285(ESP8266 + 1MB flash) (bakcport v3.1)

See merge request sdk/ESP8266_RTOS_SDK!745

Author: donghengqaz

components/app_update/esp_ota_ops.c

@@ -69,6 +69,28 @@ static ota_select s_ota_select[2];
 
 const static char *TAG = "esp_ota_ops";
 
+#ifndef CONFIG_ESP8266_BOOT_COPY_APP
+static inline int esp_ota_verify_binary(const esp_partition_pos_t *pos, esp_image_header_t *image)
+{
+    const int32_t entry = image->entry_addr - 0x40200010;
+
+    ESP_LOGD(TAG, "OTA binary start entry 0x%x, partition start from 0x%x to 0x%x\n", entry, pos->offset,
+                        pos->offset + pos->size);
+
+    if (pos->offset + pos->size <= 0x100000) {
+        if (entry <= 0 || entry <= pos->offset || entry >= pos->offset + pos->size) {
+            const char *doc_str = "<<ESP8266_RTOS_SDK/examples/system/ota/README.md>>";
+
+            ESP_LOGE(TAG, "**Important**: The OTA binary link data is error, "
+                          "please refer to document %s for how to generate OTA binaries", doc_str);
+            return ESP_ERR_INVALID_ARG;
+        }
+    }
+
+    return ESP_OK;
+}
+#endif
+
 /* Return true if this is an OTA app partition */
 static bool is_ota_partition(const esp_partition_t *p)
 {
@@ -244,6 +266,13 @@ esp_err_t esp_ota_end(esp_ota_handle_t handle)
         goto cleanup;
     }
 
+#ifndef CONFIG_ESP8266_BOOT_COPY_APP
+    if (esp_ota_verify_binary(&part_pos, &data.image) != ESP_OK) {
+        ret = ESP_ERR_OTA_VALIDATE_FAILED;
+        goto cleanup;
+    }
+#endif
+
 #ifdef CONFIG_SECURE_BOOT_ENABLED
     ret = esp_secure_boot_verify_signature(it->part->address, data.image_len);
     if (ret != ESP_OK) {

components/esp8266/Makefile.projbuild

@@ -94,32 +94,32 @@ OTA_V2_TO_V3_BIN  := ./build/$(PROJECT_NAME).v2_to_v3.ota.bin
 CONFIG_APP2_OFFSET ?= $(CONFIG_APP1_OFFSET)
 CONFIG_APP2_SIZE ?= $(CONFIG_APP1_SIZE)
 
-OTA1_OFFSET := CONFIG_APP1_OFFSET
+OTA1_OFFSET := $(CONFIG_APP1_OFFSET)
 ifdef CONFIG_ESP8266_BOOT_COPY_APP
 OTA2_LINK_OFFSET := $(CONFIG_APP1_OFFSET)
 else
 OTA2_LINK_OFFSET := $(CONFIG_APP2_OFFSET)
 endif
 
 $(OTA2_BIN): all_binaries
-ifeq ($(CONFIG_ESPTOOLPY_FLASHSIZE), "1MB")
+ifneq ($(OTA1_OFFSET), $(OTA2_LINK_OFFSET))
 	@rm -f ./build/esp8266/esp8266_out.ld
 	@make APP_OFFSET=$(OTA2_LINK_OFFSET) APP_SIZE=$(CONFIG_APP2_SIZE) CFLAGS= CXXFLAGS=
 endif
 	@cp $(RAW_BIN) $(OTA2_BIN)
 	@echo [GEN] $(OTA2_BIN)
 
 $(OTA1_BIN): all_binaries
-ifeq ($(CONFIG_ESPTOOLPY_FLASHSIZE), "1MB")
+ifneq ($(OTA1_OFFSET), $(OTA2_LINK_OFFSET))
 	@rm -f ./build/esp8266/esp8266_out.ld
 endif
-	@make APP_OFFSET=$(CONFIG_APP1_OFFSET) APP_SIZE=$(CONFIG_APP1_SIZE) CFLAGS= CXXFLAGS=
+	@make APP_OFFSET=$(OTA1_OFFSET) APP_SIZE=$(CONFIG_APP1_SIZE) CFLAGS= CXXFLAGS=
 	@cp $(RAW_BIN) $(OTA1_BIN)
 	@echo [GEN] $(OTA1_BIN)
 
 $(OTA_BIN): $(OTA1_BIN) $(OTA2_BIN)
 	@cp $(OTA1_BIN) $(OTA_BIN)
-ifeq ($(CONFIG_ESPTOOLPY_FLASHSIZE), "1MB")
+ifneq ($(OTA1_OFFSET), $(OTA2_LINK_OFFSET))
 	@cat $(OTA2_BIN) >> $(OTA_BIN)
 endif
 	@cp $(OTA1_BIN) $(RAW_BIN)

examples/system/ota/README.md

@@ -1,4 +1,10 @@
 
+# Important
+
+If your development board is based on **ESP8285** or **ESP8266 + 1MB flash**, you should read this document carefully, especially the Chapter **"Principle"**.
+
+---
+
 # Simple OTA Demo
 
 This example demonstrates a working OTA (over the air) firmware update workflow.
@@ -11,10 +17,68 @@ This example is a *simplified demonstration*, for production firmware updates yo
 
 An app running on ESP8266 can upgrade itself by downloading a new app "image" binary file, and storing it in flash.
 
-In this example, the ESP8266 has 3 images in flash: factory, OTA_0, OTA_1. Each of these is a self-contained partition. The number of OTA image partition is determined by the partition table layout.
+In this example, the ESP8266 has 2 images in flash: OTA_0, OTA_1. Each of these is a self-contained partition. The number of OTA image partition is determined by the partition table layout.
+
+Flash the example through serial port with command "make flash" to update the OTA_0 app image. In first boot, the bootloader loads this OTA_0 app image which then will execute an OTA update (triggered in the example code). The OTA update will download a new image from an http server and save it into the OTA_1 partition. After that, the example code will update the ota_data partition to indicate the new app partition, and then reboot, which leads to the second boot. During the second boot, the bootloader will read the ota_data, and select to run the new OTA image.
+
+# Custom partition configuration
+
+If customers want to use their own partition tables with specific partition location. Please see following steps:
+
+## Step 1: Create partition file
+
+Create a partition managment file with "cvs" formate, please refer to "doc/en/api-guides/partition-tables.rst"
+
+## Step 2: Select custom partition mode
+
+1. Select custom partition tables at "menuconfig":
+
+```
+Partition Table  --->
+    Partition Table (XXXXXX)  --->
+        (X) Custom partition table CSV
+```
+
+2. Configurate custom partition location at:
+
+```
+(XXXXXX)Custom partition CSV file
+```
+
+Note: System will add the absolute path of the project to the head of the "Custom partition CSV file" automatically when compling.
+
+3. Configurate patition table location if necessary:
+
+```
+(XXXXXX)Partition table offset address at flash
+```
+
+## Step 3: Configurate application location:
+
+Configurate application location at "mennuconfig" like following base on partition table file.
+
+If you select 1MB flash, application location configuration menu is like following:
+
+```
+Partition Table  --->
+
+    [*] Support to setup partition parameter of APP2
+    (0x5000) App1 offset address 
+    (0x7B000) App1 size by bytes 
+    (0x85000) App2 offset address
+    (0x7b000) App2 size by bytes
+```
+
+If you select 2MB flash and above size, application location configuration menu is like following:
+
+```
+Partition Table  --->
 
-Flashing the example over serial with "make flash" updates the factory app image. On first boot, the bootloader loads this factory app image which then performs an OTA update (triggered in the example code). The update downloads a new image from an http server and saves it into the OTA_0 partition. At this point the example code updates the ota_data partition to indicate the new app partition, and resets. The bootloader reads ota_data, determines the new OTA image has been selected, and runs it.
+    (0x10000) APP1 partition offset
+    (0xF0000) APP1 partition size(by bytes)
+```
 
+Note: The firmware location information must be same as partition table file. **make ota flash** will only download the app1 at **APP1 partition offset**.
 
 # Workflow
 
@@ -32,11 +96,26 @@ Python has a built-in HTTP server that can be used for example purposes.
 
 For our upgrade example OTA file, we're going to use the `get-started/project_template` example.
 
-Open a new terminal to run the HTTP server, then run these commands to build the example and start the server:
+Open a new terminal to run the HTTP server, then run these commands to build the example and start the server, if your board's flash size is "1 MB", you should firstly configure flash size to be "1 MB"(default is "2 MB") at "menuconfig" and then build project:
+
+Configure 1MB flash if it is needed:
+
+```
+Serial flasher config  --->
+    Flash size (2 MB)  --->
+        (X) 1 MB
+```
+
+Build project:
 
 ```
 cd $IDF_PATH/examples/get-started/project_template
-make
+make ota
+```
+
+Start http server at the directory of "build":
+
+```
 cd build
 python -m SimpleHTTPServer 8070
 ```
@@ -45,8 +124,6 @@ While the server is running, the contents of the build directory can be browsed
 
 NB: On some systems, the command may be `python2 -m SimpleHTTPServer`.
 
-NB: You've probably noticed there is nothing special about the "project_template" example when used for OTA updates. This is because any .bin app file which is built by esp-idf can be used as an app image for OTA. The only difference is whether it is written to a factory partition or an OTA partition.
-
 If you have any firewall software running that will block incoming access to port 8070, configure it to allow access while running the example.
 
 ## Step 3: Build OTA Example
@@ -59,6 +136,16 @@ Change back to the OTA example directory, and type `make menuconfig` to configur
 
 If serving the "project_template" example, you can leave the default filename as-is.
 
+Configure 1MB flash if need:
+
+```
+Serial flasher config  --->
+    Flash size (2 MB)  --->
+        (X) 1 MB
+```
+
+Configurate the application location information and it must be the same as the OTA example's information, you can refer to the **Step 3: Configurate application location** of **Custom partition configuration**.
+
 Save your changes, and type `make` to build the example.
 
 ## Step 4: Flash OTA Example
@@ -80,11 +167,29 @@ When the example starts up, it will print "ota: Starting OTA example..." then:
 3. Write the image to flash, and configure the next boot from this image.
 4. Reboot
 
+# Principle
+
+Command "make ota" will generate 3 binaries: "xxx(project name).app1.bin", "xxx(project name).app2.bin" and "xxx(project name).ota.bin". You should only upload the "xxx(project name).ota.bin" to your OTA server and let the app download it as the example.
+
+"xxx.app1.bin" is for downloading to OTA_0 partition, and "xxx.app2.bin" is for downloading to OTA_1 partition. If your board's flash size is larger than "1 MB" or you select "Copy OTA" function, then "xxx.app1.bin" = "xxx.app2.bin" = "xxx.ota.bin". Otherwise If your board's flash size is "1 MB" and you don't select "Copy OTA" function, "xxx.app1.bin" != "xxx.app2.bin" != "xxx.ota.bin", "xxx.ota.bin" = "xxx.app1.bin" + "xxx.app2.bin". So the flash size configuration is very important. Otherwise if and at the last The example will select the binary it needs and download it into flash.
+
+Based on the above theory, we can see that for ESP8266 + 2MB flash(or larger size), app1 and app2 are the same, you can download it directly without any distinction. But for ESP8285 (ESP8266 + 1MB flash), the ota0 (app1) and ota1 (app2) are different, you need to distinguish which one should be downloaded, and to what location, during FOTA. Now, the way in the example code is to synthesize app1 and app2 into an "xxxx (project name).ota.bin". And only write the target app (app1 or app2) into the flash, according to the location of download, when FOTA; the other part will be discarded.
+
+On the other hand, if you want to use ESP8285(ESP8266 + 1MB flash) and don't want to upload 2 binaries for OTA, you can enable the "Copy OTA" function in menuconfig.
+
+```
+Component config  --->
+    ESP8266-specific  --->
+        [*] (**Expected**)Boot copy app
+```
+
+After enabling "Copy OTA" mode, the system will always download the app bin into ota_1 partition and then re-boot. After reboot, the bootloader will unpack the app bin and copy it to the ota_0 partition, then run the application in ota_0 partition.
+
 # Troubleshooting
 
-* Check your PC can ping the ESP8266 at its IP, and that the IP, AP and other configuration settings are correct in menuconfig.
-* Check if any firewall software is preventing incoming connections on the PC.
-* Check you can see the configured file (default project_template.bin) if you browse the file listing at http://127.0.0.1/
+* Check whether your PC can ping the ESP8266 at its IP, and make sure that the IP, AP and other configuration settings are correct in menuconfig.
+* Check if there is any firewall software on the PC that prevents incoming connections.
+* Check whether you can see the configured file (default project_template.ota.bin) when browsing the file listing at http://127.0.0.1/
 * If you have another PC or a phone, try viewing the file listing from the separate host.
 
 ## Error "ota_begin error err=0x104"

examples/system/ota/main/Kconfig.projbuild

@@ -32,7 +32,7 @@ config SERVER_PORT
 
 config EXAMPLE_FILENAME
 	string "HTTP GET Filename"
-	default "/hello-world.bin"
+	default "/project_template.ota.bin"
 	help
 		Filename of the app image file to download for
 		the OTA update.