RainMaker Neo OTA

The esp_rmaker_neo_ota component: the AWS IoT Jobs based OTA client, its event loop and its status/error reporting vocabulary.

OTA

Header File

components/esp_rmaker_neo_ota/include/esp_rmaker_ota.h

Functions

esp_rmaker_error_t esp_rmaker_ota_enable(const esp_rmaker_ota_config_t *ota_config)

Enable OTA.

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

The post-OTA rollback check (esp_rmaker_ota_config_t::ota_diag) runs synchronously inside this call. The rest of the setup is queued on the work queue and completes once esp_rmaker_start() has run it.

Parameters:: ota_config – [in] Pointer to an OTA configuration structure. The structure is copied, so it need not outlive the call; the pointed-to priv data must.
Returns:: ESP_RMAKER_OK on success, or if OTA is already enabled or pending.
Returns:: error on failure

esp_rmaker_error_t esp_rmaker_ota_disable(void)

Disable OTA.

This API disables OTA and removes all OTA related resources.

Returns:: ESP_RMAKER_OK on success
Returns:: error on failure

esp_rmaker_error_t esp_rmaker_ota_report_status(esp_rmaker_ota_handle_t ota_handle, ota_status_t status, const esp_rmaker_ota_status_details_t *status_details)

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 status details. 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.

Parameters:

ota_handle – [in] The OTA handle received by the callback
status – [in] Status to be reported
status_details – [in] Status details to be reported

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_ota_default_cb(esp_rmaker_ota_handle_t handle, esp_rmaker_ota_data_t *ota_data, const esp_rmaker_ota_ft_ctx_t *ft_handler)

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 Neo Core.

Parameters:

handle – [in] An OTA handle assigned by the ESP RainMaker Neo Core
ota_data – [in] The data to be used for the OTA
ft_handler – [in] The filetype handler to be used for the OTA

Returns:

ESP_RMAKER_OK if the OTA was successful

Returns:

ESP_RMAKER_FAIL if the OTA failed.

esp_rmaker_error_t esp_rmaker_ota_default_validate_image_ref(const char *image_ref, size_t image_ref_len)

Default Image-Reference Validator.

Paired with esp_rmaker_ota_default_cb. Dispatches to the MQTT transport validator.

Parameters:

image_ref – [in] The stream name from the job document.
image_ref_len – [in] Length of image_ref in bytes, excluding any null terminator.

Returns:

ESP_RMAKER_OK if the reference is valid for the default transport.

Returns:

An error code otherwise.

esp_rmaker_error_t esp_rmaker_ota_fetch(void)

Fetch OTA Info.

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.

Returns:: ESP_RMAKER_OK if the OTA fetch request was posted to the state machine.
Returns:: error on failure

esp_rmaker_error_t esp_rmaker_ota_fetch_with_delay(int time)

Fetch OTA Info with a delay.

Same as esp_rmaker_ota_fetch(), but the request is issued after the given delay. Calling this again before the timer fires restarts the delay rather than queueing a second fetch.

Parameters:: time – [in] Delay (in seconds). Must be greater than 0.
Returns:: ESP_RMAKER_OK if the OTA fetch timer was created.
Returns:: ESP_RMAKER_INVALID_ARG if time is not greater than 0.
Returns:: ESP_RMAKER_INVALID_STATE if OTA is not enabled.
Returns:: error on failure

esp_rmaker_error_t esp_rmaker_ota_request_recovery(void)

Request Recovery.

This API can be used to request a recovery from the current error state. Use this after receiving the RMAKER_OTA_EVENT_ERROR_OCCURRED event to request recovery (see esp_rmaker_ota_event_loop.h)

Note

This does not fix underlying issues, but resumes the OTA process from the indicated recovery state.

Note

Calling this directly after receiving the RMAKER_OTA_EVENT_ERROR_OCCURRED event might likely cause an infinite error loop.

Note

You are responsible for ensuring that the underlying issue is fixed before requesting recovery.

Returns:: ESP_RMAKER_OK if the recovery request was posted to the state machine.
Returns:: error on failure

esp_rmaker_error_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 Neo core does its own validations (primarily MQTT connection).

