OTA Interface

Detailed Description

Interface for the OTA Functionality.

Summary

The OTA interface provides the ability to read, write, erase, and blank check the FW versions and data regions.

Data Structures
struct	rm_ota_w_update_proc_t
struct	rm_ota_w_image_header_data_t
struct	ota_regions_t
struct	ota_info_t
struct	ota_callback_args_t
struct	ota_cfg_t
struct	ota_api_t
struct	ota_instance_t

Typedefs
typedef void	ota_ctrl_t

Enumerations
enum	rm_ota_w_update_type_t
enum	ota_event_t

---

Data Structure Documentation

rm_ota_w_update_proc_t

struct rm_ota_w_update_proc_t

Settings structure used for ota update requests

Data Fields
rm_ota_w_update_type_t	update_type
	FW type being downloaded.
char	update_cache [RM_OTA_W_CACHE_LEN]
	Cache data from last update.
uint32_t	auto_swap
	If the value is true, if the new firmware download is successful, it will reboot with the new firmware. Only for RTOS.
uint32_t	download_sflash_addr
	Flash address where the downloaded FW is written.
void(*	download_notify )(rm_ota_w_update_type_t update_type, uint32_t ret_status, uint32_t progress)
	Callback function pointer to check the download status.
void(*	swap_notify )(uint32_t ret_status)
	Callback function pointer to check the swap state. Only for RTOS.
uint32_t	update_state
	Status of the download process (not_ready, ready, progress, finish, stop).
uint32_t	status
	Download status. (success or failed)
uint32_t	progress_rtos
	RTOS download progress.
uint32_t	progress_mcu_fw
	MCU FW download progress.
uint32_t	progress_cert_key
	CERT_KEY download progress.

rm_ota_w_image_header_data_t

struct rm_ota_w_image_header_data_t

Image header data for updates

ota_regions_t

struct ota_regions_t

OTA block details

Data Fields
uint32_t	num_regions	Length of block info array.
ota_block_info_t const *	p_block_array	Block info array base address.

ota_info_t

struct ota_info_t

Information about the ota blocks

Data Fields
ota_regions_t	code_ota	Information about the code ota regions.
ota_regions_t	data_ota	Information about the code ota regions.

ota_callback_args_t

struct ota_callback_args_t

Callback function parameter data

Data Fields
ota_event_t	event	Event can be used to identify what caused the callback (ota ready or error).
void const *	p_context	Placeholder for user data. Set in ota_api_t::open function in::ota_cfg_t.

ota_cfg_t

struct ota_cfg_t

OTA Configuration

Data Fields
bool	data_ota_bgo
	True if BGO (Background Operation) is enabled for Data OTA.
void(*	p_callback )(ota_callback_args_t *p_args)
	Callback provided when a OTA interrupt ISR occurs.
void const *	p_extend
	OTA hardware dependent configuration.
void const *	p_context
	Placeholder for user data. Passed to user callback in ota_callback_args_t.
uint8_t	ipl
	OTA ready interrupt priority.
IRQn_Type	irq
	OTA ready interrupt number.
uint8_t	err_ipl
	OTA error interrupt priority.
IRQn_Type	err_irq
	OTA error interrupt number.

ota_api_t

struct ota_api_t

Shared Interface definition for OTA

Data Fields
fsp_err_t(*	open )(ota_ctrl_t *const p_ctrl, ota_cfg_t const *const p_cfg)
fsp_err_t(*	swap )(ota_ctrl_t *const p_ctrl)
fsp_err_t(*	getImageInfo )(ota_ctrl_t *const p_ctrl, rm_ota_w_update_type_t update_type, uint32_t sector_addr, rm_ota_w_image_header_data_t *info_image)
fsp_err_t(*	bootIdxSet )(ota_ctrl_t *const p_ctrl, uint8_t boot_idx)
fsp_err_t(*	bootIdxGet )(ota_ctrl_t *const p_ctrl, uint8_t *boot_idx)
fsp_err_t(*	getAddr )(ota_ctrl_t *const p_ctrl, uint8_t state, rm_ota_w_update_type_t update_type, uint32_t *addr)
fsp_err_t(*	setAddr )(ota_ctrl_t *const p_ctrl, uint8_t key_type, uint32_t key_val)
fsp_err_t(*	cert )(ota_ctrl_t *const p_ctrl, uint8_t cert_type, uint32_t sector_addr)
fsp_err_t(*	close )(ota_ctrl_t *const p_ctrl)

Field Documentation

open

fsp_err_t(* ota_api_t::open) (ota_ctrl_t *const p_ctrl, ota_cfg_t const *const p_cfg)

