         Here are listed all the functions that implement the System Time APIs.

Functions
sint8	m2m_wifi_configure_sntp (uint8 *pu8NTPServerName, uint8 u8NTPServerNameLength, tenuSNTPUseDHCP useDHCP)
	Configures what NTP server the SNTP client should use. More...

sint8	m2m_wifi_enable_sntp (uint8 bEnable)
	Synchronous function to enable/disable the native Simple Network Time Protocol(SNTP) client in the WINC15x0 firmware. More...

sint8	m2m_wifi_get_system_time (void)
	Asynchronous API to obtain the system time in use by the WINC IC. More...

sint8	m2m_wifi_set_system_time (uint32 u32UTCSeconds)
	Function for setting the system time within the WINC IC. More...

NMI_API sint8 m2m_wifi_configure_sntp	(	uint8 *	pu8NTPServerName,
		uint8	u8NTPServerNameLength,
		tenuSNTPUseDHCP	useDHCP
	)

Configures what NTP server the SNTP client should use.

Parameters

[in]	pu8NTPServerName	Buffer holding the NTP server name. If the first character is an asterisk () then it will be treated as a server pool, where the asterisk will be replaced with an incrementing value from 0 to 3 each time a server fails (example: .pool.ntp.org).
[in]	u8NTPServerNameLength	Length of the NTP server name. Should not exceed the maximum NTP server name length of M2M_NTP_MAX_SERVER_NAME_LENGTH
[in]	useDHCP	Should the NTP server provided by the DHCP server be used.

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

Configures what NTP server the SNTP client should use. Only 1 server name can be provided, if the configured server name begins with an asterisk then it will be treated as a server pool.
The SNTP client can also use the NTP server provided by the DHCP server through option 42.
By default the NTP server provided by DHCP will be tried first, then the built-in default NTP server (time.nist.gov) will be used.

Parameters

[in]	pu8NTPServerName	Buffer holding the NTP server name. If the first character is an asterisk () then it will be treated as a server pool, where the asterisk will be replaced with an incrementing value from 0 to 3 each time a server fails (example: .pool.ntp.org).
[in]	u8NTPServerNameLength	Length of the NTP server name. Should not exceed the maximum NTP server name length of M2M_NTP_MAX_SERVER_NAME_LENGTH.
[in]	useDHCP	Explicity tell the WINC if it should use the NTP server provided by the DHCP server or not.

Warning: SNTP should be configured before the connection takes place. If SNTP is configured after the device connects to a network, the new configuration can take a minimum of 24h to be applied. However, it can take even longer since it is triggered by DHCP renewal. Currently there is also a known issue in which if the WINC obtains the NTP server from DHCP and then connects to a different network, it will still use the NTP from the previous network. Configuring a server name will overwrite the built-in default server until next reboot.

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

Configures what NTP server the SNTP client should use. Only 1 server name can be provided, if the configured server name begins with an asterisk then it will be treated as a server pool.
The SNTP client can also use the NTP server provided by the DHCP server through option 42.
By default the NTP server provided by DHCP will be tried first, then the built-in default NTP server (time.nist.gov) will be used.

Parameters

[in]	pu8NTPServerName	Buffer holding the NTP server name. If the first character is an asterisk () then it will be treated as a server pool, where the asterisk will be replaced with an incrementing value from 0 to 3 each time a server fails (example: .pool.ntp.org).
[in]	u8NTPServerNameLength	Length of the NTP server name. Should not exceed the maximum NTP server name length of M2M_NTP_MAX_SERVER_NAME_LENGTH.
[in]	useDHCP	Explicity tell the WINC if it should use the NTP server provided by the DHCP server or not.

Warning: SNTP should be configured before the connection takes place. If SNTP is configured after the device connects to a network, the new configuration can take a minimum of 24h to be applied. However, it can take even longer since it is triggered by DHCP renewal. Currently there is also a known issue in which if the WINC obtains the NTP server from DHCP and then connects to a different network, it will still use the NTP from the previous network. Configuring a server name will overwrite the built-in default server until next reboot.

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

Referenced by main().

NMI_API sint8 m2m_wifi_enable_sntp ( uint8 bEnable )