Returns:: ESP_RMAKER_OK on success
Returns:: error on failure

esp_rmaker_error_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 Neo core’s internal logic and the application’s logic mark the OTA as valid.

Returns:: ESP_RMAKER_OK on success
Returns:: error on failure

Structures

struct esp_rmaker_ota_data_t

OTA Data

Public Members

char *stream_id: The Stream ID received from job doc

int filesize: Size of the OTA File

uint32_t file_id: The file ID within the stream, as declared by the job doc.

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

char *file_md5: The MD5 of the OTA File (lowercase hex string). NULL if the job did not declare one. When present, enables OTA auto-resume and an end-to-end MD5 integrity check on completion.

char *file_signature: The signature of the OTA File. Base64 encoded.

char *ota_job_id: The OTA Job ID received from job doc

char *priv: The private data passed as esp_rmaker_ota_config_t::priv to esp_rmaker_ota_enable()

char *metadata: OTA Metadata, taken from the optional “metadata” field of the job document. NULL if the job did not declare one.

struct esp_rmaker_ota_diag_priv_t

Context passed to the OTA diagnostics (rollback check) callback

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 Neo 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 Neo OTA Configuration

Public Members

esp_rmaker_ota_ft_lookup_handler_t custom_filetype_handler_lookup: Custom OTA Filetype handler lookup function. The function to be used to lookup the OTA Filetype handler context for a custom filetype. If kept NULL, custom filetype handling will not be enabled.

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_ota_validate_image_ref_t validate_image_ref: Optional Image-Reference Validator. Validates the image reference (MQTT stream id) parsed from the OTA job document before any download is started. Return ESP_RMAKER_OK to accept; any non-OK return causes the job to be REJECTED with reason “Image reference failed”. If NULL, no validation is performed. When ota_cb is left NULL and the SDK selects the built-in transport callback, it also installs the matching built-in validator.

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.

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_rmaker_error_t (*esp_rmaker_ota_cb_t)(esp_rmaker_ota_handle_t handle, esp_rmaker_ota_data_t *ota_data, const esp_rmaker_ota_ft_ctx_t *ft_handler)

Function prototype for OTA Callback.

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

Param handle:: [in] An OTA handle assigned by the ESP RainMaker Neo Core
Param ota_data:: [in] The data to be used for the OTA
Param ft_handler:: [in] The filetype handler to be used for the OTA
Return:: ESP_RMAKER_OK if the OTA was successful
Return:: ESP_RMAKER_FAIL if the OTA failed.

typedef esp_rmaker_error_t (*esp_rmaker_ota_validate_image_ref_t)(const char *image_ref, size_t image_ref_len)

Function prototype for validating the OTA image reference (MQTT stream id).

Invoked by the OTA engine after parsing the job document but before any image download is attempted. Must return ESP_RMAKER_OK to accept the reference; any non-OK return causes the job to be REJECTED with reason “Image reference failed”.

The MQTT stream id must fit within the AWS MQTT file-downloader’s fixed-size topic buffer, so the transport ships its own validator alongside its OTA callback.

Param image_ref:: [in] The image reference (NUL-terminated string).
Param image_ref_len:: [in] Length of image_ref (excluding terminator).
Return:: ESP_RMAKER_OK if the reference is acceptable for download.
Return:: Non-OK error code to reject the job.

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.

Param ota_diag_priv:: [in] Diagnostics context: the current state and whether the OTA was triggered by RainMaker Neo.
Param priv:: [in] The private data passed as esp_rmaker_ota_config_t::priv to esp_rmaker_ota_enable().
Return:: esp_rmaker_ota_diag_status_t as applicable

Enumerations

enum ota_status_t

OTA Status to be reported to ESP RainMaker Neo Cloud

Values:

enumerator OTA_STATUS_IN_PROGRESS: OTA is in Progress. This can be reported multiple times as the OTA progresses.

enumerator OTA_STATUS_SUCCESS: OTA Succeeded. This should be reported only once, at the end of OTA.

enumerator OTA_STATUS_FAILED: OTA Failed. This should be reported only once, at the end of OTA.

enumerator OTA_STATUS_DELAYED: OTA was delayed by the application

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

