wefax: auto-align carrier frequencies for usb tuning

routes/wefax.py

@@ -11,11 +11,17 @@ import queue
 from flask import Blueprint, Response, jsonify, request, send_file
 
 import app as app_module
-from utils.logging import get_logger
-from utils.sse import sse_stream_fanout
-from utils.validation import validate_frequency
-from utils.wefax import get_wefax_decoder
-from utils.wefax_stations import get_current_broadcasts, get_station, load_stations
+from utils.logging import get_logger
+from utils.sse import sse_stream_fanout
+from utils.validation import validate_frequency
+from utils.wefax import get_wefax_decoder
+from utils.wefax_stations import (
+    WEFAX_USB_ALIGNMENT_OFFSET_KHZ,
+    get_current_broadcasts,
+    get_station,
+    load_stations,
+    resolve_tuning_frequency_khz,
+)
 
 logger = get_logger('intercept.wefax')
 
@@ -69,15 +75,16 @@ def start_decoder():
     """Start WeFax decoder.
 
     JSON body:
-        {
-            "frequency_khz": 4298,
-            "station": "NOJ",
-            "device": 0,
-            "gain": 40,
-            "ioc": 576,
-            "lpm": 120,
-            "direct_sampling": true
-        }
+        {
+            "frequency_khz": 4298,
+            "station": "NOJ",
+            "device": 0,
+            "gain": 40,
+            "ioc": 576,
+            "lpm": 120,
+            "direct_sampling": true,
+            "frequency_reference": "auto"  // auto, carrier, or dial
+        }
     """
     decoder = get_wefax_decoder()
 
@@ -115,17 +122,36 @@ def start_decoder():
             'message': f'Invalid frequency: {e}',
         }), 400
 
-    station = str(data.get('station', '')).strip()
-    device_index = data.get('device', 0)
-    gain = float(data.get('gain', 40.0))
-    ioc = int(data.get('ioc', 576))
-    lpm = int(data.get('lpm', 120))
-    direct_sampling = bool(data.get('direct_sampling', True))
-
-    # Validate IOC and LPM
-    if ioc not in (288, 576):
-        return jsonify({
-            'status': 'error',
+    station = str(data.get('station', '')).strip()
+    device_index = data.get('device', 0)
+    gain = float(data.get('gain', 40.0))
+    ioc = int(data.get('ioc', 576))
+    lpm = int(data.get('lpm', 120))
+    direct_sampling = bool(data.get('direct_sampling', True))
+    frequency_reference = str(data.get('frequency_reference', 'auto')).strip().lower()
+    if not frequency_reference:
+        frequency_reference = 'auto'
+
+    try:
+        tuned_frequency_khz, resolved_reference, usb_offset_applied = (
+            resolve_tuning_frequency_khz(
+                listed_frequency_khz=frequency_khz,
+                station_callsign=station,
+                frequency_reference=frequency_reference,
+            )
+        )
+        tuned_mhz = tuned_frequency_khz / 1000.0
+        validate_frequency(tuned_mhz, min_mhz=2.0, max_mhz=30.0)
+    except ValueError as e:
+        return jsonify({
+            'status': 'error',
+            'message': f'Invalid frequency settings: {e}',
+        }), 400
+
+    # Validate IOC and LPM
+    if ioc not in (288, 576):
+        return jsonify({
+            'status': 'error',
             'message': 'IOC must be 288 or 576',
         }), 400
 
@@ -146,28 +172,34 @@ def start_decoder():
             'message': error,
         }), 409
 
