1 /**
2  *
3  * \file
4  *
5  * \brief WINC OTA Upgrade API Interface.
6  *
7  * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved.
8  *
9  * \asf_license_start
10  *
11  * \page License
12  *
13  * Redistribution and use in source and binary forms, with or without
14  * modification, are permitted provided that the following conditions are met:
15  *
16  * 1. Redistributions of source code must retain the above copyright notice,
17  *    this list of conditions and the following disclaimer.
18  *
19  * 2. Redistributions in binary form must reproduce the above copyright notice,
20  *    this list of conditions and the following disclaimer in the documentation
21  *    and/or other materials provided with the distribution.
22  *
23  * 3. The name of Atmel may not be used to endorse or promote products derived
24  *    from this software without specific prior written permission.
25  *
26  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
27  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
28  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
29  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
30  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
34  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
35  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36  * POSSIBILITY OF SUCH DAMAGE.
37  *
38  * \asf_license_stop
39  *
40  */
41 
42 #ifndef __M2M_OTA_H__
43 #define __M2M_OTA_H__
44 
45 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
46 INCLUDES
47 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
48 
49 #include "common/include/nm_common.h"
50 #include "driver/include/m2m_types.h"
51 #include "driver/source/nmdrv.h"
52 /**@addtogroup WlanEnums DataTypes
53  * @ingroup m2m_wifi
54  */
55  /* @{ */
56 
57 
58 /*!
59 @typedef void (*tpfOtaNotifCb) (tstrOtaUpdateInfo *);
60 
61 @brief
62 		A callback to get notification about a potential OTA update.
63 
64 @param[in] pstrOtaUpdateInfo
65 		A structure to provide notification payload.
66 @sa
67 	tstrOtaUpdateInfo
68 @warning
69 		The notification is not supported (Not implemented yet)
70 
71 */
72 typedef void (*tpfOtaNotifCb) (tstrOtaUpdateInfo * pstrOtaUpdateInfo);
73 
74 
75 /*!
76 @typedef void (*tpfOtaUpdateCb) (uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus);
77 
78 @brief
79    A callback to get OTA status update, the callback provide the status type and its status.
80    The OTA callback provides the download status, the switch to the downloaded firmware status and roll-back status.
81 
82 @param[in] u8OtaUpdateStatusType Possible values are listed in tenuOtaUpdateStatusType.
83 
84 @param[in] u8OtaUpdateStatus Possible values are listed as enumerated by @ref tenuOtaUpdateStatus.
85 
86 @see
87 	tenuOtaUpdateStatusType
88 	tenuOtaUpdateStatus
89  */
90 typedef void (*tpfOtaUpdateCb) (uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus);
91  /**@}*/
92 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
93 FUNCTION PROTOTYPES
94 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
95 
96 #ifdef __cplusplus
97      extern "C" {
98 #endif
99 
100 /** @defgroup OtaInitFn m2m_ota_init
101  *  @ingroup WLANAPI
102 * Synchronous initialization function for the OTA layer by registering the update callback.
103 * The notification callback is not supported at the current version. Calling this API is a
104 * MUST for all the OTA API's.
105 
106  */
107  /**@{*/
108 /*!
109 @fn	\
110 	NMI_API sint8  m2m_ota_init(tpfOtaUpdateCb  pfOtaUpdateCb,tpfOtaNotifCb  pfOtaNotifCb)
111 
112 @param [in]	pfOtaUpdateCb
113 				OTA Update callback function
114 
115 @param [in]	pfOtaNotifCb
116 				OTA notify callback function
117 
118 @return
119 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
120 */
121 NMI_API sint8  m2m_ota_init(tpfOtaUpdateCb  pfOtaUpdateCb,tpfOtaNotifCb  pfOtaNotifCb);
122  /**@}*/
123 
124  /** @defgroup OtaNotifStFn m2m_ota_notif_set_url
125  *  @ingroup WLANAPI
126  * Set the OTA notification server URL, the functions need to be called before any check for update
127  */
128  /**@{*/
129 /*!
130 @fn	\
131 	NMI_API sint8  m2m_ota_notif_set_url(uint8 * u8Url);
132 
133 @param [in]	u8Url
134 			 Set the OTA notification server URL, the functions need to be called before any check for update.
135 @warning
136 			Calling m2m_ota_init is required
137 			Notification Server is not supported in the current version (function is not implemented)
138 @see
139 			m2m_ota_init
140 @return
141 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
142 */
143 NMI_API sint8  m2m_ota_notif_set_url(uint8 * u8Url);
144  /**@}*/
145  /** @defgroup OtaNotifCheckFn m2m_ota_notif_check_for_update
146  *  @ingroup WLANAPI
147  * Synchronous function to check for the OTA update using the Notification Server
148  * URL. Function is not implemented (not supported at the current version)
149  *
150  */
151   /**@{*/
152 /*!
153 @fn	\
154 	NMI_API sint8  m2m_ota_notif_check_for_update(void);
155 
156 @warning
157 		Function is not implemented (not supported at the current version)
158 
159 @sa
160 			m2m_ota_init
161 			m2m_ota_notif_set_url
162 @return
163 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
164 */
165 NMI_API sint8  m2m_ota_notif_check_for_update(void);
166  /**@}*/
167  /** @defgroup OtaSched m2m_ota_notif_sched
168 *  @ingroup WLANAPI
169 * Schedule OTA notification Server check for update request after specific number of days
170 */
171   /**@{*/
172 /*!
173 @fn	\
174 	NMI_API sint8 m2m_ota_notif_sched(uint32 u32Period);
175 
176 
177 @param [in]	u32Period
178 			Period in days
179 
180 @sa
181 		m2m_ota_init
182 		m2m_ota_notif_check_for_update
183 		m2m_ota_notif_set_url
184 @return
185 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
186 */
187 NMI_API sint8 m2m_ota_notif_sched(uint32 u32Period);
188   /**@}*/
189 /** @defgroup OtaStartUpdatefn m2m_ota_start_update
190 *  @ingroup WLANAPI
191 *	Request OTA start update using the downloaded URL, the OTA module will download the OTA image and ensure integrity of the image,
192 *   and update the validity of the image in control structure. Switching to that image requires calling @ref m2m_ota_switch_firmware API.
193 *   As a prerequisite @ref m2m_ota_init should be called before using @ref m2m_ota_start().
194 */
195   /**@{*/
196 /*!
197 @fn	\
198 	NMI_API sint8 m2m_ota_start_update(uint8 * u8DownloadUrl);
199 
200 @param [in]	u8DownloadUrl
201 		The download firmware URL, you get it from device info according to the application server
202 
203 @warning
204 	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.
205 	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
206 	except the flash roll-back image location to validate the downloaded image from
207 
208 @see
209 		m2m_ota_init
210 		tpfOtaUpdateCb
211 
212 @return
213 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
214 \section Example
215    The example shows an example of how the OTA image update is carried out.
216 @code
217 static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus)
218 {
219 	if(u8OtaUpdateStatusType == DL_STATUS) {
220 		if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
221 			//switch to the upgraded firmware
222 			m2m_ota_switch_firmware();
223 		}
224 	}
225 	else if(u8OtaUpdateStatusType == SW_STATUS) {
226 		if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) {
227 			M2M_INFO("Now OTA successfully done");
228 			//start the host SW upgrade then system reset is required (Reinitialize the driver)
229 		}
230 	}
231 }
232 void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
233 {
234 	case M2M_WIFI_REQ_DHCP_CONF:
235 	{
236 		//after successfully connection, start the over air upgrade
237 		m2m_ota_start_update(OTA_URL);
238 	}
239 	break;
240 	default:
241 	break;
242 }
243 int main (void)
244 {
245 	tstrWifiInitParam param;
246 	tstr1xAuthCredentials gstrCred1x    = AUTH_CREDENTIALS;
247 	nm_bsp_init();
248 
249 	m2m_memset((uint8*)&param, 0, sizeof(param));
250 	param.pfAppWifiCb = wifi_event_cb;
251 
252 	//Initialize the WINC Driver
253 	ret = m2m_wifi_init(&param);
254 	if (M2M_SUCCESS != ret)
255 	{
256 		M2M_ERR("Driver Init Failed <%d>\n",ret);
257 		while(1);
258 	}
259 	//Initialize the OTA module
260 	m2m_ota_init(OtaUpdateCb,NULL);
261 	//connect to AP that provide connection to the OTA server
262 	m2m_wifi_default_connect();
263 
264 	while(1)
265 	{
266 
267 		//Handle the app state machine plus the WINC event handler
268 		while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) {
269 
270 		}
271 
272 	}
273 }
274 @endcode
275 
276 */
277 NMI_API sint8 m2m_ota_start_update(uint8 * u8DownloadUrl);
278     /**@}*/
279 /** @defgroup OtaStartUpdatefn m2m_ota_start_update_crt
280 *  @ingroup WLANAPI
281 *	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,
282 *   and update the validity of the image in control structure. Switching to that image requires calling @ref m2m_ota_switch_crt API.
283 *   As a prerequisite @ref m2m_ota_init should be called before using @ref m2m_ota_start_update_crt().
284 */
285   /**@{*/
286 /*!
287 @fn	\
288 	NMI_API sint8 m2m_ota_start_update_crt(uint8 * u8DownloadUrl);
289 
290 @param [in]	u8DownloadUrl
291 		The cortus application image url.
292 @warning
293 	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.
294 	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
295 	except the flash roll-back image location to validate the downloaded image from
296 
297 @see
298 		m2m_ota_init
299 		tpfOtaUpdateCb
300 
301 @return
302 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
303 */
304 NMI_API sint8 m2m_ota_start_update_crt(uint8 * u8DownloadUrl);
305   /**@}*/
306 /** @defgroup OtaRollbackfn m2m_ota_rollback
307 *  @ingroup WLANAPI
308 	Request OTA Roll-back to the old (other) WINC image, the WINC firmware will check the validation of the Roll-back image
309 	and switch to it if it is valid.
310 	If the API response is success, system restart is required (re-initialize the driver with hardware rest) update the host driver version may
311 	be required if it is did not match the minimum version supported by the  WINC firmware.
312 
313 */
314   /**@{*/
315 /*!
316 @fn	\
317 	NMI_API sint8 m2m_ota_rollback(void);
318 
319 @sa
320 	m2m_ota_init
321 	m2m_ota_start_update
322 
323 @return
324 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
325 */
326 NMI_API sint8 m2m_ota_rollback(void);
327     /**@}*/
328 /** @defgroup OtaRollbackfn m2m_ota_rollback_crt
329 *  @ingroup WLANAPI
330 	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
331 	and switch to it if it is valid.
332 	If the API response is success, system restart is required (re-initialize the driver with hardware rest) update the host driver version may
333 	be required.
334 
335 */
336   /**@{*/
337 /*!
338 @fn	\
339 	NMI_API sint8 m2m_ota_rollback_crt(void);
340 
341 @sa
342 	m2m_ota_init
343 	m2m_ota_start_update_crt
344 
345 @return
346 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
347 */
348 NMI_API sint8 m2m_ota_rollback_crt(void);
349   /**@}*/
350 /** @defgroup OtaAbortfn m2m_ota_abort
351 *  @ingroup WLANAPI
352 	Request abort of current OTA download.
353 	The WINC firmware will terminate the OTA download if one is in progress.
354 	If no download is in progress, the API will respond with failure.
355 */
356   /**@{*/
357 /*!
358 @fn	\
359 	NMI_API sint8 m2m_ota_abort(void);
360 
361 @return
362 	The function returns @ref M2M_SUCCESS for successful operation and a negative value otherwise.
363 */
364 NMI_API sint8 m2m_ota_abort(void);
365   /**@}*/
366   /**@}*/
367 /** @defgroup OtaSwitchFirmware m2m_ota_switch_firmware
368 *  @ingroup WLANAPI
369 * Switch to the upgraded Firmware, that API will update the control structure working image to the upgraded image
370   take effect will be on the next system restart
371 */
372   /**@{*/
373 /*!
374 @fn	\
375 	NMI_API sint8 m2m_ota_switch_firmware(void);
376 
377 @warning
378    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
379    if it does not match the minimum driver version supported by the WINC's firmware.
380 @sa
381 	m2m_ota_init
382 	m2m_ota_start_update
383 
384 @return
385 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
386 */
387 NMI_API sint8 m2m_ota_switch_firmware(void);
388   /**@}*/
389   /**@}*/
390 /** @defgroup OtaSwitchFirmware m2m_ota_switch_crt
391 *  @ingroup WLANAPI
392 * Switch to the upgraded cortus application, that API will update the control structure working image to the upgraded image
393   take effect will be on the next system restart
394 */
395   /**@{*/
396 /*!
397 @fn	\
398 	NMI_API sint8 m2m_ota_switch_firmware(void);
399 
400 @warning
401    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
402    if it does not match the minimum driver version supported by the WINC's firmware.
403 @sa
404 	m2m_ota_init
405 	m2m_ota_start_update_crt
406 
407 @return
408 	The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
409 */
410 NMI_API sint8 m2m_ota_switch_crt(void);
411 /*!
412 @fn	\
413 	NMI_API sint8 m2m_ota_get_firmware_version(void);
414 
415 @brief
416 	Get the OTA Firmware version.
417 
418 @return
419 	The function SHALL return 0 for success and a negative value otherwise.
420 */
421 NMI_API sint8 m2m_ota_get_firmware_version(tstrM2mRev *pstrRev);
422   /**@}*/
423 NMI_API sint8 m2m_ota_test(void);
424 
425 #ifdef __cplusplus
426 }
427 #endif
428 #endif /* __M2M_OTA_H__ */
429