enum esp_rmaker_ota_diag_status_t

Outcome reported by the OTA diagnostics (rollback check) callback

Values:

enumerator OTA_DIAG_STATUS_FAIL: OTA Diagnostics Failed. Rollback the firmware.

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

enumerator OTA_DIAG_STATUS_SUCCESS: OTA Diagnostics Succeeded. Firmware can be considered valid.

enum esp_rmaker_ota_diag_state_t

Point in the boot sequence at which the OTA diagnostics callback is invoked

Values:

enumerator OTA_DIAG_STATE_INIT: OTA State: Initialised.

enumerator OTA_DIAG_STATE_POST_MQTT: OTA state: MQTT has connected.

Event Loop

Header File

components/esp_rmaker_neo_ota/include/esp_rmaker_ota_event_loop.h

Enumerations

enum esp_rmaker_ota_event_t

ESP RainMaker Neo OTA Events

Values:

enumerator RMAKER_OTA_EVENT_BASE_ANY: Wildcard: register a handler with this id to receive every RMAKER_OTA_EVENT.

enumerator RMAKER_OTA_EVENT_INVALID

enumerator RMAKER_OTA_EVENT_STARTING

RainMaker Neo OTA is Starting

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_STARTING

enumerator RMAKER_OTA_EVENT_FETCH_REQUEST_IGNORED

RainMaker Neo OTA Fetch request ignored This event is reported when the OTA state machine is not in an appropriate state to handle a fetch request via esp_rmaker_ota_fetch(). e.g., the OTA state machine is currently processing a job. You can use this event to trigger a delayed fetch request.

Event data: NULL

enumerator RMAKER_OTA_EVENT_RESUMED

RainMaker Neo OTA download resumed from a previous partial download. Only fired when CONFIG_RMNG_OTA_RESUME=y and a matching persisted tracker was found.

Event data: *uint32_t (resume byte offset - bytes already present at the start of this attempt)

enumerator RMAKER_OTA_EVENT_IN_PROGRESS

RainMaker Neo OTA in progress

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_IN_PROGRESS

enumerator RMAKER_OTA_EVENT_SUCCESSFUL

RainMaker Neo OTA Successful

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_SUCCEEDED

enumerator RMAKER_OTA_EVENT_FAILED

RainMaker Neo OTA Failed

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_FAILED

enumerator RMAKER_OTA_EVENT_REJECTED

RainMaker Neo OTA Rejected

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_REJECTED

enumerator RMAKER_OTA_EVENT_DELAYED

RainMaker Neo OTA Delayed

Event data: *esp_rmaker_ota_status_details_t
Type: ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_DELAYED

enumerator 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

Event data: NULL

enumerator RMAKER_OTA_EVENT_ERROR_OCCURRED

RainMaker Neo OTA Error Occurred

Event data: *esp_rmaker_ota_error_reason_t

File Type Handlers

Header File

components/esp_rmaker_neo_ota/include/esp_rmaker_ota_filetype_handler.h

Functions

esp_rmaker_error_t esp_rmaker_ota_report_final_status(const esp_rmaker_ota_status_details_t *status_details)

Report the final status of the OTA update. This uses the current job ID.

You should only call this when you are sure that the OTA update has completed successfully or failed. Some possible locations:

Within the on_post_download_checks_complete handler
After the on_post_download_checks_complete handler has started an asynchronous operation, and that operation has completed successfully or failed.
Within the on_post_reboot handler
After the on_post_reboot handler has started an asynchronous operation, and that operation has completed successfully or failed.

Note

This function will only accept “final” statuses:

SUCCEEDED
FAILED Fill the status details struct with the appropriate fill function from esp_rmaker_ota_status_details.h.

Parameters:: status_details – [in] The status details to report. The status itself is part of this struct.
Returns:: ESP_RMAKER_OK on success, otherwise an error code

Structures

struct esp_rmaker_ota_ft_version_t: Version string and length.

struct esp_rmaker_ota_ft_ctx_t: Filetype handler context containing all callback handlers.

Type Definitions

