RainMaker OTA¶
Header File¶
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)
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, alongwith the OTA URL
-
char *
-
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.
-
esp_rmaker_ota_cb_t
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
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.)
-