ntp_service.h File Reference

Optional SNTP wall-clock time sync (DETWS_ENABLE_NTP). More...

#include "ServerConfig.h"
#include <stddef.h>
#include <stdint.h>
#include <time.h>

Go to the source code of this file.

Functions
bool	detws_ntp_begin (const char *tz=nullptr, const char *server1="pool.ntp.org", const char *server2="time.nist.gov")
	Start the SNTP client.
bool	detws_ntp_synced ()
	True once a plausible wall-clock time has been obtained from SNTP.
time_t	detws_ntp_epoch ()
	Current Unix epoch seconds, or 0 if not yet synced (or disabled).
size_t	detws_ntp_http_date (char *out, size_t out_cap)
	Format the current time as an RFC 7231 IMF-fixdate (HTTP Date).
uint32_t	ntp_time_source (void)
	NTP as a time source for the multi-source registry (services/time_source).

Detailed Description

Optional SNTP wall-clock time sync (DETWS_ENABLE_NTP).

Thin wrapper over the ESP-IDF SNTP client (configTzTime). Gives a clock-less device wall-clock time for log timestamps, the HTTP Date header, and future TLS certificate-validity checks. No-op stub when DETWS_ENABLE_NTP is 0 or on non-Arduino builds.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file ntp_service.h.

Function Documentation

detws_ntp_begin()

bool detws_ntp_begin	(	const char *	tz = nullptr,
		const char *	server1 = "pool.ntp.org",
		const char *	server2 = "time.nist.gov"
	)

Start the SNTP client.

Returns immediately; the first sync arrives asynchronously (poll detws_ntp_synced()). Call once after the WiFi link is up.

Parameters

tz	POSIX TZ string (e.g. "UTC0", "EST5EDT,M3.2.0,M11.1.0"). Pass nullptr for UTC.
server1	Primary NTP server (default "pool.ntp.org").
server2	Secondary NTP server (default "time.nist.gov").

Returns

true if the client was started; false if disabled at compile time.

Definition at line 63 of file ntp_service.cpp.

detws_ntp_synced()

bool detws_ntp_synced

(

)

True once a plausible wall-clock time has been obtained from SNTP.

Checks that the system clock has advanced past 2021-01-01, which only happens after a successful sync (the RTC starts at the epoch on a cold boot).

Definition at line 70 of file ntp_service.cpp.

detws_ntp_epoch()

time_t detws_ntp_epoch

(

)

Current Unix epoch seconds, or 0 if not yet synced (or disabled).

Definition at line 74 of file ntp_service.cpp.

Referenced by detws_ntp_http_date(), and ntp_time_source().

detws_ntp_http_date()

size_t detws_ntp_http_date	(	char *	out,
		size_t	out_cap
	)

Format the current time as an RFC 7231 IMF-fixdate (HTTP Date).

Writes e.g. "Sun, 06 Nov 1994 08:49:37 GMT" into out. Always GMT.

Parameters

out	Destination buffer (>= 30 bytes recommended).
out_cap	Capacity of out.

Returns

Number of characters written (excluding the null), or 0 if time is not yet available / disabled.

Definition at line 78 of file ntp_service.cpp.

References detws_http_date(), and detws_ntp_epoch().

ntp_time_source()

uint32_t ntp_time_source

(

void

)

NTP as a time source for the multi-source registry (services/time_source).

Register with detws_time_source_add("ntp", priority, ntp_time_source) so the aggregated detws_time_now() (and thus the HTTP Date header when DETWS_ENABLE_TIME_SOURCE is set) can be fed by NTP alongside an RTC / GPS. Returns the current epoch, or 0 when not synced.

Definition at line 88 of file ntp_service.cpp.

References detws_ntp_epoch().