typedef void *esp_rmaker_ota_ft_download_handle_t: Download handle.

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_version_to_uint32_handler_t)(const esp_rmaker_ota_ft_version_t version, uint32_t *version_num)

(Optional Pair [1/2]) Versioning handler: Convert a version string to a uint32_t

A higher uint32_t value means a higher version. If the version is not required, then provide a NULL function for this handler.

Note

This MUST be implemented if the get_version handler is implemented, i.e., as a pair.

Param version:: [in] Version to convert
Param version_num:: [out] Version number
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_get_version_handler_t)(esp_rmaker_ota_ft_version_t *p_version)

(Optional Pair [2/2]) Versioning handler: Get the current version

If the version is not required, then provide a NULL function for this handler.

Note

This MUST be implemented if the version_to_uint32 handler is implemented, i.e., as a pair.

Param p_version:: [out] Current version
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_set_version_handler_t)(const esp_rmaker_ota_ft_version_t version)

(Optional) Versioning handler: Set the version after successful integration

If version saving is not required, then provide a NULL function for this handler.

e.g., the version is embedded in the file and does not need to be persisted.

Param version:: [in] Version to persist for this filetype
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_download_begin_handler_t)(esp_rmaker_ota_ft_download_handle_t *p_download_handle, size_t expected_size)

(Required) Execution handler: Called when download is beginning

Param p_download_handle:: [out] Download handle.
Param expected_size:: [in] Expected size of the download.
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_download_resume_handler_t)(esp_rmaker_ota_ft_download_handle_t *p_download_handle, size_t expected_size, size_t resume_offset)

(Optional) Execution handler: Resume an interrupted download without discarding already-written data.

Called instead of on_download_begin when the SDK has a valid persisted progress tracker for the exact same target image (matched via the job’s file_md5). The handler must reopen its destination WITHOUT erasing the bytes already received, ready to accept further on_download_chunk writes (which use absolute offsets). For firmware this maps to osal_ota_resume().

Resume is strictly best-effort: if this returns an error, the SDK falls back to a fresh on_download_begin (full re-download). If NULL, the filetype never resumes.

Param p_download_handle:: [out] Download handle.
Param expected_size:: [in] Expected total size of the download.
Param resume_offset:: [in] Number of leading bytes already known-good (sequential transports); MQTT passes 0 since it tracks received blocks via a bitmap.
Return:: ESP_RMAKER_OK on success, otherwise an error code (triggers fresh-download fallback).

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_download_chunk_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, const uint8_t *data, size_t size, size_t offset)

(Required) Execution handler: Write chunk data to destination

Param download_handle:: [in] Download handle.
Param data:: [in] Data buffer to process
Param size:: [in] Size of data to write
Param offset:: [in] Offset in the stream
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_download_complete_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, bool success)

(Required) Execution handler: Called when download is complete

Param download_handle:

[in] Download handle.

Param success:

[in] True if the download succeeded, false otherwise

If success is true, the download handle should remain valid for post download checks.
If success is false, the download handle should be cleaned up and should no longer be used.

Return:

ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_get_sha256_hash_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, uint8_t hash[32])

(Required) Execution handler: Get SHA256 hash of the processed data

Param download_handle:: [in] Download handle.
Param hash:: [out] Buffer to store the hash in. Will be pre-allocated to 32 bytes.
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_get_md5_hash_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, uint8_t hash[16])

(Optional) Execution handler: Get MD5 hash of the processed data.

Used for the optional end-to-end file_md5 integrity check (job document file_md5). If NULL, the MD5 completion check is skipped even when the job declares a file_md5.

Param download_handle:: [in] Download handle.
Param hash:: [out] Buffer to store the hash in. Will be pre-allocated to 16 bytes.
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_perform_integration_check_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle)

(Required) Execution handler: Perform integration check

You should ensure that the downloaded file is integrated into the system before or during this call.
e.g., for firmware images, written to the appropriate partition and passed checksum verifications.

Param download_handle:: [in] Download handle.
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_verify_image_header_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, const char *expected_fw_version)

(Optional) Execution handler: Verify the downloaded image’s embedded header matches the job’s claims.

