The panel's wall clock: whether it holds a real date, whether a file's stamp says anything, the time zones SETUP offers, the one NTP (Network Time Protocol) request a join makes, and the slow clock's console line. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Data Structures
struct	wall_ntp_t
	One join's request: at most one per join. More...

Macros
#define	WALL_VALID_FLOOR_S 1767225600LL
	The first second the clock is taken to hold a real date: 2026-01-01 00:00:00 UTC, in seconds since 1970-01-01 UTC. An unset clock counts uptime from 1970 and stays below it for 56 years of uptime.
#define	WALL_STAMP_FLOOR_S 347198400LL
	The first file stamp taken as known: 1981-01-01 12:00:00 UTC. FAT (File Allocation Table) dates start in 1980, and FatFs stamps any time before 1980 as 1980. Read back through mktime() in a zone from UTC-12 to UTC+14, every 1980 stamp is below this and every stamp from 1981-01-03 on is above it.
#define	WALL_NTP_TIMEOUT_MS 30000u
	How long a join waits for an NTP answer: 30000ms.
#define	WALL_NTP_SERVER "pool.ntp.org"
	The NTP server a join asks.
#define	WALL_ZONE_DEFAULT 2
	The time zone a panel starts with: Berlin (CET/CEST).
#define	WALL_ZONE_COUNT 10
	The number of time zones SETUP offers.

Enumerations
enum	wall_ntp_state_t { WALL_NTP_IDLE = 0 , WALL_NTP_ASKING , WALL_NTP_DONE }
	Where a join's NTP request stands. More...
enum	wall_ntp_do_t { WALL_NTP_NONE = 0 , WALL_NTP_START , WALL_NTP_STOP , WALL_NTP_SET , WALL_NTP_GAVE_UP }
	What wall_ntp_step() asks of the caller. More...
enum	wall_slow_src_t { WALL_SLOW_RC = 0 , WALL_SLOW_CRYSTAL , WALL_SLOW_OTHER }
	The RTC (real-time clock) slow clock the ESP32-P4's RTC timer counts, as ESP-IDF's rtc_clk_slow_src_get() reports it. More...

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.
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".
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.

Detailed Description

The panel's wall clock: whether it holds a real date, whether a file's stamp says anything, the time zones SETUP offers, the one NTP (Network Time Protocol) request a join makes, and the slow clock's console line.

The panel board (Waveshare ESP32-P4-WIFI6-Touch-LCD-7B) carries no RTC (real-time clock) chip. The ESP32-P4's own RTC timer keeps the system time across a software restart, counting the 32.768kHz crystal Y3 or, when that does not start, the internal RC oscillator; a power-on starts it at 1970-01-01 00:00:00 UTC (coordinated universal time). An NTP answer on the home network sets it. Until then the clock is uptime since 1970, and FatFs clamps such a stamp to 1980 (ESP-IDF's get_fattime()).

Nothing here reads a clock, a network or a card: every time is the caller's, so the host suite holds every rule. wall_local_s() reads the C library's time zone, which the panel sets from SETUP. The panel's end is firmware/panel/components/wifi_access/wifi_ntp.c and firmware/panel/main/panel_settings.c.

C and the C library's localtime_r(), no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Enumeration Type Documentation

◆ wall_ntp_do_t

enum wall_ntp_do_t

What wall_ntp_step() asks of the caller.

Enumerator
WALL_NTP_NONE	nothing
WALL_NTP_START	start the request
WALL_NTP_STOP	the join ended unanswered: stop it
WALL_NTP_SET	answered: log the line, stop the request
WALL_NTP_GAVE_UP	WALL_NTP_TIMEOUT_MS unanswered: log, stop

◆ wall_ntp_state_t

enum wall_ntp_state_t

Where a join's NTP request stands.

Enumerator
WALL_NTP_IDLE	not joined, or joined and not yet asked
WALL_NTP_ASKING	the request runs
WALL_NTP_DONE	answered or given up; nothing until a new join

◆ wall_slow_src_t

enum wall_slow_src_t

The RTC (real-time clock) slow clock the ESP32-P4's RTC timer counts, as ESP-IDF's rtc_clk_slow_src_get() reports it.

Enumerator
WALL_SLOW_RC	the internal RC oscillator, 136kHz nominal
WALL_SLOW_CRYSTAL	the 32.768kHz crystal (Y3 on the panel)
WALL_SLOW_OTHER	any other source

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.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ wall_ntp_do_t

◆ wall_ntp_state_t

◆ wall_slow_src_t

Function Documentation

◆ wall_local_s()

◆ wall_ntp_hold_step()

◆ wall_ntp_holds()

◆ wall_ntp_line()

◆ wall_ntp_step()

◆ wall_slow_clock_line()

◆ wall_slow_fell_back()

◆ wall_slow_mhz()

◆ wall_stamp_known()

◆ wall_utc_text()

◆ wall_valid()

◆ wall_zone_posix()