wall_clock.c File Reference

The panel's wall clock rules. See wall_clock.h. More...

#include "wall_clock.h"
#include <inttypes.h>
#include <stdio.h>
#include <time.h>

Macros
#define	_POSIX_C_SOURCE   200809L
	localtime_r() is POSIX: newlib and glibc declare it with this, and its name is the standard's, not ours.

Functions
bool	wall_valid (int64_t unix_s)
	Whether a clock reading holds a real date.
bool	wall_stamp_known (int64_t mtime)
	Whether a file's stamp says when it was written: false for a stamp FatFs made from an unset clock (any time in 1980) and for none at all.
const char *	wall_zone_posix (int index)
	Time zone index as a POSIX TZ string, for setenv("TZ") and tzset(). The order is the SETUP row's (UI_OPTIONS(time_zone) in ui_text.def): UTC, London, Berlin, Helsinki, New York, Chicago, Denver, Los Angeles, Tokyo, Sydney.
int64_t	wall_local_s (int64_t unix_s)
	A time moved by the zone in force (TZ, tzset()) at that time, so a UTC civil reading of the result shows the local date and time: what FILES INFO, the Wi-Fi page and the ZIP file write. The file stamps FatFs writes are local; mktime() turns them into true seconds since 1970, and this turns them back.
char *	wall_utc_text (char *out, size_t n, int64_t unix_s)
	A UTC time as "YYYY-MM-DD HH:MM:SS UTC".
char *	wall_ntp_line (char *out, size_t n, const char *server, int64_t new_us, int64_t old_us)
	The console line of an NTP answer: the server, the time set and how far it moved the clock, e.g. "ntp: pool.ntp.org set 2026-10-24 14:03:12 UTC, offset +1792739352.345s from the old clock".
wall_ntp_do_t	wall_ntp_step (wall_ntp_t *n, bool joined, bool answered, uint32_t now_ms)
	Move the request on. Joined: one START, then SET on an answer or GAVE_UP after WALL_NTP_TIMEOUT_MS. A join that ends while it asks: STOP. The next join asks again.
bool	wall_ntp_holds (const wall_ntp_t *n, bool lingers, uint32_t now_ms)
	Whether the radio stays up past its session's end for this request: the session lingers (wa_lingers() in wa_session.h) and the request asks, less than WALL_NTP_TIMEOUT_MS after its START. An answer at 29.9s ends the hold with it; the time-out at 30s ends it unanswered.
wall_ntp_do_t	wall_ntp_hold_step (wall_ntp_t *n, bool joined, bool lingers, bool answered, uint32_t now_ms)
	wall_ntp_step() across a session's end that lingers: a request that asks counts the lingering station as joined, so it ends with its answer (SET) or after WALL_NTP_TIMEOUT_MS (GAVE_UP), not with the session (STOP). A lingering station starts no request.
uint64_t	wall_slow_mhz (uint32_t cal)
	A slow clock's frequency from ESP-IDF's calibration value: the period in microseconds with 19 fractional bits (esp_clk_slowclk_cal_get(), RTC_CLK_CAL_FRACT), measured against the 40MHz main crystal at start-up.
bool	wall_slow_fell_back (wall_slow_src_t src, bool crystal)
	Whether the slow clock fell back from the crystal: the build asks for it and another source runs.
char *	wall_slow_clock_line (char *out, size_t n, wall_slow_src_t src, bool crystal, uint32_t cal)
	The console line of the slow clock at start, after the tag "clock": the source, its calibrated frequency, and whether the 32.768kHz crystal the build asks for failed to start, e.g. "rtc slow clock 32k crystal, 32768.012Hz calibrated" or "rtc slow clock internal RC, 136000.000Hz calibrated: the 32k crystal did not start".

Variables
static const char *const	k_zones [WALL_ZONE_COUNT]
	POSIX TZ strings, the order of UI_OPTIONS(time_zone). Daylight saving: the EU (European Union) from the last Sunday of March 01:00 UTC to the last Sunday of October 01:00 UTC; the US (United States) from the second Sunday of March 02:00 local to the first Sunday of November 02:00 local; Sydney from the first Sunday of October 02:00 to the first Sunday of April 03:00 local. Tokyo has none.

