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

esp_https_ota: Add esp_https_ota component (Backport v3.1)

See merge request idf/esp-idf!2954

Author: projectgus

components/esp_http_client/esp_http_client.c

@@ -273,7 +273,7 @@ esp_err_t esp_http_client_delete_header(esp_http_client_handle_t client, const c
     return http_header_delete(client->request->headers, key);
 }
 
-static esp_err_t _set_config(esp_http_client_handle_t client, esp_http_client_config_t *config)
+static esp_err_t _set_config(esp_http_client_handle_t client, const esp_http_client_config_t *config)
 {
     client->connection_info.method = config->method;
     client->connection_info.port = config->port;
@@ -411,7 +411,7 @@ static esp_err_t esp_http_client_prepare(esp_http_client_handle_t client)
     return ESP_OK;
 }
 
-esp_http_client_handle_t esp_http_client_init(esp_http_client_config_t *config)
+esp_http_client_handle_t esp_http_client_init(const esp_http_client_config_t *config)
 {
 
     esp_http_client_handle_t client;
@@ -992,3 +992,14 @@ bool esp_http_client_is_chunked_response(esp_http_client_handle_t client)
 {
     return client->response->is_chunked;
 }
+
+esp_http_client_transport_t esp_http_client_get_transport_type(esp_http_client_handle_t client)
+{
+    if (!strcmp(client->connection_info.scheme, "https") ) {
+        return HTTP_TRANSPORT_OVER_SSL;
+    } else if (!strcmp(client->connection_info.scheme, "http")) {
+        return HTTP_TRANSPORT_OVER_TCP;
+    } else {
+        return HTTP_TRANSPORT_UNKNOWN;
+    }
+}

components/esp_http_client/include/esp_http_client.h

@@ -131,7 +131,7 @@ typedef struct {
  *     - `esp_http_client_handle_t`
  *     - NULL if any errors
  */
-esp_http_client_handle_t esp_http_client_init(esp_http_client_config_t *config);
+esp_http_client_handle_t esp_http_client_init(const esp_http_client_config_t *config);
 
 /**
  * @brief      Invoke this function after `esp_http_client_init` and all the options calls are made, and will perform the
@@ -334,11 +334,22 @@ esp_err_t esp_http_client_close(esp_http_client_handle_t client);
  */
 esp_err_t esp_http_client_cleanup(esp_http_client_handle_t client);
 
+/**
+ * @brief      Get transport type
+ *
+ * @param[in]  client   The esp_http_client handle
+ *
+ * @return
+ *     - HTTP_TRANSPORT_UNKNOWN
+ *     - HTTP_TRANSPORT_OVER_TCP
+ *     - HTTP_TRANSPORT_OVER_SSL
+ */
+esp_http_client_transport_t esp_http_client_get_transport_type(esp_http_client_handle_t client);
 
 
 #ifdef __cplusplus
 }
 #endif
 
 
-#endif
+#endif

components/esp_https_ota/component.mk

@@ -0,0 +1,3 @@
+COMPONENT_SRCDIRS := src
+
+COMPONENT_ADD_INCLUDEDIRS := include

components/esp_https_ota/include/esp_https_ota.h

@@ -0,0 +1,45 @@
+// Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <esp_http_client.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief    HTTPS OTA Firmware upgrade.
+ *
+ * This function performs HTTPS OTA Firmware upgrade
+ *
+ * @param[in]  config       pointer to esp_http_client_config_t structure.
+ *
+ * @note     For secure HTTPS updates, the `cert_pem` member of `config`
+ *           structure must be set to the server certificate.
+ *
+ * @return
+ *    - ESP_OK: OTA data updated, next reboot will use specified partition.
+ *    - ESP_FAIL: For generic failure.
+ *    - ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image
+ *    - ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation.
+ *    - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed.
+ *    - For other return codes, refer OTA documentation in esp-idf's app_update component.
+ */
+esp_err_t esp_https_ota(const esp_http_client_config_t *config);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_https_ota/src/esp_https_ota.c

@@ -0,0 +1,130 @@
+// Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <esp_https_ota.h>
+#include <esp_ota_ops.h>
+#include <esp_log.h>
+
+#define OTA_BUF_SIZE 256
+static const char *TAG = "esp_https_ota";
+
+static void http_cleanup(esp_http_client_handle_t client)
+{
+    esp_http_client_close(client);
+    esp_http_client_cleanup(client);
+}
+
+esp_err_t esp_https_ota(const esp_http_client_config_t *config)
+{
+    if (!config) {
+        ESP_LOGE(TAG, "esp_http_client config not found");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    if (!config->cert_pem) {
+        ESP_LOGE(TAG, "Server certificate not found in esp_http_client config");
+        return ESP_FAIL;
+    }
+
+    esp_http_client_handle_t client = esp_http_client_init(config);
+    if (client == NULL) {
+        ESP_LOGE(TAG, "Failed to initialise HTTP connection");
+        return ESP_FAIL;
+    }
+
+    if (esp_http_client_get_transport_type(client) != HTTP_TRANSPORT_OVER_SSL) {
+        ESP_LOGE(TAG, "Transport is not over HTTPS");
+        return ESP_FAIL;
+    }
+
+    esp_err_t err = esp_http_client_open(client, 0);
+    if (err != ESP_OK) {
+        esp_http_client_cleanup(client);
+        ESP_LOGE(TAG, "Failed to open HTTP connection: %s", esp_err_to_name(err));
+        return err;
+    }
+    esp_http_client_fetch_headers(client);
+
+    esp_ota_handle_t update_handle = 0;
+    const esp_partition_t *update_partition = NULL;
+    ESP_LOGI(TAG, "Starting OTA...");
+    update_partition = esp_ota_get_next_update_partition(NULL);
+    if (update_partition == NULL) {
+        ESP_LOGE(TAG, "Passive OTA partition not found");
+        http_cleanup(client);
+        return ESP_FAIL;
+    }
+    ESP_LOGI(TAG, "Writing to partition subtype %d at offset 0x%x",
+             update_partition->subtype, update_partition->address);
+
+    err = esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "esp_ota_begin failed, error=%d", err);
+        http_cleanup(client);
+        return err;
+    }
+    ESP_LOGI(TAG, "esp_ota_begin succeeded");
+    ESP_LOGI(TAG, "Please Wait. This may take time");
+
+    esp_err_t ota_write_err = ESP_OK;
+    char *upgrade_data_buf = (char *)malloc(OTA_BUF_SIZE);
+    if (!upgrade_data_buf) {
+        ESP_LOGE(TAG, "Couldn't allocate memory to upgrade data buffer");
+        return ESP_ERR_NO_MEM;
+    }
+    int binary_file_len = 0;
+    while (1) {
+        int data_read = esp_http_client_read(client, upgrade_data_buf, OTA_BUF_SIZE);
+        if (data_read == 0) {
+            ESP_LOGI(TAG, "Connection closed,all data received");
+            break;
+        }
+        if (data_read < 0) {
+            ESP_LOGE(TAG, "Error: SSL data read error");
+            break;
+        }
+        if (data_read > 0) {
+            ota_write_err = esp_ota_write( update_handle, (const void *)upgrade_data_buf, data_read);
+            if (ota_write_err != ESP_OK) {
+                break;
+            }
+            binary_file_len += data_read;
+            ESP_LOGD(TAG, "Written image length %d", binary_file_len);
+        }
+    }
+    free(upgrade_data_buf);
+    http_cleanup(client); 
+    ESP_LOGD(TAG, "Total binary data length writen: %d", binary_file_len);
+    
+    esp_err_t ota_end_err = esp_ota_end(update_handle);
+    if (ota_write_err != ESP_OK) {
+        ESP_LOGE(TAG, "Error: esp_ota_write failed! err=0x%d", err);
+        return ota_write_err;
+    } else if (ota_end_err != ESP_OK) {
+        ESP_LOGE(TAG, "Error: esp_ota_end failed! err=0x%d. Image is invalid", ota_end_err);
+        return ota_end_err;
+    }
+
+    err = esp_ota_set_boot_partition(update_partition);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "esp_ota_set_boot_partition failed! err=0x%d", err);
+        return err;
+    }
+    ESP_LOGI(TAG, "esp_ota_set_boot_partition succeeded"); 
+
+    return ESP_OK;
+}

