File espos_time.h¶

FileList > espos_time > include > espos_time.h

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

Classes¶

Type	Name
struct	espos_time_parts_t Broken-down local time, for a display.

Public Types¶

Type	Name
typedef void(*	espos_time_cb_t Called whenever a source sets or refreshes the clock.
enum	espos_time_src_t Where the current time came from.

Public Functions¶

Type	Name
bool	espos_time_is_synced (void) True when the device believes it knows the time: a source set the clock this boot, or an RTC value survived a deep sleep and is not yet stale (CONFIG_ESPOS_TIME_RTC_STALE_H).
size_t	espos_time_iso8601 (char * buf, size_t n) Write the current time as "2026-09-07T10:12:13.456Z" into buf (needs ESPOS_TIME_ISO_MAX bytes) and return its length.
size_t	espos_time_iso8601_of (int64_t unix_ms, char * buf, size_t n) Format an explicit unix-millisecond instant the same way.
int64_t	espos_time_now_ms (void) Unix milliseconds UTC, or 0 when unsynced — never a plausible-looking 1970, so a caller that forgets to check produces a missing value rather than a wrong one.
int64_t	espos_time_now_ms_or_zero (void * arg) espos_time_now_ms() with the signature a consumer's clock hook wants (`int64_t ()(void )` , the shapeespos_sk_delta_set_clock() takes).
esp_err_t	espos_time_parts (espos_time_parts_t * out) Fill `out` with the current time in the configured timezone.
esp_err_t	espos_time_set (int64_t unix_ms, espos_time_src_t src) Tell the clock what time it is.
esp_err_t	espos_time_set_tz (const char * posix_tz) Set the POSIX timezone string used by espos_time_parts() — "UTC0", "CET-1CEST,M3.5.0,M10.5.0/3" — and persist it in time.tz.
espos_time_src_t	espos_time_source (void) Which source the current time came from; NONE while unsynced.
const char *	espos_time_src_str (espos_time_src_t src) Name of a source as the REST document spells it: "none", "rtc", "sk", "manual", "sntp".
esp_err_t	espos_time_start (void) Start the clock: read the configuration, adopt an RTC value this boot may have inherited, register the /time endpoints and — when time.sntp is on — arm SNTP so it starts on the first ESPOS_EVENT_NETWORK_UP.
esp_err_t	espos_time_status_json (char ** out_json) The clock as the JSON document of docs/rest-api.md (malloc'ed; caller frees).
esp_err_t	espos_time_subscribe (espos_time_cb_t cb, void * arg)
const char *	espos_time_tz (void) The configured POSIX timezone string; "UTC0" when none was set.
esp_err_t	espos_time_unsubscribe (espos_time_cb_t cb, void * arg)

Macros¶

Type	Name
define	ESPOS_TIME_ISO_MAX `25`
define	ESPOS_TIME_TZ_MAX `40`

Public Types Documentation¶

typedef espos_time_cb_t¶

Called whenever a source sets or refreshes the clock.

typedef void(* espos_time_cb_t) (espos_time_src_t src, void *arg);

Runs on that source's task — IDF's SNTP task for SRC_SNTP, the SignalK stream task for SRC_SK, the HTTP server's task for a manual PUT — with no espos_time lock held. Copy what you need and return; never block, and never call back into a component that might be waiting for your task. arg is handed back untouched. Small fixed table: ESP_ERR_NO_MEM when full; the same (cb, arg) pair registered twice is called once. Callable before espos_time_start().

enum espos_time_src_t¶

Where the current time came from.

enum espos_time_src_t {
    ESPOS_TIME_SRC_NONE = 0,
    ESPOS_TIME_SRC_RTC = 1,
    ESPOS_TIME_SRC_SK = 2,
    ESPOS_TIME_SRC_MANUAL = 3,
    ESPOS_TIME_SRC_SNTP = 4,
    ESPOS_TIME_SRC_MAX = 5
};

Also the ranking: a source never overrides one above it, so a coarse SignalK timestamp cannot walk back over a clock SNTP already disciplined, while any source at all beats none. Values are part of the ABI: append before _MAX, never renumber.

Public Functions Documentation¶

function espos_time_is_synced¶

True when the device believes it knows the time: a source set the clock this boot, or an RTC value survived a deep sleep and is not yet stale (CONFIG_ESPOS_TIME_RTC_STALE_H).

bool espos_time_is_synced (
    void
)

False before espos_time_start().

function espos_time_iso8601¶

Write the current time as "2026-09-07T10:12:13.456Z" into buf (needs ESPOS_TIME_ISO_MAX bytes) and return its length.

size_t espos_time_iso8601 (
    char * buf,
    size_t n
)

Writes "" and returns 0 while unsynced — the same "obviously missing" rule as now_ms().

function espos_time_iso8601_of¶

Format an explicit unix-millisecond instant the same way.

size_t espos_time_iso8601_of (
    int64_t unix_ms,
    char * buf,
    size_t n
)

unix_ms of 0 or below yields "" and 0, so a caller can pass a stored stamp straight through without testing it first.

function espos_time_now_ms¶

Unix milliseconds UTC, or 0 when unsynced — never a plausible-looking 1970, so a caller that forgets to check produces a missing value rather than a wrong one.

int64_t espos_time_now_ms (
    void
)

function espos_time_now_ms_or_zero¶

espos_time_now_ms() with the signature a consumer's clock hook wants (int64_t (*)(void *) , the shapeespos_sk_delta_set_clock() takes).

int64_t espos_time_now_ms_or_zero (
    void * arg
)

arg is ignored. Exists so espos_sk can pass the clock across without inventing a trampoline of its own.

function espos_time_parts¶

Fill out with the current time in the configured timezone.

esp_err_t espos_time_parts (
    espos_time_parts_t * out
)

ESP_ERR_INVALID_STATE while unsynced (out is left untouched).

function espos_time_set¶

Tell the clock what time it is.

esp_err_t espos_time_set (
    int64_t unix_ms,
    espos_time_src_t src
)

Used by the SignalK fallback, by PUT /api/v1/time and by an application with a GPS or an RTC chip of its own. Refused with ESP_ERR_INVALID_STATE when a strictly higher-ranked source already set the clock this boot, so a coarse source can never degrade a good one; the same source may always refresh itself. ESP_ERR_INVALID_ARG for a non-positive unix_ms or a src outside the enum. On success the subscribers run on the calling task before it returns.

function espos_time_set_tz¶

Set the POSIX timezone string used by espos_time_parts() — "UTC0", "CET-1CEST,M3.5.0,M10.5.0/3" — and persist it in time.tz.

esp_err_t espos_time_set_tz (
    const char * posix_tz
)

Purely a display concern: nothing espOS publishes is ever in local time. NULL or "" resets to UTC. ESP_ERR_INVALID_SIZE beyond ESPOS_TIME_TZ_MAX.

function espos_time_source¶

Which source the current time came from; NONE while unsynced.

espos_time_src_t espos_time_source (
    void
)

function espos_time_src_str¶

Name of a source as the REST document spells it: "none", "rtc", "sk", "manual", "sntp".

const char * espos_time_src_str (
    espos_time_src_t src
)

function espos_time_start¶

Start the clock: read the configuration, adopt an RTC value this boot may have inherited, register the /time endpoints and — when time.sntp is on — arm SNTP so it starts on the first ESPOS_EVENT_NETWORK_UP.

esp_err_t espos_time_start (
    void
)

Requires espos_init() (config) and espos_httpd_start(); call it after espos_net_start() so the first NETWORK_UP is not missed. Idempotent.

function espos_time_status_json¶

The clock as the JSON document of docs/rest-api.md (malloc'ed; caller frees).

esp_err_t espos_time_status_json (
    char ** out_json
)

ESP_ERR_INVALID_STATE before espos_time_start().

function espos_time_subscribe¶

esp_err_t espos_time_subscribe (
    espos_time_cb_t cb,
    void * arg
)

function espos_time_tz¶

The configured POSIX timezone string; "UTC0" when none was set.

const char * espos_time_tz (
    void
)

function espos_time_unsubscribe¶

esp_err_t espos_time_unsubscribe (
    espos_time_cb_t cb,
    void * arg
)

Macro Definition Documentation¶

define ESPOS_TIME_ISO_MAX¶

#define ESPOS_TIME_ISO_MAX `25`

define ESPOS_TIME_TZ_MAX¶

#define ESPOS_TIME_TZ_MAX `40`

The documentation for this class was generated from the following file espos_time/include/espos_time.h