Functions
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 (unsigned char *pcDownloadUrl)
	Request OTA start update using the downloaded URL. More...

NMI_API sint8	m2m_ota_switch_firmware (void)
	Switch to the upgraded Firmware. More...

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.
Function is not implemented (not supported at the current version).

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Warning: Function is not implemented (not supported at the current version).

See Also: m2m_ota_init m2m_ota_notif_set_url

Returns: The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

References hif_send(), M2M_OTA_REQ_NOTIF_CHECK_FOR_UPDATE, M2M_REQ_GROUP_OTA, M2M_SUCCESS, and NULL.

sint8 m2m_ota_notif_sched ( uint32 u32Period )

Schedule OTA update.

Schedule OTA notification Server check for update request after specific number of days.
Function is not implemented (not supported at the current version).

Parameters

[in] u32Period Period in days

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Parameters

[in] u32Period Period in days

Warning: Function is not implemented (not supported at the current version).

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.

References hif_send(), M2M_OTA_REQ_NOTIF_CHECK_FOR_UPDATE, M2M_REQ_GROUP_OTA, M2M_SUCCESS, and NULL.

sint8 m2m_ota_notif_set_url ( uint8 * u8Url )

Set the OTA url.

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

Parameters

[in] u8Url The url server address.

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Parameters

[in] u8Url Set the OTA notification server URL, the function needs to be called before any check for update.

Precondition: Prior calling of m2m_ota_init is required.

Warning: Notification Server is not supported in the current version (function is not implemented).

See Also: m2m_ota_init

Returns: The function returns M2M_SUCCESS for successful operations and a negative value otherwise.

References hif_send(), M2M_OTA_REQ_NOTIF_SET_URL, M2M_REQ_GROUP_OTA, m2m_strlen(), M2M_SUCCESS, and NULL.

sint8 m2m_ota_rollback ( void )

Request OTA Rollback image.

Request OTA Roll-back to the old (inactive) WINC image, the WINC firmware will check the validity of the inactive image and activate it if 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.

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Warning: If rollback requires 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.

References hif_send(), M2M_OTA_REQ_ROLLBACK_FW, M2M_REQ_GROUP_OTA, M2M_SUCCESS, and NULL.

sint8 m2m_ota_start_update ( unsigned char * pcDownloadUrl )

Request OTA start update using the downloaded URL.

Request OTA start update using the download URL. The 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] pcDownloadUrl The download firmware URL, you get it from device info.

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Parameters

[in] pcDownloadUrl The 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 any previous valid rollback image, irrespective of the result, but when the OTA succeeds, the current image will become the rollback image after m2m_ota_switch_firmware.

Precondition: m2m_ota_init is a prerequisite and must have been called before using m2m_ota_start_update.
Switching to the newly downloaded image requires calling m2m_ota_switch_firmware API.

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:

static void OtaUpdateCb(uint8 u8OtaUpdateStatusType, uint8 u8OtaUpdateStatus)
{
    M2M_INFO("%d %d\n", u8OtaUpdateStatusType, u8OtaUpdateStatus);
    switch(u8OtaUpdateStatusType)
    {
    case DL_STATUS:
        if(u8OtaUpdateStatus == OTA_STATUS_SUCCESS)
        {
            M2M_INFO("OTA download succeeded\n");
            // 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.
            // Switch to the upgraded firmware
            M2M_INFO("Now switching active partition...\n");
            m2m_ota_switch_firmware();
        }
        break;
    case SW_STATUS:
    case RB_STATUS:
        if(u8OtaUpdateStatus == OTA_STATUS_SUCCESS)
        {
            M2M_INFO("Switch/Rollback succeeded\n");
            // Start the host SW upgrade if required, then system reset is required (Reinitialize the driver)
            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;
    default:
    break;
    // ...
}
int main (void)
{
    tstrWifiInitParam     param;
    sint8                 s8Ret             = M2M_SUCCESS;
    bool                  rollback_required = FALSE;
    tstr1xAuthCredentials gstrCred1x        = AUTH_CREDENTIALS;
    // System init, etc should be here...
    m2m_memset((uint8*)&param, 0, sizeof(param));
    param.pfAppWifiCb = wifi_event_cb;
    // Initialize the WINC Driver
    s8Ret = m2m_wifi_init(&param);
    if(s8Ret == M2M_ERR_FW_VER_MISMATCH)
    {
        M2M_ERR("Firmware version mismatch\n");
    }
    if (M2M_SUCCESS != s8Ret)
    {
        M2M_ERR("Driver Init Failed <%d>\n",s8Ret);
        while(1);
    }
    // Initialize the OTA module
    m2m_ota_init(OtaUpdateCb,NULL);
    // 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) {
        }
    }
}

References hif_send(), M2M_OTA_REQ_START_FW_UPDATE, M2M_REQ_GROUP_OTA, m2m_strlen(), M2M_SUCCESS, and NULL.

Referenced by wifi_cb().

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

Returns: The function returns M2M_SUCCESS for success and a negative value otherwise.

Warning: If switch requires 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.

References hif_send(), M2M_OTA_REQ_SWITCH_FIRMWARE, M2M_REQ_GROUP_OTA, M2M_SUCCESS, and NULL.

Referenced by OtaUpdateCb().

Microchip® Advanced Software Framework

Functions

Example