Compares the embedded project_name against the currently running project_name.
Compares the embedded firmware version against the version declared in the job document. If NULL, the header verification step is skipped (NOT recommended; allows downgrade-by-lying and cross-project flashes).

Param download_handle:: [in] Download handle.
Param expected_fw_version:: [in] Firmware version string declared in the job document (must match exactly). May be NULL if the job did not declare one; implementation should decide policy.
Return:: ESP_RMAKER_OK if the image header is valid and matches, otherwise an error code.

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_post_download_checks_complete_handler_t)(esp_rmaker_ota_ft_download_handle_t download_handle, bool success, bool *p_should_reboot)

(Required) Execution handler: Called when post download checks are complete, which include:

Signature verification using the hash of the processed data
Integration check (e.g., for firmware images, written to the appropriate partition and passed checksum verifications)

Note

Before this handler is called, a timer is started to wait for a final status to be reported.

This timer is stopped when esp_rmaker_ota_report_final_status() is called.
If the timer expires, the OTA update is considered failed. You should therefore report the final status within this handler, or within an asynchronous operation that is started by this handler. If you are rebooting the device, then this timer is stopped, and restarted by the on_post_reboot handler.

Note

The download handle should be cleaned up and should no longer be used after this call.

Param download_handle:: [in] Download handle.
Param success:: [in] True if the post download checks succeeded, false otherwise
Param p_should_reboot:: [out] True if the device should reboot, false otherwise
Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef esp_rmaker_error_t (*esp_rmaker_ota_ft_on_post_reboot_handler_t)(void)

(Optional) Execution handler: Called when the device has rebooted after an OTA update

Note

Before this handler is called, a timer is started to wait for a final status to be reported.

This timer is stopped when esp_rmaker_ota_report_final_status() is called.
If the timer expires, the OTA update is considered failed. You should therefore report the final status within this handler, or within an asynchronous operation that is started by this handler.

Note

If your on_post_download_checks_complete handler signals for a reboot, but this handler is not provided, then the job will be explicitly failed.

The reason for this is that the device will not reboot, and the job will therefore be in the IN_PROGRESS state indefinitely.
Ensure that you provide this handler if you signal for a reboot in your on_post_download_checks_complete handler.

Return:: ESP_RMAKER_OK on success, otherwise an error code

typedef const esp_rmaker_ota_ft_ctx_t *(*esp_rmaker_ota_ft_lookup_handler_t)(const char *filetype, size_t filetype_len)

Lookup function: Get the OTA Filetype handler context.

Param filetype:: [in] OTA Filetype to get the context for
Param filetype_len:: [in] Length of the filetype
Return:: OTA Filetype handler context

Status Details

Header File

components/esp_rmaker_neo_ota/include/esp_rmaker_ota_status_details.h

Functions

void esp_rmaker_ota_status_details_fill_starting(esp_rmaker_ota_status_details_t *status_details, const char *job_id, const char *filetype, const char *fw_version)

Fill a STARTING status details struct.

Parameters:

status_details – [out] The status details struct to fill.
job_id – [in] The job ID of the OTA job.
filetype – [in] The filetype of the OTA job.
fw_version – [in] The firmware version of the OTA image.

void esp_rmaker_ota_status_details_fill_in_progress(esp_rmaker_ota_status_details_t *status_details, uint32_t downloaded_bytes, uint32_t total_bytes)

Fill an IN_PROGRESS status details struct.

Parameters:

status_details – [out] The status details struct to fill.
downloaded_bytes – [in] The number of bytes downloaded so far.
total_bytes – [in] The total number of bytes to download.

void esp_rmaker_ota_status_details_fill_succeeded(esp_rmaker_ota_status_details_t *status_details, const char *filetype, const char *fw_version)

Fill a SUCCEEDED status details struct.

Parameters:

status_details – [out] The status details struct to fill.
filetype – [in] The filetype of the OTA job.
fw_version – [in] The firmware version of the OTA image.

void esp_rmaker_ota_status_details_fill_failed(esp_rmaker_ota_status_details_t *status_details, const char *reason)

Fill a FAILED status details struct.

Parameters:

status_details – [out] The status details struct to fill.
reason – [in] The reason for failure.

