Functions
Functions
OTA
Collaboration diagram for Functions:

Functions

NMI_API sint8 m2m_ota_abort (void)
 Request OTA Abort. More...
 
NMI_API sint8 m2m_ota_init (tpfOtaUpdateCb pfOtaUpdateCb, tpfOtaNotifCb pfOtaNotifCb)
 Initialize the OTA layer. More...
 
NMI_API sint8 m2m_ota_notif_check_for_update (void)
 check for ota update More...
 
NMI_API sint8 m2m_ota_notif_sched (uint32 u32Period)
 Schedule OTA update. More...
 
NMI_API sint8 m2m_ota_notif_set_url (uint8 *u8Url)
 Set the OTA url. More...
 
NMI_API sint8 m2m_ota_rollback (void)
 Request OTA Rollback image. More...
 
NMI_API sint8 m2m_ota_start_update (uint8 *u8DownloadUrl)
 Request OTA start update using the downloaded url. More...
 
NMI_API sint8 m2m_ota_switch_firmware (void)
 Switch to the upgraded Firmware. More...
 

Detailed Description

Function Documentation

◆ m2m_ota_abort()

NMI_API sint8 m2m_ota_abort ( void  )

Request OTA Abort.

Abort an ota in progress (eg if server has stalled) and clean up

See also
m2m_ota_init m2m_ota_start_update
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 269 of file m2m_ota.c.

◆ m2m_ota_init()

NMI_API sint8 m2m_ota_init ( tpfOtaUpdateCb  pfOtaUpdateCb,
tpfOtaNotifCb  pfOtaNotifCb 
)

Initialize the OTA layer.

Synchronous initialization function for the OTA layer by registering the update callback. The notification callback is not supported at the current version. Calling this API is a prerequisite for all other OTA API's.

Parameters
[in]pfOtaUpdateCbOTA Update callback function
[in]pfOtaNotifCbOTA notify callback function
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
Parameters
[in]pfOtaUpdateCbOTA Update callback function
[in]pfOtaNotifCbOTA notify callback function
Returns
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 121 of file m2m_ota.c.

◆ m2m_ota_notif_check_for_update()

NMI_API sint8 m2m_ota_notif_check_for_update ( void  )

check for ota update

Synchronous function to check for the OTA update using the Notification Server URL. This functionality is not supported by WINC firmware.

Warning
This functionality is not supported by WINC firmware.
See also
m2m_ota_init m2m_ota_notif_set_url
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 175 of file m2m_ota.c.

◆ m2m_ota_notif_sched()

NMI_API sint8 m2m_ota_notif_sched ( uint32  u32Period)

Schedule OTA update.

Schedule OTA notification Server check for update request after specific number of days. This functionality is not supported by WINC firmware.

Parameters
[in]u32PeriodPeriod in days
Warning
This functionality is not supported by WINC firmware.
See also
m2m_ota_init m2m_ota_notif_check_for_update m2m_ota_notif_set_url
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
Parameters
[in]u32PeriodPeriod in days
Returns
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 195 of file m2m_ota.c.

◆ m2m_ota_notif_set_url()

NMI_API sint8 m2m_ota_notif_set_url ( uint8 *  u8Url)

Set the OTA url.

Set the OTA notification server URL, the functions need to be called before any check for update. This functionality is not supported by WINC firmware.

Parameters
[in]u8UrlSet the OTA notification server URL, the functions need to be called before any check for update.
Warning
This functionality is not supported by WINC firmware.
See also
m2m_ota_init
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
Parameters
[in]u8UrlThe url server address
Returns
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 153 of file m2m_ota.c.

◆ m2m_ota_rollback()

NMI_API sint8 m2m_ota_rollback ( void  )

Request OTA Rollback image.

Request rollback to the old (inactive) WINC image. The WINC firmware will check the validity of the inactive image and activate it if it is valid. On completion, a callback of type tpfOtaUpdateCb is called (application must previously have provided the callback via m2m_ota_init()). If the callback indicates successful activation, the newly-activated image will start running after next system reset.

Warning
If rollback will necessitate a host driver update in order to maintain HIF compatibility (HIF major value change), then it is recommended to update the host driver prior to calling this API. In the event of system reset with incompatible driver/firmware, compatibility can be recovered by calling m2m_ota_rollback or m2m_ota_switch_firmware. See Example.
See also
m2m_ota_init m2m_ota_start_update
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 238 of file m2m_ota.c.

◆ m2m_ota_start_update()

NMI_API sint8 m2m_ota_start_update ( uint8 *  u8DownloadUrl)

Request OTA start update using the downloaded url.

Request OTA start update using the downloaded URL. The firmware OTA module will download the OTA image, ensure integrity of the image, and update the validity of the image in the control structure. On completion, a callback of type tpfOtaUpdateCb is called (callback previously provided via m2m_ota_init()). Switching to the updated image additionally requires completion of m2m_ota_switch_firmware(), and system_reset().

