Add 500 Hz narrowband OFDM mode (OFDM_NARROW) for low-SNR operation

Adds a 500 Hz narrowband OFDM mode that provides ~7.5 dB noise bandwidth
advantage over wideband, enabling reliable communication at SNR 5-10 dB
where wideband fails. The entire session stays within 500 Hz.

- FFT=2048, 21 carriers, 23.4 Hz bin spacing, 492 Hz occupied BW
- Narrowband chirp sync (1250-1750 Hz, 1000ms) + MC-DPSK handshake (4 carriers)
- Dual-listen: RX detects both wideband and narrowband chirps when idle
- ARQ window=1 (stop-and-wait) with ~7s timeout for long frame times
- LTS threshold lowered to 0.50 for narrowband (fewer carriers = weaker correlation)
- isOFDMMode() helper unifies OFDM_CHIRP/OFDM_COX/OFDM_NARROW checks
- ~103 bps (R1/4) to ~230 bps (R1/2), 10x slower but works where wideband cannot
- Tested: AWGN SNR=8 100%, good fading SNR=8 100% data + all messages delivered

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: secup

CLAUDE.md

@@ -74,13 +74,25 @@
 - **Preamble:** Light preamble (LTS only) for data after handshake
 - **Key files:** `decodeFixedFrame()` in frame_v2.cpp
 
+### Mode 3: OFDM_NARROW (SNR 5-10 dB, 500 Hz bandwidth)
+- **When:** Narrowband chirp detected (1250-1750 Hz), low SNR where wideband fails
+- **Waveform:** OFDM with narrowband chirp sync, FFT=2048, 21 carriers, 492 Hz BW
+- **ARQ:** Stop-and-wait (window=1) - same as MC-DPSK due to long frame times (~3s)
+- **Frame format:** Same as wideband OFDM (4 CW data, 1 CW control)
+- **Interleaving:** Frame-level + optional channel interleaving (same as OFDM)
+- **Preamble:** Light preamble (LTS only) for data after handshake
+- **Dual-listen:** RX listens for both wideband AND narrowband chirps when idle
+- **Throughput:** ~103 bps (R1/4) to ~230 bps (R1/2) — 10× slower than wideband but works at 7.5 dB lower SNR
+
 ### Mode Selection Flow
-1. **Connection starts:** Always MC-DPSK for PING/PONG/CONNECT
-2. **After CONNECT_ACK:** SNR is measured, mode is negotiated
-   - SNR < 10: Stay in MC-DPSK
-   - SNR ≥ 10: Switch to OFDM
-3. **enterConnected():** Sets ARQ window based on mode (1 vs 4)
-4. **StreamingEncoder/Decoder:** Check `mode_` to use correct path
+1. **Connection starts:** MC-DPSK for PING/PONG/CONNECT (wideband or narrowband chirp)
+2. **Dual-listen:** RX detects chirp type → sets BandwidthMode (WIDE or NARROW)
+3. **After CONNECT_ACK:** SNR is measured, mode is negotiated
+   - SNR < 10 + wideband: Stay in MC-DPSK
+   - SNR ≥ 10 + wideband: Switch to OFDM_CHIRP
+   - Narrowband detected: Switch to OFDM_NARROW
+4. **enterConnected():** Sets ARQ window based on mode (1 for MC-DPSK/NARROW, 4 for wideband OFDM)
+5. **StreamingEncoder/Decoder:** Check `mode_` to use correct path, `isOFDMMode()` for OFDM family
 
 ### NEVER MIX THESE:
 - MC-DPSK frames through OFDM encoder (corrupts control frames)
@@ -98,8 +110,10 @@
 | OFDM_CHIRP | AWGN | 15+ | 100% |
 | OFDM_CHIRP | Good fading | 15 | **100%** |
 | OFDM_CHIRP | Moderate fading | 15 | ~90% |
+| OFDM_NARROW | AWGN | 8+ | 100% |
+| OFDM_NARROW | Good fading | 8 | 100% data, 90%+ ACK |
 