void esp_rmaker_ota_status_details_fill_rejected(esp_rmaker_ota_status_details_t *status_details, const char *reason)

Fill a REJECTED status details struct.

Parameters:

status_details – [out] The status details struct to fill.
reason – [in] The reason for rejection.

void esp_rmaker_ota_status_details_fill_delayed(esp_rmaker_ota_status_details_t *status_details, const char *reason)

Fill a DELAYED status details struct.

Note

The reason is only carried to the application in RMAKER_OTA_EVENT_DELAYED.

Parameters:

status_details – [out] The status details struct to fill.
reason – [in] The reason for delay.

esp_rmaker_ota_status_details_t *esp_rmaker_ota_status_details_copy(const esp_rmaker_ota_status_details_t *status_details)

Copy a status details struct.

Parameters:: status_details – [in] The status details struct to copy.
Returns:: A pointer to the copied status details struct. If not NULL, the caller is responsible for freeing the pointer.

char *esp_rmaker_ota_status_details_to_json(const esp_rmaker_ota_status_details_t *status_details)

Convert a status details struct to a JSON string.

Parameters:: status_details – [in] The status details struct to convert.
Returns:: A pointer to the JSON string. If not NULL, the caller is responsible for freeing the string using free().

Unions

union esp_rmaker_ota_status_details_union_t

#include <esp_rmaker_ota_status_details.h>

Union of status details.

Public Members

esp_rmaker_ota_status_details_starting_t starting

esp_rmaker_ota_status_details_in_progress_t in_progress

esp_rmaker_ota_status_details_succeeded_t succeeded

esp_rmaker_ota_status_details_failed_t failed

esp_rmaker_ota_status_details_rejected_t rejected

esp_rmaker_ota_status_details_delayed_t delayed

Structures

struct esp_rmaker_ota_status_details_starting_t

Status details for a STARTING update.

Public Members

const char *job_id: The job ID of the OTA job

const char *filetype: The job filetype of the OTA job

const char *fw_version: The firmware version of the OTA image

struct esp_rmaker_ota_status_details_in_progress_t

Status details for an IN_PROGRESS update.

Public Members

uint32_t downloaded_bytes: The number of bytes downloaded so far

uint32_t total_bytes: The total number of bytes to download

struct esp_rmaker_ota_status_details_succeeded_t

Status details for a SUCCEEDED update.

Public Members

const char *filetype: The job filetype of the OTA job

const char *fw_version: The firmware version of the OTA image

struct esp_rmaker_ota_status_details_failed_t

Status details for a FAILED update.

Public Members

const char *reason: Reason for failure

struct esp_rmaker_ota_status_details_rejected_t

Status details for a REJECTED update.

Public Members

const char *reason: Reason for rejection

struct esp_rmaker_ota_status_details_delayed_t

Status details for a DELAYED update.

Public Members

const char *reason: Reason for delay

struct esp_rmaker_ota_status_details_t: Status details for an OTA update.

Macros

ESP_RMAKER_OTA_REJECTED_REASON_FW_VERSION_REQUIRED: Firmware version is required for filetype

ESP_RMAKER_OTA_REJECTED_REASON_FW_VERSION_UNSUPPORTED: Unsupported firmware version

ESP_RMAKER_OTA_REJECTED_REASON_FW_VERSION_TOO_LOW: Firmware version too low

ESP_RMAKER_OTA_REJECTED_REASON_JOB_DOC_MISSING_RMNG: Missing RainMaker Neo-specific fields in job document

ESP_RMAKER_OTA_REJECTED_REASON_JOB_DOC_MISSING_AFR_OTA: Missing AFR-specific fields in job document

ESP_RMAKER_OTA_REJECTED_REASON_SIGNATURE_MISSING: Missing signature in job document

ESP_RMAKER_OTA_REJECTED_REASON_SIGNATURE_INVALID_BASE64: Invalid signature in job document

ESP_RMAKER_OTA_REJECTED_REASON_FILETYPE_TOO_LONG: Filetype too long

ESP_RMAKER_OTA_REJECTED_REASON_NO_CUSTOM_FILETYPE_IMPL: No custom filetype implementation - This means a lookup function was not provided.

