Skip to content

[Proposal] Repeater Channel Activity Cache & Smart Metrics Framework #3558

Open

Description

@neohiro

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.

Activity

  1. LitBomb commented on Oct 6, 2026

    @LitBomb
    SponsorContributor

    This seems like a very unnecessary feature. I sure do not want the most popular random hashtag channels get auto populated into my companions, especially if they are no name channels and only have a 1-byte channel hash. Large meshes have tens if not hundreds of private and hashtag channels, you get 1-byte channel collision easily and that would screw up your stats.

    I also don't want or care to have my repeaters to manage stats for hashtag channels on device. that is a lot of extra work on repeaters for no gain. And repeaters would use more memory and battery. This would be especially unnecessary for solar powered repeaters. Even if this is implemented as something that can be turned off, it is unnecessary complexity added to the firmware code.

    All the metrics, if they even make sense to have, could get processed by other MQTT-brokered services, not on device.

  2. neohiro commented on Oct 27, 2026

    @neohiro
    Author

    It would indeed be only about public hashtag channels that are actively used by the community.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions