Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

Functions

NMI_API sint8 m2m_ota_host_file_erase (uint8 u8Handler, tpfFileEraseCb pfHFDEraseCb)
 Erase any traces of an existing file, this means from host driver and WINC firmware. More...
 
NMI_API sint8 m2m_ota_host_file_get (unsigned char *pcDownloadUrl, tpfFileGetCb pfHFDGetCb)
 Download a file from a remote location and store it in the WINC's Flash. More...
 
NMI_API sint8 m2m_ota_host_file_read_hif (uint8 u8Handler, uint32 u32Offset, uint32 u32Size, tpfFileReadCb pfHFDReadCb)
 Read a certain amount of bytes from a file in WINC's Flash using HIF transfer. More...
 
NMI_API sint8 m2m_ota_host_file_read_spi (uint8 u8Handler, uint8 *pu8Buff, uint32 u32Offset, uint32 u32Size)
 Read a certain amount of bytes from a file in WINC's Flash using SPI transfer. More...
 

sint8 m2m_ota_host_file_erase ( uint8  u8Handler,
tpfFileEraseCb  pfHFDEraseCb 
)

Erase any traces of an existing file, this means from host driver and WINC firmware.

Erase any traces of file stored in WINC's Flash.

Parameters
[in]u8HandlerID of the file we are trying to erase. Must be valid.
[in]pfHFDEraseCbPointer to callback to execute when the file erase in the WINC completes.
Returns
Status of the erase operation.
Note
Providing a callback is optional. If the current handler is invalid at this point, it means one of the three:
  1. The file never existed;
  2. The file has already been already deleted;
  3. The request to get the file hasn't fully completed. For 1. and 2. there is no need to signal the WINC to erase the file in Flash. For 3. the Flash can't be erased while a file download is ongoing.
Parameters
[in]u8HandlerHandler of the file we are trying to erase. Must be valid.
[in]pfHFDEraseCbPointer to callback (see tpfFileEraseCb) to execute when the file erase is completed by the WINC.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Precondition
In order to execute the callback, m2m_ota_init must be called before requesting the erase.
Note
Providing a callback is optional. If the current handler is invalid at this point, it means one of the three:
  1. The file never existed;
  2. The file has already been already deleted;
  3. The request to get the file hasn't fully completed.
For 1. and 2. there is no need to signal the WINC to erase the file in Flash.
For 3. the Flash can't be erased while a file download is ongoing.
Warning
A valid file handler must be provided, this means that it needs to match the handler internally stored by the WINC and must not be HFD_INVALID_HANDLER.
The handlers will be destroyed regardless of the call returning success or not.
See Also
m2m_ota_init m2m_ota_host_file_get

References gpfHFDEraseCb, gpfHFDReadCb, gu8CurrFileHandlerID, HFD_INVALID_HANDLER, hif_send(), M2M_ERR_INVALID, M2M_OTA_REQ_HOST_FILE_ERASE, M2M_REQ_GROUP_OTA, and NULL.

sint8 m2m_ota_host_file_get ( unsigned char *  pcDownloadUrl,
tpfFileGetCb  pfHFDGetCb 
)

Download a file from a remote location and store it in the WINC's Flash.

Download a file from a remote location and store it in WINC's Flash.

Parameters
[in]pcDownloadUrlUrl pointing to the remote file. HTTP/HTTPS only.
[in]pfHFDGetCbPointer to a callback to be executed when the download finishes.
Returns
Status of the get operation.
Warning
Providing a callback is mandatory.
Parameters
[in]pcDownloadUrlUrl pointing to the remote file. HTTP/HTTPS only.
[in]pfHFDGetCbPointer to a callback (see tpfFileGetCb) to be executed when the download finishes.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Precondition
Requires m2m_ota_init to be called before a download can start.
Warning
This functionality is only supported from WINC release 19.6.1 onwards. The maximum file size that can be stored in WINC1510 is 508KB, the WINC1500 variant is not supported for Host File Download.
Concurrent use of Host File Get and WINC OTA is not possible.
Providing a callback is mandatory.
See Also
m2m_ota_init tpfFileGetCb