ESP_RMAKER_OTA_REJECTED_REASON_FILETYPE_NOT_SUPPORTED: Filetype not supported - This means a handler was not found for the filetype using the provided lookup function.

ESP_RMAKER_OTA_REJECTED_REASON_FILETYPE_HANDLER_INVALID: Filetype handler is invalid - This means the provided implementation has missing or invalid fields.

ESP_RMAKER_OTA_REJECTED_REASON_IMAGE_REFERENCE_INVALID: Image reference (MQTT stream id) rejected by transport validator.

ESP_RMAKER_OTA_REJECTED_REASON_JOB_UPDATE_UNRECOVERABLE: The job execution can no longer accept updates (deleted or already in a terminal state), so its outcome can never be reported to the cloud.

ESP_RMAKER_OTA_FAILED_REASON_IMAGE_DOWNLOADER_SETUP_FAILED: Image downloader setup failed

ESP_RMAKER_OTA_FAILED_REASON_MQTT_STREAM_SUBSCRIPTION_FAILED: MQTT stream subscription failed

ESP_RMAKER_OTA_FAILED_REASON_POST_DOWNLOAD_CHECKS_FAILED: Post download checks failed

ESP_RMAKER_OTA_FAILED_REASON_IMAGE_HEADER_INVALID: Downloaded image header failed verification (e.g. project name or firmware version mismatch between the binary’s embedded application descriptor and the running app / job document).

ESP_RMAKER_OTA_FAILED_REASON_SIGNATURE_INVALID: Downloaded image’s signature failed cryptographic verification against the codesign cert.

ESP_RMAKER_OTA_FAILED_REASON_MD5_INVALID: Downloaded image’s MD5 did not match the file_md5 declared in the job document.

ESP_RMAKER_OTA_FAILED_REASON_CUSTOM_FILETYPE_HANDLER_NO_POST_REBOOT_HANDLER: Custom filetype handler requested a post-download reboot but provides no on_post_reboot callback, so the job could never terminate. Reported after the reboot.

ESP_RMAKER_OTA_FAILED_REASON_UNKNOWN_ERROR: Unknown error

Enumerations

enum esp_rmaker_ota_status_details_type_t

Values:

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_INVALID

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_STARTING

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_IN_PROGRESS

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_SUCCEEDED

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_FAILED

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_REJECTED

enumerator ESP_RMAKER_OTA_STATUS_DETAILS_TYPE_DELAYED

Error Reasons

Header File

components/esp_rmaker_neo_ota/include/esp_rmaker_ota_error_reasons.h

Functions

const char *esp_rmaker_ota_error_reason_to_string(esp_rmaker_ota_error_reason_t reason)

Returns a string representation of an OTA error reason.

Parameters:: reason – [in] The OTA error reason
Returns:: A string representing the OTA error reason

Enumerations

enum esp_rmaker_ota_error_reason_t

OTA error reasons.

Values:

enumerator OTA_ERROR_NONE: No error

enumerator OTA_ERROR_NO_PENDING_JOBS: No pending jobs - will not be posted to the event loop

enumerator OTA_ERROR_RETRY_WITH_BACKOFF: Retry with backoff - e.g., no MQTT connection

enumerator OTA_ERROR_FATAL_INIT_FAILED: Initialization failed

enumerator OTA_ERROR_FATAL_UNEXPECTED_FORMAT: Unexpected format (critical firmware issue)

enumerator OTA_ERROR_SUBSCRIPTION_FAILED: Subscription failed

enumerator OTA_ERROR_TIMEOUT_HANDLER_RESTART_FAILED: Timeout handler used for getting pending jobs / job document retrieval failed to (re)start. Treating this as a terminal error because the engine might hang indefinitely if there is no way to timeout.

enumerator OTA_ERROR_GET_PENDING_INVALID_FORMAT: Get pending jobs returned invalid JSON format

enumerator OTA_ERROR_GET_PENDING_REJECTED: Get pending rejected

enumerator OTA_ERROR_DESCRIBE_JOB_REJECTED: Describe job rejected

enumerator OTA_ERROR_JOB_DOC_PARSE_FAILED: Job doc parse failed