Synchronous function to enable/disable the native Simple Network Time Protocol(SNTP) client in the WINC15x0 firmware.

Asynchronous API to enable or disable the native Simple Network Time Protocol(SNTP) client running on the WINC.

The SNTP is enabled by default at start-up.The SNTP client at firmware is used to 
synchronize the system clock to the UTC time from the well known time servers (e.g. "time-c.nist.gov").
The SNTP client uses a default update cycle of 1 day.

The UTC is important for checking the expiration date of X509 certificates used while establishing
TLS (Transport Layer Security) connections.

It is highly recommended to use it if there is no other means to get the UTC time. If there is a RTC
on the host MCU, the SNTP could be disabled and the host should set the system time to the firmware 
using the @ref m2m_wifi_set_system_time function.

Parameters

[in] bEnable Enables or disables the SNTP service '0' :disable SNTP '1' :enable SNTP

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_set_system_time

The SNTP client is enabled by default during chip initialization. This function can be used to
disable or subsequently re-enable the service.

The service is capable of synchronizing the WINC system clock to the UTC time from a well-known
(and trusted) time server, for example "time.nist.gov". By default the SNTP client will update the
system time once every 24 hours. The ability to track the time accurately is important for various
applications such as checking expiry of X509 certificates during TLS (Transport Layer Security)
session establishment.

It is highly recommended to leave SNTP enabled if there is no alternative source of timing
information. For systems including an RTC device, SNTP may not be needed and the WINC's time
may be set using the @ref m2m_wifi_set_system_time function.

Parameters

[in] bEnable Enables or disables the SNTP service '0' :disable SNTP '1' :enable SNTP

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_set_system_time

NMI_API sint8 m2m_wifi_get_system_time ( void )

Asynchronous API to obtain the system time in use by the WINC IC.

Asynchronous API to obtain the system time in use by the WINC.

See Also: m2m_wifi_enable_sntp tstrSystemTime

Note: get the system time from the sntp client using the API m2m_wifi_get_system_time.

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

Asynchronous function used to retrieve the system time through the use of the 
response @ref M2M_WIFI_RESP_GET_SYS_TIME.
Response time retrieved is parsed into the members defined in the 
structure @ref tstrSystemTime.

Note: Get the system time from the SNTP client using the API m2m_wifi_get_system_time.

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_enable_sntp tstrSystemTime

This function will request the WINC to report its current system time to the application. The
information will arrive at the application via the @ref tpfAppWifiCb and event @ref M2M_WIFI_RESP_GET_SYS_TIME.
Response time retrieved is parsed into the members defined in the structure @ref tstrSystemTime.

Note

A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered during initialization. Registration of the callback is done via the m2m_wifi_init API.
The event M2M_WIFI_RESP_GET_SYS_TIME must be handled in the callback.

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_enable_sntp tstrSystemTime

NMI_API sint8 m2m_wifi_set_system_time ( uint32 u32UTCSeconds )

Function for setting the system time within the WINC IC.

Asynchronous function for setting the system time within the WINC.

Synchronous function for setting the system time in time/date format (@ref uint32).
The @ref tstrSystemTime structure can be used as a reference to the time values that 
should be set and pass its value as @ref uint32.

Parameters

[in] u32UTCSeconds Seconds elapsed since January 1, 1900 (NTP Timestamp).

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_enable_sntp tstrSystemTime

Note: If there is an RTC on the host MCU, the SNTP may be disabled and the host may set the system time within the firmware using the API m2m_wifi_set_system_time.

Function for setting the system time in time/date format (@ref uint32).
The @ref tstrSystemTime structure can be used as a reference to the time values that
should be set and pass its value as @ref uint32.

Parameters

[in] u32UTCSeconds Seconds elapsed since January 1, 1900 (NTP Timestamp).

Returns: The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also: m2m_wifi_enable_sntp tstrSystemTime

Note: If there is an RTC on the host MCU, the SNTP may be disabled and the host may set the system time within the firmware using the API m2m_wifi_set_system_time.

Referenced by os_m2m_wifi_set_sytem_time_imp().

Microchip® Advanced Software Framework

Functions