AetherSDR's VHF 1200 baud AX.25 decode rate was 27% of Direwolf's on identical audio. This PR brings it to 96% on the default A+ profile — matching and slightly exceeding both Direwolf and Graywolf — by replacing the libmodem sinc-correlator with a Direwolf-derived AFSK demodulator.

Summary

Three branches of development have been squashed into a single commit for review:

• feat/aether-afsk-demod — Direwolf-derived AFSK demodulator, Profile A
• feat/aether-afsk-profile-b — full 6-mode selector (A / B / AB / A+ / B+ / AB+)
• feat/ax25-shim-worker-thread — worker thread + full 9-slicer bank + HdlcCodec Phase 1a+1b

Also addresses #3387.

Relationship to issue #2701

Issue #2701 describes a phased roadmap for a native Soft-TNC. This PR lands the following pieces of that plan:

Phase 1a — HdlcCodec (src/core/tnc/HdlcCodec.{h,cpp} + tests/hdlc_codec_test.cpp): the native HDLC framing layer called out in the plan. 27 unit tests; CRC-16-CCITT cross-checked against both Direwolf and graywolf as the plan specified. This is the first of the planned test suite to land.

Phase 2 — AFSK demodulator: the plan described a "correlator-difference AFSK demod + early-late symbol clock" for a new ClientTnc. Rather than build a new wrapper, we replaced the demodulator inside the existing AetherAx25LibmodemShim, producing a working VHF 1200 baud decode path without disrupting the surrounding architecture. The demodulator is Direwolf-derived (Profiles A/B/AB/A+/B+/AB+). AX.25 structure parsing remains on libmodem for now.

Threading: The plan describes ClientTnc running inline on the AudioEngine thread. We chose a dedicated QThread instead — see the Worker thread section below for the reasoning.

Changes

1. Direwolf-derived AFSK demodulator (third_party/direwolf_afsk/)

Replaces lm::sinc_corr_afsk_demodulator for VHF 1200 baud. HF 300 baud continues to use libmodem unchanged.

Source location: third_party/direwolf_afsk/, following the libmodem_core/ subset pattern. README.aethersdr.md records the upstream release, referenced files, license compatibility rationale, and what was omitted. THIRD_PARTY_LICENSES updated.

License: Direwolf is GPL-2-or-later. AetherSDR is GPL-3. GPL-2-or-later is one-way compatible into GPL-3 (FSF). Source headers reflect GPL-3, not the previously-cited GPL-2+.

Six VHF modes exposed via a new VhfMode enum and runtime QComboBox selector. The AETHERSDR_USE_AETHERDEMOD compile-time switch from the initial draft has been removed — VHF 1200 always uses the Direwolf-derived path. The selector is disabled when HF 300 is active:

Default is A+, matching Direwolf's MODEM 1200 default.

Profile A (AetherAFSKDemod): IQ-mix + RRC + DPLL, space-gain bank. The A+ 9-slicer values {0.500, 0.648, 0.841, 1.091, 1.414, 1.834, 2.378, 3.084, 4.000} are the exact geometric series from Direwolf's demod_afsk.c (MAX_SUBCHANS=9), compensating for VHF FM de-emphasis on the 2200 Hz space tone.

Profile B (AetherFMDiscrimDemod): FM discriminator — IQ-mix → atan2 → phase rate → normalize. Targets signals where amplitude balance between mark and space is unreliable (frequency-offset stations, Doppler, weak paths). Complements A+: each catches signals the other misses. The B+ 9 slice offsets {−0.500, −0.375, …, 0.500} match Direwolf's MAX_SLICERS=9 linear series.

2. Worker thread

AetherAx25LibmodemShim now runs entirely on a dedicated QThread (m_shimThread) owned by Ax25HfPacketDecodeDialog. Both the VHF (AetherAFSKDemod) and HF 300 baud (libmodem) paths run through the same feedAudio() entry point, so both move to the worker thread automatically.

