HFD

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]	u8Handler	ID of the file we are trying to erase. Must be valid.
[in]	pfHFDEraseCb	Pointer 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]	u8Handler	Handler of the file we are trying to erase. Must be valid.
[in]	pfHFDEraseCb	Pointer 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]	pcDownloadUrl	Url pointing to the remote file. HTTP/HTTPS only.
[in]	pfHFDGetCb	Pointer to a callback to be executed when the download finishes.

Returns

Status of the get operation.

Warning

Providing a callback is mandatory.

Parameters

[in]	pcDownloadUrl	Url pointing to the remote file. HTTP/HTTPS only.
[in]	pfHFDGetCb	Pointer 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]	u8Handler	ID of the file we are trying to read from. Must be valid.
[in]	u32Offset	Offset from start of the file to read from (in bytes).
[in]	u32Size	The amount of data to read (in bytes).
[in]	pfHFDReadCb	Callback to be executed when the read operation completes.

Returns

Status of the read operation.

Warning

Providing a callback is mandatory.

Parameters

[in]	u8Handler	Handler of the file we are trying to read from. Must be valid.
[in]	u32Offset	Offset from start of the file to read from (in bytes).
[in]	u32Size	The amount of data to read (in bytes).
[in]	pfHFDReadCb	Callback (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]	u8Handler	ID of the file we are trying to read from. Must be valid.
[in]	pu8Buff	Pointer to a buffer to store the data being read. Must be valid.
[in]	u32Offset	Offset from start of the file to read from (in bytes).
[in]	u32Size	The 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]	u8Handler	Handler of the file we are trying to read from. Must be valid.
[in]	pu8Buff	Pointer to a buffer to store the data being read. Must not be NULL.
[in]	u32Offset	Offset from start of the file to read from (in bytes).
[in]	u32Size	The 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)
{
    case M2M_WIFI_REQ_DHCP_CONF:
    {
        // 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)
{
    sint8 s8Ret = M2M_ERR_FAIL;

    if(WIFI_STATE_DEINIT != m2m_wifi_get_state())
        m2m_wifi_deinit(NULL);

    s8Ret = m2m_wifi_download_mode();
    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
    m2m_ota_init(OtaUpdateCb, NULL);
    m2m_wifi_default_connect();

EXIT:
    return;
}

void main(void)
{
    nm_bsp_init();

    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
    m2m_ota_init(OtaUpdateCb, NULL);

    // *** Connect to a wifi network by calling m2m_wifi_connect() ***

    while(1) m2m_wifi_handle_events(NULL);
}

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.