rdsclock 0.2.2__tar.gz → 0.4.0__tar.gz

{rdsclock-0.2.2 → rdsclock-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdsclock
-Version: 0.2.2
+Version: 0.4.0
 Summary: Passive RDS Clock-Time receiver for FM via RTL-SDR, with multi-source consensus for GPS-denied environments
 Author-email: Mateusz Klatt <mateusz@klatt.ie>
 License-Expression: Apache-2.0
@@ -221,11 +221,17 @@ for environments where:
 4. **RF fingerprinting** — per-station features (CFO, RSSI, PI) are
    recorded for later analysis. Automated shift detection is on the
    roadmap.
-5. **Holdover** — between Clock-Time messages the receiver
+5. **Receive timestamping** — live captures anchor decoded Group 4A
+   receipt to the host monotonic clock and correct the bit-rate estimate
+   from the 19 kHz pilot tone. With healthy NTP this is a roughly
+   30-80 ms UTC claim; without internet, a 3+ station field demo should
+   be treated as roughly 100-250 ms. Hardware-grade timing requires a
+   hardware time source.
+6. **Holdover** — between Clock-Time messages the receiver
    extrapolates UTC from a local monotonic clock disciplined by an
    estimated ppm drift. Uncertainty grows linearly with the age of
    the most recent CT.
-6. **Operator display** — `UTC 2026-05-17 04:23:18  ±2s  N=3  trust=HIGH`.
+7. **Operator display** — `UTC 2026-05-17 04:23:18  ±2s  N=3  trust=HIGH`.
 
 ### Quick Run
 
@@ -267,12 +273,15 @@ the local antenna picks up.
 
 ## Status
 
-- **0.2.2** — current release. Operator-facing polish: 250 kS/s SDR
-  captures can now play at 48 kHz audio via rational resampling, and
-  Programme Service names are displayed only after validation so
-  dynamic-PS stations do not show mixed scrolling fragments. Decoder
-  group counts and PI codes remain locked to the 0.2.1 baseline.
-  Pre-1.0; the CLI and on-disk formats may still change.
+- **0.4.0** — current release. Decoded Clock-Time values now include
+  optional receive timestamp metadata on the host monotonic clock, using
+  group bit positions plus pilot-derived bit-rate drift correction. A
+  parallel sub-second consensus path can learn per-station Group 4A
+  transmit latency across multiple stations. Expected UTC precision is
+  about 30-80 ms with a healthy NTP-disciplined host and about
+  100-250 ms in a 3+ station field demo without internet; this is not
+  a hardware-time-source claim. Pre-1.0; the CLI and on-disk formats may
+  still change.
 - 240+ tests including a real-IQ regression backed by a 6 s capture
   of Polskie Radio Trójka 98.8 from Warsaw; line coverage **100 %**
   (tracked by SonarCloud).

{rdsclock-0.2.2 → rdsclock-0.4.0}/README.md

@@ -183,11 +183,17 @@ for environments where:
 4. **RF fingerprinting** — per-station features (CFO, RSSI, PI) are
    recorded for later analysis. Automated shift detection is on the
    roadmap.
-5. **Holdover** — between Clock-Time messages the receiver
+5. **Receive timestamping** — live captures anchor decoded Group 4A
+   receipt to the host monotonic clock and correct the bit-rate estimate
+   from the 19 kHz pilot tone. With healthy NTP this is a roughly
+   30-80 ms UTC claim; without internet, a 3+ station field demo should
+   be treated as roughly 100-250 ms. Hardware-grade timing requires a
+   hardware time source.
+6. **Holdover** — between Clock-Time messages the receiver
    extrapolates UTC from a local monotonic clock disciplined by an
    estimated ppm drift. Uncertainty grows linearly with the age of
    the most recent CT.
-6. **Operator display** — `UTC 2026-05-17 04:23:18  ±2s  N=3  trust=HIGH`.
+7. **Operator display** — `UTC 2026-05-17 04:23:18  ±2s  N=3  trust=HIGH`.
 
 ### Quick Run
 
@@ -229,12 +235,15 @@ the local antenna picks up.
 
 ## Status
 
-- **0.2.2** — current release. Operator-facing polish: 250 kS/s SDR
-  captures can now play at 48 kHz audio via rational resampling, and
-  Programme Service names are displayed only after validation so
-  dynamic-PS stations do not show mixed scrolling fragments. Decoder
-  group counts and PI codes remain locked to the 0.2.1 baseline.
-  Pre-1.0; the CLI and on-disk formats may still change.
+- **0.4.0** — current release. Decoded Clock-Time values now include
+  optional receive timestamp metadata on the host monotonic clock, using
+  group bit positions plus pilot-derived bit-rate drift correction. A
+  parallel sub-second consensus path can learn per-station Group 4A
+  transmit latency across multiple stations. Expected UTC precision is
+  about 30-80 ms with a healthy NTP-disciplined host and about
+  100-250 ms in a 3+ station field demo without internet; this is not
+  a hardware-time-source claim. Pre-1.0; the CLI and on-disk formats may
+  still change.
 - 240+ tests including a real-IQ regression backed by a 6 s capture
   of Polskie Radio Trójka 98.8 from Warsaw; line coverage **100 %**
   (tracked by SonarCloud).

{rdsclock-0.2.2 → rdsclock-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rdsclock"
-version = "0.2.2"
+version = "0.4.0"
 description = "Passive RDS Clock-Time receiver for FM via RTL-SDR, with multi-source consensus for GPS-denied environments"
 readme = "README.md"
 requires-python = ">=3.12"

{rdsclock-0.2.2 → rdsclock-0.4.0}/src/rdsclock/__init__.py

@@ -19,4 +19,4 @@ Modules:
                      scan / recon / demo.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"

{rdsclock-0.2.2 → rdsclock-0.4.0}/src/rdsclock/cli.py

@@ -72,6 +72,8 @@ def _print_station(info: StationInfo) -> None:
         ct = info.latest_clock
         if ct is not None:
             print(f"  ClockTime: {ct}  → local: {ct.local.strftime('%Y-%m-%d %H:%M %Z')}")
+            if ct.rx_monotonic_ns is not None:
+                print(f"  rx_monotonic: {ct.rx_monotonic_ns:_d} ns (host time at receipt)")
             print(f"  CT count:  {len(info.clock_times)}")
     else:
         print("  ClockTime: NONE (station not transmitting Group 4A or sending dummy data)")
@@ -80,6 +82,16 @@ def _print_station(info: StationInfo) -> None:
         print(f"  Groups:    {dict(items)}")
 
 
+def _capture_start_iso_to_ns(value: str | None) -> int | None:
+    if value is None:
+        return None
+    normalized = value.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(normalized)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return int(dt.timestamp() * 1_000_000_000)
+
+
 # ---------- generate ----------
 
 
@@ -132,6 +144,7 @@ def cmd_decode(args: argparse.Namespace) -> int:
             print(f"  ▸ {msg}")
 
     start = time.time()
+    capture_start_ns = _capture_start_iso_to_ns(args.capture_start_iso)
     if args.carrier_hz is not None:
         try:
             iq = dsp.read_iq_complex64(args.file)
@@ -139,15 +152,25 @@ def cmd_decode(args: argparse.Namespace) -> int:
                 iq = dsp.read_iq_u8(args.file)
         except Exception:
             iq = dsp.read_iq_u8(args.file)
-        result = decode_iq(
-            iq,
-            fs=args.fs,
-            carrier_hz=args.carrier_hz,
-            auto_carrier=False,
-            progress=progress,
-        )
+        decode_kwargs = {
+            "fs": args.fs,
+            "carrier_hz": args.carrier_hz,
+            "auto_carrier": False,
+            "progress": progress,
+        }
+        if capture_start_ns is not None:
+            decode_kwargs["capture_start_monotonic_ns"] = capture_start_ns
+        result = decode_iq(iq, **decode_kwargs)
     else:
-        result = decode_file(args.file, fs=args.fs, progress=progress)
+        if capture_start_ns is None:
+            result = decode_file(args.file, fs=args.fs, progress=progress)
+        else:
+            result = decode_file(
+                args.file,
+                fs=args.fs,
+                progress=progress,
+                capture_start_monotonic_ns=capture_start_ns,
+            )
     elapsed = time.time() - start
 
     print(f"\n=== {args.file} ===")
@@ -176,6 +199,7 @@ def cmd_live(args: argparse.Namespace) -> int:
         _configure_gain(client, args.gain)
 
         print(f"Recording {args.duration}s @ {args.freq} MHz …")
+        capture_start_ns = time.monotonic_ns()
         iq = client.record(args.duration, args.fs)
         print(
             f"  samples: {len(iq)}  power: "
@@ -192,6 +216,7 @@ def cmd_live(args: argparse.Namespace) -> int:
         carrier_hz=args.carrier_hz,
         auto_carrier=args.carrier_hz is None,
         progress=(lambda m: print(f"  ▸ {m}")) if args.verbose else None,
+        capture_start_monotonic_ns=capture_start_ns,
     )
     print(
         f"\n  Groups: {result.n_groups}  Bits: {result.n_bits}  Δf={result.freq_offset_hz:+.1f} Hz"
@@ -652,6 +677,12 @@ def build_parser() -> argparse.ArgumentParser:
         help="Override the RDS subcarrier frequency",
     )
     pd.add_argument("-v", "--verbose", action="store_true", help="Print pipeline steps")
+    pd.add_argument(
+        "--capture-start-iso",
+        default=None,
+        dest="capture_start_iso",
+        help="Optional ISO timestamp for the start of an offline capture",
+    )
     pd.set_defaults(func=cmd_decode)
 
     # live

{rdsclock-0.2.2 → rdsclock-0.4.0}/src/rdsclock/decoder.py

@@ -6,12 +6,15 @@ function accepts an optional ``progress`` callback.
 
 import os
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 import numpy as np
 
 from . import dsp
-from .rds_blocks import find_groups_in_bitstream
+from .rds_blocks import (
+    GROUP_BITS,
+    _find_groups_in_bitstream_with_counts_and_positions,
+)
 from .rds_clock import ClockTime
 from .rds_groups import StationInfo, parse_groups
 
@@ -25,6 +28,13 @@ class DecodeResult:
     n_bits: int
     freq_offset_hz: float
     symbol_offset: int
+    n_groups_clean: int = -1
+    n_groups_corrected: int = 0
+    group_bit_positions: list[int] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.n_groups_clean < 0:
+            self.n_groups_clean = self.n_groups
 
     @property
     def clock_times(self) -> list[ClockTime]:
@@ -40,6 +50,7 @@ def decode_iq(
     costas_beta: float = 0.005,
     auto_carrier: bool = True,
     progress: Callable[[str], None] | None = None,
+    capture_start_monotonic_ns: int | None = None,
 ) -> DecodeResult:
     """Run the full pipeline. Returns a ``DecodeResult`` aggregating groups.
 
@@ -57,6 +68,9 @@ def decode_iq(
 
     emit("fm_demod")
     fm = dsp.fm_demod(iq)
+    bit_rate_drift = (
+        dsp.measure_bit_rate_drift(fm, fs) if capture_start_monotonic_ns is not None else None
+    )
 
     if carrier_hz is None:
         if auto_carrier:
@@ -93,6 +107,9 @@ def decode_iq(
     emit(f"biphase matched filter + offset search (sps {sps})")
     matched = dsp.biphase_matched_filter(rds_sync, sps_bit=sps)
     best_groups: list[bytearray] | None = None
+    best_positions: list[int] | None = None
+    best_groups_clean = 0
+    best_groups_corrected = 0
     best_bits: np.ndarray | None = None
     variant_used = "biphase/none"
     sym_offset = 0
@@ -101,41 +118,78 @@ def decode_iq(
         if len(sampled) < 100:
             continue
         bits_candidate = dsp.bits_from_symbols_diff(sampled)
-        groups_candidate, variant_candidate = _best_variant_groups(bits_candidate)
-        if best_groups is None or len(groups_candidate) > len(best_groups):
+        (
+            groups_candidate,
+            positions_candidate,
+            variant_candidate,
+            groups_clean_candidate,
+            groups_corrected_candidate,
+        ) = _best_variant_groups(bits_candidate)
+        if best_groups is None or _group_score(
+            groups_candidate, groups_clean_candidate, groups_corrected_candidate
+        ) > _group_score(best_groups, best_groups_clean, best_groups_corrected):
             best_groups = groups_candidate
+            best_positions = positions_candidate
+            best_groups_clean = groups_clean_candidate
+            best_groups_corrected = groups_corrected_candidate
             best_bits = bits_candidate
             variant_used = f"biphase/off{offset}/{variant_candidate}"
             sym_offset = offset
 
-    if best_groups is None or best_bits is None:
+    if best_groups is None or best_positions is None or best_bits is None:
         # Very short streams may not have enough biphase samples for the
         # offset sweep. Preserve the legacy paths for those callers.
         emit(f"clock recovery fallback: best_offset + mueller_muller (sps {sps})")
         bo_symbols, bo_sym_off = dsp.best_symbol_offset(rds_sync, sps=sps)
         bo_bits = dsp.bits_from_symbols_diff(bo_symbols)
-        bo_groups, bo_variant = _best_variant_groups(bo_bits)
+        bo_groups, bo_positions, bo_variant, bo_groups_clean, bo_groups_corrected = (
+            _best_variant_groups(bo_bits)
+        )
 
         mm_symbols = dsp.clock_recovery_mm(rds_sync, sps=sps)
         mm_bits = dsp.bits_from_symbols_diff(mm_symbols)
-        mm_groups, mm_variant = _best_variant_groups(mm_bits)
+        mm_groups, mm_positions, mm_variant, mm_groups_clean, mm_groups_corrected = (
+            _best_variant_groups(mm_bits)
+        )
 
-        if len(mm_groups) > len(bo_groups):
+        if _group_score(mm_groups, mm_groups_clean, mm_groups_corrected) > _group_score(
+            bo_groups, bo_groups_clean, bo_groups_corrected
+        ):
             groups = mm_groups
+            group_positions = mm_positions
+            groups_clean = mm_groups_clean
+            groups_corrected = mm_groups_corrected
             variant_used = f"mm/{mm_variant}"
             bits = mm_bits
             sym_offset = -1  # MM has no fixed offset, only its mu state
         else:
             groups = bo_groups
+            group_positions = bo_positions
+            groups_clean = bo_groups_clean
+            groups_corrected = bo_groups_corrected
             variant_used = f"bo/{bo_variant}"
             bits = bo_bits
             sym_offset = bo_sym_off
     else:
         groups = best_groups
+        group_positions = best_positions
+        groups_clean = best_groups_clean
+        groups_corrected = best_groups_corrected
         bits = best_bits
 
-    info = parse_groups(groups)
-    emit(f"groups={len(groups)} variant={variant_used} freq_off={freq_off:+.1f} Hz")
+    rx_monotonic_ns_by_group = _rx_monotonic_ns_by_group(
+        capture_start_monotonic_ns,
+        group_positions,
+        bit_rate_drift,
+    )
+    if rx_monotonic_ns_by_group is None:
+        info = parse_groups(groups)
+    else:
+        info = parse_groups(groups, rx_monotonic_ns_by_group=rx_monotonic_ns_by_group)
+    emit(
+        f"groups={len(groups)} clean={groups_clean} corrected={groups_corrected} "
+        f"variant={variant_used} freq_off={freq_off:+.1f} Hz"
+    )
 
     return DecodeResult(
         info=info,
@@ -143,10 +197,19 @@ def decode_iq(
         n_bits=len(bits),
         freq_offset_hz=float(freq_off),
         symbol_offset=sym_offset,
+        n_groups_clean=groups_clean,
+        n_groups_corrected=groups_corrected,
+        group_bit_positions=group_positions,
     )
 
 
-def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], str]:
+def _group_score(
+    groups: list[bytearray], n_groups_clean: int, n_groups_corrected: int
+) -> tuple[int, int, int]:
+    return len(groups), n_groups_clean, -n_groups_corrected
+
+
+def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], list[int], str, int, int]:
     """Try the four bitstream polarity/order variants and return the one
     that yields the most groups.
 
@@ -156,19 +219,49 @@ def _best_variant_groups(bits: np.ndarray) -> tuple[list[bytearray], str]:
     flips symbol order (mainly relevant for short streams).
     """
     candidates = [
-        ("normal", bits),
-        ("inverted", 1 - bits),
-        ("reversed", bits[::-1]),
-        ("inv+rev", (1 - bits)[::-1]),
+        ("normal", bits, False),
+        ("inverted", 1 - bits, False),
+        ("reversed", bits[::-1], True),
+        ("inv+rev", (1 - bits)[::-1], True),
     ]
     best: list[bytearray] = []
+    best_positions: list[int] = []
     best_name = "normal"
-    for name, bstream in candidates:
-        g = find_groups_in_bitstream(np.ascontiguousarray(bstream))
-        if len(g) > len(best):
+    best_clean = 0
+    best_corrected = 0
+    for name, bstream, reversed_axis in candidates:
+        g, positions, n_clean, n_corrected = _find_groups_in_bitstream_with_counts_and_positions(
+            np.ascontiguousarray(bstream), tolerate_single_bit=True
+        )
+        if _group_score(g, n_clean, n_corrected) > _group_score(best, best_clean, best_corrected):
             best = g
+            best_positions = _positions_on_capture_axis(len(bits), positions, reversed_axis)
             best_name = name
-    return best, best_name
+            best_clean = n_clean
+            best_corrected = n_corrected
+    return best, best_positions, best_name, best_clean, best_corrected
+
+
+def _positions_on_capture_axis(n_bits: int, positions: list[int], reversed_axis: bool) -> list[int]:
+    if not reversed_axis:
+        return positions
+    return [n_bits - pos - GROUP_BITS for pos in positions]
+
+
+def _rx_monotonic_ns_by_group(
+    capture_start_monotonic_ns: int | None,
+    group_positions: list[int],
+    bit_rate_drift: dsp.BitRateDrift | None,
+) -> list[int | None] | None:
+    if capture_start_monotonic_ns is None or bit_rate_drift is None:
+        return None
+    bit_rate_hz = bit_rate_drift.bit_rate_hz
+    return [
+        capture_start_monotonic_ns
+        + int((bit_position + GROUP_BITS) / bit_rate_hz * 1e9)
+        + dsp.PIPELINE_GROUP_DELAY_NS
+        for bit_position in group_positions
+    ]
 
 
 def decode_file(
@@ -176,6 +269,7 @@ def decode_file(
     fs: float = dsp.DEFAULT_INPUT_FS,
     progress: Callable[[str], None] | None = None,
     fmt: str | None = None,
+    capture_start_monotonic_ns: int | None = None,
 ) -> DecodeResult:
     """Load an IQ file and decode it.
 
@@ -209,4 +303,11 @@ def decode_file(
 
     if len(iq) == 0:
         raise ValueError(f"empty IQ file: {path}")
-    return decode_iq(iq, fs=fs, progress=progress)
+    if capture_start_monotonic_ns is None:
+        return decode_iq(iq, fs=fs, progress=progress)
+    return decode_iq(
+        iq,
+        fs=fs,
+        progress=progress,
+        capture_start_monotonic_ns=capture_start_monotonic_ns,
+    )

{rdsclock-0.2.2 → rdsclock-0.4.0}/src/rdsclock/dsp.py

@@ -5,6 +5,8 @@ NumPy ndarrays (typically ``complex64`` for IQ samples and ``float32``
 for FM-demodulated baseband).
 """
 
+from dataclasses import dataclass
+
 import numpy as np
 from scipy.signal import filtfilt, firwin, lfilter, resample_poly
 
@@ -23,6 +25,17 @@ SYMBOL_LPF_HZ = 4_000  # LPF in the symbol-rate domain (after decimation)
 
 DEFAULT_INPUT_FS = 250_000  # rtl_sdr -s 250000
 DEFAULT_RDS_FS = 19_000  # after decimation; ~16 samples/symbol
+PIPELINE_GROUP_DELAY_NS = -2_528_000
+
+
+@dataclass(frozen=True)
+class BitRateDrift:
+    """Pilot-derived RDS bit-rate estimate and stability flag."""
+
+    bit_rate_hz: float
+    pilot_hz: float
+    pilot_mad_hz: float
+    confident: bool
 
 
 def read_iq_u8(path: str) -> np.ndarray:
@@ -109,6 +122,48 @@ def estimate_pilot_19khz(baseband: np.ndarray, fs: float, search_span_hz: float
     return float(sub_freqs[int(np.argmax(sub_spec))])
 
 
+def measure_bit_rate_drift(
+    baseband: np.ndarray,
+    fs: float,
+    n_windows: int = 4,
+    pilot_mad_threshold_hz: float = 50.0,
+) -> BitRateDrift:
+    """Estimate RDS bit-rate drift from the 19 kHz stereo pilot.
+
+    The RDS subcarrier is locked to the third pilot harmonic, so the
+    bit rate follows the same ppm drift. If the pilot estimate is
+    unstable across windows, return the nominal 1187.5 bit/s rate and
+    mark the estimate as not confident.
+    """
+    if n_windows <= 0:
+        raise ValueError("n_windows must be positive")
+
+    samples = np.asarray(baseband)
+    if len(samples) < n_windows * 1024:
+        return BitRateDrift(
+            bit_rate_hz=RDS_SYMBOL_RATE,
+            pilot_hz=19_000.0,
+            pilot_mad_hz=float("inf"),
+            confident=False,
+        )
+
+    window_len = len(samples) // n_windows
+    estimates = [
+        estimate_pilot_19khz(samples[i * window_len : (i + 1) * window_len], fs)
+        for i in range(n_windows)
+    ]
+    pilot_hz = float(np.median(estimates))
+    pilot_mad_hz = float(np.median(np.abs(np.asarray(estimates) - pilot_hz)))
+    confident = pilot_mad_hz <= pilot_mad_threshold_hz
+    bit_rate_hz = RDS_SYMBOL_RATE * pilot_hz / 19_000.0 if confident else RDS_SYMBOL_RATE
+    return BitRateDrift(
+        bit_rate_hz=float(bit_rate_hz),
+        pilot_hz=pilot_hz,
+        pilot_mad_hz=pilot_mad_hz,
+        confident=confident,
+    )
+
+
 def estimate_rds_carrier(
     baseband: np.ndarray,
     fs: float,