feat(clock): a node with no GPS starts at its build epoch, not in 2024

Measured 7. 8. 2026: bench-board had been running 811 days behind since it was
deployed, and every board on the bench was 812 days behind. Nobody had ever
set their clocks, because setting one was a manual step documented in two
places and performed in neither.

That is not cosmetic. Mesh.cpp stamps every advert a node transmits from the
RTC, and a receiver drops a stale timestamp as a replay -- so a wrong clock
turns into replies that vanish.

Nothing could fix it by itself. The only automatic sources in the tree are GPS
(which these nodes do not have) and BaseChatMesh, which the repeater build does
not link; and `clock sync` cannot work from the console at all, because USB and
BLE share one command buffer and pass sender_timestamp = 0, so the
`sender_timestamp > curr` guard is never satisfied.

So build_version.py now also stamps FIRMWARE_BUILD_EPOCH, and that -- not a
hardcoded 15 May 2024 -- is where a clock with no other source comes up. A
freshly flashed board is right to within "time since compile". It needs no GPS,
nothing carrying a correct time on air, and no host: the one case the host-side
tooling cannot reach. Verified on x1: build epoch 1786100869 = 11:07:49, and
after a reboot the board came up at 11:07:47.

The #ifndef fallback is load-bearing, not decoration: build_version.py is
nRF52-only and reaches 7 of the 16 local envs, so upstream envs never define it.
Verifying an integer define is not `strings` -- dump .text and look for the
word, and check the old literal is gone from all three sites.

`clock` also reports the epoch now. Its human part is minutes only, so a host
comparing clocks could not see a difference under a minute and had to leave a
59 s deadband; appended, so anything that just prints the reply is unaffected.

Also here, and DISABLED, is carrying the clock across a soft reset in retained
RAM. It was tried and measured not to work: the record at 0x2003FFE0 came back
as `00000000 10001000 00000000` after a reboot -- not zeroed, OVERWRITTEN, and
0x10001000 is the nRF52 UICR base, i.e. a UICR pointer left on the Adafruit
bootloader's stack. The bootloader runs before the app on every reset and links
against the full RAM, so it owns the top of it; being outside the app's linker
region is not enough. The code stays because it self-disables against __StackTop
and now says so at boot, and because the same doubt applies to the hardfault
record at 0x2003FFF0, which sits HIGHER -- treat a missing hardfault report as
"unknown", not as "nothing crashed".

Two things that cost a cycle each and are now designed out: the restore's
"nothing stored" branch was silent, which is indistinguishable from "working";
and `clkreboot` would have undone itself, writing the build epoch and then
having the reboot restore the value it just discarded (weak
retainedClockInvalidate() closes that).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5 committed 2026-08-09 22:24:59 +02:00
1 parent a49bbb914d
commit 4fb886170f
8 files changed
+248 -8

No files matched your search

