Functions
fsp_err_t	RM_OTA_W_Open (ota_ctrl_t const p_api_ctrl, ota_cfg_t const const p_cfg)

fsp_err_t	RM_OTA_W_Close (ota_ctrl_t *const p_api_ctrl)

fsp_err_t	RM_OTA_W_Swap (ota_ctrl_t *const p_api_ctrl)

fsp_err_t	RM_OTA_W_GetImageInfo (ota_ctrl_t const p_api_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	RM_OTA_W_BootIdxSet (ota_ctrl_t *const p_api_ctrl, uint8_t boot_idx)

fsp_err_t	RM_OTA_W_BootIdxGet (ota_ctrl_t const p_api_ctrl, uint8_t boot_idx)

fsp_err_t	RM_OTA_W_GetAddr (ota_ctrl_t const p_api_ctrl, uint8_t state, rm_ota_w_update_type_t update_type, uint32_t addr)

fsp_err_t	RM_OTA_W_SetAddr (ota_ctrl_t *const p_api_ctrl, uint8_t update_type, uint32_t addr)

fsp_err_t	RM_OTA_W_Cert (ota_ctrl_t *const p_api_ctrl, uint8_t cert_type, uint32_t sector_addr)

Detailed Description

Middleware for the OTA module on RAFW. This module implements the OTA Interface.

Overview

Features

Standard OTA RTOS Download
Standard OTA MCU_FW Download
Standard OTA BLE_FW Download
Standard OTA CERT_KEY Download

Configuration

The OTA (Over The Air FW update) module must be added by the user to enable OTA functionality.
The operating state of the OTA module can be set via the RAFW Configuration.
When the OTA stack will be added, the relevant files will be ported.
In startup the user will be able to use the API functions mentioned in this document.

Build Time Configurations for rm_ota_w

The following build time configurations are defined in fsp_cfg/rm_ota_w_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build. The Default (BSP) value is BSP_CFG_PARAM_CHECKING_ENABLE. It is the value of RRQ Common\|Parameter checking under BSP
WIFI Task Support	Enable Disable	Enable	Enable support OTA on WIFI task.

Configurations for System > OTA (rm_ota_w)

This module can be added to the Stacks tab via New Stack > System > OTA (rm_ota_w).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_ota0	Module name.

Usage Notes

Performance

OTA (Over The Air) refers to FW updates over the air. Supporting OTA update: DOWNLOAD and SWAP. The download is the process of downloading firmware from the server or host and storing it into the SFLASH area. The download sequence proceeds as follows, and both success and failure results can be delivered through the callback function: The swap only operates when the firmware download is successful. Download history should be available after power on.

Examples

OTA_W Example

This is a basic example of basic use of the OTA_W in an application.

void rm_ota_w_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;
    /* Open the ota instance with initial configuration. */
    err = RM_OTA_W_Open(&g_ota_example_ctrl, &g_ota_example_cfg);
    assert(FSP_SUCCESS == err);
    err = RM_OTA_W_GetImageInfo(&g_ota_example_ctrl, RM_OTA_W_TYPE_RTOS, RM_OTA_W_STOR_RTOS_0_ADDR, &info_image_example);
    err = RM_OTA_W_GetImageInfo(&g_ota_example_ctrl, RM_OTA_W_TYPE_RTOS, RM_OTA_W_STOR_RTOS_1_ADDR, &info_image_example);
    assert(FSP_SUCCESS == err);
    err = RM_OTA_W_BootIdxGet(&g_ota_example_ctrl, &boot_idx_example);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	rm_ota_w_update_sflash_t
	Struct for flash writing. More...

struct	rm_ota_w_update_download_t
	Structure to download firmware. More...

struct	rm_ota_w_instance_ctrl_t

Macros
#define	RM_OTA_W_OPEN

#define	RM_OTA_W_NVRAM_DW_PROGRESS
	NVRAM name of Download progress.

#define	RM_OTA_W_SUCCESS
	Return success.

#define	RM_OTA_W_FAILED
	Return failed.

#define	RM_OTA_W_ERROR_SFLASH_ADDR
	SFLASH address is wrong.

#define	RM_OTA_W_ERROR_TYPE
	FW type is unknown.

#define	RM_OTA_W_ERROR_URL
	Server URL is unknown.

#define	RM_OTA_W_ERROR_SIZE
	FW size is wrong or offset address to be downloaded is wrong.

#define	RM_OTA_W_ERROR_CRC
	CRC is not correct.

#define	RM_OTA_W_VERSION_UNKNOWN
	FW version is unknown.

#define	RM_OTA_W_VERSION_INCOMPATI
	FW version is incompatible.

#define	RM_OTA_W_NOT_FOUND
	FW not found on the server.

#define	RM_OTA_W_NOT_CONNECTED
	Failed to connect to server.

#define	RM_OTA_W_NOT_ALL_DOWNLOAD
	All new FWs have not been downloaded.

#define	RM_OTA_W_MEM_ALLOC_FAILED
	Failed to alloc memory.

#define	RM_OTA_W_BLE_VERSION_UNKNOWN
	BLE FW version is unknown.

#define	IMAGE_HEADER_MAGIC_CODE
	Image MAGIC CODE.

#define	IMAGE_HEADER_NAME_LEN
	Image Name Length.

#define	RM_OTA_W_STATE_NOT_READY
	Process is not ready.

#define	RM_OTA_W_STATE_READY
	Process is ready.

#define	RM_OTA_W_STATE_PROGRESS
	Process is ongoing.

#define	RM_OTA_W_STATE_FINISH
	Process completed.

#define	RM_OTA_W_STATE_STOP
	Process stopped.

#define	RM_OTA_W_VER_START_OFFSET
	address 0x02008 ~ 0x02063

#define	RM_OTA_W_FW_MAGIC_NUM
	IMAGE_HEADER_MAGIC_CODE 0x36314144.

#define	RM_OTA_W_UPDATE_TYPE_MAX
	Firmware version structure.

#define	RM_OTA_W_MCU_FW_NAME_LEN
	MCU Firmware version structure.

Enumerations
enum	rm_ota_w_version_flags_t
	Status for version check. More...

enum	rm_ota_w_refuse_type_t

enum	rm_ota_w_state_t

enum	rm_ota_w_bgo_operation_t

Data Structure Documentation

◆ rm_ota_w_update_sflash_t

struct rm_ota_w_update_sflash_t

Struct for flash writing.

Data Fields
UINT	sflash_addr	Starting address for the image.
UINT	total_length	Overall length of the block.
UINT	length	Buffer length.
UINT	offset	Update offset from starting address.
UCHAR *	buffer	Pointer to the data buffer.

◆ rm_ota_w_update_download_t

struct rm_ota_w_update_download_t

Structure to download firmware.

Data Fields
rm_ota_w_update_type_t	update_type	Update type.
rm_ota_w_update_sflash_t	write	Write struct field.
UINT	download_status	Status of the downloading operation.
UINT	version_check	Version check information.
UINT	content_length	The size of the download image in bytes.
UINT	received_length	Updated data which was received in the current process.

◆ rm_ota_w_instance_ctrl_t

struct rm_ota_w_instance_ctrl_t

Ota b instance control block. DO NOT INITIALIZE.

Data Fields
uint32_t	opened
	To check whether api has been opened or not.

uint32_t	source_start_offset
	Offset for continous download update.

rm_ota_w_bgo_operation_t	current_operation
	Operation in progress, for example, FLASH_OPERATION_CF_ERASE.

rm_ota_w_update_type_t	ota_update_type
	Update type.

uint8_t	update_cache [RM_OTA_W_CACHE_LEN]
	Server address where firmware exists.

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.

uint8_t	ota_auto_swap
	If true, reboot after FW download process is successfully (Only for RTOS)

uint32_t	download_sflash_addr
	Address of SFLASH 2nd FW is stored. (Only for MCU_FW and CERT_KEY)

uint8_t	update_state
	Download status. (success or failed)

uint8_t	status
	Status of the download process (not_ready, ready, progress, finish, stop).

uint8_t	progress_rtos
	RTOS download progress.

uint8_t	progress_mcu_fw
	MCU FW download progress.

uint8_t	progress_cert_key
	CERT_KEY download progress.

uint8_t	progress_ble
	BLE download progress.

uint32_t	ota_custom_address
	Set the address for custom data for fw_mcu and cert keys.

char	mcu_fw_name [RM_OTA_W_MCU_FW_NAME_LEN]
	Set MCU FW name.

void(*	p_callback )(ota_callback_args_t *)
	Pointer to callback.

ota_callback_args_t *	p_callback_memory
	Pointer to optional callback argument memory.

void const *	p_context
	Pointer to context to be passed into callback function.

Macro Definition Documentation

◆ RM_OTA_W_OPEN

#define RM_OTA_W_OPEN

"OPEN" in ASCII, used to avoid multiple open.

Enumeration Type Documentation

◆ rm_ota_w_version_flags_t

enum rm_ota_w_version_flags_t

Status for version check.

Enumerator
RM_OTA_W_HEADER_INIT	Init value.
RM_OTA_W_HEADER_SAME_FW_TYPE	The type of FW to be compared is the same.
RM_OTA_W_HEADER_SAME_MODULE	The Module name of FW to be compared is the same.
RM_OTA_W_HEADER_DIFF_SDK	The SDK version of FW to be compared is different.
RM_OTA_W_HEADER_DIFF_CUST	The customer version of FW to be compared is different.
RM_OTA_W_HEADER_DIFF_FW_TYPE	The type of FW to be compared is different.
RM_OTA_W_HEADER_DIFF_MODULE	The Module of FW to be compared is the different.
RM_OTA_W_HEADER_SAME_MAGIC	The magic number of the FW is the same.
RM_OTA_W_HEADER_INCOMPATI_MAGIC	The magic number of the FW is not compatible.
RM_OTA_W_HEADER_VER_DONT_CARE	The FW is not involved in version checking. (user FW or cert)
RM_OTA_W_HEADER_ERROR	Error.

◆ rm_ota_w_refuse_type_t

enum rm_ota_w_refuse_type_t

Enumerator
RM_OTA_W_REFUSE_CLR	INIT value.
RM_OTA_W_REFUSE_SET	RTOS FW update.

◆ rm_ota_w_state_t

enum rm_ota_w_state_t

Enumerator
RM_OTA_W_STATUS_IDLE	The flash is idle.
RM_OTA_W_STATUS_BUSY	The flash is currently processing a command.

◆ rm_ota_w_bgo_operation_t

enum rm_ota_w_bgo_operation_t

Possible Flash operation states

Function Documentation

◆ RM_OTA_W_Open()

fsp_err_t RM_OTA_W_Open	(	ota_ctrl_t *const	p_api_ctrl,
		ota_cfg_t const *const	p_cfg
	)

Initializes the high performance OTA peripheral. Implements ota_api_t::open.

The Open function initializes the ota.

Example:

/* Open the ota instance with initial configuration. */

err = RM_OTA_W_Open(&g_ota_example_ctrl, &g_ota_example_cfg);

Return values

FSP_SUCCESS	Initialization was successful and timer has started.
FSP_ERR_ALREADY_OPEN	The OTA control block is already open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl or p_cfg.
FSP_ERR_IRQ_BSP_DISABLED	Caller is requesting BGO but the OTA interrupts are not enabled.
FSP_ERR_FCLK	FCLK must be a minimum of 4 MHz for OTA operations.

◆ RM_OTA_W_Close()

fsp_err_t RM_OTA_W_Close ( ota_ctrl_t *const p_api_ctrl )

Releases any resources that were allocated by the Open() or any subsequent OTA operations.

Implements ota_api_t::close.

Return values

FSP_SUCCESS	Successfully close.
FSP_ERR_NOT_OPEN	The control block is not open.
FSP_ERR_ASSERTION	NULL provided for p_ctrl or p_cfg.

◆ RM_OTA_W_Swap()

fsp_err_t RM_OTA_W_Swap ( ota_ctrl_t *const p_api_ctrl )

Trigger versions swap. Swap the programs located at address 0x00002000 and address 0x00400000. Before version swap is done, there will be version check and boot index toggle.

Implements ota_api_t::swap.

Return values

FSP_SUCCESS	Version swap finished successfully.
FSP_ERR_ASSERTION	NULL provided for p_ctrl.
FSP_ERR_IN_USE	OTA process is in progress, we need to wait for last process to finished.

◆ RM_OTA_W_GetImageInfo()

fsp_err_t RM_OTA_W_GetImageInfo	(	ota_ctrl_t *const	p_api_ctrl,
		rm_ota_w_update_type_t	update_type,
		uint32_t	sector_addr,
		rm_ota_w_image_header_data_t *	info_image
	)

Returns the information about the image installed in a specific address.

Implements ota_api_t::getImageInfo.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_INVALID_ADDRESS	Invalid image address was input.

◆ RM_OTA_W_BootIdxSet()

fsp_err_t RM_OTA_W_BootIdxSet	(	ota_ctrl_t *const	p_api_ctrl,
		uint8_t	boot_idx
	)

Updates the boot index value.

Implements ota_api_t::bootIdxSet.

Return values

FSP_SUCCESS	Successfully set the request data.
FSP_ERR_INVALID_ADDRESS	Invalid boot index value

◆ RM_OTA_W_BootIdxGet()

fsp_err_t RM_OTA_W_BootIdxGet	(	ota_ctrl_t *const	p_api_ctrl,
		uint8_t *	boot_idx
	)

Query the current boot index.

Note: This function may also update/synchronize the boot index before returning it.

Implements ota_api_t::bootIdxGet.

Return values

FSP_SUCCESS Successfully retrieved the request information.

◆ RM_OTA_W_GetAddr()

fsp_err_t RM_OTA_W_GetAddr	(	ota_ctrl_t *const	p_api_ctrl,
		uint8_t	state,
		rm_ota_w_update_type_t	update_type,
		uint32_t *	addr
	)

Query the address information regarding the current version address and swap version address.

Implements ota_api_t::getAddr.

Return values

FSP_SUCCESS	Successfully retrieved the request information.
FSP_ERR_INVALID_ADDRESS	Invalid state address value

◆ RM_OTA_W_SetAddr()

fsp_err_t RM_OTA_W_SetAddr	(	ota_ctrl_t *const	p_api_ctrl,
		uint8_t	update_type,
		uint32_t	addr
	)

Set Address value for user device.

Implements ota_api_t::setAddr.

Return values

FSP_SUCCESS	Key variable was changed successfully.
FSP_ERR_INVALID_ADDRESS	Invalid data flash address was input.
FSP_ERR_INVALID_DATA	Invalid key type or unknown data source.

◆ RM_OTA_W_Cert()

fsp_err_t RM_OTA_W_Cert	(	ota_ctrl_t *const	p_api_ctrl,
		uint8_t	cert_type,
		uint32_t	sector_addr
	)

Performs a certification check over the program data, base program or downloaded data based on a specified address area.

Implements ota_api_t::cert.

Return values

FSP_SUCCESS	Operation check passed successfully.
FSP_ERR_INVALID_DATA	Operation check failed due to calculation failure

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for rm_ota_w

Configurations for System > OTA (rm_ota_w)

Usage Notes

Performance

Examples

OTA_W Example

Data Structures

Macros

Enumerations

Data Structure Documentation

◆ rm_ota_w_update_sflash_t

◆ rm_ota_w_update_download_t

◆ rm_ota_w_instance_ctrl_t

Data Fields

Macro Definition Documentation

◆ RM_OTA_W_OPEN

Enumeration Type Documentation

◆ rm_ota_w_version_flags_t

◆ rm_ota_w_refuse_type_t

◆ rm_ota_w_state_t

◆ rm_ota_w_bgo_operation_t

Function Documentation

◆ RM_OTA_W_Open()

◆ RM_OTA_W_Close()

◆ RM_OTA_W_Swap()

◆ RM_OTA_W_GetImageInfo()

◆ RM_OTA_W_BootIdxSet()

◆ RM_OTA_W_BootIdxGet()

◆ RM_OTA_W_GetAddr()

◆ RM_OTA_W_SetAddr()

◆ RM_OTA_W_Cert()