RainMaker OTA

Functions

esp_err_t esp_rmaker_ota_enable(esp_rmaker_ota_config_t *ota_config, esp_rmaker_ota_type_t type)

Enable OTA

Calling this API enables OTA as per the ESP RainMaker specification. Please check the various ESP RainMaker configuration options to use the different variants of OTA. Refer the documentation for additional details.

Return

ESP_OK on success

Return

error on failure

Parameters
  • [in] ota_config: Pointer to an OTA configuration structure

  • [in] type: The OTA workflow type

esp_err_t esp_rmaker_ota_report_status(esp_rmaker_ota_handle_t ota_handle, ota_status_t status, char *additional_info)

Report OTA Status

This API must be called from the OTA Callback to indicate the status of the OTA. The OTA_STATUS_IN_PROGRESS can be reported multiple times with appropriate additional information. The final success/failure should be reported only once, at the end.

This can be ignored if you are using the default internal OTA callback.

Return

ESP_OK on success

Return

error on failure

Parameters
  • [in] ota_handle: The OTA handle received by the callback

  • [in] status: Status to be reported

  • [in] additional_info: NULL terminated string indicating additional information for the status

Structures

struct esp_rmaker_ota_data_t

OTA Data

Public Members

char *url

The OTA URL received from ESP RainMaker Cloud

int filesize

Size of the OTA File. Can be 0 if the file size isn’t received from the ESP RainMaker Cloud

const char *server_cert

The server certificate passed in esp_rmaker_enable_ota()

char *priv

The private data passed in esp_rmaker_enable_ota()

struct esp_rmaker_ota_config_t

ESP RainMaker OTA Configuration

Public Members

esp_rmaker_ota_cb_t ota_cb

OTA Callback. The callback to be invoked when an OTA Job is available. If kept NULL, the internal default callback will be used (Recommended).

esp_rmaker_post_ota_diag_t ota_diag

OTA Diagnostics Callback. A post OTA diagnostic handler to be invoked if app rollback feature is enabled. If kept NULL, the new firmware will be assumed to be fine, and no rollback will be performed.

const char *server_cert

Server Certificate. The certificate to be passed to the OTA callback for server authentication. This is mandatory, unless you have disabled it in ESP HTTPS OTA config option. If you are using the ESP RainMaker OTA Service, you can just set this to ESP_RMAKER_DEFAULT_OTA_SERVER_CERT.

void *priv

Private Data. Optional private data to be passed to the OTA callback.

Type Definitions

typedef void *esp_rmaker_ota_handle_t

The OTA Handle to be used by the OTA callback

typedef esp_err_t (*esp_rmaker_ota_cb_t)(esp_rmaker_ota_handle_t handle, esp_rmaker_ota_data_t *ota_data)

Function prototype for OTA Callback

This function will be invoked by the ESP RainMaker core whenever an OTA is available. The esp_rmaker_report_ota_status() API should be used to indicate the progress and success/fail status.

Return

ESP_OK if the OTA was successful

Return

ESP_FAIL if the OTA failed.

Parameters
  • [in] handle: An OTA handle assigned by the ESP RainMaker Core

  • [in] ota_data: The data to be used for the OTA

typedef bool (*esp_rmaker_post_ota_diag_t)(void)

Function Prototype for Post OTA Diagnostics

If the Application rollback feature is enabled, this callback will be invoked as soon as you call esp_rmaker_ota_enable(), if it is the first boot after an OTA. You may perform some application specific diagnostics and report the status which will decide whether to roll back or not.

Return

true if diagnostics are successful, meaning that the new firmware is fine.

Return

false if diagnostics fail and a roolback to previous firmware is required.

Enumerations

enum ota_status_t

OTA Status to be reported to ESP RainMaker Cloud

Values:

OTA_STATUS_IN_PROGRESS = 1

OTA is in Progress. This can be reported multiple times as the OTA progresses.

OTA_STATUS_SUCCESS

OTA Succeeded. This should be reported only once, at the end of OTA.

OTA_STATUS_FAILED

OTA Failed. This should be reported only once, at the end of OTA.

OTA_STATUS_DELAYED

OTA was delayed by the application

enum esp_rmaker_ota_type_t

OTA Workflow type

Values:

OTA_USING_PARAMS = 1

OTA will be performed using services and parameters.

OTA_USING_TOPICS

OTA will be performed using pre-defined MQTT topics.