feat(notecard): Add StaticNotecard::ping() + parameterize seed source

Three connected changes that round out the ping work:

1. `StaticNotecard::ping()` lands as a mirror of `Notecard::ping()`,
so the user-facing surface is the same on both Notecard variants. Important for the AVR / singleton path, where StaticNotecard is the only handle the application sees.

2. Both implementations are now **stateless**. The 16-character nonce
is derived from a fresh xorshift32 seed per call, rather than from a PRNG state stored on the Notecard. The previous design stored a `uint32_t ping_prng_` member that the linker could not remove even when no caller invoked `ping()` — every `StaticNotecard` instance paid 4 bytes of RAM and the constructor paid ~8 bytes of flash for zero-initialising it, whether the feature was used or not.

3. Both implementations accept an optional `PingSeedFn` parameter that
supplies the seed. The default is `hal().millis()`, which is what production callers want — millis advances between calls so consecutive nonces differ naturally on real hardware. Tests can inject a deterministic seed function instead so consecutive nonces are predictable.

Surface details:

  - `using PingSeedFn = uint32_t(*)();` lives in `note::` namespace
(defined in `include/note/notecard.hpp`, visible to both Notecard and StaticNotecard since static_notecard.hpp already includes notecard.hpp). Function-pointer shape rather than template / std::function — keeps AVR-class targets free of template explosion and `<functional>` baggage.
  - `Result<void> Notecard::ping(uint32_t timeout_ms = 500,
PingSeedFn seed_fn = nullptr);`
  - `Result<void> StaticNotecard::ping(...)` — same signature.
  - `note::NotecardApi::ping(...)` pass-throughs updated on both the
C++20 TargetT template and the legacy form.
  - The seed (user-supplied or millis) is XORed with the xorshift32
seed constant `0x2545F491u` so a caller that returns 0 (or a just-booted clock that has not advanced from 0) still produces a non-zero xorshift state.

Test update:

  - `tests/test_ping.cpp` "successive calls produce different nonces"
renamed to "different seeds produce different nonces" and now injects a counter-based seed function. Under the mocked transport `hal().millis()` returns 0, so without the injection two consecutive calls would share a nonce — the test now explicitly documents and verifies that two distinct seeds produce two distinct nonces.

AVR size verification:

avr-notecpp              flash  +0   ram  +0 avr-notecpp-direct       flash  +0   ram  +0 avr-notecpp-raw          flash  +0   ram  +0 avr-notecpp-multistack   flash  +0   ram  +0

Zero cost on every env — the `ping()` template method is correctly DCE'd by the linker when no caller instantiates it, and no member is added to the class either. The `+8 B / +4 B` cost from the stateful first cut is fully recovered.

CHANGELOG: Unreleased section gains an entry describing the new `nc.ping()` surface, available on both `note::Notecard` and `note::StaticNotecard`.

Host: 1877 cases pass. Arduino: 1894 cases pass.

Author: m-mcgowan

CHANGELOG.md

@@ -10,6 +10,9 @@ details belong in git commit messages and design docs, not here.
 
 ## [Unreleased]
 
