Merge branch 'bugfix/ota_documentation' into 'master'

Update OTA README, set custom headers in esp_https_ota

Closes IDFGH-3535 and IDFGH-3619

See merge request espressif/esp-idf!10053

components/esp_https_ota/include/esp_https_ota.h

@@ -22,12 +22,14 @@ extern "C" {
 #endif
 
 typedef void *esp_https_ota_handle_t;
+typedef esp_err_t(*http_client_init_cb_t)(esp_http_client_handle_t);
 
 /**
  * @brief ESP HTTPS OTA configuration
  */
 typedef struct {
     const esp_http_client_config_t *http_config;   /*!< ESP HTTP client configuration */
+    http_client_init_cb_t http_client_init_cb;     /*!< Callback after ESP HTTP client is initialised */
 } esp_https_ota_config_t;
 
 #define ESP_ERR_HTTPS_OTA_BASE            (0x9000)

components/esp_https_ota/src/esp_https_ota.c

@@ -173,6 +173,14 @@ esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_
         goto failure;
     }
 
+    if (ota_config->http_client_init_cb) {
+        err = ota_config->http_client_init_cb(https_ota_handle->http_client);
+        if (err != ESP_OK) {
+            ESP_LOGE(TAG, "http_client_init_cb returned %d", err);
+            goto failure;
+        }
+    }
+
     err = _http_connect(https_ota_handle->http_client);
     if (err != ESP_OK) {
         ESP_LOGE(TAG, "Failed to establish HTTP connection");

examples/system/ota/README.md

@@ -9,7 +9,9 @@ ESP32 application can do upgrading at runtime by downloading new image from spec
 - Using the native APIs provided by `app_update` component.
 - Using simplified APIs provided by  `esp_https_ota` component, which adds an abstraction layer over the native OTA APIs in order to upgrading with HTTPS protocol.
 
-Both methods are demonstrated in OTA Demos under `native_ota_example` and `simple_ota_example` respectively.
+Use of native APIs is demonstrated under `native_ota_example` while use of APIs provided by `esp_https_ota` component is demonstrated under `simple_ota_example` and `advanced_https_ota`.
+
+For information regarding APIs provided by `esp_https_ota` component, please refer to [ESP HTTPS OTA](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_https_ota.html).
 
 For simplicity, the OTA examples choose the pre-defined partition table by enabling `CONFIG_PARTITION_TABLE_TWO_OTA` option in menuconfig, which supports three app partitions: factory, OTA_0 and OTA_1. For more information about partition table, please refer to [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html).
 

examples/system/ota/advanced_https_ota/README.md

@@ -0,0 +1,7 @@
+# Advanced HTTPS OTA example
+
+This example is based on `esp_https_ota` component's APIs.
+
+## Configuration
+
+Refer README.md in the parent directory for setup details

examples/system/ota/advanced_https_ota/main/advanced_https_ota_example.c

@@ -52,6 +52,14 @@ static esp_err_t validate_image_header(esp_app_desc_t *new_app_info)
     return ESP_OK;
 }
 
+static esp_err_t _http_client_init_cb(esp_http_client_handle_t http_client)
+{
+    esp_err_t err = ESP_OK;
+    /* Uncomment to add custom headers to HTTP request */
+    // err = esp_http_client_set_header(http_client, "Custom-Header", "Value");
+    return err;
+}
+
 void advanced_ota_example_task(void *pvParameter)
 {
     ESP_LOGI(TAG, "Starting Advanced OTA example");
@@ -83,6 +91,7 @@ void advanced_ota_example_task(void *pvParameter)
 
     esp_https_ota_config_t ota_config = {
         .http_config = &config,
+        .http_client_init_cb = _http_client_init_cb, // Register a callback to be invoked after esp_http_client is initialized
     };
 
     esp_https_ota_handle_t https_ota_handle = NULL;