References gpfHFDGetCb, gu8CurrFileHandlerID, HFD_INVALID_HANDLER, hif_send(), M2M_ERR, M2M_ERR_FAIL, M2M_INFO, M2M_OTA_REQ_HOST_FILE_DOWNLOAD, M2M_REQ_GROUP_OTA, m2m_strlen(), M2M_SUCCESS, and NULL.

sint8 m2m_ota_host_file_read_hif ( uint8  u8Handler,
uint32  u32Offset,
uint32  u32Size,
tpfFileReadCb  pfHFDReadCb 
)

Read a certain amount of bytes from a file in WINC's Flash using HIF transfer.

Read a certain amount of bytes from a file previously stored in WINC's Flash using HIF transfer.

Parameters
[in]u8HandlerID of the file we are trying to read from. Must be valid.
[in]u32OffsetOffset from start of the file to read from (in bytes).
[in]u32SizeThe amount of data to read (in bytes).
[in]pfHFDReadCbCallback to be executed when the read operation completes.
Returns
Status of the read operation.
Warning
Providing a callback is mandatory.
Parameters
[in]u8HandlerHandler of the file we are trying to read from. Must be valid.
[in]u32OffsetOffset from start of the file to read from (in bytes).
[in]u32SizeThe amount of data to read (in bytes).
[in]pfHFDReadCbCallback (see tpfFileReadCb) to be executed when the read operation completes.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Precondition
Requires m2m_ota_init to be called before a read via HIF can be requested.
Warning
There is a limitation on how much data can be transferred at a time using HIF read, which is 128 bytes. The limitation described above can potentially reduce the speed of the read due to extra overhead, but using the HIF is non-blocking and therefore the Application can continue execution as normal, being interrupted only when data is available. Another advantage is that it does not require the WINC to be reset or put in download mode, as it is the case for reading the file via SPI (see m2m_ota_host_file_read_spi).
A valid file handler must be provided, this means that it needs to match the handler internally stored by the WINC and must not be HFD_INVALID_HANDLER.
Providing a callback is mandatory.
Note
When calling this API while specifying a size > 128 bytes, the read will be limited to the first 128 bytes starting at the read offset. It it recommended that a read for sizes above 128 bytes is performed in multiple steps, using the callback to advance the offset and request another read of 128 bytes (or less) each time.
See Also
m2m_ota_init m2m_ota_host_file_get tpfFileReadCb

References gpfHFDReadCb, gu8CurrFileHandlerID, HFD_INVALID_HANDLER, hif_send(), M2M_ERR_INVALID_ARG, M2M_OTA_REQ_HOST_FILE_READ, M2M_REQ_GROUP_OTA, M2M_SUCCESS, NULL, FileBlockDescriptor::u32Offset, and FileBlockDescriptor::u32Size.

sint8 m2m_ota_host_file_read_spi ( uint8  u8Handler,
uint8 pu8Buff,
uint32  u32Offset,
uint32  u32Size 
)

Read a certain amount of bytes from a file in WINC's Flash using SPI transfer.

Parameters
[in]u8HandlerID of the file we are trying to read from. Must be valid.
[in]pu8BuffPointer to a buffer to store the data being read. Must be valid.
[in]u32OffsetOffset from start of the file to read from (in bytes).
[in]u32SizeThe amount of data to read (in Bytes).
Returns
Status of the read operation.
Warning
Before using m2m_ota_host_file_read_spi, the WINC needs to be put in a special mode to allow for a safe access to the Flash. This can be done by calling m2m_wifi_download_mode or m2m_wifi_reinit_hold before trying to read.
Parameters
[in]u8HandlerHandler of the file we are trying to read from. Must be valid.
[in]pu8BuffPointer to a buffer to store the data being read. Must not be NULL.
[in]u32OffsetOffset from start of the file to read from (in bytes).
[in]u32SizeThe amount of data to read (in Bytes).
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Warning
Reading of a file via SPI can be much faster than by reading it via the HIF. However, the read will be blocking and it will require the WINC to be put into download mode prior to the read, the download mode means that the WINC will act as Flash device and not as a Wifi device. So, before using m2m_ota_host_file_read_spi, the Application should call m2m_wifi_download_mode before trying to read. After the read finishes, the WINC needs to be reset (see m2m_wifi_reinit).
A valid file handler must be provided, this means that it needs to match the handler internally stored by the WINC and must not be HFD_INVALID_HANDLER.
See Also
m2m_ota_init m2m_ota_host_file_get

