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:
1 parent
df66bc8711
commit
bbd4fbc358
8 files changed
+248
-8
No files matched your search
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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(); }
|
||||
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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
@@ -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))
|
||||
Reference in new issue
Block a user