-**Current state (2026-02-11):**
+**Current state (2026-03-01):**
 - MC-DPSK: WORKING - 100% at SNR=10 with moderate fading
 - OFDM_CHIRP DQPSK R1/4 AWGN: WORKING - 100% at SNR=15 and SNR=20 (0 retries)
 - OFDM_CHIRP DQPSK R1/4 Good fading SNR=15: WORKING - 100% (0 retries, 0 failures)
@@ -118,6 +132,8 @@
 - OFDM_CHIRP DQPSK R3/4 Good fading: NOT RECOMMENDED (23 retx / 5 seeds — AWGN only)
 - 1-CW ACK frames: WORKING - control frames use 1 CW (3x faster ACK)
 - Variable-CW frames: WORKING - CONNECT/DISCONNECT use exact CW count (2 at R1/2, 3 at R1/4)
+- OFDM_NARROW DQPSK R1/4 AWGN: WORKING - 100% at SNR=8 (0 retransmissions)
+- OFDM_NARROW DQPSK R1/4 Good fading SNR=8: WORKING - 100% data decode, 93% ACK, all messages delivered via ARQ
 - OFDM_COX: WORKING - DATA phase passes at SNR=20 dB
 - OTFS: EXPERIMENTAL - See OTFS Status section below
 - cli_simulator: FULLY WORKING - all phases pass on AWGN and fading
@@ -300,13 +316,15 @@ make -j4
 | Mode | Sync Method | SNR Range | Max Throughput | CFO Tolerance | Fading |
 |------|-------------|-----------|----------------|---------------|--------|
 | **MC-DPSK** | Dual Chirp | -3 to 10 dB | 938 bps | ±50 Hz | Good |
+| **OFDM_NARROW** | NB Chirp + LTS | 5-10 dB | ~230 bps | ±50 Hz | Good (R1/4) |
 | **OFDM_CHIRP** | Dual Chirp + LTS | 10-17 dB | 3.4 kbps | ±50 Hz | Good (R1/4) |
 | **OFDM_COX** | Schmidl-Cox | 17+ dB | 7.9 kbps | Needs testing | Poor |
 | **OTFS** | Dual Chirp | 15+ dB | ~2 kbps | ±50 Hz | **Poor** (experimental) |
 | **SC-DPSK** | Barker-13 | -8 to -3 dB | 125 bps | N/A | Good |
 
 **Waveform Selection:**
 - Poor HF channels (2ms delay): Use MC-DPSK
+- Low SNR (5-10 dB) with good/moderate fading: Use OFDM_NARROW (~103 bps R1/4, ~230 bps R1/2)
 - Moderate/Good HF: Use OFDM_CHIRP (10-17 dB) or OFDM_COX (17+ dB)
 - Very low SNR: Use SC-DPSK or MC-DPSK
 - **DO NOT use OTFS on fading channels** - it's experimental and underperforms OFDM_CHIRP

docs/CHANGELOG.md

@@ -10,6 +10,64 @@ This log tracks all bug fixes and behavioral changes to prevent re-doing work du
 
 ---
 