+17 -1
View File
@@ -16,7 +16,23 @@ MEMORY
*/
/* CUSTOM (TeTeHacko): reserve 16 B at the end of RAM for a hardfault record
* (PC/LR survive soft reset, printed on next boot) — see HardFault_Handler
* in the framework and the boot-time printout in main.cpp. */
* in the framework and the boot-time printout in main.cpp.
*
* MEASURED 7. 8. 2026, AND IT UNDERMINES THE PREMISE: keeping an address out of
* the linker's region is NOT enough to survive a soft reset on this hardware.
* A clock record was tried at 0x2003FFE0 (32 B reserved) and came back as
* `00000000 10001000 00000000` after a `reboot` — not zeroed, OVERWRITTEN, and
* 0x10001000 is the nRF52 UICR base, i.e. a UICR pointer left on somebody's
* stack. The Adafruit bootloader runs before the app on every reset and links
* against the full RAM, so its stack starts at 0x20040000 and grows down
* through this area; it reached at least 24 B down.
*
* The hardfault record at 0x2003FFF0 is HIGHER, i.e. the first thing that stack
* touches, so it is unlikely to be any safer. Nothing here has ever
* demonstrated it surviving. Do not build anything new on this mechanism
* without proving retention first, and treat a missing hardfault report as
* "unknown" rather than "no fault happened".
*/
RAM (rwx) : ORIGIN = 0x20006000, LENGTH = 0x2003FFF0 - 0x20006000
}
+35
View File
@@ -47,18 +47,36 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Note:** No reply is sent.
Resets the clock to the firmware's build epoch (or, on an unstamped build, the
upstream 15 May 2024 literal) and reboots. This is the **only** way to move a
clock backwards: `time` and `clock sync` both refuse to.
---
### Sync the clock with the remote device
**Usage:**
- `clock sync`
Takes the time from the *packet's* `sender_timestamp`, so it works **only over
the remote admin CLI**, never from the USB or BLE console — those pass
`sender_timestamp = 0` (they share one command buffer, see
`examples/simple_repeater/main.cpp`), and `0 > curr` is never true, so a local
`clock sync` always answers `ERR: clock cannot go backwards`. Use `time <epoch>`
locally.
---
### Display current time in UTC
**Usage:**
- `clock`
**Reply:** `HH:MM - D/M/YYYY UTC (epoch <seconds>)`
The epoch is a TeTeHacko addition. The human part is minutes only, so a host
comparing clocks cannot see a difference smaller than a minute and has to leave
a deadband of over 59 s; the epoch makes the comparison exact. It is appended,
so anything that only prints the reply is unaffected.
---
### Set the time to a specific timestamp
@@ -68,6 +86,23 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `epoch_seconds`: Unix epoch time
Refuses to go backwards (`secs > curr`), answering
`(ERR: clock cannot go backwards)`. That reply usually means the clock was
already right, so treat it as success and judge by reading `clock` back.
**Where the clock comes from if nobody sets it.** Without GPS and without an
I2C RTC the clock is volatile: it starts at the build epoch and only ticks from
`millis()`. It is worth setting, because the RTC stamps every advert the node
transmits and a receiver drops a stale timestamp as a replay. Automatic sources,
in order of preference:
- **GPS** (`gps duty` is enough — see `docs/power-saving.md`);
- **an attached host** — `tools/ble_cli.py <MAC> "time {epoch}"`, the
`meshcore-ble-bridge`/`meshcore-serial-bridge` scrape, or
`tools/xiao_uf2_flash.sh`, which sets it right after every flash;
- **the build epoch**, which is where a freshly flashed board starts, and
which needs nothing at all.
---
### Send a flood advert
+123
View File
@@ -657,6 +657,65 @@ static unsigned long userBtnDownAt = 0;
#define USER_BTN_HOLD_OFF_MILLIS 1500
#endif
#if defined(RETAINED_CLOCK_ADDR) && defined(NRF52_PLATFORM)
// CUSTOM (TeTeHacko): carry the wall clock across a soft reset in retained RAM.
//
// ESP32 already gets this for free -- ESP32RTCClock::begin() only re-seeds the
// clock when esp_reset_reason() == ESP_RST_POWERON, so a reboot there keeps the
// time. nRF52 had nothing: VolatileRTCClock's constructor runs on every boot and
// throws the clock back to the build epoch, so a node with no GPS and no I2C RTC
// lost a correct clock to any `reboot`, `dfu` or watchdog.
//
// RAM survives a soft reset physically; the only thing that destroys it is the
// startup code zeroing .bss. So the record lives at a fixed address kept OUTSIDE
// the linker's RAM region -- the same trick, and the neighbouring 16 bytes, as the
// hardfault record printed in setup() below. Reserved in
// boards/nrf52840_s140_v7_extrafs.ld; RETAINED_CLOCK_ADDR is only defined for envs
// that use that script, because the other nRF52 ldscripts run RAM to 0x20040000
// and writing there would land in live memory.
//
// Cost: 12 bytes of RAM and a store every 60 s. No flash, so no wear.
#define RETAINED_CLOCK_MAGIC 0xC10CB0DE
extern "C" { extern uint32_t __StackTop; } // = ORIGIN(RAM) + LENGTH(RAM)
static volatile uint32_t* _retainedClock() {
// Refuse to touch the address unless it really is above everything the linker
// handed out. This is what catches RETAINED_CLOCK_ADDR being paired with an
// ldscript that does not reserve it -- otherwise the symptom would be silent
// corruption of whatever variable happens to live there.
if ((uint32_t) RETAINED_CLOCK_ADDR < (uint32_t) (uintptr_t) &__StackTop) return NULL;
return (volatile uint32_t*) (uintptr_t) RETAINED_CLOCK_ADDR;
}
static void retainedClockSave(uint32_t now) {
volatile uint32_t* rc = _retainedClock();
if (rc == NULL) return;
rc[1] = now;
rc[2] = ~now;
rc[0] = RETAINED_CLOCK_MAGIC; // magic last: a reset mid-write leaves it invalid
}
// 0 = nothing trustworthy stored. The complement makes a chance match of
// uninitialised RAM about 2^-64, so this does not need a checksum.
static uint32_t retainedClockLoad() {
volatile uint32_t* rc = _retainedClock();
if (rc == NULL || rc[0] != RETAINED_CLOCK_MAGIC) return 0;
uint32_t t = rc[1];
return (rc[2] == ~t) ? t : 0;
}
// Called by `clkreboot` (CommonCLI.cpp) through a weak symbol. WITHOUT THIS the
// retained record defeats the one command that exists to fix a wrong clock:
// clkreboot writes the build epoch and reboots, and the restore above would then
// see the stale record sitting above it and put the bad time straight back. The
// only way out of an over-set clock would be a power cycle.
extern "C" void retainedClockInvalidate() {
volatile uint32_t* rc = _retainedClock();
if (rc != NULL) rc[0] = 0;
}
#endif
void setup() {
Serial.begin(115200);
delay(1000);
@@ -690,6 +749,12 @@ void setup() {
// while chasing boards that vanished from USB after `dfu`.
{
uint32_t rr = readResetReason();
// The build epoch belongs next to it: it is what the clock comes up at when
// nothing else sets it, so without it printed you cannot tell "fell back to
// the build epoch" from "restored something" -- and comparing against the
// epoch of a DIFFERENT build of the same tree invents discrepancies that are
// not there. Cost one wrong conclusion here.
Serial.printf("boot: FIRMWARE_BUILD_EPOCH=%lu\n", (unsigned long) FIRMWARE_BUILD_EPOCH);
Serial.printf("boot: RESETREAS=0x%08lX%s%s%s%s%s\n", (unsigned long)rr,
rr == 0 ? " (none set = power-on/brownout: power was removed)" : "",
(rr & 0x01) ? " RESETPIN" : "",
@@ -793,6 +858,49 @@ void setup() {
halt();
}
#if defined(RETAINED_CLOCK_ADDR) && defined(NRF52_PLATFORM)
// Deliberately AFTER radio_init(), which is what calls rtc_clock.begin(Wire) and
// therefore what decides whether this node has a hardware RTC at all. Run any
// earlier and getCurrentTime() below would read the volatile fallback instead of
// the chip, and the "do not go backwards" test would compare against the wrong
// clock. See the record layout above, near the hardfault record it sits beside.
{
uint32_t saved = retainedClockLoad();
uint32_t rr = readResetReason();
if (saved == 0) {
// NOT silent. A quiet "nothing stored" branch is indistinguishable from
// "the feature is working", and that cost a whole flash-and-reboot cycle
// to notice: the clock came up at the build epoch with no message at all,
// which looked identical to a node that had simply never saved. Print the
// raw words so the next boot says WHY -- gated off, wrong address, or a
// record that really was wiped.
volatile uint32_t* rc = _retainedClock();
if (rc == NULL) {
Serial.printf("boot: retained hodiny VYPNUTY -- adresa %08lX je pod __StackTop %08lX\n",
(unsigned long) RETAINED_CLOCK_ADDR, (unsigned long) (uintptr_t) &__StackTop);
} else {
Serial.printf("boot: retained hodiny prazdne (%08lX: %08lX %08lX %08lX, cekal magic %08lX)\n",
(unsigned long) RETAINED_CLOCK_ADDR, (unsigned long) rc[0],
(unsigned long) rc[1], (unsigned long) rc[2],
(unsigned long) RETAINED_CLOCK_MAGIC);
}
} else if (rr == 0) {
// No bit set = power-on/brownout. RAM can still hold its contents through a
// short outage, so the record may well validate -- but it is then stale by
// however long the power was gone, which is unknowable. Build epoch is the
// honest answer.
Serial.println("boot: retained hodiny ignorovany (power-on, stara hodnota by lhala)");
} else if (saved > rtc_clock.getCurrentTime()) {
rtc_clock.setCurrentTime(saved);
Serial.printf("boot: hodiny obnoveny z retained RAM (epoch %lu)\n",
(unsigned long) saved);
}
// else: the clock is already ahead of the record -- a battery-backed I2C RTC,
// or a build newer than the record. Leave it alone; this is the guard that
// keeps the restore from ever making a good clock worse.
}
#endif
fast_rng.begin(radio_driver.getRngSeed());
FILESYSTEM* fs;
@@ -1035,6 +1143,21 @@ void loop() {
#endif
rtc_clock.tick();
#if defined(RETAINED_CLOCK_ADDR) && defined(NRF52_PLATFORM)
// Stash the clock once a minute, so a reboot resumes from at most a minute ago.
// It has to be periodic rather than written on the way out: a watchdog reset or
// a lockup never reaches a shutdown path, and those are exactly the reboots
// nobody planned for. int32_t delta so the 49-day millis() wrap cannot park this
// either permanently on or permanently off -- same reason as the gps duty timers.
{
static unsigned long next_clock_save = 0;
if ((int32_t) (millis() - next_clock_save) >= 0) {
next_clock_save = millis() + 60000;
retainedClockSave(rtc_clock.getCurrentTime());
}
}
#endif
bool ble_tx_busy = false;
#if defined(BLE_PIN_CODE) && defined(NRF52_PLATFORM)
ble_tx_busy = bleTxPending(); // console output still queued -> keep pumping
+20
View File
@@ -74,6 +74,26 @@ public:
virtual const char* getShutdownReasonString(uint8_t reason) { return "Not available"; }
};
// CUSTOM (TeTeHacko): the time a clock with no other source comes up at.
//
// tools/build_version.py injects FIRMWARE_BUILD_EPOCH = the moment of compile, so
// a freshly flashed board is right to within "time since build" -- seconds on the
// bench -- with no GPS, no I2C RTC, nothing carrying a correct time on air and no
// host attached. Without it the value is upstream's hardcoded 15 May 2024, which
// is where bench-board sat for 811 days and every bench board for 812: the clock had
// simply never been set, because setting it was a manual step.
//
// That is not cosmetic. Mesh.cpp stamps every advert this node transmits from the
// RTC, and a receiver drops a stale timestamp as a replay (BaseChatMesh.cpp), so
// a wrong clock turns into replies that vanish.
//
// The fallback is NOT optional: build_version.py is wired in through
// ${stamped.extra_scripts}, which is nRF52-only and reaches 7 of the 16 envs in
// platformio.local.ini. Upstream envs never define it and must keep compiling.
#ifndef FIRMWARE_BUILD_EPOCH
#define FIRMWARE_BUILD_EPOCH 1715770351 // 15 May 2024, 8:50pm
#endif
/**
* An abstraction of the device's Realtime Clock.
*/
+3 -1
View File
@@ -8,7 +8,9 @@ class VolatileRTCClock : public mesh::RTCClock {
uint64_t accumulator;
unsigned long prev_millis;
public:
VolatileRTCClock() { base_time = 1715770351; accumulator = 0; prev_millis = millis(); } // 15 May 2024, 8:50pm
// FIRMWARE_BUILD_EPOCH = compile time when the build is stamped, else upstream's
// 15 May 2024 literal. See the define in MeshCore.h for why this matters.
VolatileRTCClock() { base_time = FIRMWARE_BUILD_EPOCH; accumulator = 0; prev_millis = millis(); }
uint32_t getCurrentTime() override { return base_time + accumulator/1000; }
void setCurrentTime(uint32_t time) override { base_time = time; accumulator = 0; prev_millis = millis(); }
+26 -3
View File
@@ -10,6 +10,12 @@
#define BRIDGE_MAX_BAUD 115200
#endif
// CUSTOM (TeTeHacko): defined by apps that keep the wall clock in retained RAM
// across a soft reset (examples/simple_repeater/main.cpp). Weak, so every build
// that does not links fine and the pointer is simply NULL. `clkreboot` has to
// clear that record or it would undo itself -- see the call site below.
extern "C" void retainedClockInvalidate() __attribute__((weak));
// Believe it or not, this std C function is busted on some platforms!
static uint32_t _atoi(const char* sp) {
uint32_t n = 0;
@@ -246,8 +252,18 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re
} else if (memcmp(command, "reboot", 6) == 0) {
_board->reboot(); // doesn't return
} else if (memcmp(command, "clkreboot", 9) == 0) {
// Reset clock
getRTCClock()->setCurrentTime(1715770351); // 15 May 2024, 8:50pm
// Reset clock. On a volatile clock this write is redundant -- the reboot
// re-runs the constructor, which seeds the same value -- but on a battery
// backed I2C RTC it really does rewrite the chip, so it must not put the
// year 2024 there. This is also the ONLY way to move a clock BACKWARDS:
// `time` and `clock sync` both refuse to, so an over-set clock can only be
// fixed by resetting it here and setting it again.
//
// The retained-RAM copy has to die with it. Otherwise the reboot restores
// the very value being thrown away here, and the command silently does
// nothing on exactly the nodes that keep their clock across a reset.
if (retainedClockInvalidate) retainedClockInvalidate();
getRTCClock()->setCurrentTime(FIRMWARE_BUILD_EPOCH);
_board->reboot(); // doesn't return
} else if (memcmp(command, "advert.zerohop", 14) == 0 && (command[14] == 0 || command[14] == ' ')) {
// send zerohop advert
@@ -274,7 +290,14 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re
} else if (memcmp(command, "clock", 5) == 0) {
uint32_t now = getRTCClock()->getCurrentTime();
DateTime dt = DateTime(now);
sprintf(reply, "%02d:%02d - %d/%d/%d UTC", dt.hour(), dt.minute(), dt.day(), dt.month(), dt.year());
// CUSTOM (TeTeHacko): the epoch goes on the end. The human part is minutes
// only, so a host comparing its own clock against this one cannot see a
// difference smaller than a minute -- meaning it cannot tell a node that is
// 40 s out from one that is exact, and has to leave a >59 s deadband. The
// epoch makes the comparison exact. Appended, so anything that only reads
// or prints the reply is unaffected.
sprintf(reply, "%02d:%02d - %d/%d/%d UTC (epoch %u)", dt.hour(), dt.minute(),
dt.day(), dt.month(), dt.year(), (unsigned) now);
} else if (memcmp(command, "time ", 5) == 0) { // set time (to epoch seconds)
uint32_t secs = _atoi(&command[5]);
uint32_t curr = getRTCClock()->getCurrentTime();
+1 -1
View File
@@ -165,7 +165,7 @@ public:
if (reason == ESP_RST_POWERON) {
// start with some date/time in the recent past
struct timeval tv;
tv.tv_sec = 1715770351; // 15 May 2024, 8:50pm
tv.tv_sec = FIRMWARE_BUILD_EPOCH; // compile time when stamped, else 15 May 2024
tv.tv_usec = 0;
settimeofday(&tv, NULL);
}
+23 -2
View File
@@ -71,9 +71,30 @@ if len(version) > VER_LIMIT:
# yymmdd hhmm = exactly 11. Not pretty, but complete and sortable; the readable
# "%d %b %Y %H:%M" is 17 and lost its time to the 12-byte field.
build_date = datetime.now().strftime("%y%m%d %H%M")[:DATE_LIMIT]
now = datetime.now()
build_date = now.strftime("%y%m%d %H%M")[:DATE_LIMIT]
# The same instant as an epoch, which VolatileRTCClock uses as its base_time
# instead of the hardcoded 15 May 2024 (src/helpers/ArduinoHelpers.h). This is
# the ONLY way a node gets a sane clock with no GPS, no I2C RTC, nothing
# carrying a correct time on air, and no host attached -- i.e. a bench board.
# It is not cosmetic: the RTC stamps every advert the node transmits, and a
# receiver drops a stale timestamp as a replay, so a 2024 clock turns into
# dropped replies. Measured 7. 8. 2026: bench-board had run 811 days behind since
# deployment and every board on the bench was 812 days behind, all because
# `time <epoch>` was a manual step nobody performed.
#
# NOT StringifyMacro: this has to reach the compiler as the integer 1786095587,
# not as the string "1786095587". SCons renders a (name, value) tuple as
# -Dname=value verbatim.
#
# Costs no extra rebuilds -- FIRMWARE_BUILD_DATE already changes every build, so
# the tree is already fully recompiled each time.
build_epoch = int(now.timestamp())
env.Append(CPPDEFINES=[
("FIRMWARE_VERSION", env.StringifyMacro(version)),
("FIRMWARE_BUILD_DATE", env.StringifyMacro(build_date)),
("FIRMWARE_BUILD_EPOCH", str(build_epoch)),
])
print("build_version.py: %s (Build: %s)" % (version, build_date))
print("build_version.py: %s (Build: %s, epoch %d)" % (version, build_date, build_epoch))