feat(modem): Personal Mailbox System (PMS) over connected-mode AX.25

[jensenpat]

Summary

Adds a Personal Mailbox System (PMS / PBBS) to AetherModem: a compact mailbox
that a single remote caller can connect to over
1200-baud AX.25 connected mode to read, list, and send messages, see who has
been heard, and disconnect — plus a new Mailbox config tab and an hourly
beacon. Built on top of #3279 (KISS-over-TCP TNC).

This required implementing AX.25 v2.0 connected mode (LAPB), which the modem
did not have before (it only did connectionless UI/APRS frames). The new
connected-mode layers are deliberately split out and reusable for the planned
APRS/AX.25 digipeater.

✅ Validated over the air at 1200 baud against a BTECH UV-Pro + PacketCommander
(iOS TNC): connect, single-line and multi-line command replies, T1 retries on a
lossy link, and graceful back-to-back connections all confirmed. See
Over-the-air validation below.

What's new

Reusable AX.25 primitives (RF-agnostic, unit-tested)

• src/core/tnc/Ax25.{h,cpp} — Address (callsign/SSID encode/decode) and
  Frame parse/build for I, RR/RNR/REJ, SABM, DISC, DM, UA, FRMR, and UI frames
  (address..info, no FCS — the same convention as the KISS path and
  buildTransmitAudioFromFrame). Handles the command/response C-bits and the
  mod-8 control field.
• src/core/tnc/Ax25Connection.{h,cpp} — a single-connection LAPB state
  machine: accepts an inbound SABM (→ UA), tracks V(S)/V(R)/V(A), acknowledges
  received I-frames with RR, segments outbound data into I-frames (≤ paclen), and
  retransmits unacked I-frames on the T1 timeout up to N2 tries before
  declaring link failure. Honours RR/RNR/REJ, poll/final, and DISC. One caller at
  a time (extra SABMs get a polite DM). Defaults (T1 6 s, N2 8, paclen 128,
  window 1) are sized for a half-duplex, PTT-keyed 1200-baud FM link — see
  the connection notes below for why the window is 1.

The mailbox service

• src/core/pms/PmsMailbox.{h,cpp} (one file pair, as requested) — owns the
  Ax25Connection, greets a caller by callsign with the AetherMailbox SID and
  version, runs a line-oriented command interpreter, maintains the heard
  list (updated for all received frames so callers can find other PMS/BBS in
  the area), and sends an optional hourly UI beacon announcing it is online
  and how to connect. State persists as JSON under
  ~/.config/AetherSDR/pms/ (messages.json, callers.json, heard.json;
  overridable via AETHER_PMS_DIR). RF-agnostic: fed via onAirFrame(), emits
  frames on transmitFrame().

AetherModem Mailbox tab

• Enable PMS, a listen callsign (full CALL-SSID, e.g. KI6BCJ-10) and an
  optional vanity alias the mailbox also answers on (e.g. AETBBS; AX.25
  limits a callsign to 6 chars + optional -SSID), a welcome / PTEXT line,
  the hourly-beacon toggle + text, and a stats row with Statistics on the
  left and the last callers on the right. All settings persist in
  AppSettings (AetherModemPms* keys) across restarts. Enabling the mailbox
  turns the modem on; outbound frames share the existing one-at-a-time PTT/DAX
  keying/pacing path. The bottom of the window is a slim status bar (modem state,
  gain, compact packet-activity strip).

Supported mailbox commands

KPC-3 subset (first letter or full word; case-insensitive):