Detailed Description

The panel's wall clock rules. See wall_clock.h.

SPDX-License-Identifier: MIT

Function Documentation

wall_local_s()

int64_t wall_local_s

(

int64_t

unix_s

)

A time moved by the zone in force (TZ, tzset()) at that time, so a UTC civil reading of the result shows the local date and time: what FILES INFO, the Wi-Fi page and the ZIP file write. The file stamps FatFs writes are local; mktime() turns them into true seconds since 1970, and this turns them back.

Parameters

unix_s

Seconds since 1970-01-01 00:00:00 UTC; a negative time (no stamp) is returned as it is.

Returns

The local civil time as seconds since 1970 read as UTC; unix_s itself when the C library cannot convert it.

wall_ntp_hold_step()

wall_ntp_do_t wall_ntp_hold_step	(	wall_ntp_t *	n,
		bool	joined,
		bool	lingers,
		bool	answered,
		uint32_t	now_ms )

wall_ntp_step() across a session's end that lingers: a request that asks counts the lingering station as joined, so it ends with its answer (SET) or after WALL_NTP_TIMEOUT_MS (GAVE_UP), not with the session (STOP). A lingering station starts no request.

Parameters

n	The request; zeroed is IDLE.
joined	The session holds an address on the home network.
lingers	The session ended and lets the radio stay up.
answered	An answer has set the clock since START.
now_ms	A millisecond clock; its wrap is taken.

Returns

What the caller does now.

wall_ntp_holds()

bool wall_ntp_holds	(	const wall_ntp_t *	n,
		bool	lingers,
		uint32_t	now_ms )

Whether the radio stays up past its session's end for this request: the session lingers (wa_lingers() in wa_session.h) and the request asks, less than WALL_NTP_TIMEOUT_MS after its START. An answer at 29.9s ends the hold with it; the time-out at 30s ends it unanswered.

Parameters

n	The request.
lingers	The session ended and lets the radio stay up.
now_ms	The millisecond clock of wall_ntp_step(); its wrap is taken.

Returns

True while the radio waits for this request.

wall_ntp_line()

char * wall_ntp_line	(	char *	out,
		size_t	n,
		const char *	server,
		int64_t	new_us,
		int64_t	old_us )

The console line of an NTP answer: the server, the time set and how far it moved the clock, e.g. "ntp: pool.ntp.org set 2026-10-24 14:03:12 UTC, offset +1792739352.345s from the old clock".

Parameters

out	The buffer.
n	Its size in bytes; 128 holds a 32-character server name and a 12-digit offset.
server	The server asked.
new_us	The time the answer set, microseconds since 1970 UTC.
old_us	What the clock read at that moment before the answer.

Returns

out, or NULL when out is NULL or n is 0.

wall_ntp_step()

wall_ntp_do_t wall_ntp_step	(	wall_ntp_t *	n,
		bool	joined,
		bool	answered,
		uint32_t	now_ms )

Move the request on. Joined: one START, then SET on an answer or GAVE_UP after WALL_NTP_TIMEOUT_MS. A join that ends while it asks: STOP. The next join asks again.

Parameters

n	The request; zeroed is IDLE.
joined	The station holds an address on the home network.
answered	An answer has set the clock since START.
now_ms	A millisecond clock; its wrap is taken.

Returns

What the caller does now.

wall_slow_clock_line()

char * wall_slow_clock_line	(	char *	out,
		size_t	n,
		wall_slow_src_t	src,
		bool	crystal,
		uint32_t	cal )

The console line of the slow clock at start, after the tag "clock": the source, its calibrated frequency, and whether the 32.768kHz crystal the build asks for failed to start, e.g. "rtc slow clock 32k crystal, 32768.012Hz calibrated" or "rtc slow clock internal RC, 136000.000Hz calibrated: the 32k crystal did not start".

