OTA Functions

group group_ota_functions

Functions to start/stop and query the OTA Agent.

OTA functions for starting, stopping, and getting information about the OTA Agent.

Functions

cy_rslt_t cy_ota_agent_start(cy_ota_network_params_t *network_params, cy_ota_agent_params_t *agent_params, cy_ota_context_ptr *ota_ptr)

Start the OTA Background Agent.

Start a thread to monitor for OTA updates. This consumes resources until cy_ota_agent_stop() is called.

Parameters
  • network_params[in] Pointer to cy_ota_network_params_t.

  • agent_params[in] Pointer to cy_ota_agent_params_t.

  • ota_ptr[out] Handle to store the OTA Agent context structure pointer, Which is used for other OTA calls.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BADARG CY_RSLT_OTA_ERROR_ALREADY_STARTED CY_RSLT_OTA_ERROR

cy_rslt_t cy_ota_agent_stop(cy_ota_context_ptr *ota_ptr)

Stop OTA Background Agent.

Stop the thread to monitor OTA updates and release resources.

Parameters

ota_ptr[in] Pointer to the OTA Agent context storage returned from cy_ota_agent_start();

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BADARG

cy_rslt_t cy_ota_get_update_now(cy_ota_context_ptr ota_ptr)

Check for OTA update availability and download update now.

Once cy_ota_start() has returned CY_RSLT_SUCCESS, you can initiate an OTA update availability check whenever you require; this supercedes the timing values. It does not change the timer values, and will set the timer to the current values after an OTA download cycle.

Parameters

ota_ptr[in] Pointer to the OTA Agent context storage returned from cy_ota_agent_start();

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BADARG CY_RSLT_OTA_ERROR_ALREADY_STARTED

cy_rslt_t cy_ota_storage_open(cy_ota_context_ptr ctx)

Open the storage area for download.

NOTE: Typically, this erases the secondary slot.

Parameters

ctx[in] - Pointer to the OTA agent context cy_ota_context_ptr.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_OPEN_STORAGE

cy_rslt_t cy_ota_storage_read(cy_ota_context_ptr ctx_ptr, cy_ota_storage_write_info_t *chunk_info)

Read from storage area.

Parameters
  • ctx[in] - pointer to OTA agent context cy_ota_context_t

  • out][in] chunk_info - pointer to chunk information, buffer pointer used for the read

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_READ_STORAGE

cy_rslt_t cy_ota_storage_write(cy_ota_context_ptr ctx, cy_ota_storage_write_info_t *chunk_info)

Write data into the storage area.

NOTE: This writes data directly into FLASH. For writing data from a TAR archive, use cy_ota_write_incoming_data_block(), which checks for TAR archives and separates the data properly.

Parameters
  • ctx[in] - Pointer to the OTA agent context cy_ota_context_ptr.

  • chunk_info[in] - Pointer to the chunk information.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_WRITE_STORAGE

cy_rslt_t cy_ota_write_incoming_data_block(cy_ota_storage_write_info_t *chunk_info)

Determine if tar or non-tar and call correct write function.

NOTE: This function handles both TAR archive and non-TAR archive files. This function is used by Pull Mode for MQTT and HTTP

Parameters

chunk_info[in] - pointer to chunk information

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_storage_close(cy_ota_context_ptr ctx)

Close the storage area for download.

Parameters

ctx[in] - Pointer to the OTA agent context cy_ota_context_ptr.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_CLOSE_STORAGE

cy_rslt_t cy_ota_storage_verify(cy_ota_context_ptr ctx)

Verify the download signature on the whole OTA image.

Parameters

ctx[in] - Pointer to the OTA agent context cy_ota_context_ptr.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_VERIFY

cy_rslt_t cy_ota_storage_validated(void)

The application has validated the new OTA image.

This call must be after reboot and MCUboot has copied the new application to the primary slot.

Returns

CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

void cy_ota_set_log_level(CY_LOG_LEVEL_T level)

Set the OTA log output level.

To get the OTA log output, first call cy_log_init(). Call this routine at any time to set the OTA logging level.

Parameters

level[in] Required logging level from OTA logs.

Returns

N/A

cy_rslt_t cy_ota_get_state(cy_ota_context_ptr ota_ptr, cy_ota_agent_state_t *state)

Get the OTA Agent State.

Use this function to determine what state the OTA Agent is in. Do not check if the OTA Agent is in CY_OTA_STATE_AGENT_WAITING because it will interrupt an OTA cycle.

Parameters
  • ota_ptr[in] Pointer to the OTA Agent context returned from cy_ota_agent_start();

  • state[out] Current OTA State.

Returns

CY_RSLT_SUCCESS sets cy_ota_agent_state_t CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_get_last_error(void)

Get the last OTA error.

The last error value is persistent, and can be queried after cy_ota_agent_stop().

Returns

the last error that occurred (see cy_rslt_t).

const char *cy_ota_get_error_string(cy_rslt_t error)

Get a string representation of the error.

This can be called at any time.

Parameters

error[in] Value returned from cy_ota_get_last_error().

Returns

Pointer to a string (NULL for unknown error).

const char *cy_ota_get_state_string(cy_ota_agent_state_t state)

Get a string Representation of the OTA state.

This can be called at any time.

Parameters

state[in] cy_ota_agent_state_t

Returns

Pointer to the string (NULL for unknown state).

const char *cy_ota_get_callback_reason_string(cy_ota_cb_reason_t reason)

Get a string representation for the callback reason.

This can be called at any time.

Parameters

reason[in] cy_ota_cb_reason_t

Returns

Pointer to the string (NULL for unknown reason).