Add APRS Digipeater tab to AetherModem TNC (MVP: WIDE1-1 fill-in)

[jensenpat]

Summary

Add an APRS Digipeater tab to the AetherModem TNC (Ax25HfPacketDecodeDialog). The codebase is already wired for it — several files carry // for the future APRS/AX.25 digipeater comments and the AX.25 model already tracks the has-been-repeated (H) bit and the via path. This issue scopes a minimum-viable WIDE1-1 fill-in digipeater first, then a full wide-area digi.

Follow-up to #3530 (AetherModem APRS client).

Background — what a digipeater does (researched + source-verified)

A digipeater receives an AX.25 UI frame, inspects its via path, and if addressed to an alias it handles, retransmits a modified copy. The modern New-N paradigm (Bob Bruninga, aprs.org/newN). Note the APRS Protocol Reference 1.01 deliberately does not specify digipeater behavior, which is why historical implementations diverged — so we follow the New-N docs + reference implementations, not the base spec.

Core algorithm (New-N), for a WIDEn-N via field

N is the SSID in the high bits of the last AX.25 address octet.

• N ≥ 2 → decrement N; insert MYCALL ahead of the decremented entry (subject to the 8-address AX.25 limit); set the H bit only on the inserted MYCALL, leaving WIDEn-(N-1) unmarked so downstream digis keep relaying.
• N = 1 → replace the field with MYCALL and set its H bit (avoids a useless WIDEn-0).
• N = 0 → hop count exhausted → do not digipeat.

Two alias flavors:

• TRACE (WIDEn-N): substitutes/inserts the transmitter callsign + sets H → full path traceability.
• non-trace / FLOOD (state/section SSn-N): decrements but does not insert a callsign.

MVP vs full-featured

	MVP — fill-in / home digi	Full wide-area digi
Responds to	WIDE1-1 + own MYCALL only	+ WIDEn-N (trace) + SSn-N state/section (flood)
Behavior	one hop out of a dead zone, MYCALL implied, digipeat once	full decrement/insert + N-trapping
Dire Wolf analog	DIGIPEAT 0 0 ^WIDE1-1$ ^WIDE1-1$	DIGIPEAT + ^WIDE[3-7]-[1-7]$ trap

MVP target = WIDE1-1 fill-in. Genuinely useful, low network risk, exercises the full RX→modify→TX path.

Mandatory correctness features (required even for MVP)

1. Duplicate suppression — compare source-SSID + destination + info payload, ignoring the via path, over a ~30 s window (Dire Wolf DEDUPE 30, KPC-3+ UIDUPE 30). Not optional — RELAY is obsolete precisely because it lacked dupe-elimination. (Caveat: 30 s is the convention but imperfect; delayed packets can exceed it.)
2. Hop exhaustion — never retransmit a field at N=0.
3. H-bit correctness — set H on the inserted/substituted MYCALL; never re-process a via field already marked H.

Network-friendliness features (full version / config knobs)

• N-trapping — high-N paths (e.g. WIDE3-7) repeated once (replaced by MYCALL, no decrement) to kill abusive long paths. Trap boundary is a tunable, commonly N ≥ 3.
• Viscous delay (aprx, 0–9 s; fill-in technique) — hold the packet; if the dupe detector sees another copy before the delay expires, discard (a stronger digi already covered it). Recommend 0 for normal digi, 5 for fill-in.
• No stagger (UIDWAIT off) — let multiple digis transmit simultaneously ("fratricide"); this is the primary channel-load minimizer, not a bug.
• Direct-only mode (aprx directonly) — fill-in repeats only directly-heard (not already-digipeated) packets.
• Tiered self-beacon — direct posit every 10 min, 1-hop every 30 min, 2-hop every 60 min. Disable any non-APRS HID/ID packet.

Mapping onto AetherModem (architecture is ready)