Parameters
[in]u8DownloadUrlThe download firmware URL, according to the application server.
Warning
Calling this API does not guarantee OTA WINC image update; it depends on the connection with the download server and the validity of the image. Calling this API invalidates the previous rollback image. The current image will become the rollback image after m2m_ota_switch_firmware().
Precondition
m2m_ota_init() must have been called before using m2m_ota_start_update().
See also
m2m_ota_init() m2m_ota_switch_firmware() tpfOtaUpdateCb
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise. Note that successful operation in this context means the OTA update request has reached the firmware OTA module. It does not indicate whether or not the image update succeeded.

Example

This example shows how an OTA image update and switch is carried out. It demonstrates use of the following OTA APIs: m2m_ota_init() tpfOtaUpdateCb m2m_ota_start_update() m2m_ota_switch_firmware() m2m_ota_rollback() It also makes use of m2m_wifi_check_ota_rb() in order to inform OTA decisions.

static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus)
{
sint8 s8tmp;
tstrM2mRev strtmp;
M2M_INFO("%d %d\n", u8OtaUpdateStatusType, u8OtaUpdateStatus);
switch(u8OtaUpdateStatusType) {
case DL_STATUS:
if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
M2M_INFO("OTA download succeeded\n");
s8tmp = m2m_wifi_check_ota_rb();
if(s8tmp == M2M_ERR_FW_VER_MISMATCH) {
// In this case the application SHOULD update the host driver before calling
// @ref m2m_ota_switch_firmware(). Switching firmware image and resetting without updating host
// driver would lead to severely limited functionality (i.e. OTA rollback only).
}
else if(s8tmp == M2M_SUCCESS) {
// In this case the application MAY WANT TO update the host driver before calling
// @ref m2m_ota_switch_firmware(). Switching firmware image and resetting without updating host
// driver may lead to suboptimal functionality.
}
else {
M2M_INFO("Cannot recognize downloaded image\n");
// In this case the application MUST NOT update the host driver if such an update would change the
// driver HIF Major field. Firmware switch @ref using m2m_ota_switch_firmware() is blocked.
break;
}
M2M_INFO("Now switching active partition...\n");
s8tmp = m2m_ota_switch_firmware();
}
break;
case SW_STATUS:
case RB_STATUS:
if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
M2M_INFO("Switch/Rollback succeeded\n");
M2M_INFO("Now resetting the system...\n");
system_reset();
}
break;
}
}
static void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
// ...
case M2M_WIFI_REQ_DHCP_CONF:
{
//After successful connection, start the OTA upgrade.
m2m_ota_start_update(OTA_URL);
}
break;
// ...
}
int main (void)
{
sint8 ret = M2M_SUCCESS;
tstrWifiInitParam param;
bool rollback_required = FALSE;
// ... system init etc here ...
//Initialize the WINC Driver.
m2m_memset((uint8*)&param, 0, sizeof(param));
param.pfAppWifiCb = wifi_event_cb;
ret = m2m_wifi_init(&param);
if(ret == M2M_ERR_FW_VER_MISMATCH) {
ret = m2m_wifi_check_ota_rb();
if(ret == M2M_SUCCESS) {
// In this case the image in the inactive partition has compatible HIF. We will switch/rollback to it
// after initializing the OTA module.
rollback_required = TRUE;
}
}
if(ret != M2M_SUCCESS) {
M2M_ERR("Driver Init Failed <%d>\n",ret);
while(1);
}
//Initialize the OTA module.
m2m_ota_init(OtaUpdateCb, NULL);
if(rollback_required) {
// We need to call either @ref m2m_ota_rollback() or @ref m2m_ota_switch_firmware() (functionally equivalent).
m2m_ota_rollback();
} else {
// Connect to AP that provides connection to the OTA server
m2m_wifi_default_connect();
}
while(1) {
// Handle the app state machine plus the WINC event handler.
while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) {
}
}
}
Parameters
[in]u8DownloadUrlThe download firmware url, you get it from device info
Returns
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 216 of file m2m_ota.c.

◆ m2m_ota_switch_firmware()

NMI_API sint8 m2m_ota_switch_firmware ( void  )

Switch to the upgraded Firmware.

Request switch to the updated WINC image. The WINC firmware will check the validity of the inactive image and activate it if it is valid. On completion, a callback of type tpfOtaUpdateCb is called (application must previously have provided the callback via m2m_ota_init()). If the callback indicates successful activation, the newly-activated image will start running after next system reset.

Warning
If switch will necessitate a host driver update in order to maintain HIF compatibility (HIF major value change), then it is recommended to update the host driver prior to calling this API. In the event of system reset with incompatible driver/firmware, compatibility can be recovered by calling m2m_ota_rollback or m2m_ota_switch_firmware. See Example.
See also
m2m_ota_init m2m_ota_start_update
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
The function SHALL return 0 for success and a negative value otherwise.

Definition at line 287 of file m2m_ota.c.


inertial_sense_ros
Author(s):
autogenerated on Sun Feb 28 2021 03:18:00