diff --git a/components/esp_https_ota/include/esp_https_ota.h b/components/esp_https_ota/include/esp_https_ota.h index 9e9b43232c..9dee205c5b 100644 --- a/components/esp_https_ota/include/esp_https_ota.h +++ b/components/esp_https_ota/include/esp_https_ota.h @@ -53,9 +53,9 @@ typedef struct { * reads image data from HTTP stream and writes it to OTA partition and * finishes HTTPS OTA Firmware upgrade operation. * This API supports URL redirection, but if CA cert of URLs differ then it - * should be appended to `cert_pem` member of `config`. + * should be appended to `cert_pem` member of `ota_config->http_config`. * - * @param[in] config pointer to esp_http_client_config_t structure. + * @param[in] ota_config pointer to esp_https_ota_config_t structure. * * @note This API handles the entire OTA operation, so if this API is being used * then no other APIs from `esp_https_ota` component should be called. @@ -72,7 +72,7 @@ typedef struct { * - 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); +esp_err_t esp_https_ota(const esp_https_ota_config_t *ota_config); /** * @brief Start HTTPS OTA Firmware upgrade @@ -99,7 +99,7 @@ esp_err_t esp_https_ota(const esp_http_client_config_t *config); * - For other return codes, refer documentation in app_update component and esp_http_client * component in esp-idf. */ -esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle); +esp_err_t esp_https_ota_begin(const esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle); /** * @brief Read image data from HTTP stream and write it to OTA partition diff --git a/components/esp_https_ota/src/esp_https_ota.c b/components/esp_https_ota/src/esp_https_ota.c index 98ff25cf7d..4ca82a478b 100644 --- a/components/esp_https_ota/src/esp_https_ota.c +++ b/components/esp_https_ota/src/esp_https_ota.c @@ -191,13 +191,13 @@ static esp_err_t _ota_write(esp_https_ota_t *https_ota_handle, const void *buffe return err; } -static bool is_server_verification_enabled(esp_https_ota_config_t *ota_config) { +static bool is_server_verification_enabled(const esp_https_ota_config_t *ota_config) { return (ota_config->http_config->cert_pem || ota_config->http_config->use_global_ca_store || ota_config->http_config->crt_bundle_attach != NULL); } -esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle) +esp_err_t esp_https_ota_begin(const esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle) { esp_err_t err; @@ -648,19 +648,15 @@ int esp_https_ota_get_image_size(esp_https_ota_handle_t https_ota_handle) return handle->image_length; } -esp_err_t esp_https_ota(const esp_http_client_config_t *config) +esp_err_t esp_https_ota(const esp_https_ota_config_t *ota_config) { - if (!config) { - ESP_LOGE(TAG, "esp_http_client config not found"); + if (ota_config == NULL || ota_config->http_config == NULL) { + ESP_LOGE(TAG, "esp_https_ota: Invalid argument"); return ESP_ERR_INVALID_ARG; } - esp_https_ota_config_t ota_config = { - .http_config = config, - }; - esp_https_ota_handle_t https_ota_handle = NULL; - esp_err_t err = esp_https_ota_begin(&ota_config, &https_ota_handle); + esp_err_t err = esp_https_ota_begin(ota_config, &https_ota_handle); if (https_ota_handle == NULL) { return ESP_FAIL; } diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst index 4bbebd1c26..ed5123eeb5 100644 --- a/docs/en/api-reference/system/esp_https_ota.rst +++ b/docs/en/api-reference/system/esp_https_ota.rst @@ -20,7 +20,10 @@ Application Example .url = CONFIG_FIRMWARE_UPGRADE_URL, .cert_pem = (char *)server_cert_pem_start, }; - esp_err_t ret = esp_https_ota(&config); + esp_https_ota_config_t ota_config = { + .http_config = &config, + }; + esp_err_t ret = esp_https_ota(&ota_config); if (ret == ESP_OK) { esp_restart(); } else { @@ -47,6 +50,21 @@ Signature Verification For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates` +Advanced APIs +------------- + +``esp_https_ota`` also provides advanced APIs which can be used if more information and control is needed during the OTA process. + +Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_https_ota`. + + +OTA Upgrades with Pre-Encrypted Firmware +---------------------------------------- + +To perform OTA upgrades with Pre-Encrypted Firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component menuconfig. + +Example that performs OTA upgrade with Pre-Encrypted Firmware: :example:`system/ota/pre_encrypted_ota`. + API Reference ------------- diff --git a/docs/en/migration-guides/protocols.rst b/docs/en/migration-guides/protocols.rst index 3916fdcb48..cfc0c934de 100644 --- a/docs/en/migration-guides/protocols.rst +++ b/docs/en/migration-guides/protocols.rst @@ -72,3 +72,12 @@ Names of variables holding different certs in :cpp:type:`httpd_ssl_config_t` str * :cpp:member:`servercert_len` variable inherits role of :cpp:member:`cacert_len` variable * :cpp:member:`cacert_pem` variable inherits role of :cpp:member:`client_verify_cert_pem` variable * :cpp:member:`cacert_len` variable inherits role of :cpp:member:`client_verify_cert_len` variable + + +ESP HTTPS OTA +-------------- + +Breaking Changes (Summary) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The function :cpp:func:`esp_https_ota()` now requires pointer to :cpp:type:`esp_https_ota_config_t` as argument instead of pointer to :cpp:type:`esp_http_client_config_t`. diff --git a/examples/system/ota/simple_ota_example/main/simple_ota_example.c b/examples/system/ota/simple_ota_example/main/simple_ota_example.c index 33679ece75..6de619cd1e 100644 --- a/examples/system/ota/simple_ota_example/main/simple_ota_example.c +++ b/examples/system/ota/simple_ota_example/main/simple_ota_example.c @@ -121,8 +121,11 @@ void simple_ota_example_task(void *pvParameter) config.skip_cert_common_name_check = true; #endif + esp_https_ota_config_t ota_config = { + .http_config = &config, + }; ESP_LOGI(TAG, "Attempting to download update from %s", config.url); - esp_err_t ret = esp_https_ota(&config); + esp_err_t ret = esp_https_ota(&ota_config); if (ret == ESP_OK) { esp_restart(); } else {