RainMaker OTA¶

Header File¶

components/esp_rainmaker/include/esp_rmaker_ota.h

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

esp_err_t esp_rmaker_ota_default_cb(esp_rmaker_ota_handle_t handle, esp_rmaker_ota_data_t *ota_data)¶

Default OTA callback

This is the default OTA callback which will get used if you do not pass your own callback. You can call this even from your callback, in case you want better control on when the OTA can proceed and yet let the actual OTA process be managed by the RainMaker Core.

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

esp_err_t esp_rmaker_ota_fetch(void)¶

Fetch OTA Info

For OTA using Topics, this API can be used to explicitly ask the backend if an OTA is available. If it is, then the OTA callback would get invoked.

Return: ESP_OK if the OTA fetch publish message was successful.
Return: error on failure

esp_err_t esp_rmaker_ota_fetch_with_delay(int time)¶

Fetch OTA Info with a delay

For OTA using Topics, this API can be used to explicitly ask the backend if an OTA is available after a delay (in seconds) passed as an argument.

Return

ESP_OK if the OTA fetch timer was created.

Return

error on failure

Parameters

[in] time: Delay (in seconds)

esp_err_t esp_rmaker_ota_mark_valid(void)¶

Mark OTA as valid

This should be called if the OTA validation has been kept pending by returning OTA_DIAG_STATUS_PENDING in the ota_diag callback and then, the validation was eventually successful. This can also be used to mark the OTA valid even before RainMaker core does its own validations (primarily MQTT connection).

Return: ESP_OK on success
Return: error on failure

esp_err_t esp_rmaker_ota_mark_invalid(void)¶

Mark OTA as invalid

This should be called if the OTA validation has been kept pending by returning OTA_DIAG_STATUS_PENDING in the ota_diag callback and then, the validation eventually failed. This can even be used to rollback at any point of time before RainMaker core’s internal logic and the application’s logic mark the OTA as valid.

Return: ESP_OK on success
Return: error on failure

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

char *fw_version¶: The firmware version of the OTA image

char *ota_job_id¶: The OTA Job ID received from 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()

char *metadata¶: OTA Metadata. Applicable only for OTA using Topics. Will be received (if applicable) from the backend, along with the OTA URL

struct esp_rmaker_ota_diag_priv_t¶

Public Members

esp_rmaker_ota_diag_state_t state¶: OTA diagnostic state

bool rmaker_ota¶: Flag to indicate whether the OTA which has triggered the Diagnostics checks for rollback was triggered via RainMaker or not. This would be useful only when your application has some other mechanism for OTA too.

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_OTA_DEFAULT_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 esp_rmaker_ota_diag_status_t (*esp_rmaker_post_ota_diag_t)(esp_rmaker_ota_diag_priv_t *ota_diag_priv, void *priv)¶

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.

This will be invoked once again after MQTT has connected, in case some additional validations are to be done later.

If OTA state == OTA_DIAG_STATE_INIT, then return OTA_DIAG_STATUS_FAIL to indicate failure and rollback. return OTA_DIAG_STATUS_SUCCESS or OTA_DIAG_STATUS_PENDING to tell internal OTA logic to continue further.

If OTA state == OTA_DIAG_STATE_POST_MQTT, then return OTA_DIAG_STATUS_FAIL to indicate failure and rollback. return OTA_DIAG_STATUS_SUCCESS to indicate validation was successful and mark OTA as valid return OTA_DIAG_STATUS_PENDING to indicate that some additional validations will be done later and the OTA will eventually be marked valid/invalid using esp_rmaker_ota_mark_valid() or esp_rmaker_ota_mark_invalid() respectively.

Return: esp_rmaker_ota_diag_status_t as applicable

Enumerations¶

enum esp_rmaker_ota_event_t¶

ESP RainMaker Events

Values:

RMAKER_OTA_EVENT_INVALID = 0¶

RMAKER_OTA_EVENT_STARTING¶: RainMaker OTA is Starting

RMAKER_OTA_EVENT_IN_PROGRESS¶: RainMaker OTA has Started

RMAKER_OTA_EVENT_SUCCESSFUL¶: RainMaker OTA Successful

RMAKER_OTA_EVENT_FAILED¶: RainMaker OTA Failed

RMAKER_OTA_EVENT_REJECTED¶: RainMaker OTA Rejected

RMAKER_OTA_EVENT_DELAYED¶: RainMaker OTA Delayed

RMAKER_OTA_EVENT_REQ_FOR_REBOOT¶: OTA Image has been flashed and active partition changed. Reboot is requested. Applicable only if Auto reboot is disabled

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

OTA_STATUS_REJECTED¶: OTA rejected due to some reason (wrong project, version, etc.)

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.

enum esp_rmaker_ota_diag_status_t¶

Values:

OTA_DIAG_STATUS_FAIL¶: OTA Diagnostics Failed. Rollback the firmware.

OTA_DIAG_STATUS_PENDING¶: OTA Diagnostics Pending. Additional validations will be done later.

OTA_DIAG_STATUS_SUCCESS¶: OTA Diagnostics Succeeded. Firmware can be considered valid.

enum esp_rmaker_ota_diag_state_t¶

Values:

OTA_DIAG_STATE_INIT¶: OTA State: Initialised.

OTA_DIAG_STATE_POST_MQTT¶: OTA state: MQTT has connected.