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

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 df66bc8711
commit bbd4fbc358
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))