Open OTA device.

Parameters

[in]	p_ctrl	Pointer to OTA device control. Must be declared by user. Value set here.
[in]	ota_cfg_t	Pointer to OTA configuration structure. All elements of this structure must be set by the user.

swap

fsp_err_t(* ota_api_t::swap) (ota_ctrl_t *const p_ctrl)

Swap is the process for swapping programs after 2nd download program is valid. When the program data is successfully applied, the new program data will be executed after reboot. The swap process will trigger the reset if version check is pass.

Parameters

[in]

p_ctrl

Pointer to OTA device control.

getImageInfo

fsp_err_t(* ota_api_t::getImageInfo) (ota_ctrl_t *const p_ctrl, rm_ota_w_update_type_t update_type, uint32_t sector_addr, rm_ota_w_image_header_data_t *info_image)

Get program image in a specific location

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	update_type	Specifies the update type id for info request.
[in]	sector_addr	Sector address for version header info.
[out]	info_image	Parsed data of the image information.

bootIdxSet

fsp_err_t(* ota_api_t::bootIdxSet) (ota_ctrl_t *const p_ctrl, uint8_t boot_idx)

Set the image index.

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	boot_idx	Boot index to be set.

bootIdxGet

fsp_err_t(* ota_api_t::bootIdxGet) (ota_ctrl_t *const p_ctrl, uint8_t *boot_idx)

Get Current image index which is set

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	boot_idx	Boot index to get.

getAddr

fsp_err_t(* ota_api_t::getAddr) (ota_ctrl_t *const p_ctrl, uint8_t state, rm_ota_w_update_type_t update_type, uint32_t *addr)

Load key data value from device

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	state	Specifies which program data, current or other.
[in]	update_type	Specifies the update type id for info request.
[out]	addr	Pointer for the version address

setAddr

fsp_err_t(* ota_api_t::setAddr) (ota_ctrl_t *const p_ctrl, uint8_t key_type, uint32_t key_val)

Set Address value for user device

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	update_type	Specifies which program data, current or other.
[in]	addr	New address value

cert

fsp_err_t(* ota_api_t::cert) (ota_ctrl_t *const p_ctrl, uint8_t cert_type, uint32_t sector_addr)

Data validation of image data

Parameters

[in]	p_ctrl	Pointer to OTA device control.
[in]	cert_type	Type of the validation data.
[in]	sector_addr	Address for sector data.

close

fsp_err_t(* ota_api_t::close) (ota_ctrl_t *const p_ctrl)

Close FLASH device.

Parameters

[in]

p_ctrl

Pointer to FLASH device control.

ota_instance_t

struct ota_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
ota_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
ota_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
ota_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

ota_ctrl_t

typedef void ota_ctrl_t

OTA control block. Allocate an instance specific control block to pass into the OTA API calls.

Enumeration Type Documentation

rm_ota_w_update_type_t

enum rm_ota_w_update_type_t

Update type for certain operations

Enumerator
RM_OTA_W_TYPE_INIT	INIT value.
RM_OTA_W_TYPE_RTOS	RTOS FW update.
RM_OTA_W_TYPE_BLE_FW	BLE FW update.
RM_OTA_W_TYPE_BLE_COMBO	RTOS and BLE FW update.
RM_OTA_W_TYPE_MCU_FW	MCU FW update.
RM_OTA_W_TYPE_CERT_KEY	Certification key update.

ota_event_t

enum ota_event_t

Event types returned by the ISR callback when used in Data OTA BGO mode

Enumerator
RM_OTA_W_DOWNLOAD_RESULT_OK	File successfully received.
RM_OTA_W_DOWNLOAD_RESULT_ERR_UNKNOWN	Unknown error.
RM_OTA_W_DOWNLOAD_RESULT_ERR_CONNECT	Connection to server failed.
RM_OTA_W_DOWNLOAD_RESULT_ERR_HOSTNAME	Failed to resolve server hostname.
RM_OTA_W_DOWNLOAD_RESULT_ERR_CLOSED	Connection unexpectedly closed by remote server.
RM_OTA_W_DOWNLOAD_RESULT_ERR_TIMEOUT	Connection timed out (server didn't respond in time)
RM_OTA_W_DOWNLOAD_RESULT_ERR_SVR_RESP	Server responded with an error code.
RM_OTA_W_DOWNLOAD_RESULT_ERR_MEM	Local memory error.
RM_OTA_W_DOWNLOAD_RESULT_LOCAL_ABORT	Local abort.
RM_OTA_W_DOWNLOAD_RESULT_ERR_CONTENT_LEN	Content length mismatch.