• AX.25 model already has what we need: ax25::Address.hasBeenRepeated (H bit) + ssid, and ax25::Frame.via — src/core/tnc/Ax25.h:22 / :62. Encode/decode preserve H bits (Ax25.cpp:53, :124).
• RX hook: AetherAx25LibmodemShim::frameDecoded → distributed in Ax25HfPacketDecodeDialog.cpp:889. A new AprsDigipeater slot taps the same signal alongside PMS/terminal/MQTT.
• TX hook: emit transmitFrame(QByteArray rawNoFcs) → shared KISS TX queue (m_kissTxQueue, depth-capped) → buildTransmitAudioFromFrame(). Same contract AprsMessenger uses (AprsMessenger.cpp:168).
• Dedupe helper exists: AprsStationList already does ~30 s source+payload suppression — reuse/generalize it.
• Tab pattern: add a 5th button to tabGroup + a buildDigipeaterPage() into m_tabStack (Ax25HfPacketDecodeDialog.cpp:670–755).
• Settings: new DigipeaterSettings under key "AetherModemDigipeater", mirroring AprsSettings (JSON blob).

Proposed scope

Phase 1 — MVP (this issue)

• New class AprsDigipeater : public QObject — RX → decode → match alias → modify path → re-TX.
• WIDE1-1 + MYCALL fill-in only; digipeat-once semantics.
• 30 s dedupe (source+dest+payload, ignore path); hop-exhaustion + H-bit correctness.
• New Digipeater tab: enable toggle, MYCALL field, live heard/repeated/dropped counters, recent-repeat log.
• DigipeaterSettings persistence ("AetherModemDigipeater").
• Safety: no RF TX without explicit enable and a visible "Digi TX active" indicator. Default off.

Phase 2 — wide-area + polish

• WIDEn-N trace + SSn-N flood handling.
• N-trapping (configurable boundary), viscous delay, direct-only mode.
• Tiered self-beacon (10/30/60 min) + ensure no non-APRS HID.
• Per-station digi statistics / map integration.

Open questions

• Preemptive digipeating (Dire Wolf PREEMPT OFF/DROP/MARK/TRACE) — defer to Phase 2+? When is it network-friendly vs abusive?
• Combined Tx-iGate + digi gating rules (third-party framing, avoid double-injecting RF back to APRS-IS) — out of scope here, but note the interaction.
• HF vs VHF: digipeating convention is a VHF (1200 baud) practice; should the tab gate on the modem profile (Ax25DemodConfig) to avoid encouraging HF 300-baud digipeating?

References

• New-N paradigm / WIDE1-1 settings (Bruninga) — https://www.aprs.org/newN/WIDE1-1settings.txt
• Digi beacon rates + HID-off — https://www.aprs.org/digis/digi-rates.txt
• KPC-3+ WIDEn-N (UITRACE/UIFLOOD/UIDUPE/UIDWAIT) — https://www.aprs.org/kpc3/kpc3+WIDEn.txt
• Dire Wolf digipeater + DEDUPE — https://github.com/wb2osz/direwolf/blob/master/digipeater.c · User-Guide.pdf
• aprx digipeater + viscous-delay/relay-modes — https://github.com/PhirePhly/aprx/blob/master/digipeater.c · https://manpages.debian.org/testing/aprx/aprx.8.en.html
• On duplicate & delayed packets (aprs.fi) — https://blog.aprs.fi/2008/03/on-duplicate-and-delayed-packets.html

---

Design researched via fan-out web search with 3-vote adversarial verification (24/25 claims confirmed). The one refuted claim: WIDEn-N dedup is per-digi, not a network-wide single copy — fratricide intentionally produces multiple simultaneous transmissions.

[aethersdr-agent]

Triage: maintainer-review

I verified every architecture claim in this issue against the source — it all checks out, and the design is sound. This is a clean, well-scoped Phase-1 feature with no blocking unknowns. Handoff below.

Integration points (verified)

