NTP time synchronization

Data Structures
struct	ntp_cfg
	NTP configuration. More...

Macros
#define	NTP_DEFAULT_SERVERS
	Default NTP server addresses. More...
#define	NTP_DEFAULT_RESPONSE_TMO_S   (15)
	Default NTP response timeout. More...
#define	NTP_DEFAULT_RETRY_INTVL_S   (15)
	Default NTP retry interval. More...
#define	NTP_DEFAULT_DNS_TMO_S   (10)
	Default timeout for DNS resolution of the NTP server hostname. More...
#define	NTP_DEFAULT_REFRESH_INTVL_S   (30000)
	Default interval for NTP refresh requests. More...

Functions
bool	rtc_synced (void)
	Return true if the RTC has been synchronized. More...
static struct ntp_cfg	ntp_default_cfg (void)
	Get the NTP default configuration. More...

Detailed Description

The server requires an accurately synchronized clock, among other things because:

• for TLS, the certficate's validity period is checked. When an https connection is initiated and the TLS handshake is performed, the client will verify that the current time lies between the "Not Before" and "Not After" times of the certificate. With an accurate clock, mbedtls can be configured to check the certificate's validity.
• for HTTP generally (with or without TLS), the Date response header must represent an accurate time. The value of Date is evaluated in the age calculation of a response, which supports a client's decisions about caching responses.

The Date header is generated automatically by the server, so application code does not need to do so.

picow-http uses the PicoW's real time clock (RTC) to keep the time, synchronized to UTC time using the Network Time Protocol (NTP). When an HTTP server is started, the following actions are initiated (running asynchronously):

• the RTC is set to run from the PicoW's crystal oscillator (XOSC)
• a DNS lookup is initiated for the first NTP server listed in the configuration (see struct ntp_cfg)
• if the lookup succeeds, a request is sent to the server
• if a response is received successfully from the NTP server, then the RTC is set to UTC time according to the response
• the time is also set so that time(NULL) from C's time.h returns the synchronized epoch time
• at relatively long intervals, a "refresh" request is sent to the next NTP server to update the clock (in order to minimize clock drift)

These operations are started as soon as the server starts, so there is a brief interval just after server startup (usually a few seconds) in which the RTC is not synchronized. During that interval:

• no Date header is generated in response headers
• the date/time field in request logs is empty
• time(NULL) does not return the current time

rtc_synced() can be used to check whether the RTC has been successfully synced with an NTP server.

If any of the operations described above fail (such DNS lookup or the NTP request), they are retried after an interval set in the configuration (see struct ntp_cfg). For refreshes and retries, the NTP servers listed in the configuration are attempted in order.

NTP synchronization is initialized when http_srv_init() is called for the first (and possibly only) HTTP server. If you call http_srv_init() for one or more additional servers (for example to implement a server without TLS listening on port 80 and a server with TLS on port 443), the NTP configuration of the second and any other initialized HTTP server is ignored.

NTP synchronization stops when the last running HTTP server is stopped with http_srv_fini(). If a server is stopped while other HTTP servers are still running, NTP synchronization continues.

Macro Definition Documentation

NTP_DEFAULT_DNS_TMO_S

#define NTP_DEFAULT_DNS_TMO_S   (10)

Default timeout in seconds for the DNS request used to resolve the NTP server hostname.

See also

ntp_default_cfg()

NTP_DEFAULT_REFRESH_INTVL_S

#define NTP_DEFAULT_REFRESH_INTVL_S   (30000)

Default interval in seconds after which NTP synchronization is refreshed. After a synchronization succeeds, and then this interval elapses, a new NTP request is sent to the next configured server.

The default interval is chosen so that the clock is not likely to drift by much more than a second, assuming the accuracy of 30ppm documented for the crystal oscillator used on the PicoW.

See also

ntp_default_cfg()

NTP_DEFAULT_RESPONSE_TMO_S

#define NTP_DEFAULT_RESPONSE_TMO_S   (15)

Default timeout in seconds for the response to an NTP client request.

See also

ntp_default_cfg()

NTP_DEFAULT_RETRY_INTVL_S

#define NTP_DEFAULT_RETRY_INTVL_S   (15)

Default interval in seconds after which failed NTP-related operations are re-attempted, such as an NTP client request or DNS lookup.

The default is a customary minimum interval for NTP clients between retry attempts, so as not to overload NTP servers.

See also

ntp_default_cfg()

NTP_DEFAULT_SERVERS

#define NTP_DEFAULT_SERVERS

Value:

    "0.slimhazard.pool.ntp.org 1.slimhazard.pool.ntp.org "  \
    "2.slimhazard.pool.ntp.org 3.slimhazard.pool.ntp.org"

The NTP server addresses set in the default configuration – a whitespace-separated list of host names or IP addresses.

The default references an open source vendor pool with worldwide scope; consider using a pool or server that is "closer" to the location where your PicoW is deployed.

See also

ntp_default_cfg()

Function Documentation

ntp_default_cfg()

static struct ntp_cfg ntp_default_cfg ( void  )

inlinestatic

Returns an instance of struct ntp_cfg whose fields are set as follows:

• servers: NTP_DEFAULT_SERVERS
• response_tmo_s: NTP_DEFAULT_RESPONSE_TMO_S
• retry_intvl_s: NTP_DEFAULT_RETRY_INTVL_S
• dns_tmo_s: NTP_DEFAULT_DNS_TMO_S
• refresh_intvl_s: NTP_DEFAULT_REFRESH_INTVL_S

Example:

#include "picow_http/http.h"
 
// Initialize cfg to defaults, so that we only have to change
// individual fields.
struct ntp_cfg cfg = ntp_default_cfg();
 
// Use the NTP pool in Germany
cfg.server = "0.de.pool.ntp.org 1.de.pool.ntp.org 2.de.pool.ntp.org";

Returns

an NTP configuration set to default values

rtc_synced()

bool rtc_synced

(

void

)

Returns

true if an NTP client request has succeeded, and the RTC has been set to UTC time