m2m_ota.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC OTA Upgrade API Interface.
00006  *
00007  * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041 
00042 #ifndef __M2M_OTA_H__
00043 #define __M2M_OTA_H__
00044 
00045 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00046 INCLUDES
00047 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00048 
00049 #include "common/include/nm_common.h"
00050 #include "driver/include/m2m_types.h"
00051 #include "driver/source/nmdrv.h"
00052 /**@addtogroup WlanEnums DataTypes
00053  * @ingroup m2m_wifi
00054  */
00055  /* @{ */
00056 
00057 
00058 /*!
00059 @typedef void (*tpfOtaNotifCb) (tstrOtaUpdateInfo *);
00060 
00061 @brief  
00062         A callback to get notification about a potential OTA update.
00063  
00064 @param[in] pstrOtaUpdateInfo 
00065         A structure to provide notification payload.
00066 @sa 
00067     tstrOtaUpdateInfo
00068 @warning 
00069         The notification is not supported (Not implemented yet)
00070 
00071 */
00072 typedef void (*tpfOtaNotifCb) (tstrOtaUpdateInfo * pstrOtaUpdateInfo);
00073 
00074 
00075 /*!
00076 @typedef void (*tpfOtaUpdateCb) (uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus);
00077 
00078 @brief 
00079    A callback to get OTA status update, the callback provide the status type and its status.
00080    The OTA callback provides the download status, the switch to the downloaded firmware status and roll-back status. 
00081  
00082 @param[in] u8OtaUpdateStatusType Possible values are listed in tenuOtaUpdateStatusType.
00083 
00084 @param[in] u8OtaUpdateStatus Possible values are listed as enumerated by @ref tenuOtaUpdateStatus. 
00085 
00086 @see
00087     tenuOtaUpdateStatusType
00088     tenuOtaUpdateStatus
00089  */
00090 typedef void (*tpfOtaUpdateCb) (uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus);
00091  /**@}*/
00092 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00093 FUNCTION PROTOTYPES
00094 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00095 
00096 #ifdef __cplusplus
00097      extern "C" {
00098 #endif
00099 
00100 /** @defgroup OtaInitFn m2m_ota_init
00101  *  @ingroup WLANAPI
00102 * Synchronous initialization function for the OTA layer by registering the update callback.
00103 * The notification callback is not supported at the current version. Calling this API is a
00104 * MUST for all the OTA API's.
00105 
00106  */
00107  /**@{*/
00108 /*!
00109 @fn \
00110     NMI_API sint8  m2m_ota_init(tpfOtaUpdateCb  pfOtaUpdateCb,tpfOtaNotifCb  pfOtaNotifCb)
00111 
00112 @param [in] pfOtaUpdateCb
00113                 OTA Update callback function
00114                 
00115 @param [in] pfOtaNotifCb
00116                 OTA notify callback function 
00117 
00118 @return     
00119     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00120 */
00121 NMI_API sint8  m2m_ota_init(tpfOtaUpdateCb  pfOtaUpdateCb,tpfOtaNotifCb  pfOtaNotifCb);
00122  /**@}*/
00123  
00124  /** @defgroup OtaNotifStFn m2m_ota_notif_set_url
00125  *  @ingroup WLANAPI
00126  * Set the OTA notification server URL, the functions need to be called before any check for update
00127  */
00128  /**@{*/
00129 /*!
00130 @fn \
00131     NMI_API sint8  m2m_ota_notif_set_url(uint8 * u8Url);
00132 
00133 @param [in] u8Url
00134              Set the OTA notification server URL, the functions need to be called before any check for update.
00135 @warning 
00136             Calling m2m_ota_init is required
00137             Notification Server is not supported in the current version (function is not implemented)
00138 @see    
00139             m2m_ota_init            
00140 @return     
00141     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00142 */
00143 NMI_API sint8  m2m_ota_notif_set_url(uint8 * u8Url);
00144  /**@}*/
00145  /** @defgroup OtaNotifCheckFn m2m_ota_notif_check_for_update
00146  *  @ingroup WLANAPI
00147  * Synchronous function to check for the OTA update using the Notification Server
00148  * URL. Function is not implemented (not supported at the current version)
00149  *
00150  */
00151   /**@{*/
00152 /*!
00153 @fn \
00154     NMI_API sint8  m2m_ota_notif_check_for_update(void);
00155 
00156 @warning 
00157         Function is not implemented (not supported at the current version)
00158         
00159 @sa   
00160             m2m_ota_init
00161             m2m_ota_notif_set_url
00162 @return     
00163     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00164 */
00165 NMI_API sint8  m2m_ota_notif_check_for_update(void);
00166  /**@}*/
00167  /** @defgroup OtaSched m2m_ota_notif_sched
00168 *  @ingroup WLANAPI
00169 * Schedule OTA notification Server check for update request after specific number of days
00170 */
00171   /**@{*/
00172 /*!
00173 @fn \
00174     NMI_API sint8 m2m_ota_notif_sched(uint32 u32Period);
00175 
00176 
00177 @param [in] u32Period
00178             Period in days
00179 
00180 @sa 
00181         m2m_ota_init
00182         m2m_ota_notif_check_for_update
00183         m2m_ota_notif_set_url
00184 @return     
00185     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00186 */
00187 NMI_API sint8 m2m_ota_notif_sched(uint32 u32Period);
00188   /**@}*/
00189 /** @defgroup OtaStartUpdatefn m2m_ota_start_update
00190 *  @ingroup WLANAPI
00191 *   Request OTA start update using the downloaded URL, the OTA module will download the OTA image and ensure integrity of the image, 
00192 *   and update the validity of the image in control structure. Switching to that image requires calling @ref m2m_ota_switch_firmware API. 
00193 *   As a prerequisite @ref m2m_ota_init should be called before using @ref m2m_ota_start().
00194 */
00195   /**@{*/
00196 /*!
00197 @fn \
00198     NMI_API sint8 m2m_ota_start_update(uint8 * u8DownloadUrl);
00199 
00200 @param [in] u8DownloadUrl
00201         The download firmware URL, you get it from device info according to the application server
00202 
00203 @warning
00204     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.
00205     If the API response is failure this may invalidate the roll-back image if it was previously valid, since the WINC does not have any internal memory 
00206     except the flash roll-back image location to validate the downloaded image from
00207                 
00208 @see        
00209         m2m_ota_init
00210         tpfOtaUpdateCb
00211         
00212 @return     
00213     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00214 \section Example
00215    The example shows an example of how the OTA image update is carried out.
00216 @code
00217 static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus)
00218 {
00219     if(u8OtaUpdateStatusType == DL_STATUS) {
00220         if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
00221             //switch to the upgraded firmware
00222             m2m_ota_switch_firmware();
00223         }
00224     }
00225     else if(u8OtaUpdateStatusType == SW_STATUS) {
00226         if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
00227             M2M_INFO("Now OTA successfully done");
00228             //start the host SW upgrade then system reset is required (Reinitialize the driver)
00229         }
00230     }
00231 }
00232 void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
00233 {
00234     case M2M_WIFI_REQ_DHCP_CONF:
00235     {
00236         //after successfully connection, start the over air upgrade
00237         m2m_ota_start_update(OTA_URL);
00238     }
00239     break;
00240     default:
00241     break;
00242 }
00243 int main (void)
00244 {
00245     tstrWifiInitParam param;
00246     tstr1xAuthCredentials gstrCred1x    = AUTH_CREDENTIALS;
00247     nm_bsp_init();
00248     
00249     m2m_memset((uint8*)&param, 0, sizeof(param));
00250     param.pfAppWifiCb = wifi_event_cb;
00251     
00252     //Initialize the WINC Driver
00253     ret = m2m_wifi_init(&param);
00254     if (M2M_SUCCESS != ret)
00255     {
00256         M2M_ERR("Driver Init Failed <%d>\n",ret);
00257         while(1);
00258     }
00259     //Initialize the OTA module
00260     m2m_ota_init(OtaUpdateCb,NULL);
00261     //connect to AP that provide connection to the OTA server
00262     m2m_wifi_default_connect();
00263 
00264     while(1)
00265     {
00266         
00267         //Handle the app state machine plus the WINC event handler                                                                     
00268         while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) {
00269             
00270         }
00271         
00272     }
00273 }
00274 @endcode        
00275 
00276 */
00277 NMI_API sint8 m2m_ota_start_update(uint8 * u8DownloadUrl);
00278     /**@}*/
00279 /** @defgroup OtaStartUpdatefn m2m_ota_start_update_crt
00280 *  @ingroup WLANAPI
00281 *   Request OTA start for cortus application image using the downloaded URL, the OTA module will download the OTA image and ensure integrity of the image, 
00282 *   and update the validity of the image in control structure. Switching to that image requires calling @ref m2m_ota_switch_crt API. 
00283 *   As a prerequisite @ref m2m_ota_init should be called before using @ref m2m_ota_start_update_crt().
00284 */
00285   /**@{*/
00286 /*!
00287 @fn \
00288     NMI_API sint8 m2m_ota_start_update_crt(uint8 * u8DownloadUrl);
00289 
00290 @param [in] u8DownloadUrl
00291         The cortus application image url.
00292 @warning
00293     Calling this API does not guarantee cortus application image update, It depends on the connection with the download server and the validity of the image.
00294     If the API response is failure this may invalidate the roll-back image if it was previously valid, since the WINC does not have any internal memory 
00295     except the flash roll-back image location to validate the downloaded image from
00296                 
00297 @see        
00298         m2m_ota_init
00299         tpfOtaUpdateCb
00300         
00301 @return     
00302     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00303 */
00304 NMI_API sint8 m2m_ota_start_update_crt(uint8 * u8DownloadUrl);
00305   /**@}*/
00306 /** @defgroup OtaRollbackfn m2m_ota_rollback
00307 *  @ingroup WLANAPI
00308     Request OTA Roll-back to the old (other) WINC image, the WINC firmware will check the validation of the Roll-back image
00309     and switch to it if it is valid.
00310     If the API response is success, system restart is required (re-initialize the driver with hardware rest) update the host driver version may
00311     be required if it is did not match the minimum version supported by the  WINC firmware.
00312 
00313 */
00314   /**@{*/
00315 /*!
00316 @fn \
00317     NMI_API sint8 m2m_ota_rollback(void);
00318 
00319 @sa 
00320     m2m_ota_init
00321     m2m_ota_start_update    
00322 
00323 @return     
00324     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00325 */
00326 NMI_API sint8 m2m_ota_rollback(void);
00327     /**@}*/
00328 /** @defgroup OtaRollbackfn m2m_ota_rollback_crt
00329 *  @ingroup WLANAPI
00330     Request Cortus application OTA Roll-back to the old (other) cortus application image, the WINC firmware will check the validation of the Roll-back image
00331     and switch to it if it is valid.
00332     If the API response is success, system restart is required (re-initialize the driver with hardware rest) update the host driver version may
00333     be required.
00334 
00335 */
00336   /**@{*/
00337 /*!
00338 @fn \
00339     NMI_API sint8 m2m_ota_rollback_crt(void);
00340 
00341 @sa 
00342     m2m_ota_init
00343     m2m_ota_start_update_crt    
00344 
00345 @return     
00346     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00347 */
00348 NMI_API sint8 m2m_ota_rollback_crt(void);
00349   /**@}*/
00350 /** @defgroup OtaAbortfn m2m_ota_abort
00351 *  @ingroup WLANAPI
00352     Request abort of current OTA download.
00353     The WINC firmware will terminate the OTA download if one is in progress.
00354     If no download is in progress, the API will respond with failure.
00355 */
00356   /**@{*/
00357 /*!
00358 @fn \
00359     NMI_API sint8 m2m_ota_abort(void);
00360 
00361 @return
00362     The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.
00363 */
00364 NMI_API sint8 m2m_ota_abort(void);
00365   /**@}*/
00366   /**@}*/
00367 /** @defgroup OtaSwitchFirmware m2m_ota_switch_firmware
00368 *  @ingroup WLANAPI
00369 * Switch to the upgraded Firmware, that API will update the control structure working image to the upgraded image
00370   take effect will be on the next system restart
00371 */
00372   /**@{*/
00373 /*!
00374 @fn \
00375     NMI_API sint8 m2m_ota_switch_firmware(void);
00376 
00377 @warning
00378    It is important to note that if the API succeeds, system restart is required (re-initializing the driver with hardware reset) updating the host driver version may be required 
00379    if it does not match the minimum driver version supported by the WINC's firmware.
00380 @sa 
00381     m2m_ota_init
00382     m2m_ota_start_update
00383 
00384 @return     
00385     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00386 */
00387 NMI_API sint8 m2m_ota_switch_firmware(void);
00388   /**@}*/
00389   /**@}*/
00390 /** @defgroup OtaSwitchFirmware m2m_ota_switch_crt
00391 *  @ingroup WLANAPI
00392 * Switch to the upgraded cortus application, that API will update the control structure working image to the upgraded image
00393   take effect will be on the next system restart
00394 */
00395   /**@{*/
00396 /*!
00397 @fn \
00398     NMI_API sint8 m2m_ota_switch_firmware(void);
00399 
00400 @warning
00401    It is important to note that if the API succeeds, system restart is required (re-initializing the driver with hardware reset) updating the host driver version may be required 
00402    if it does not match the minimum driver version supported by the WINC's firmware.
00403 @sa 
00404     m2m_ota_init
00405     m2m_ota_start_update_crt
00406 
00407 @return     
00408     The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00409 */
00410 NMI_API sint8 m2m_ota_switch_crt(void);
00411 /*!
00412 @fn \
00413     NMI_API sint8 m2m_ota_get_firmware_version(void);
00414 
00415 @brief
00416     Get the OTA Firmware version.
00417 
00418 @return
00419     The function SHALL return 0 for success and a negative value otherwise.
00420 */
00421 NMI_API sint8 m2m_ota_get_firmware_version(tstrM2mRev *pstrRev);
00422   /**@}*/
00423 NMI_API sint8 m2m_ota_test(void);
00424 
00425 #ifdef __cplusplus
00426 }
00427 #endif
00428 #endif /* __M2M_OTA_H__ */
00429 
00430