1.2.1.20 SNTP Module
The SNTP module implements the Simple Network Time Protocol. The module updates its internal time periodically using a pool of public global time servers. It then calculates reference times on any call to TCPIP_SNTP_TimeGet using the system timer module.
The SNTP module is good for providing absolute time stamps. However, it should not be relied upon for measuring time differences (especially small differences). The pool of public time servers is implemented using round-robin DNS, so each update will come from a different server. Differing network delays and the fact that these servers are not verified implies that this time could be non-linear. While it is deemed reliable, it is not guaranteed to be accurate.
The system timer module provides much better accuracy (since it is driven by a hardware clock) and resolution, and should be used for measuring timeouts and other internal requirements.
The preferred time server can be changed. The default is to use the global pool.
Abstraction Model
Library Interface
| Name | Description |
|---|---|
| Macros | |
| TCPIP_NTP_DEFAULT_CONNECTION_TYPE | The default connection type to use: IPv4/IPv6 |
| TCPIP_NTP_DEFAULT_IF | for multi-homed hosts, the default SNTP interface |
| TCPIP_NTP_EPOCH | Reference Epoch to use. (default: 01-Jan-1970 00:00:00) |
| TCPIP_NTP_FAST_QUERY_INTERVAL | Defines how long to wait to retry an update after a failure, seconds. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry. |
| TCPIP_NTP_MAX_STRATUM | The maximum acceptable NTP stratum number Should be less than 16 (unsynchronized server) |
| TCPIP_NTP_QUERY_INTERVAL | Defines how frequently to resynchronize the date/time, seconds (default: 10 minutes) |
| TCPIP_NTP_REPLY_TIMEOUT | Defines how long to wait before assuming the query has failed, seconds |
| TCPIP_NTP_RX_QUEUE_LIMIT | The NTP RX queue limit defines the maximum number of packets that can wait in the NTP queue |
| TCPIP_NTP_SERVER | These are normally available network time servers. The actual IP returned from the pool will vary every minute so as to spread the load around stratum 1 timeservers. For best accuracy and network overhead you should locate the pool server closest to your geography, but it will still work if you use the global pool.ntp.org address or choose the wrong one or ship your embedded device to another geography. A direct IP address works too |
| TCPIP_NTP_SERVER_MAX_LENGTH | maximum number of characters allowed for the NTP server |
| TCPIP_NTP_TASK_TICK_RATE | THE NTP task rate, in milliseconds The default value is 1100 milliseconds. This module contacts an NTP server and a high operation frequency is not required. The value cannot be lower than the TCPIP_STACK_TICK_RATE. |
| TCPIP_NTP_TIME_STAMP_TMO | elapsed time that qualifies a time stamp as stale normally it should be correlated with TCPIP_NTP_QUERY_INTERVAL |
| TCPIP_NTP_VERSION | The default NTP version to use (3 or 4) |
| Functions | |
| TCPIP_SNTP_UTCSecondsGet | Obtains the current time from the SNTP module. |
| TCPIP_SNTP_ConnectionInitiate | Forces a connection to the NTP server |
| TCPIP_SNTP_LastErrorGet | Gets the last error code set in the NTP server. |
| TCPIP_SNTP_ConnectionParamSet | Sets the current SNTP connection parameters. |
| TCPIP_SNTP_Task | Standard TCP/IP stack module task function. |
| TCPIP_SNTP_HandlerDeRegister | Deregisters a previously registered SNTP handler. |
| TCPIP_SNTP_HandlerRegister | Registers a SNTP Handler. |
| TCPIP_SNTP_TimeGet | Obtains the current time in UTC format from the SNTP module. |
| TCPIP_SNTP_TimeStampGet | Gets the last valid timestamp obtained from an NTP server. |
| TCPIP_SNTP_TimeStampStatus | Gets the current status of the timestamp; |
| Data Types and Constants | |
| TCPIP_SNTP_MODULE_CONFIG | Placeholder for SNTP Module Configuration |
| TCPIP_SNTP_RESULT | Provides a list of possible results for the SNTP module. |
| TCPIP_SNTP_EVENT | List of events for the SNTP module. |
| TCPIP_SNTP_EVENT_HANDLER | SNTP event handler prototype. |
| TCPIP_SNTP_EVENT_TIME_DATA | Data structure used by the SNTP module to report a timestamp event. |
| TCPIP_SNTP_HANDLE | SNTP handle. |
| TCPIP_SNTP_TIME_STAMP | Timestamp data structure used by the SNTP module. |