Parameters

out	The buffer.
n	Its size in bytes; 96 holds the longest line.
src	The source that runs.
crystal	The build asks for the crystal (CONFIG_RTC_CLK_SRC_EXT_CRYS).
cal	The calibration value, as wall_slow_mhz() takes it; 0 writes "frequency not known".

Returns

out, or NULL when out is NULL or n is 0.

wall_slow_fell_back()

bool wall_slow_fell_back	(	wall_slow_src_t	src,
		bool	crystal )

Whether the slow clock fell back from the crystal: the build asks for it and another source runs.

Parameters

src	The source that runs.
crystal	The build asks for the crystal.

Returns

True on a fallback, which the panel logs as a warning.

wall_slow_mhz()

uint64_t wall_slow_mhz

(

uint32_t

cal

)

A slow clock's frequency from ESP-IDF's calibration value: the period in microseconds with 19 fractional bits (esp_clk_slowclk_cal_get(), RTC_CLK_CAL_FRACT), measured against the 40MHz main crystal at start-up.

Parameters

cal	The calibration value; 0 is none.

Returns

The frequency in millihertz, rounded to the nearest; 0 for a cal of 0. A cal of 1 gives 524288000000000mHz, the largest.

wall_stamp_known()

bool wall_stamp_known

(

int64_t

mtime

)

Whether a file's stamp says when it was written: false for a stamp FatFs made from an unset clock (any time in 1980) and for none at all.

Parameters

mtime

The stamp as mktime() reads FAT's local date and time, or -1 for no stamp.

Returns

True from WALL_STAMP_FLOOR_S on.

wall_utc_text()

char * wall_utc_text	(	char *	out,
		size_t	n,
		int64_t	unix_s )

A UTC time as "YYYY-MM-DD HH:MM:SS UTC".

Parameters

out	The buffer.
n	Its size in bytes; 24 holds every year up to 9999.
unix_s	Seconds since 1970-01-01 00:00:00 UTC, 0 or more; a negative time is written as 1970-01-01 00:00:00.

Returns

out, or NULL when out is NULL or n is 0.

wall_valid()

bool wall_valid

(

int64_t

unix_s

)

Whether a clock reading holds a real date.

Parameters

unix_s

Seconds since 1970-01-01 00:00:00 UTC.

Returns

True from WALL_VALID_FLOOR_S on.

wall_zone_posix()

const char * wall_zone_posix

(

int

index

)

Time zone index as a POSIX TZ string, for setenv("TZ") and tzset(). The order is the SETUP row's (UI_OPTIONS(time_zone) in ui_text.def): UTC, London, Berlin, Helsinki, New York, Chicago, Denver, Los Angeles, Tokyo, Sydney.

Parameters

index

0 to WALL_ZONE_COUNT - 1.

Returns

The TZ string; Berlin's for an index out of range.

Variable Documentation

k_zones

const char* const k_zones[WALL_ZONE_COUNT]

static

Initial value:

                                = {
    "UTC0",                           
    "GMT0BST,M3.5.0/1,M10.5.0",       
    "CET-1CEST,M3.5.0,M10.5.0/3",     
    "EET-2EEST,M3.5.0/3,M10.5.0/4",   
    "EST5EDT,M3.2.0,M11.1.0",         
    "CST6CDT,M3.2.0,M11.1.0",         
    "MST7MDT,M3.2.0,M11.1.0",         
    "PST8PDT,M3.2.0,M11.1.0",         
    "JST-9",                          
    "AEST-10AEDT,M10.1.0,M4.1.0/3",   
}

POSIX TZ strings, the order of UI_OPTIONS(time_zone). Daylight saving: the EU (European Union) from the last Sunday of March 01:00 UTC to the last Sunday of October 01:00 UTC; the US (United States) from the second Sunday of March 02:00 local to the first Sunday of November 02:00 local; Sydney from the first Sunday of October 02:00 to the first Sunday of April 03:00 local. Tokyo has none.