docs/Doxyfile

@@ -142,6 +142,8 @@ INPUT = \
     ../../components/esp32/include/esp_ipc.h \
     ## Over The Air Updates (OTA)
     ../../components/app_update/include/esp_ota_ops.h \
+    ## ESP HTTPS OTA
+    ../../components/esp_https_ota/include/esp_https_ota.h \
     ## Sleep
     ## NOTE: for line below header_file.inc is not used
     ../../components/esp32/include/esp_sleep.h \

docs/en/api-reference/system/esp_https_ota.rst

@@ -0,0 +1,35 @@
+ESP HTTPS OTA
+=============
+
+Overview
+--------
+
+``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS.
+It's an abstraction layer over existing OTA APIs.
+
+Application Example
+-------------------
+
+    .. highlight:: c
+
+    ::
+
+        esp_err_t do_firmware_upgrade()
+        {
+            esp_http_client_config_t config = {
+                .url = CONFIG_FIRMWARE_UPGRADE_URL,
+                .cert_pem = (char *)server_cert_pem_start,
+            };
+            esp_err_t ret = esp_https_ota(&config);
+            if (ret == ESP_OK) {
+                esp_restart();
+            } else {
+                return ESP_FAIL;
+            }
+            return ESP_OK;
+        }
+
+API Reference
+-------------
+
+.. include:: /_build/inc/esp_https_ota.inc

docs/en/api-reference/system/index.rst

@@ -18,6 +18,7 @@ System API
    Sleep Modes <sleep_modes>
    Base MAC address <base_mac_address>
    Over The Air Updates (OTA) <ota>
+   ESP HTTPS OTA <esp_https_ota>
    ESP pthread <esp_pthread>
    Error Codes and Helper Functions <esp_err>
 

docs/en/api-reference/system/ota.rst

@@ -37,6 +37,7 @@ See also
 
 * :doc:`Partition Table documentation <../../api-guides/partition-tables>`
 * :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>`
+* :doc:`ESP HTTPS OTA <esp_https_ota>`
 
 Application Example
 -------------------

docs/zh_CN/api-reference/system/esp_https_ota.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/system/esp_https_ota.rst