Issue #2701 describes the long-term ClientTnc architecture running inline on the AudioEngine thread. We chose a dedicated worker thread instead, for two reasons:

• The original shim ran on the GUI thread. Multi-lane AFSK demodulation is heavy enough to cause visible UI degradation, and the RPi 5 demonstrated that audio sampling was also affected. Isolating the demod to its own thread keeps both the UI and the audio path responsive. In AB+ mode (18 lanes) on the RPi 5, the demod worker uses approximately 23% of one core.
• The AudioEngine thread is real-time / high-priority; blocking it with a 9–18 lane correlator bank would cause glitches in the waterfall, RX audio, and QSO recording. The roadmap's AudioEngine-thread approach assumes a lightweight single-lane demodulator; this implementation is considerably heavier.

When the roadmap's ClientTnc is eventually built as a lightweight single-lane demodulator, the AudioEngine-thread approach may be appropriate for that path. The shim stays on its dedicated worker.

Implementation details:

• Cross-thread calls (configure(), reset(), feedAudio(), setDiagnosticsLoggingEnabled()) dispatched via QMetaObject::invokeMethod with Qt::QueuedConnection
• A main-thread Ax25DemodConfig cache eliminates cross-thread reads on the hot path
• Signal connections (frameDecoded, diagnosticsUpdated, statusChanged) use AutoConnection — Qt resolves these to QueuedConnection automatically

Audio sampling is unaffected even when running under AddressSanitizer on the RPi 5.

3. HdlcCodec — Phase 1a (new file: src/core/tnc/HdlcCodec.{h,cpp})

Standalone native HDLC framing class replacing lm::ax25::bitstream_state in the decode lanes. Pure C++, no Qt, no libmodem dependency.

Implements: NRZI decode, bit-stuffing, CRC-16-CCITT (0x8408, poly bit-reversed, init/final XOR 0xFFFF), LSB-first byte assembly. State machine: Searching → InPreamble → InFrame → Complete/Aborted.

Verified algorithmically equivalent to both Direwolf (hdlc_rec.c / fcs_calc.c) and libmodem before replacement. 27/27 unit tests in tests/hdlc_codec_test.cpp.

4. HdlcCodec — Phase 1b (integrated into AetherAx25LibmodemShim)

DecodeLane members replaced:

• lm::ax25::bitstream_state bitstreamState → HdlcCodec hdlcCodec
• std::vector<uint8_t> bitstreamBuffer → removed (internal to HdlcCodec)
• std::array<uint8_t, 1000> candidateFrameBytes → removed (use hdlcCodec.frameData())

libmodem is retained for try_decode_frame_no_fcs (AX.25 structure parsing) and the TX packet builder. The HF 300 baud demodulator (lm::sinc_corr_afsk_demodulator) is also unchanged.

5. MSVC compatibility

third_party/direwolf_afsk: GNU __builtin_expect replaced with standard [[likely]]/[[unlikely]]; VLAs replaced with std::vector.

Addressing #3387 triage items

License (point 1): Confirmed — AetherSDR is GPL-3, not GPL-2+. Direwolf GPL-2-or-later is compatible. Source headers corrected.

Vendoring (point 2): Direwolf sources are in third_party/direwolf_afsk/ with README.aethersdr.md, matching the libmodem_core/ pattern. THIRD_PARTY_LICENSES updated.

HF 300 coverage (point 3): The Direwolf path is VHF 1200 only. The VhfMode selector is disabled for HF 300. HF 300 parity is a separate future item.

Framing layer scope (point 4): We went one step further than the triage suggested and also replaced the HDLC framing layer (Phase 1a+1b). Justification: analysis of Direwolf's hdlc_rec.c and libmodem confirmed they are algorithmically identical — same NRZI formula, same bit-stuffing check, same CRC polynomial, same byte alignment rule. The decode gap is entirely in the AFSK demodulator. Replacing libmodem's HDLC gives clean ownership of the framing layer, enables future instrumentation, and is required for the Phase 2 roadmap. The blast radius is low: the AX.25 structure parser (try_decode_frame_no_fcs) and TX path remain on libmodem.