File Download SPI Read Example

The following is an example of how to perform a read file from the WINC via SPI.

typedef struct {
uint8 u8Handler;
uint32 u32Offset;
uint32 u32Size;
uint8 au8Buff[200];
}FileDescriptor;
tstrWifiInitParam gstrWifiParam;
static FileDescriptor gstrAppFile;
char *acURL = "http://www.microchip.com/_images/ics/medium-ATWINC1500-MODULE-28.png";
static void ReadFileSPI(void);
static void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg);
static void FileGetCallback(uint8 u8Status, uint8 u8Handler, uint32 u32Size);
static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus);
static void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
{
// After successfully connection, start the File Download
gstrAppFile.u32Offset = 0;
s8Ret = m2m_ota_host_file_get(acURL, FileGetCallback);
if(s8Ret != M2M_SUCCESS)
{
M2M_ERR("File Download Failed!\n");
}
}
break;
default:
break;
}
static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus)
{
M2M_INFO("%d %d\n",u8OtaUpdateStatusType,u8OtaUpdateStatus);
if(u8OtaUpdateStatus == OTA_STATUS_SUCCESS)
{
if(u8OtaUpdateStatusType == HFD_STATUS)
{
// Read the file and process it
ReadFileSPI();
}
}
}
static void FileGetCallback(uint8 u8Status, uint8 u8Handler, uint32 u32Size)
{
if(OTA_STATUS_SUCCESS == u8Status)
{
gstrAppFile.u8Handler = u8Handler;
gstrAppFile.u32Size = u32Size;
// File Get Successful
}
else
{
M2M_ERR("File Get Failed!\n");
// File Get Failed
}
}
static void ReadFileSPI(void)
{
if(M2M_SUCCESS != s8Ret) goto EXIT;
// gstrAppFile.u32Offset can be changed to define a starting point for the read,
// in which case the size of the requested read should be adjusted to accommodate for this.
// This call assumes that m2m_ota_host_file_get was called earlier, in this example it is fine
// since ReadFileSPI is only called from the within OtaUpdateCb
// This example simply reads the first 200 bytes of the file.
uint32 u32AmountToRead = 200;
s8Ret = m2m_ota_host_file_read_spi(gstrAppFile.u8Handler, gstrAppFile.au8Buff, gstrAppFile.u32Offset, u32AmountToRead);
if(M2M_SUCCESS == s8Ret)
M2M_INFO("\nFile Read completed, Offset: %lu, Size of Read: %lu.\n", gstrAppFile.u32Offset, u32AmountToRead);
// *** Do something with the contents of gstrAppFile.au8Buff ***
s8Ret = m2m_wifi_reinit(&gstrWifiParam);
if(M2M_SUCCESS != s8Ret) goto EXIT;
// Initialize the OTA again and reconnect to the previously connected SSID
EXIT:
return;
}
void main(void)
{
m2m_memset((uint8*)&gstrWifiParam, 0, sizeof(gstrWifiParam));
gstrWifiParam.pfAppWifiCb = wifi_event_cb;
// Initialize the WINC Driver
sint8 s8Ret = m2m_wifi_init(&gstrWifiParam);
if (M2M_SUCCESS != s8Ret)
{
M2M_ERR("Driver Init Failed <%d>\n",s8Ret);
while(1);
}
// Initialize the OTA module
// *** Connect to a wifi network by calling m2m_wifi_connect() ***
}

References ENTRY_ID_HOSTFILE, FLASH_SECTOR_SZ, HFD_INVALID_HANDLER, M2M_ERR, M2M_ERR_FAIL, M2M_ERR_INVALID_ARG, M2M_SUCCESS, m2m_wifi_get_state(), NULL, spi_flash_read(), spi_flexible_flash_find_section(), and WIFI_STATE_INIT.