-    # Set callback and start
-    decoder.set_callback(_progress_callback)
-    success = decoder.start(
-        frequency_khz=frequency_khz,
-        station=station,
-        device_index=device_int,
-        gain=gain,
-        ioc=ioc,
-        lpm=lpm,
+    # Set callback and start
+    decoder.set_callback(_progress_callback)
+    success = decoder.start(
+        frequency_khz=tuned_frequency_khz,
+        station=station,
+        device_index=device_int,
+        gain=gain,
+        ioc=ioc,
+        lpm=lpm,
         direct_sampling=direct_sampling,
     )
 
     if success:
         wefax_active_device = device_int
-        return jsonify({
-            'status': 'started',
-            'frequency_khz': frequency_khz,
-            'station': station,
-            'ioc': ioc,
-            'lpm': lpm,
-            'device': device_int,
-        })
+        return jsonify({
+            'status': 'started',
+            'frequency_khz': frequency_khz,
+            'tuned_frequency_khz': tuned_frequency_khz,
+            'frequency_reference': resolved_reference,
+            'usb_offset_applied': usb_offset_applied,
+            'usb_offset_khz': (
+                WEFAX_USB_ALIGNMENT_OFFSET_KHZ if usb_offset_applied else 0.0
+            ),
+            'station': station,
+            'ioc': ioc,
+            'lpm': lpm,
+            'device': device_int,
+        })
     else:
         app_module.release_sdr_device(device_int)
         return jsonify({
@@ -290,15 +322,16 @@ def enable_schedule():
     """Enable auto-scheduling of WeFax broadcast captures.
 
     JSON body:
-        {
-            "station": "NOJ",
-            "frequency_khz": 4298,
-            "device": 0,
-            "gain": 40,
-            "ioc": 576,
-            "lpm": 120,
-            "direct_sampling": true
-        }
+        {
+            "station": "NOJ",
+            "frequency_khz": 4298,
+            "device": 0,
+            "gain": 40,
+            "ioc": 576,
+            "lpm": 120,
+            "direct_sampling": true,
+            "frequency_reference": "auto"  // auto, carrier, or dial
+        }
 
     Returns:
         JSON with scheduler status.
@@ -332,32 +365,61 @@ def enable_schedule():
         }), 400
 
     device = int(data.get('device', 0))
-    gain = float(data.get('gain', 40.0))
-    ioc = int(data.get('ioc', 576))
-    lpm = int(data.get('lpm', 120))
-    direct_sampling = bool(data.get('direct_sampling', True))
-
-    scheduler = get_wefax_scheduler()
-    scheduler.set_callbacks(_progress_callback, _scheduler_event_callback)
-
-    try:
-        result = scheduler.enable(
-            station=station,
-            frequency_khz=frequency_khz,
-            device=device,
-            gain=gain,
-            ioc=ioc,
-            lpm=lpm,
-            direct_sampling=direct_sampling,
+    gain = float(data.get('gain', 40.0))
+    ioc = int(data.get('ioc', 576))
+    lpm = int(data.get('lpm', 120))
+    direct_sampling = bool(data.get('direct_sampling', True))
+    frequency_reference = str(data.get('frequency_reference', 'auto')).strip().lower()
+    if not frequency_reference:
+        frequency_reference = 'auto'
+
+    try:
+        tuned_frequency_khz, resolved_reference, usb_offset_applied = (
+            resolve_tuning_frequency_khz(
+                listed_frequency_khz=frequency_khz,
+                station_callsign=station,
+                frequency_reference=frequency_reference,
+            )
+        )
+        tuned_mhz = tuned_frequency_khz / 1000.0
+        validate_frequency(tuned_mhz, min_mhz=2.0, max_mhz=30.0)
+    except ValueError as e:
+        return jsonify({
+            'status': 'error',
+            'message': f'Invalid frequency settings: {e}',
+        }), 400
+
+    scheduler = get_wefax_scheduler()
+    scheduler.set_callbacks(_progress_callback, _scheduler_event_callback)
+
+    try:
+        result = scheduler.enable(
+            station=station,
+            frequency_khz=tuned_frequency_khz,
+            device=device,
+            gain=gain,
+            ioc=ioc,
+            lpm=lpm,
+            direct_sampling=direct_sampling,
         )
     except Exception:
         logger.exception("Failed to enable WeFax scheduler")
-        return jsonify({
-            'status': 'error',
-            'message': 'Failed to enable scheduler',
-        }), 500
-
-    return jsonify({'status': 'ok', **result})
+        return jsonify({
+            'status': 'error',
+            'message': 'Failed to enable scheduler',
+        }), 500
+
+    return jsonify({
+        'status': 'ok',
+        **result,
+        'frequency_khz': frequency_khz,
+        'tuned_frequency_khz': tuned_frequency_khz,
+        'frequency_reference': resolved_reference,
+        'usb_offset_applied': usb_offset_applied,
+        'usb_offset_khz': (
+            WEFAX_USB_ALIGNMENT_OFFSET_KHZ if usb_offset_applied else 0.0
+        ),
+    })
 
 
 @wefax_bp.route('/schedule/disable', methods=['POST'])