+## 2026-03-01: Add OFDM_NARROW 500 Hz narrowband mode
+
+**What was added:**
+New 500 Hz narrowband OFDM mode (OFDM_NARROW) for reliable operation at much lower SNR than wideband.
+Provides ~7.5 dB noise bandwidth advantage, enabling communication at SNR 5-10 dB where wideband fails.
+
+**Key parameters:**
+- FFT=2048, 21 carriers, 23.4 Hz bin spacing, 492 Hz occupied bandwidth
+- Narrowband chirp: 1250-1750 Hz sweep, 1000ms duration
+- Narrowband MC-DPSK handshake: 4 carriers @ 1300-1700 Hz
+- Symbol duration: 46.7ms (2240 samples), CP=192 samples (MEDIUM)
+- ARQ: window=1 (stop-and-wait), timeout ~7.16s
+- Pilots: 0 for R1/4 (21 data carriers), 3 for R1/2+ (18 data carriers)
+
+**Files changed:**
+- `include/ultra/types.hpp` - BandwidthMode enum, chirp fields in ModemConfig, narrowband presets
+- `src/protocol/frame_v2.hpp/.cpp` - WaveformMode::OFDM_NARROW (0x06), isOFDMMode() helper
+- `src/psk/multi_carrier_dpsk.hpp` - mc_dpsk_presets::narrowband() (4 carriers, 1300-1700 Hz)
+- `src/waveform/ofdm_chirp_waveform.hpp/.cpp` - Config-driven chirp parameters, mode_ field
+- `src/waveform/waveform_factory.hpp/.cpp` - OFDM_NARROW creation, createNarrowbandMCDPSK()
+- `src/protocol/waveform_selection.hpp` - SNR 5-10 recommends OFDM_NARROW
+- `src/gui/modem/streaming_decoder.cpp` - Dual-listen (wideband + narrowband chirps), narrowband LTS thresholds
+- `src/gui/modem/streaming_encoder.hpp/.cpp` - narrowband_control_ flag, narrowband MC-DPSK persistence
+- `src/gui/modem/modem_engine.cpp` - bandwidth_mode_ propagation, OFDM_NARROW in mode checks
+- `src/protocol/connection.cpp/.cpp` - isOFDMMode() throughout, OFDM_NARROW timing
+- `tools/cli_simulator.cpp` - --waveform ofdm_narrow, dual-listen, extended narrowband timeouts
+- `src/main.cpp`, `src/gui/app.cpp` - CLI and GUI support
+
+**Key design decisions:**
+1. Dual-listen: RX always listens for both wideband and narrowband chirps when idle
+2. Narrowband chirp auto-identifies the mode — no manual pre-agreement needed
+3. narrowband_control_ flag persists across encoder mode switches during handshake
+4. LTS threshold lowered to 0.50 for narrowband (21 carriers produce ~0.71 correlation vs 59-carrier ~0.95)
+5. Legacy (wide-only) stations won't detect narrowband chirps → caller sees normal PING timeout
+
+**Verification:**
+```
+# AWGN
+./build/cli_simulator --snr 8 --waveform ofdm_narrow --rate r1_4 --test
+# → TEST PASSED: 100% frame success, 0 retransmissions
+
+# Good fading
+./build/cli_simulator --snr 8 --fading good --waveform ofdm_narrow --rate r1_4 --test
+# → TEST PASSED: 100% RX frame success, 92.9% TX (ACK loss), all 7 messages delivered via ARQ
+
+# Wideband regression
+./build/cli_simulator --snr 15 --fading good --rate r1_4 --test
+# → TEST PASSED: 100% frame success, 0 retransmissions (no regression)
+```
+
+**Performance:**
+| Condition | Rate | Frame Success | Throughput |
+|-----------|------|--------------|------------|
+| AWGN SNR=8 | R1/4 | 100% | ~103 bps |
+| Good fading SNR=8 | R1/4 | 100% (data), 93% (ACK) | ~60 bps (with retx) |
+
+---
+
 ## 2026-02-11: Alpha gate harness + OFDM SR-ARQ window stabilization
 
 **What was broken:**

include/ultra/types.hpp

@@ -139,13 +139,40 @@ struct PilotConfig {
         return total_carriers - num_pilots;
     }
 