Claim	Verified at
AX.25 model carries the H bit + via path	Ax25.h:28 (hasBeenRepeated), :65 (QVector<Address> via), :29 (C bit)
Encode/decode preserve H bits	Frame::encode/decode round-trip via Addresses incl. hasBeenRepeated
RX hook = frameDecoded fan-out	Ax25HfPacketDecodeDialog.cpp:1065–1082 — appendFrame, MQTT, KISS broadcast, PMS all tap the one signal; a digi slot taps the same
TX hook = transmitFrame → shared queue	AprsMessenger.cpp:174 (emit transmitFrame(frame.encode())) → Ax25HfPacketDecodeDialog.cpp:1198–1199 enqueueAprsTx → m_kissTxQueue (depth-capped, kMaxKissTxQueueDepth=64, :97) → buildTransmitAudioFromFrame
Existing dedupe pattern	AprsStationList.cpp:59–61 — suppresses same source+infoText within kDupeWindowSecs, ignoring path
Tab pattern	Ax25HfPacketDecodeDialog.cpp:846–868 — tabGroup button ids 0–3 today; digi slots in as id 4, with a buildDigipeaterPage() added to m_tabStack

What to build (Phase-1 MVP)

1. class AprsDigipeater : public QObject (suggest src/core/aprs/): connect a slot to m_shim::frameDecoded, decode via ax25::Frame::decode, run the New-N algorithm for WIDE1-1 + MYCALL only (replace field with MYCALL + set H; digipeat-once), re-encode, emit transmitFrame(raw) into the same enqueueAprsTx lambda the messenger/beacon use.
2. Dedupe — ⚠️ don't literally reuse AprsStationList::record: it mutates the station roster as a side effect and keys on source+info only (no dest). The digi needs its own small ring/cache keyed on source-SSID + dest + info, ignoring path, over ~30 s. Generalize the pattern, not the method. Pull the window into a shared constant alongside kDupeWindowSecs.
3. Correctness invariants (required even for MVP): never retransmit at N=0; set H only on the inserted/substituted MYCALL; skip any via field already H-marked.
4. Digipeater tab (5th button): enable toggle, MYCALL field, live heard/repeated/dropped counters, recent-repeat log. DigipeaterSettings JSON blob under "AetherModemDigipeater", mirroring AprsSettings.
5. Safety (this is why I tagged safety): unattended automatic RF TX. Default off; require explicit enable; show a visible "Digi TX active" indicator; respect the existing TX queue depth cap so a busy channel can't back up the keying path.

Design call worth deciding before implementation

The issue's third open question — gate the digi on the modem profile? I'd recommend yes: digipeating is a VHF 1200-baud convention, and the profile is already exposed (m_hf300Profile/m_vhf1200Profile, :893–894). Either hard-gate to 1200-baud or at minimum warn loudly when enabled on the 300-baud HF profile, to avoid encouraging HF digipeating. Preemptive digipeating and Tx-iGate gating are correctly deferred to Phase 2.

Classification

New Feature · subsystems protocol (AX.25/APRS), GUI (new tab), safety (unattended automatic RF TX). Priority left normal — it's net-new, gated behind an explicit opt-in, and carries no crash/data-loss risk.

Ready for implementation once you add aetherclaude-eligible. The dedupe-keying and VHF-gating decisions above are the only two I'd want confirmed before I start.

---

_{🤖 aethersdr-agent · cost: $2.1057 · model: claude-opus-4-8}

---

_{📍 Citation health check (Foundry Constitution Principle I): 0 resolved, 6 unresolved against /Users/aetherclaude/workspace/AetherSDR at origin/main.}

Unresolved citations (6)

Citation	Reason
AprsMessenger.cpp:174	file not found in workspace
AprsStationList.cpp:59	file not found in workspace
Ax25.h:28	file not found in workspace
Ax25HfPacketDecodeDialog.cpp:1065	file not found in workspace
Ax25HfPacketDecodeDialog.cpp:1198	file not found in workspace
Ax25HfPacketDecodeDialog.cpp:846	file not found in workspace