1 // Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include <esp_http_client.h> 18 #include <bootloader_common.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 typedef void *esp_https_ota_handle_t; 25 typedef esp_err_t(*http_client_init_cb_t)(esp_http_client_handle_t); 26 27 /** 28 * @brief ESP HTTPS OTA configuration 29 */ 30 typedef struct { 31 const esp_http_client_config_t *http_config; /*!< ESP HTTP client configuration */ 32 http_client_init_cb_t http_client_init_cb; /*!< Callback after ESP HTTP client is initialised */ 33 bool bulk_flash_erase; /*!< Erase entire flash partition during initialization. By default flash partition is erased during write operation and in chunk of 4K sector size */ 34 bool partial_http_download; /*!< Enable Firmware image to be downloaded over multiple HTTP requests */ 35 int max_http_request_size; /*!< Maximum request size for partial HTTP download */ 36 } esp_https_ota_config_t; 37 38 #define ESP_ERR_HTTPS_OTA_BASE (0x9000) 39 #define ESP_ERR_HTTPS_OTA_IN_PROGRESS (ESP_ERR_HTTPS_OTA_BASE + 1) /* OTA operation in progress */ 40 41 /** 42 * @brief HTTPS OTA Firmware upgrade. 43 * 44 * This function allocates HTTPS OTA Firmware upgrade context, establishes HTTPS connection, 45 * reads image data from HTTP stream and writes it to OTA partition and 46 * finishes HTTPS OTA Firmware upgrade operation. 47 * This API supports URL redirection, but if CA cert of URLs differ then it 48 * should be appended to `cert_pem` member of `config`. 49 * 50 * @param[in] config pointer to esp_http_client_config_t structure. 51 * 52 * @note This API handles the entire OTA operation, so if this API is being used 53 * then no other APIs from `esp_https_ota` component should be called. 54 * If more information and control is needed during the HTTPS OTA process, 55 * then one can use `esp_https_ota_begin` and subsequent APIs. If this API returns 56 * successfully, esp_restart() must be called to boot from the new firmware image. 57 * 58 * @return 59 * - ESP_OK: OTA data updated, next reboot will use specified partition. 60 * - ESP_FAIL: For generic failure. 61 * - ESP_ERR_INVALID_ARG: Invalid argument 62 * - ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image 63 * - ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. 64 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. 65 * - For other return codes, refer OTA documentation in esp-idf's app_update component. 66 */ 67 esp_err_t esp_https_ota(const esp_http_client_config_t *config); 68 69 /** 70 * @brief Start HTTPS OTA Firmware upgrade 71 * 72 * This function initializes ESP HTTPS OTA context and establishes HTTPS connection. 73 * This function must be invoked first. If this function returns successfully, then `esp_https_ota_perform` should be 74 * called to continue with the OTA process and there should be a call to `esp_https_ota_finish` on 75 * completion of OTA operation or on failure in subsequent operations. 76 * This API supports URL redirection, but if CA cert of URLs differ then it 77 * should be appended to `cert_pem` member of `http_config`, which is a part of `ota_config`. 78 * In case of error, this API explicitly sets `handle` to NULL. 79 * 80 * @param[in] ota_config pointer to esp_https_ota_config_t structure 81 * @param[out] handle pointer to an allocated data of type `esp_https_ota_handle_t` 82 * which will be initialised in this function 83 * 84 * @note This API is blocking, so setting `is_async` member of `http_config` structure will 85 * result in an error. 86 * 87 * @return 88 * - ESP_OK: HTTPS OTA Firmware upgrade context initialised and HTTPS connection established 89 * - ESP_FAIL: For generic failure. 90 * - ESP_ERR_INVALID_ARG: Invalid argument (missing/incorrect config, certificate, etc.) 91 * - For other return codes, refer documentation in app_update component and esp_http_client 92 * component in esp-idf. 93 */ 94 esp_err_t esp_https_ota_begin(esp_https_ota_config_t *ota_config, esp_https_ota_handle_t *handle); 95 96 /** 97 * @brief Read image data from HTTP stream and write it to OTA partition 98 * 99 * This function reads image data from HTTP stream and writes it to OTA partition. This function 100 * must be called only if esp_https_ota_begin() returns successfully. 101 * This function must be called in a loop since it returns after every HTTP read operation thus 102 * giving you the flexibility to stop OTA operation midway. 103 * 104 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 105 * 106 * @return 107 * - ESP_ERR_HTTPS_OTA_IN_PROGRESS: OTA update is in progress, call this API again to continue. 108 * - ESP_OK: OTA update was successful 109 * - ESP_FAIL: OTA update failed 110 * - ESP_ERR_INVALID_ARG: Invalid argument 111 * - ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image 112 * - ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. 113 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. 114 * - For other return codes, refer OTA documentation in esp-idf's app_update component. 115 */ 116 esp_err_t esp_https_ota_perform(esp_https_ota_handle_t https_ota_handle); 117 118 /** 119 * @brief Checks if complete data was received or not 120 * 121 * @note This API can be called just before esp_https_ota_finish() to validate if the complete image was indeed received. 122 * 123 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 124 * 125 * @return 126 * - false 127 * - true 128 */ 129 bool esp_https_ota_is_complete_data_received(esp_https_ota_handle_t https_ota_handle); 130 131 /** 132 * @brief Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection 133 * 134 * This function closes the HTTP connection and frees the ESP HTTPS OTA context. 135 * This function switches the boot partition to the OTA partition containing the 136 * new firmware image. 137 * 138 * @note If this API returns successfully, esp_restart() must be called to 139 * boot from the new firmware image 140 * esp_https_ota_finish should not be called after calling esp_https_ota_abort 141 * 142 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 143 * 144 * @return 145 * - ESP_OK: Clean-up successful 146 * - ESP_ERR_INVALID_STATE 147 * - ESP_ERR_INVALID_ARG: Invalid argument 148 * - ESP_ERR_OTA_VALIDATE_FAILED: Invalid app image 149 */ 150 esp_err_t esp_https_ota_finish(esp_https_ota_handle_t https_ota_handle); 151 152 153 /** 154 * @brief Clean-up HTTPS OTA Firmware upgrade and close HTTPS connection 155 * 156 * This function closes the HTTP connection and frees the ESP HTTPS OTA context. 157 * 158 * @note esp_https_ota_abort should not be called after calling esp_https_ota_finish 159 * 160 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 161 * 162 * @return 163 * - ESP_OK: Clean-up successful 164 * - ESP_ERR_INVALID_STATE: Invalid ESP HTTPS OTA state 165 * - ESP_FAIL: OTA not started 166 * - ESP_ERR_NOT_FOUND: OTA handle not found 167 * - ESP_ERR_INVALID_ARG: Invalid argument 168 */ 169 esp_err_t esp_https_ota_abort(esp_https_ota_handle_t https_ota_handle); 170 171 172 /** 173 * @brief Reads app description from image header. The app description provides information 174 * like the "Firmware version" of the image. 175 * 176 * @note This API can be called only after esp_https_ota_begin() and before esp_https_ota_perform(). 177 * Calling this API is not mandatory. 178 * 179 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 180 * @param[out] new_app_info pointer to an allocated esp_app_desc_t structure 181 * 182 * @return 183 * - ESP_ERR_INVALID_ARG: Invalid arguments 184 * - ESP_FAIL: Failed to read image descriptor 185 * - ESP_OK: Successfully read image descriptor 186 */ 187 esp_err_t esp_https_ota_get_img_desc(esp_https_ota_handle_t https_ota_handle, esp_app_desc_t *new_app_info); 188 189 190 /** 191 * @brief This function returns OTA image data read so far. 192 * 193 * @note This API should be called only if `esp_https_ota_perform()` has been called atleast once or 194 * if `esp_https_ota_get_img_desc` has been called before. 195 * 196 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 197 * 198 * @return 199 * - -1 On failure 200 * - total bytes read so far 201 */ 202 int esp_https_ota_get_image_len_read(esp_https_ota_handle_t https_ota_handle); 203 204 205 /** 206 * @brief This function returns OTA image total size. 207 * 208 * @note This API should be called after esp_https_ota_begin() has been already called. 209 * This can be used to create some sort of progress indication 210 * (in combination with esp_https_ota_get_image_len_read()) 211 * 212 * @param[in] https_ota_handle pointer to esp_https_ota_handle_t structure 213 * 214 * @return 215 * - -1 On failure or chunked encoding 216 * - total bytes of image 217 */ 218 int esp_https_ota_get_image_size(esp_https_ota_handle_t https_ota_handle); 219 #ifdef __cplusplus 220 } 221 #endif 222