-    // Create pilot config for a given code rate (59 carriers)
-    // R1/4: 0 pilots, max data, LDPC handles fading
-    // R1/2, R2/3: 6 pilots every ~10 carriers for per-symbol tracking
-    // R3/4: 4 pilots every ~15 carriers for light fading/AWGN
+    // Create pilot config for a given code rate
+    // For wideband (59 carriers):
+    //   R1/4: 0 pilots, max data, LDPC handles fading
+    //   R1/2, R2/3: 6 pilots every ~10 carriers for per-symbol tracking
+    //   R3/4: 4 pilots every ~15 carriers for light fading/AWGN
+    // For narrowband (≤25 carriers):
+    //   R1/4: 0 pilots (all 21 carriers are data)
+    //   R1/2+: 3 pilots at {0, N/3, 2N/3} (18 data carriers)
     static PilotConfig forCodeRate(CodeRate rate, int num_carriers = 59) {
         PilotConfig cfg;
 
+        // Narrowband: fewer carriers need different pilot layout
+        if (num_carriers <= 25) {
+            switch (rate) {
+                case CodeRate::R1_4:
+                case CodeRate::R1_3:
+                default:
+                    // 0 pilots - all carriers data, LDPC handles fading
+                    cfg.num_pilots = 0;
+                    cfg.pilot_indices.clear();
+                    break;
+
+                case CodeRate::R1_2:
+                case CodeRate::R2_3:
+                case CodeRate::R3_4:
+                    // 3 pilots evenly spaced across narrowband carriers
+                    cfg.num_pilots = 3;
+                    cfg.pilot_indices = {0, num_carriers / 3, 2 * num_carriers / 3};
+                    break;
+            }
+            return cfg;
+        }
+
+        // Wideband (59 carriers)
         switch (rate) {
             case CodeRate::R3_4:
                 // 4 pilots for light fading/AWGN - every 15th carrier
@@ -181,6 +208,12 @@ struct PilotConfig {
     }
 };
 
+// Bandwidth mode for narrowband vs wideband operation
+enum class BandwidthMode : uint8_t {
+    WIDE = 0,    // Standard 2.8 kHz bandwidth (59 carriers)
+    NARROW = 1,  // 500 Hz narrowband (21 carriers, FFT=2048)
+};
+
 // Channel quality estimate
 struct ChannelQuality {
     float snr_db;           // Estimated SNR in dB
@@ -234,6 +267,12 @@ struct ModemConfig {
     // Default 40x gives RMS ~0.4, matching chirp amplitude ~0.5
     float output_scale = 40.0f;
 
+    // Chirp sync parameters (wideband defaults, backward compatible)
+    // Narrowband mode overrides these to 1250-1750 Hz @ 1000ms
+    float chirp_f_start = 300.0f;       // Chirp start frequency (Hz)
+    float chirp_f_end = 2700.0f;        // Chirp end frequency (Hz)
+    float chirp_duration_ms = 500.0f;   // Chirp duration (ms)
+
     // Simulation: TX carrier frequency offset (Hz)
     // Simulates radio tuning error - shifts ALL frequencies by this amount
     // Default 0 = no CFO. Set to e.g. ±20 Hz for testing CFO tolerance.
@@ -384,6 +423,39 @@ inline ModemConfig high_speed() {
     return cfg;
 }
 
+// Narrowband OFDM: 500 Hz bandwidth, FFT=2048, 21 carriers
+// 7.5 dB noise bandwidth advantage over wideband (2.8 kHz)
+// For low-SNR conditions (3-10 dB) where wideband doesn't work
+inline ModemConfig narrowbandOFDM() {
+    ModemConfig cfg;
+    cfg.fft_size = 2048;                    // 23.4 Hz bin spacing
+    cfg.num_carriers = 21;                  // 492 Hz occupied bandwidth
+    cfg.sample_rate = 48000;
+    cfg.center_freq = 1500;
+    cfg.cp_mode = CyclicPrefixMode::MEDIUM; // 192 samples = 4.0ms at 2048 FFT
+    cfg.modulation = Modulation::DQPSK;     // Differential for fading
+    cfg.code_rate = CodeRate::R1_4;         // Most robust
+    cfg.use_pilots = true;
+    cfg.pilot_spacing = 10;                 // Will be adjusted by PilotConfig
+    cfg.chirp_f_start = 1250.0f;            // Narrowband chirp: 1250-1750 Hz
+    cfg.chirp_f_end = 1750.0f;
+    cfg.chirp_duration_ms = 1000.0f;        // 1000ms for processing gain
+    cfg.speed_profile = SpeedProfile::CONSERVATIVE;
+    return cfg;
+}
+
+// Narrowband MC-DPSK: 4 carriers @ 1300-1700 Hz
+// Used for PING/PONG/CONNECT handshake in narrowband sessions
+inline ModemConfig narrowbandMCDPSK() {
+    ModemConfig cfg;
+    cfg.sample_rate = 48000;
+    cfg.center_freq = 1500;
+    cfg.chirp_f_start = 1250.0f;            // Narrowband chirp
+    cfg.chirp_f_end = 1750.0f;
+    cfg.chirp_duration_ms = 1000.0f;
+    return cfg;
+}
+
 // Get config for given speed profile
 inline ModemConfig forProfile(SpeedProfile profile) {
     switch (profile) {

src/gui/app.cpp

@@ -192,6 +192,7 @@ static const char* waveformDisplayName(protocol::WaveformMode mode) {
         case protocol::WaveformMode::MFSK: return "MFSK";
         case protocol::WaveformMode::OTFS_EQ:
         case protocol::WaveformMode::OTFS_RAW: return "OTFS";
+        case protocol::WaveformMode::OFDM_NARROW: return "OFDM Narrow";
         case protocol::WaveformMode::OFDM_CHIRP:
         case protocol::WaveformMode::OFDM_COX:
         default: return "OFDM";
@@ -563,6 +564,7 @@ App::App(const Options& opts) : options_(opts), sim_ui_visible_(opts.enable_sim)
             case protocol::WaveformMode::OTFS_EQ: mode_name = "OTFS"; break;
             case protocol::WaveformMode::OTFS_RAW: mode_name = "OTFS"; break;
             case protocol::WaveformMode::OFDM_CHIRP: mode_name = "OFDM"; break;
+            case protocol::WaveformMode::OFDM_NARROW: mode_name = "OFDM Narrow"; break;
             case protocol::WaveformMode::OFDM_COX: mode_name = "OFDM"; break;
             default: mode_name = "OFDM"; break;
         }

src/gui/modem/modem_engine.cpp

@@ -94,6 +94,13 @@ ModemEngine::ModemEngine() {
 
     startupTrace("ModemEngine", "decoder-set-ping-callback-enter");
     streaming_decoder_->setPingCallback([this](float snr_db, float cfo_hz) {
+        // If narrowband chirp detected, switch control waveform for PONG/CONNECT_ACK
+        if (streaming_decoder_->getDetectedBandwidth() == BandwidthMode::NARROW) {
+            if (streaming_encoder_) {
+                streaming_encoder_->setNarrowbandControl(true);
+            }
+            LOG_MODEM(INFO, "Narrowband chirp detected, switching control waveform");
+        }
         if (ping_received_callback_) {
             ping_received_callback_(snr_db);
         }
@@ -165,9 +172,7 @@ void ModemEngine::setConfig(const ModemConfig& config) {
 
     // Propagate OFDM config to StreamingDecoder for OFDM modes
     // This allows custom FFT/carrier settings (like NVIS mode with 1024 FFT)
-    if (streaming_decoder_ &&
-        (waveform_mode_ == protocol::WaveformMode::OFDM_COX ||
-         waveform_mode_ == protocol::WaveformMode::OFDM_CHIRP)) {
+    if (streaming_decoder_ && protocol::isOFDMMode(waveform_mode_)) {
         streaming_decoder_->setOFDMConfig(config_);
         LOG_MODEM(INFO, "setConfig: StreamingDecoder OFDM config updated (FFT=%d, carriers=%d)",
                   config_.fft_size, config_.num_carriers);
@@ -268,8 +273,7 @@ std::vector<float> ModemEngine::transmit(const Bytes& data) {
         LOG_MODEM(INFO, "[%s] TX: Connected+handshake -> waveform_mode_=%d",
                   log_prefix_.c_str(), static_cast<int>(tx_waveform_mode));
     }
-    bool is_ofdm = (tx_waveform_mode == protocol::WaveformMode::OFDM_CHIRP ||
-                    tx_waveform_mode == protocol::WaveformMode::OFDM_COX);
+    bool is_ofdm = protocol::isOFDMMode(tx_waveform_mode);
 
     // ========================================================================
     // 2. Determine modulation and code rate

src/gui/modem/modem_mode.cpp

@@ -50,18 +50,15 @@ void ModemEngine::setWaveformMode(protocol::WaveformMode mode) {
     // When disconnected, always use MC_DPSK for PING detection (chirp-based sync)
     if (streaming_decoder_) {
         protocol::WaveformMode decoder_mode = connected_ ? mode : protocol::WaveformMode::MC_DPSK;
-        if (connected_ &&
-            (mode == protocol::WaveformMode::OFDM_COX ||
-             mode == protocol::WaveformMode::OFDM_CHIRP)) {
+        if (connected_ && protocol::isOFDMMode(mode)) {
             streaming_decoder_->setConnectedOFDMMode(mode, config_, data_modulation_, data_code_rate_);
             LOG_MODEM(INFO, "setWaveformMode: StreamingDecoder connected OFDM config set (FFT=%d, carriers=%d)",
                       config_.fft_size, config_.num_carriers);
         } else {
             streaming_decoder_->setMode(decoder_mode, connected_);
 
             // For OFDM modes, propagate the current config (for custom FFT/carriers like NVIS mode)
-            if (mode == protocol::WaveformMode::OFDM_COX ||
-                mode == protocol::WaveformMode::OFDM_CHIRP) {
+            if (protocol::isOFDMMode(mode)) {
                 streaming_decoder_->setOFDMConfig(config_);
                 LOG_MODEM(INFO, "setWaveformMode: StreamingDecoder OFDM config set (FFT=%d, carriers=%d)",
                           config_.fft_size, config_.num_carriers);
@@ -72,8 +69,7 @@ void ModemEngine::setWaveformMode(protocol::WaveformMode mode) {
     // Update StreamingEncoder to match
     if (streaming_encoder_) {
         streaming_encoder_->setMode(mode);
-        if (mode == protocol::WaveformMode::OFDM_COX ||
-            mode == protocol::WaveformMode::OFDM_CHIRP) {
+        if (protocol::isOFDMMode(mode)) {
             streaming_encoder_->setOFDMConfig(config_);
         }
     }
@@ -91,6 +87,11 @@ void ModemEngine::setWaveformMode(protocol::WaveformMode mode) {
                       config_.num_carriers);
             break;
 
+        case protocol::WaveformMode::OFDM_NARROW:
+            LOG_MODEM(INFO, "OFDM_NARROW mode active: %d carriers, 500 Hz narrowband",
+                      config_.num_carriers);
+            break;
+
         case protocol::WaveformMode::OFDM_COX:
         default:
             LOG_MODEM(INFO, "OFDM mode active: %d carriers, %s",
@@ -147,8 +148,7 @@ void ModemEngine::setConnected(bool connected) {
             streaming_decoder_->setMode(waveform_mode_, true);  // true = connected
 
             // For OFDM modes, propagate the correct config (with proper pilot settings)
-            if (waveform_mode_ == protocol::WaveformMode::OFDM_COX ||
-                waveform_mode_ == protocol::WaveformMode::OFDM_CHIRP) {
+            if (protocol::isOFDMMode(waveform_mode_)) {
                 streaming_decoder_->setConnectedOFDMMode(
                     waveform_mode_, config_, data_modulation_, data_code_rate_);
             }
@@ -164,8 +164,7 @@ void ModemEngine::setConnected(bool connected) {
         // Update StreamingEncoder for connected state
         if (streaming_encoder_) {
             streaming_encoder_->setMode(waveform_mode_);
-            if (waveform_mode_ == protocol::WaveformMode::OFDM_COX ||
-                waveform_mode_ == protocol::WaveformMode::OFDM_CHIRP) {
+            if (protocol::isOFDMMode(waveform_mode_)) {
                 streaming_encoder_->setOFDMConfig(config_);
                 streaming_encoder_->setDataMode(data_modulation_, data_code_rate_);
             }
@@ -232,9 +231,7 @@ void ModemEngine::setDataMode(Modulation mod, CodeRate rate) {
     // Update StreamingDecoder's waveform configuration
     // CRITICAL: Set OFDM config BEFORE setDataMode so decoder has correct pilot layout
     if (streaming_decoder_) {
-        if (connected_ &&
-            (waveform_mode_ == protocol::WaveformMode::OFDM_CHIRP ||
-             waveform_mode_ == protocol::WaveformMode::OFDM_COX)) {
+        if (connected_ && protocol::isOFDMMode(waveform_mode_)) {
             streaming_decoder_->setConnectedOFDMMode(
                 waveform_mode_, config_, mod, rate);
         } else {
@@ -350,6 +347,7 @@ fec::CodecType ModemEngine::getCodecForWaveform(protocol::WaveformMode mode) {
             return fec::CodecType::LDPC;
 
         case protocol::WaveformMode::OFDM_CHIRP:
+        case protocol::WaveformMode::OFDM_NARROW:
         case protocol::WaveformMode::OFDM_COX:
         default:
             return fec::CodecType::LDPC;