Export boot timestamp, update docs and examples to use it

src/sntp.c

@@ -7,10 +7,10 @@
 #define SNTP_TIME_OFFSET 2208988800U  // (1970 - 1900) in seconds
 #define SNTP_MAX_FRAC 4294967295.0    // 2 ** 32 - 1
 
-static uint64_t s_boot_timestamp = 0;  // Updated by SNTP
+uint64_t mg_boot_timestamp_ms = 0;  // Updated by SNTP
 
 uint64_t mg_now(void) {
-  return mg_millis() + s_boot_timestamp;
+  return mg_millis() + mg_boot_timestamp_ms;
 }
 
 static int64_t gettimestamp(const uint32_t *data) {
@@ -37,7 +37,7 @@ int64_t mg_sntp_parse(const unsigned char *buf, size_t len) {
     int64_t now = (int64_t) mg_millis();
     int64_t latency = (now - origin_time) - (transmit_time - receive_time);
     epoch_milliseconds = transmit_time + latency / 2;
-    s_boot_timestamp = (uint64_t) (epoch_milliseconds - now);
+    mg_boot_timestamp_ms = (uint64_t) (epoch_milliseconds - now);
   } else {
     MG_ERROR(("unexpected version: %d", version));
   }
@@ -53,7 +53,7 @@ static void sntp_cb(struct mg_connection *c, int ev, void *ev_data) {
   } else if (ev == MG_EV_READ) {
     int64_t milliseconds = mg_sntp_parse(c->recv.buf, c->recv.len);
     if (milliseconds > 0) {
-      s_boot_timestamp = (uint64_t) milliseconds - mg_millis();
+      mg_boot_timestamp_ms = (uint64_t) milliseconds - mg_millis();
       mg_call(c, MG_EV_SNTP_TIME, (uint64_t *) &milliseconds);
       MG_DEBUG(("%lu got time: %lld ms from epoch", c->id, milliseconds));
     }
@@ -86,3 +86,4 @@ struct mg_connection *mg_sntp_connect(struct mg_mgr *mgr, const char *url,
   if (url == NULL) url = "udp://time.google.com:123";
   return mg_connect_svc(mgr, url, fn, fn_data, sntp_cb, NULL);
 }
+

src/sntp.h

@@ -1,10 +1,58 @@
+// Time / SNTP functions
+
 #pragma once
 
 #include "net.h"
 
+// Return milliseconds since boot (uptime). Never goes backwards.
+// On RTOS targets (FreeRTOS, ThreadX, Zephyr, etc.) uses the RTOS tick count.
+// On STM32/Cube uses HAL_GetTick(). On Arduino uses millis().
+// On Linux/macOS uses CLOCK_MONOTONIC_RAW or CLOCK_MONOTONIC; falls back to
+// CLOCK_REALTIME if neither is available.
+uint64_t mg_millis(void);
+
+// Boot timestamp in ms since Epoch. Updated by successful SNTP request
+extern uint64_t mg_boot_timestamp_ms;
+
+// Return milliseconds since Epoch: mg_millis() + mg_boot_timestamp_ms.
+// Until a successful SNTP request completes, this is identical to mg_millis().
+uint64_t mg_now(void);
+
+// Return true if the periodic timer has fired; advance `expiration` by one
+// `period`. Handles wrap-around. Usage example:
+//
+// ```c
+// uint64_t timer = 0;
+// for (;;) {
+//   if (mg_timer_expired(&timer, 1000, mg_millis())) {
+//     MG_INFO(("Hi"));  // Print a message every second
+//   }
+//   mg_mgr_poll(&mgr, 10);
+// }
+// ```
+bool mg_timer_expired(uint64_t *expiration, uint64_t period, uint64_t now);
+
+// Connect to an SNTP server and send a time request.
+// `url` defaults to "udp://time.google.com:123" when NULL.
+// On success the internal boot timestamp is updated so that mg_now() returns
+// the correct wall-clock time, and MG_EV_SNTP_TIME is fired on `fn` (if not
+// NULL) with a pointer to the int64_t epoch in milliseconds.
+// Pass fn == NULL and fn_data == NULL for a fire-and-forget sync that only
+// updates mg_boot_timestamp_ms. Typical polling usage:
+//
+// ```c
+// uint64_t timer = 0;
+// for (;;) {
+//   uint64_t period = mg_boot_timestamp_ms == 0 ? 1000 : 3600 * 1000;
+//   if (mg_timer_expired(&timer, period, mg_millis())) {
+//     mg_sntp_connect(&mgr, NULL, NULL, NULL);
+//   }
+//   mg_mgr_poll(&mgr, 1000);
+// }
+// ```
 struct mg_connection *mg_sntp_connect(struct mg_mgr *mgr, const char *url,
                                       mg_event_handler_t fn, void *fn_data);
+
+// Private API, do not expose
 void mg_sntp_request(struct mg_connection *c);
 int64_t mg_sntp_parse(const unsigned char *buf, size_t len);
-
-uint64_t mg_now(void);     // Return milliseconds since Epoch

src/timer.h

@@ -21,4 +21,3 @@ void mg_timer_init(struct mg_timer **head, struct mg_timer *timer,
                    void *arg);
 void mg_timer_free(struct mg_timer **head, struct mg_timer *);
 void mg_timer_poll(struct mg_timer **head, uint64_t new_ms);
-bool mg_timer_expired(uint64_t *expiration, uint64_t period, uint64_t now);

src/util.h

@@ -17,7 +17,6 @@ void mg_bzero(volatile unsigned char *buf, size_t len);
 bool mg_random(void *buf, size_t len);
 char *mg_random_str(char *buf, size_t len);
 uint32_t mg_crc32(uint32_t crc, const char *buf, size_t len);
-uint64_t mg_millis(void);  // Return milliseconds since boot
 bool mg_path_is_sane(const struct mg_str path);
 void mg_delayms(unsigned int ms);