General Description

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. More...

cy_rslt_t	cy_ota_agent_stop (cy_ota_context_ptr *ota_ptr)
	Stop OTA Background Agent. More...

cy_rslt_t	cy_ota_get_update_now (cy_ota_context_ptr ota_ptr)
	Check for OTA update availability and download update now. More...

cy_rslt_t	cy_ota_storage_open (cy_ota_context_ptr ota_ptr)
	Open the storage area for download. More...

cy_rslt_t	cy_ota_storage_read (cy_ota_context_ptr ota_ptr, cy_ota_storage_write_info_t *chunk_info)
	Read from storage area. More...

cy_rslt_t	cy_ota_storage_write (cy_ota_context_ptr ota_ptr, cy_ota_storage_write_info_t *chunk_info)
	Write data into the storage area. More...

cy_rslt_t	cy_ota_write_incoming_data_block (cy_ota_context_ptr ota_ptr, cy_ota_storage_write_info_t *chunk_info)
	Determine if tar or non-tar and call correct write function. More...

cy_rslt_t	cy_ota_ble_download_prepare (cy_ota_context_ptr ota_ptr, uint16_t bt_conn_id, uint16_t bt_config_descriptor)
	Prepare for Bluetooth® OTA Download. More...

cy_rslt_t	cy_ota_ble_download (cy_ota_context_ptr ota_ptr, wiced_bt_gatt_event_data_t *p_req, uint16_t bt_conn_id, uint16_t bt_config_descriptor)
	Bluetooth® OTA Download starting. More...

cy_rslt_t	cy_ota_ble_download_write (cy_ota_context_ptr ota_ptr, wiced_bt_gatt_event_data_t *p_req)
	Bluetooth® OTA data write. More...

cy_rslt_t	cy_ota_ble_download_verify (cy_ota_context_ptr ota_ptr, wiced_bt_gatt_event_data_t *p_req, uint16_t bt_conn_id)
	Bluetooth® OTA Verify download. More...

cy_rslt_t	cy_ota_ble_download_abort (cy_ota_context_ptr ota_ptr)
	Abort Bluetooth® OTA download. More...

cy_rslt_t	cy_ota_storage_close (cy_ota_context_ptr ota_ptr)
	Close the storage area for download. More...

cy_rslt_t	cy_ota_storage_verify (cy_ota_context_ptr ota_ptr)
	Verify the download signature on the whole OTA image. More...

cy_rslt_t	cy_ota_storage_validated (void)
	The application has validated the new OTA image. More...

void	cy_ota_set_log_level (CY_LOG_LEVEL_T level)
	Set the OTA log output level. More...

cy_rslt_t	cy_ota_get_state (cy_ota_context_ptr ota_ptr, cy_ota_agent_state_t *state)
	Get the OTA Agent State. More...

cy_rslt_t	cy_ota_get_last_error (void)
	Get the last OTA error. More...

const char *	cy_ota_get_error_string (cy_rslt_t error)
	Get a string representation of the error. More...

const char *	cy_ota_get_state_string (cy_ota_agent_state_t state)
	Get a string Representation of the OTA state. More...

const char *	cy_ota_get_callback_reason_string (cy_ota_cb_reason_t reason)
	Get a string representation for the callback reason. More...

Function Documentation

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

[in]	network_params	Pointer to cy_ota_network_params_t.
[in]	agent_params	Pointer to cy_ota_agent_params_t.
[out]	ota_ptr	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

[in] ota_ptr 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

[in] ota_ptr 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 ota_ptr )

Open the storage area for download.

NOTE: Typically, this erases the secondary slot.

Parameters

[in] ota_ptr 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	ota_ptr,
		cy_ota_storage_write_info_t *	chunk_info
	)

Read from storage area.

Parameters

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_t
[in]	out]	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	ota_ptr,
		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

[in]	ota_ptr	Pointer to the OTA agent context cy_ota_context_ptr.
[in]	chunk_info	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_context_ptr	ota_ptr,
		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

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_ptr
[in]	chunk_info	Pointer to chunk information

Returns: CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_GENERAL

cy_rslt_t cy_ota_ble_download_prepare	(	cy_ota_context_ptr	ota_ptr,
		uint16_t	bt_conn_id,
		uint16_t	bt_config_descriptor
	)

Prepare for Bluetooth® OTA Download.

Parameters

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_ptr
[in]	bt_conn_id	Bluetooth® Connection id
[in]	bt_config_descriptor	Bluetooth® configuration (notification vs. indication )

Returns: CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BLE_GATT

cy_rslt_t cy_ota_ble_download	(	cy_ota_context_ptr	ota_ptr,
		wiced_bt_gatt_event_data_t *	p_req,
		uint16_t	bt_conn_id,
		uint16_t	bt_config_descriptor
	)

Bluetooth® OTA Download starting.

Parameters

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_ptr
[in]	p_req	Pointer to gatt event data structure
[in]	bt_conn_id	Bluetooth® Connection id
[in]	bt_config_descriptor	Bluetooth® configuration (notification vs. indication )

Returns: CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BLE_GATT

cy_rslt_t cy_ota_ble_download_write	(	cy_ota_context_ptr	ota_ptr,
		wiced_bt_gatt_event_data_t *	p_req
	)

Bluetooth® OTA data write.

Parameters

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_ptr
[in]	p_req	Pointer to gatt event data structure

Returns: CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BLE_GATT

cy_rslt_t cy_ota_ble_download_verify	(	cy_ota_context_ptr	ota_ptr,
		wiced_bt_gatt_event_data_t *	p_req,
		uint16_t	bt_conn_id
	)

Bluetooth® OTA Verify download.

Parameters

[in]	ota_ptr	Pointer to OTA agent context cy_ota_context_ptr
[in]	p_req	Pointer to gatt event data structure
[in]	bt_conn_id	Bluetooth® Connection id

Returns: CY_RSLT_SUCCESS CY_RSLT_OTA_ERROR_BLE_GATT

cy_rslt_t cy_ota_ble_download_abort ( cy_ota_context_ptr ota_ptr )

Abort Bluetooth® OTA download.

Parameters

[in] ota_ptr Pointer to OTA agent context cy_ota_context_ptr

Returns: CY_RSLT_SUCCESS

cy_rslt_t cy_ota_storage_close ( cy_ota_context_ptr ota_ptr )

Close the storage area for download.

Parameters

[in] ota_ptr - 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 ota_ptr )

Verify the download signature on the whole OTA image.

Parameters

[in] ota_ptr - 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

[in] level 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

[in]	ota_ptr	Pointer to the OTA Agent context returned from cy_ota_agent_start();
[out]	state	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

[in] error 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

[in] state 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

[in] reason cy_ota_cb_reason_t

Returns: Pointer to the string (NULL for unknown reason).