[Proposal] Repeater Channel Activity Cache & Smart Metrics Framework

Start with examples/simple_repeater/MyMesh.h/.cpp and the existing anonymous request handlers, then inspect packet forwarding and channel history around the referenced changes. The proposal spans repeater caching, protocol formats, companion behavior, configuration, and tests across several phases. Done means implementing and validating the agreed phase; the issue requests maintainer feedback on the design before coding.

Executive Summary

This proposal introduces a repeater firmware feature that caches the most active hashtag channels (by message volume over rolling 30-day windows) and automatically populates them into MeshCore companions. It also establishes a framework for repeaters to store derived metrics weekly and share them with companions — all without online lookups, fully region-scoped, and built on existing flood routing.

---

1. Core Proposal: Active Channel Cache on Repeaters

1.1 What It Does

• Each repeater maintains a bounded in-RAM ring buffer (configurable, default 64 entries) of channel activity observations from GRP_TXT packets it forwards.
• Observations are aggregated per channel hash with a decaying weight (exponential moving average over ~30 days).
• Top-N most active channels (default N=16) are served to companions via a new anonymous request subtype (ANON_REQ 0x05).

1.2 Wire Format

ANON_REQ 0x05  {reply-path}{params_len=2}{max_channels:u8}{min_activity_threshold:u16}

Response (direct, never re-flooded):

{tag:4}{count:u8}  then count × {channel_hash:1}{activity_score:u16}{last_seen_ts:u32}{channel_name_len:u8}{channel_name}

