npr::rf::SignalingClientCache class final
#include <npr/stats/signaling_client_cache.hpp>

Observability-only cache of signaling WHO data and local RSSI samples.

The cache is deliberately role-neutral:

  • entries 0..6 represent NPR client IDs observed in WHO signaling,
  • the final entry stores the broadcast/master WHO identity when present.

Future master implementation is expected to reuse this cache for neighbor visibility instead of introducing a separate incompatible WHO model. This cache must not be required for protocol correctness.

Public static variables

static size_t kMasterEntryIndex constexpr
static size_t kMaxEntries constexpr
static size_t kMaxSlaveEntries constexpr

Public functions

void invalidate(uint8_t who_client_id)
Invalidates one cached entry by WHO/client ID.
void log_periodic(uint64_t now_us)
Emits periodic human-readable cache table to logger.
void prune_stale(uint64_t now_us, uint64_t max_age_us)
Drops entries that have not been refreshed within max_age_us.
void reset()
Clears all cached entries and periodic log cadence state.
auto snapshot(SignalingWhoEntry* out_entries, size_t max_entries) const -> size_t
Copies currently active WHO entries into caller buffer.
void update_local_rssi(uint8_t client_id, uint8_t rssi_local, uint64_t now_us)
Updates locally measured RSSI for source client.
void update_timing_advance(uint8_t who_client_id, int16_t timing_advance, uint64_t now_us)
Updates cached timing-advance for one entry without changing WHO ownership semantics.
void update_uplink_rssi(uint8_t who_client_id, uint8_t rssi_ul)
Updates uplink RSSI observed by the current node for an existing entry.
void update_who(uint8_t source_client_id, uint8_t who_client_id, const char* callsign, uint32_t ip_start, uint32_t ip_size, uint8_t rssi, uint16_t ber, int16_t timing_advance, uint64_t now_us)
Updates cache from one parsed WHO element.
void upsert_identity(uint8_t who_client_id, const char* callsign, uint32_t ip_start, uint32_t ip_size, uint64_t now_us)
Refreshes identity fields (callsign/IP/timestamp) without altering cached radio metrics.

Function documentation

void npr::rf::SignalingClientCache::prune_stale(uint64_t now_us, uint64_t max_age_us)

Drops entries that have not been refreshed within max_age_us.

This is intentionally explicit instead of hidden in snapshot() so the caller keeps control over role-specific retention policy.

size_t npr::rf::SignalingClientCache::snapshot(SignalingWhoEntry* out_entries, size_t max_entries) const

Copies currently active WHO entries into caller buffer.

Returns number of copied active entries.

void npr::rf::SignalingClientCache::update_uplink_rssi(uint8_t who_client_id, uint8_t rssi_ul)

Updates uplink RSSI observed by the current node for an existing entry.

In current PacketRF semantics this is primarily used by the master role, where every uplink frame from a client is a direct local observation of that client's uplink signal at the master.

void npr::rf::SignalingClientCache::upsert_identity(uint8_t who_client_id, const char* callsign, uint32_t ip_start, uint32_t ip_size, uint64_t now_us)

Refreshes identity fields (callsign/IP/timestamp) without altering cached radio metrics.

Use this for periodic control-path refresh where no new measured WHO metrics are available.