Command	Action
H / ? / HELP	Command help
B / BYE	Disconnect (sends sign-off then DISC)
I / INFO	Mailbox info / welcome + counts
J / JHEARD	Stations heard recently, newest first (find other PMS/BBS)
L / LIST	List all messages (#, type, to, from, date, subject)
LM	List messages addressed to the caller
R n / READ n	Read message n (marks own private mail read)
K n / KILL n	Delete message n (own / to-you / ALL bulletins)
S call / SP call / SEND call	Send a private message
SB cat	Send a bulletin (use ALL for everyone)
U / USERS	Who is connected

Composing: after S/SP/SB the mailbox prompts SUBJECT:, then collects body
lines until /EX or Ctrl-Z on a line by itself. Address a message to ALL
for a public/bulletin message.

AX.25 connection details to be aware of

• Connected mode, AX.25 v2.0, mod-8 sequence space (the 1200-baud norm), not
  the connectionless UI path the modem already had.
• We answer, we don't originate. The PMS replies to an inbound SABM with
  UA; an unexpected frame while disconnected gets DM. Only one caller at a
  time — a second SABM from a different station is refused with DM.
• Addressing: the mailbox answers on the configured listen callsign
  (CALL-SSID) and the optional vanity alias; the address the caller dialed
  is used for the whole session (UA, greeting, replies). Command/response sense is
  carried in the two address C-bits (command: dest C=1, src C=0).
• Flow control / reliability: window k=1 (MAXFRAME=1), paclen 128.
  Received I-frames are acked with RR; out-of-sequence triggers REJ.
  Unacked I-frames retransmit on T1 (6 s) up to N2 (8) tries, then the
  link is declared failed (DM + disconnect). RNR pauses sending.
  • Why window=1: on a half-duplex radio each I-frame is its own PTT keyup.
    Sending several back-to-back keeps us transmitting (and deaf) long enough that
    the caller's RR ack lands while we cannot hear it → a T1 retransmit loop. With
    k=1 we send one frame, then listen for its ack before the next. This was the
    fix for an observed live multi-line-reply stall (see fixes below). setWindow()
    (1–7) leaves room for a future single-keyup multi-frame TX path or a
    full-duplex transport.
• TX path: each frame is keyed through the existing serialized DAX/PTT pacing
  queue (one transmission at a time), shared with the KISS TX path.
• RX path: decoded frames arrive via the libmodem decoder
  (Ax25DecodedFrame::ax25FrameNoFcs), which is frame-type-aware (validates I/S/U
  frames), so SABM/RR/I/DISC all reach the data link. (A connect-frame decode bug
  was found and fixed during bring-up — see fixes below.)
• Beacon: a UI frame (src = PMS addr, dest = BEACON) every hour while
  enabled, with customizable text plus a "connect to " hint.

Fixes during bring-up (post-initial-PR)

Validating against real hardware surfaced three real bugs, each fixed with a
regression test:

1. Connect frames silently dropped (beb73ae). The bitstream decoder
   (try_decode_frame in third_party/libmodem_core/bitstream.h) rejected frames
   < 18 bytes, but the shortest valid AX.25 frame with FCS is 17 (14
   address + 1 control + 2 FCS, no PID) — exactly every connected-mode U-frame
   (SABM/DISC/UA/DM). So the mailbox could never be reached in connected mode even
   with perfect audio. Gate corrected to < 17. (UI/APRS frames carry a PID byte
   and are ≥ 18, which is why connectionless decode always worked.)
2. Multi-frame replies stalled in a T1 loop (25c9db3). Default send window
   was 4, so a multi-I-frame reply (e.g. LIST) went out as several back-to-back
   keyups; on half-duplex the caller's ack arrived while we were still
   transmitting and was missed every cycle → retransmit storm to link failure.
   Fixed by defaulting window to 1 (one frame per ack).
3. Diagnostic tool counter (83db57a). The offline ax25_replay tool counted
   a Qt signal that processMonoFloat() never emits, so it under-reported decodes;
   fixed to count the return value. (Tooling only — also added tools/ax25_replay.cpp,
   an offline WAV→decoder diagnostic, built on demand.)

Tests

pms_mailbox_test (Qt6::Core only, no DSP/radio) covers:

• Address parse/format and Frame encode/decode round-trips (SABM, I, RR,
  UI(+via)), incl. the 6-char-callsign limit;
• the connection handshake (SABM→UA→connected, I-frame delivery + ack,
  DISC→disconnected, frames for other stations ignored);
• half-duplex window=1: a 3-I-frame reply drains one-frame-per-ack with no
  retransmit storm (regression guard for fix build(deps): Bump github/codeql-action from 3 to 4 #2);
• vanity-alias dial (UA + greeting sent from the alias address);
• a full mailbox session driven as a remote TNC would: connect → greeting →
  H → compose (SP/SUBJECT/body//EX) → L → R → J → B.

ax25_libmodem_shim_test gains a SABM AFSK loopback test (regression
guard for fix #1): a real 17-byte SABM rendered through the modem decodes back as
FrameType::SABM with the right addresses.

Tests use AETHER_PMS_DIR to isolate storage, so they are repeatable and never
touch a live operator's mailbox.

Test status

• pms_mailbox_test and ax25_libmodem_shim_test: pass (incl. repeated runs).
• Full AetherSDR app builds and links clean on macOS (Ninja, RelWithDebInfo).

Over-the-air validation

Confirmed on real hardware — BTECH UV-Pro radio + PacketCommander (iOS
TNC) at 1200-baud 2 m FM:

• Connect: caller dials the listen callsign, gets the AetherMailbox greeting.
• Single-line command replies (INFO, prompts) — clean.
• Multi-line command replies (LIST, READ) — drain correctly, no T1 loop.
• Retries on a lossy link — T1 retransmit recovers rather than stalling.
• Back-to-back connections handled gracefully (clean teardown + re-connect).

Docs

docs/MODEM.md gains a Personal Mailbox System (PMS) section (architecture,
commands, the reuse path for a future digipeater).

Test plan (for reviewers)

• Set a listen callsign on the Mailbox tab; Enable PMS → confirm
  "Listening as -".
• From a TNC, C <call>-<ssid> at 1200 baud → AetherMailbox greeting; try
  H, L, SP, R n, J, B.
• Verify messages/callers/heard persist across an AetherSDR restart.
• Enable the hourly beacon; confirm a UI beacon is keyed.
• Confirm AX.25 UI decode/TX and the KISS TNC are unchanged.

💻 Generated with Claude Code (Opus 4.8) with architecture by @jensenpat

[jensenpat]

UI iteration pass (commit 1e9c4d2), verified: full app builds clean and pms_mailbox_test passes on repeated runs.

• Listen callsign + vanity alias free-text fields (no defaults) replace the answer-SSID spinbox. The mailbox answers on either; the dialed address is used for the whole session (UA, greeting, replies). Note: AX.25 limits a callsign to 6 characters + optional -SSID, so a 7-char vanity like AETHBBS isn't a legal address — use ≤6 (e.g. AETBBS). The field placeholder/tooltip says so.
• Statistics (left) and Last callers (right) split into two aligned panels.
• Removed the "A single remote caller…" help paragraph.
• Collapsed MODEM STATUS / GAIN STAGE / PACKET ACTIVITY into one slim inline status bar with a compact activity strip.

Ax25Connection gained an optional alias address; PmsMailbox swapped base-call+SSID for setListenCallsign()/setAliasCallsign(). New alias-dial unit test plus address-length checks.

[jensenpat]

Root cause found: connect frames (SABM) were silently dropped by an off-by-one length gate

Troubleshooting a live PMS connect failure (caller's TNC connect frames never answered) surfaced a real decoder bug, independent of the original no-audio symptom.

The bug: try_decode_frame() in third_party/libmodem_core/bitstream.h rejected any frame < 18 bytes. But the shortest valid AX.25 frame with FCS is 17 bytes (14 address + 1 control + 2 FCS, no PID/info) — which is exactly every connected-mode U-frame: SABM, DISC, UA, DM. So the modem silently dropped every connect/disconnect/ack, and a PMS/BBS could never be reached in connected mode even with perfect audio. UI/APRS frames carry a PID byte (≥18 bytes), which is why connectionless decode always worked. Fix: gate < 18 → < 17.

How it was found / tooling added:

• tools/ax25_replay.cpp — replays a captured mono-float32 WAV through the decoder (sweeps both tone polarities), printing decoded frames + reject counters.
• testSabmConnectFrameLoopbackDecodes — builds a real SABM, runs it through the AFSK modem, asserts it decodes back as FrameType::SABM. Regression guard.
• PmsMailbox::onAirFrame now logs each decoded frame with the listen/alias address-match decision (decode-vs-mismatch at a glance on aether.ax25).

Verified: shim test (incl. 10 SABM assertions) + pms test pass deterministically; app + replay build clean.

Operator note (separate issue)

The capture you provided contained no packet keyups at all — flat ~−23 dBFS hiss for the full 180 s, only ~10 dB dynamic range, zero bad-FCS candidates across 21k HDLC false-triggers. So the connect audio wasn't reaching the modem. That points at the RX audio path, not this bug. Worth checking: the slice is actually receiving on the packet freq, squelch open, PC/DAX RX audio routed to AetherModem, and the BTECH is keying on the same frequency/tone. Once audio flows, this fix is what lets the connect actually complete.

[jensenpat]

✅ Validated over the air

Tested end-to-end on real hardware — BTECH UV-Pro + PacketCommander (iOS TNC), 1200-baud 2 m FM:

• Connect → AetherMailbox greeting by callsign.
• Single-line replies (INFO, prompts) — clean.
• Multi-line replies (LIST, READ) — drain correctly, no T1 retransmit loop.
• Retries on a lossy link — T1 retransmit recovers rather than stalling.
• Back-to-back connections — graceful teardown and re-connect.

Fixes landed since this PR opened (each with a regression test)

Commit	Fix
beb73ae	Decode connect frames — try_decode_frame < 18→< 17 byte gate was silently dropping every 17-byte U-frame (SABM/DISC/UA/DM), so connected mode could never be reached even with perfect audio.
25c9db3	Half-duplex window=1 — multi-frame replies were blasting back-to-back PTT keyups; the caller's RR ack arrived while we were transmitting (deaf), causing a T1 retransmit loop. One frame per ack fixes it.
83db57a	ax25_replay diagnostic counted an unemitted Qt signal; now counts the decode return value. (Added tools/ax25_replay.cpp, an offline WAV→decoder diagnostic.)

The PR description has been updated with the window=1 rationale, the listen+vanity-alias callsign UI, and the OTA results. pms_mailbox_test + ax25_libmodem_shim_test pass; app builds clean on macOS.

[ten9876]

@jensenpat — heads up: this PR was auto-closed as a side effect of my admin-merging #3279 with `--delete-branch`. The base ref `aether/kiss-tnc-ux` was deleted on merge, which GitHub then took as a signal to auto-close every PR stacked on it. The closure was not intentional and is not a rejection of the PMS work.

The good news: your stacking design has the PMS commits preserved inside #3381's cumulative diff per your own note there. So the work isn't lost — it'll naturally surface when #3381 rebases against current main now that #3279 has landed.

If you'd prefer to keep the PMS work in its own PR (separate from the terminal client), feel free to reopen this against `main` and rebase — the branch `aether/pms-mailbox` should still exist with all commits intact. Otherwise the cumulative #3381 path also works.

Sorry for the merge-mechanics caused noise. Tracking the deeper KissTncServer ownership refactor in #3424.