Long-term build switch (point 5): The AETHERSDR_USE_AETHERDEMOD compile switch is removed. VHF 1200 always uses the Direwolf-derived demodulator. The runtime VhfMode selector (default A+) gives operators the tradeoff knob.

Performance

The original comparison cited in #3387 was libmodem 777 vs Direwolf 2891 over the same audio (3.7×). Long-duration live comparisons on 144.390 MHz APRS on a Raspberry Pi 5 show AetherSDR at or above parity with both Direwolf and Graywolf on the default A+ profile:

A+ mode (default) — 987 packets heard:

AB+ mode (18 lanes) — 2,405 packets heard, 12-hour run:

On A+, AetherSDR leads both reference decoders. The AB+ result (4 points behind) is characterised by the confidence data: AetherSDR's average confidence on missed packets (GW+DW only: 23 frames, confidence 57–59) is marginally lower than on all-three packets (61), indicating conservative behaviour on the very weakest signals rather than systematic error. AetherSDR's false-positive rate is effectively zero in both datasets.

Comparison methodology

Decode performance was measured using a three-decoder comparison running continuously on a Raspberry Pi 5, listening to live 144.390 MHz APRS traffic via a FlexRadio 6600. All three decoders ran on separate slice receivers, each receiving the same 144.390 MHz signal. Direwolf and Graywolf listened to DAX audio streams from their respective slices; AetherSDR's internal decoder published decoded frames via MQTT.

Comparator: A purpose-built Python webapp subscribes to all three sources simultaneously — MQTT for AetherSDR, REST API polling for Graywolf, and subprocess stdout for Direwolf. Frames are matched within a 5-second window on content. Duplicate copies of the same RF burst (digipeated repeats) are counted once per decoder, making the totals directly comparable. A live browser UI and analysis endpoint show per-decoder counts and decode-combination breakdowns in real time.

Quality metrics: Each decoder was instrumented to report a signal quality value alongside each decoded frame — AetherSDR's existing confidence field (0–1, from the MQTT payload), Graywolf's decoded.quality field from its REST response, and Direwolf's per-bit EMA quality from its q=N audio level line. These were used to characterise the missed-packet population rather than as a pass/fail threshold.

What does not change

• HF 300 baud decode path — unchanged, still uses libmodem
• AX.25 structure parsing (try_decode_frame_no_fcs) — unchanged, still libmodem
• TX audio generation — unchanged
• KISS TNC, TCI server, MQTT paths — unchanged

Testing

tests/hdlc_codec_test.cpp — 27 tests, all pass.

Built against both HdlcCodec and libmodem simultaneously, using libmodem as ground truth:

The testFcsMatchesLibmodem test is the key cross-check called out in the #2701 plan — it proves HdlcCodec and libmodem compute the same CRC-16-CCITT over identical frame bytes, ruling out the polynomial/init/final-XOR mismatch the plan specifically flagged as a risk.

tests/ax25_libmodem_shim_test — 120 tests, all pass. Covers the full shim end-to-end: AFSK loopback (HF 300 and VHF 1200), TX/RX round-trips, KISS framing, diagnostics, and bad-FCS detection. This suite exercises HdlcCodec through the shim integration, confirming the Phase 1b replacement did not change observable behaviour.

Live VHF decode confirmed on 144.390 MHz on macOS (Apple Silicon M2), Raspberry Pi 5, and Windows 11.

Built and smoke tested on: MacBook Air M2 / RPi 5 Debian trixie / Windows 11 on Intel i3

Happy to split into separate PRs (demodulator / worker thread / HdlcCodec) if that makes review easier — the three areas are independent once the lane-management interface is stable.