+### Added
+- `nc.ping()` — a one-shot connectivity probe that sends a nonce-bearing `echo` request and confirms the Notecard echoes the same nonce back. The call is deliberately stripped down: a single attempt, a short fixed default timeout (500 ms), and no retry, CRC, or transport reset on failure. The probe is safe to call at any point in the lifecycle, including before any other transaction has run. Available on both `note::Notecard` (polymorphic) and `note::StaticNotecard` (singleton / AVR). See [troubleshooting.md](docs/troubleshooting.md#im-getting-no-response-from-the-notecard) for guidance on using it as a triage step.
+
 ## [0.2.0] - 2026-04-21
 
 ### Added

src/note/notecard.hpp

@@ -23,6 +23,15 @@
 
 namespace note {
 
+/// Optional seed-supplying function for `Notecard::ping()` /
+/// `StaticNotecard::ping()`. The probe's 16-character nonce is derived
+/// from this seed via an internal xorshift32 PRNG; passing `nullptr`
+/// (the default) seeds from the HAL clock (`hal().millis()`), which is
+/// what production callers want. Tests inject a deterministic seed
+/// function so consecutive nonces are predictable.
+using PingSeedFn = uint32_t(*)();
+
+
 #if NOTE_SINGLETON
 namespace detail {
 /// Shared NcT* (type-erased to void*) for all `request_traits<T>` under
@@ -704,25 +713,28 @@ class Notecard {
     /// safe to call at any point in the lifecycle, including before any
     /// other transaction has run.
     ///
+    /// The 16-character nonce is generated by an xorshift32 PRNG seeded
+    /// from `seed_fn()` (or, when null, from the HAL clock). Tests can
+    /// inject a deterministic seed function to make consecutive nonces
+    /// predictable; production callers should leave `seed_fn` at its
+    /// default so consecutive pings carry different nonces.
+    ///
     /// Returns success when the nonce matches; a transport error when
     /// the transport itself failed; or `Error::Json` when the response
     /// is missing a `text` field or its `text` value does not match the
     /// sent nonce.
-    Result<void> ping(uint32_t timeout_ms = 500) {
+    Result<void> ping(uint32_t timeout_ms = 500, PingSeedFn seed_fn = nullptr) {
         if (!transport_)
             return make_error(Error::NotReady, NOTE_ERR("no transport configured"));
 
-        if (ping_prng_ == 0)
-            ping_prng_ = 0x2545F491u ^ hal().millis();
+        uint32_t seed = (seed_fn ? seed_fn() : hal().millis()) ^ 0x2545F491u;
 
         char nonce[16];
         for (int i = 0; i < 16; ++i) {
-            uint32_t x = ping_prng_;
-            x ^= x << 13;
-            x ^= x >> 17;
-            x ^= x << 5;
-            ping_prng_ = x;
-            nonce[i] = static_cast<char>('A' + (x % 26));
+            seed ^= seed << 13;
+            seed ^= seed >> 17;
+            seed ^= seed << 5;
+            nonce[i] = static_cast<char>('A' + (seed % 26));
         }
 
         // Hand-build the request so we do not pull in snprintf on AVR.
@@ -1313,11 +1325,6 @@ class Notecard {
     TransactionTiming timing_{};
     uint32_t next_request_id_ = 1;
     bool request_ids_enabled_ = true;
-    // xorshift32 state for the ping() nonce generator. Zero means
-    // "uninitialised"; ping() seeds it lazily from the host clock on
-    // first use so two Notecards constructed in quick succession do
-    // not share a sequence.
-    uint32_t ping_prng_ = 0;
 #if !NOTE_NO_MD5
     // Static, shared across all Notecards: avoids a self-reference inside
     // Notecard (pointer to own member), which broke every move-assignment

src/note/notecard_api.hpp

@@ -141,9 +141,10 @@ class NotecardApi : private detail::NcOwner, public Api<TargetT> {
     }
 
     /// One-shot `echo` connectivity probe. Forwarded to Notecard::ping;
-    /// see the description there for the wire shape and timing.
-    Result<void> ping(uint32_t timeout_ms = 500) {
-        return nc_.ping(timeout_ms);
+    /// see the description there for the wire shape, timing, and the
+    /// meaning of `seed_fn`.
+    Result<void> ping(uint32_t timeout_ms = 500, PingSeedFn seed_fn = nullptr) {
+        return nc_.ping(timeout_ms, seed_fn);
     }
 
     Notecard& notecard() { return nc_; }
@@ -203,8 +204,8 @@ class NotecardApi : private detail::NcOwner, public Api<Notecard> {
     }
 
     /// One-shot `echo` connectivity probe — see C++20 overload above.
-    Result<void> ping(uint32_t timeout_ms = 500) {
-        return nc().ping(timeout_ms);
+    Result<void> ping(uint32_t timeout_ms = 500, PingSeedFn seed_fn = nullptr) {
+        return nc().ping(timeout_ms, seed_fn);
     }
 
     Notecard& notecard() { return nc(); }

src/note/static_notecard.hpp

@@ -308,6 +308,56 @@ class StaticNotecard {
                                           timeout_ms);
     }
 
+    /// One-shot `echo` connectivity probe. Mirror of `Notecard::ping()` —
+    /// see the description there for the wire shape, timing, error
+    /// semantics, and the meaning of `seed_fn`. The two implementations
+    /// are deliberately kept in sync so the user-facing surface is the
+    /// same on both Notecard variants.
+    Result<void> ping(uint32_t timeout_ms = 500, PingSeedFn seed_fn = nullptr) {
+        uint32_t seed = (seed_fn ? seed_fn() : stack_.transport.hal().millis()) ^ 0x2545F491u;
+
+        char nonce[16];
+        for (int i = 0; i < 16; ++i) {
+            seed ^= seed << 13;
+            seed ^= seed >> 17;
+            seed ^= seed << 5;
+            nonce[i] = static_cast<char>('A' + (seed % 26));
+        }
+
+        constexpr char kPrefix[] = R"({"req":"echo","text":")";
+        constexpr char kSuffix[] = R"("})";
+        constexpr size_t kPrefixLen = sizeof(kPrefix) - 1;
+        constexpr size_t kSuffixLen = sizeof(kSuffix) - 1;
+        char req[kPrefixLen + 16 + kSuffixLen];
+        memcpy(req, kPrefix, kPrefixLen);
+        memcpy(req + kPrefixLen, nonce, 16);
+        memcpy(req + kPrefixLen + 16, kSuffix, kSuffixLen);
+
+#if !NOTE_NO_RETRY
+        enforce_timing();
+#endif
+        char rsp_buf[64];
+        auto rv = stack_.transport.transact_raw(string_view(req, sizeof(req)),
+                                                rsp_buf, sizeof(rsp_buf),
+                                                timeout_ms);
+#if !NOTE_NO_RETRY
+        record_timing();
+#endif
+        if (!rv) return Unexpected(rv.error());
+
+        string_view rsp = *rv;
+        constexpr string_view key = R"("text":")";
+        auto pos = rsp.find(key);
+        if (pos == string_view::npos)
+            return make_error(Error::Json, NOTE_ERR("ping: response missing text field"));
+        pos += key.size();
+        if (pos + 16 > rsp.size())
+            return make_error(Error::Json, NOTE_ERR("ping: response text too short"));
+        if (memcmp(rsp.data() + pos, nonce, 16) != 0)
+            return make_error(Error::Json, NOTE_ERR("ping: nonce mismatch"));
+        return Result<void>{};
+    }
+
 private:
     using InplaceBuilder = void(*)(JsonRender& w, const void* ctx);
 

tests/test_ping.cpp

@@ -88,7 +88,7 @@ TEST_CASE("ping: propagates transport errors") {
     CHECK_FALSE(rv);
 }
 
-TEST_CASE("ping: successive calls produce different nonces") {
+TEST_CASE("ping: different seeds produce different nonces") {
     std::string first_request;
     std::string second_request;
     int call = 0;
@@ -104,9 +104,17 @@ TEST_CASE("ping: successive calls produce different nonces") {
             return string_view(rsp_buf, static_cast<size_t>(n));
         });
 
+    // The default seed is hal().millis(), which is 0 under the mocked
+    // transport, so two consecutive calls would otherwise share a nonce.
+    // Inject a counter-based seed to make consecutive nonces predictable
+    // and confirm they differ.
+    static uint32_t counter;
+    counter = 1;
+    auto seed = []() -> uint32_t { return counter++; };
+
     Notecard nc(nullptr, t);
-    auto a = nc.ping();
-    auto b = nc.ping();
+    auto a = nc.ping(500, seed);
+    auto b = nc.ping(500, seed);
     REQUIRE(a);
     REQUIRE(b);
     auto first_nonce  = extract_nonce(first_request);