• activity_score: 0–65535 scaled EMA (higher = more active)
• channel_name: UTF-8, up to 32 bytes (from repeater's local cache if known, else empty)
• Rate-limited by existing anon_limiter (same as regions/clock/time-sync)

1.3 Companion Integration

• On startup / periodic (configurable, default 6h), companion sends ANON_REQ 0x05 to nearest repeater(s).
• Received channels are auto-added to companion's channel list (if not present) with a "discovered via repeater" flag.
• User sees: "Discovered: #emergency (high activity), #local-news (medium)" — one tap to join.

1.4 Storage & RAM Budget

Component	Size (default)	Notes
Activity ring buffer	64 × 12 B = 768 B	channel_hash(1) + score(2) + last_seen(4) + name_len(1) + name(up to 32, avg ~12)
Top-N cache	16 × 40 B = 640 B	Pre-computed for fast serve
Total	~1.4 KB RAM	Fits on all supported targets (ESP32, nRF52, RP2040)

Configurable via set channel_cache.size <N> and set channel_cache.top_n <M>.

---

2. Extended Metrics Framework (Weekly Derived Metrics)

2.2 Metrics Computed Weekly (on repeater, zero airtime cost)

Metric	Description	Use Case
channel_activity_ema[hash]	EMA of message count per channel	Auto-discovery, health dashboards
peer_contact_rate[hash]	Unique peer hashes seen per channel	Community size estimation
avg_hops_per_channel[hash]	Mean path_len of forwarded GRP_TXT	Reach / topology insight
airtime_util_pct	% airtime busy (from PR #3332)	Congestion awareness
rx_quality_pct	Good decodes / total attempts (SNR-gated)	Link health
unique_senders_total	Distinct src_hash across all traffic	Network population proxy
flood_drop_reasons	Counters per drop reason (from PR #2114)	Repeater tuning

2.3 Sharing Metrics to Companions

New anonymous request: ANON_REQ 0x06 (metrics snapshot)

ANON_REQ 0x06 {reply-path}{params_len=1}{metric_set_bitmap:u8}

Response: CBOR-encoded map (compact, ~200–400 bytes) with timestamps and values.

Companion renders in "Mesh Health" screen; can push to app via BLE/serial for logging.

---

3. Additional Smart Repeater Data Uses

3.1 Channel Popularity Heatmap (Geo-Tagged)

• If repeater has GPS (or fixed lat/lon from config), tag each observation with coarse location (geohash-4, ~20km).
• Serve via ANON_REQ 0x07 → companions can show "activity near you" map.
• Privacy: Only repeater's own location, never peer locations.

3.2 Path Quality Matrix

• For each (channel_hash, next_hop_hash) pair, track success rate of forwarded packets.
• Enables companions to prefer better routes (future: sendFoldScoped with quality hint).

3.3 Emergency Channel Beacon

• Repeater can be configured with set emergency_channel #emergency.
• Periodically (default 15 min) emits a tiny GRP_TXT beacon on that channel: "BEACON {repeater_hash} {ts} {uptime}".
• Companions auto-detect → "Emergency repeater reachable: 2 hops, 45 min ago".

3.4 Firmware Version Census

• Capture app_data from ADVERT packets (contains firmware version).
• Aggregate: {version: count} served via metrics API.
• Helps operators see upgrade adoption in their region.

---

4. Topology & Firmware Mapping

Device Role	Firmware Example	Supports Cache?	Supports Metrics?	Notes
Repeater	simple_repeater	✅ Yes (primary target)	✅ Yes	Always on, sees all flood traffic
Room Server	simple_room_server	✅ Optional	✅ Optional	Can enable if RAM allows
Companion	companion_radio	❌ No (client only)	❌ Consumer only	Receives via ANON_REQ
Sensor	simple_sensor	❌ No	❌ No	Too constrained
KISS Modem	kiss_modem	⚠️ Host-dependent	⚠️ Host-dependent	Host (PC/SBC) can implement

Chipset support: ESP32 (Heltec, T-Beam, Wio), nRF52840 (SenseCAP, Xiao), RP2040 (Waveshare) — all have ≥ 64 KB RAM, so ~1.4 KB is trivial.

---

5. Caveats & Truthful Impossibilities

Claim	Reality
"Repeater knows channel names"	❌ False. Repeater only sees channel_hash (1 byte). Names only known if repeater operator manually configures them (set channel_cache.name 0x11 "#emergency").
"Companion gets perfect activity ranking"	⚠️ Partial. Ranking is from one repeater's perspective. Multiple repeaters → different views. Companion should query several and merge.
"No airtime cost"	⚠️ Mostly true. ANON_REQ + direct reply adds ~2 packets per query. At 6h interval × 50 companions = negligible. Weekly metrics push (if added) would be ~1 packet/repeater/week.
"Works for private channels"	❌ False. Only public (GRP_TXT) channels are visible to repeaters. Private/DM channels use direct routing.
"Survives repeater reboot"	❌ False by design. Cache is RAM-only (flash wear avoidance). Persistency = anti-pattern. On reboot, cache rebuilds organically in hours.
"Prevents spam channels from dominating"	⚠️ Mitigated. min_activity_threshold filters noise. Operator can set channel_cache.blocklist 0xAA,0xBB.
"KISS modem repeaters can do this"	✅ Yes, on host. The KISS host (PC/SBC) has unlimited RAM — it can implement full cache + metrics + persistence.

---

6. Implementation Plan (Phased)

Phase 1: Core Cache + ANON_REQ 0x05 (2–3 weeks)

• ChannelActivityCache class (template, hardware-independent)
• Hook in simple_repeater/MyMesh::onRecvPacket() for GRP_TXT capture
• ANON_REQ 0x05 handler in onAnonDataRecv()
• CLI: set channel_cache.*, channel_cache.status, channel_cache.clear
• Unit tests (native env): EMA decay, ring wrap, top-N selection, serve logic
• Hardware test: 2 repeaters, 3 companions, verify auto-join

Phase 2: Companion Auto-Discovery (1–2 weeks)

• Companion loop(): periodic ANON_REQ 0x05 to nearest repeater(s)
• UI: "Discovered Channels" section with activity badges
• Config: set auto_discover.enabled on|off, set auto_discover.interval_h <N>

Phase 3: Weekly Metrics + ANON_REQ 0x06 (2 weeks)

• Weekly aggregation task (RTC-aligned, Monday 00:00 UTC)
• CBOR encoding (use existing cbor.h if available, else minimal encoder)
• ANON_REQ 0x06 handler
• Companion "Mesh Health" screen

Phase 4: Optional Enhancements (parallel, opt-in)

• Geo-tagged heatmap (ANON_REQ 0x07) — requires GPS or fixed location
• Emergency beacon — set emergency_channel.*
• Firmware census — parse ADVERT.app_data

---

7. Why This Is Attractive (Marketing Angle)

"Your repeater already knows which channels are alive. Now it tells your phone."

• Zero config for users — channels just appear, ranked by actual usage
• Zero infrastructure — no servers, no internet, no accounts
• Region-scoped by physics — you see what's active where you are
• Privacy-first — no message content, no peer IDs, only channel hashes + counts
• KISS-compatible — host-side implementation gets the same data over serial

---

8. Example User Flow

1. User flashes Heltec V3 as repeater, places on roof.
2. Repeater starts forwarding #emergency, #local-news, #hiking, #crypto, #spam.
3. After 2 days: EMA scores — #emergency: 42000, #local-news: 18000, #hiking: 9000, #crypto: 300, #spam: 50.
4. User powers on companion in valley (no direct peers).
5. Companion sends ANON_REQ 0x05 → repeater replies with top 3 channels.
6. Companion UI: "📡 Discovered via repeater AB:CD:EF: #emergency 🔥 HIGH, #local-news 📍 MEDIUM, #hiking 🥾 LOW"
7. User taps #emergency → joins instantly (PSK known or prompted).
8. Weekly: repeater computes metrics → companion shows "Mesh Health: 12 active channels, 47 unique peers, 23% airtime util".

---

9. Files to Touch (Reference)

File	Change
src/helpers/ChannelActivityCache.h/.cpp	New — core cache logic
examples/simple_repeater/MyMesh.h/.cpp	Add cache member, hooks, ANON_REQ handlers, CLI
src/helpers/AnonReqTypes.h	New — define 0x05, 0x06, 0x07 subtypes
docs/payloads.md	Document wire formats
examples/companion_radio/MyMesh.h/.cpp	Periodic discovery, UI integration
src/helpers/CommonCLI.h/.cpp	Shared CLI helpers for cache config

---

10. Request for Feedback

Maintainers, please weigh in on:

1. Default buffer sizes — 64 entries / top-16 OK for all targets?
2. ANON_REQ subtype allocation — 0x05/0x06/0x07 reserved?
3. No-login for channel discovery — consistent with regions/clock/time-sync?
4. RAM-only cache — confirmed acceptable (rebuilds fast)?
5. CBOR for metrics — or simpler TLV? (CBOR decoder exists in src/helpers/cbor.h?)
6. Phase 1 scope — ship cache + ANON_REQ 0x05 first, metrics later?

---

Built on: MeshCore dev branch (post #1677 AEAD, post #3332 radio stats, post #2114 repeater stats, post #3078 channel history).
Author: Ready to implement — seeking design blessing before code.