nearlink_sdr.phy.timing 源代码

"""Packet-local PSK clock recovery after matched filtering (TXS-10002-2025 §6.2.1.2).

The standard defines the waveform; this NDA Gardner/PI receiver is an implementation
choice, not a mandated algorithm or a statement of clock-compliance limits.
"""

from dataclasses import dataclass

import numpy as np
from scipy.interpolate import CubicSpline

__all__ = ["PSKTimingConfig", "track_psk_timing"]


[文档] @dataclass(frozen=True) class PSKTimingConfig: """Normalized loop bandwidth and experimental integral rate bound. Gains assume beta=.4 RRC and power-normalized complex Gardner error. The detector gain 1.2 per symbol was measured with the independent TX reference for both alternating-rotation QPSK and 8PSK. Bounds are not SLE limits. """ bandwidth: float = .003 max_rate_ppm: float = 500.0 def __post_init__(self): if (not np.isfinite([self.bandwidth, self.max_rate_ppm]).all() or not 0 < self.bandwidth <= .02 or not 0 < self.max_rate_ppm <= 10000): raise ValueError("Need finite bandwidth in (0,.02] and rate bound in (0,10000] ppm")
[文档] def track_psk_timing(filtered: np.ndarray, sps: int, start: float, stop: float, *, hold_symbols: int = 32, config: PSKTimingConfig | None = None) -> dict: """Track a single packet without decisions, expected payload, CRC or modulation labels. ``start`` is the already selected known-sync center, ``stop`` an exclusive original-sample bound. Hold the sync centers fixed, then update the NCO phase and rate for every symbol. Error = Re[(previous-current)*conj(midpoint)] / power. Positive error advances the next center toward a later sample. Returned rate is the PI integrator state; it is not calibrated SRO or an independent truth. Cubic coefficients are built once; the feedback loop uses scalar Horner evaluation rather than a SciPy call per symbol. Centered matched filtering and cubic lookahead remain offline; state resets for every packet. """ if config is None: config = PSKTimingConfig() z = np.asarray(filtered) if (z.ndim != 1 or len(z) < 4 or not np.isfinite(z).all() or not isinstance(sps, int) or isinstance(sps, bool) or sps < 2 or not isinstance(hold_symbols, int) or isinstance(hold_symbols, bool) or hold_symbols < 1 or not np.isfinite([start, stop]).all() or not 0 <= start < stop <= len(z) - 1): raise ValueError("Need finite 1D filtered IQ, integer SPS>=2, positive hold and sample bounds") if not isinstance(config, PSKTimingConfig): raise ValueError("config must be PSKTimingConfig") damping, detector_gain = 2 ** -.5, 1.2 theta = config.bandwidth / (damping + .25 / damping) denominator = 1 + 2 * damping * theta + theta * theta kp = sps * 4 * damping * theta / denominator / detector_gain ki = sps * 4 * theta * theta / denominator / detector_gain lower = sps * (1 - config.max_rate_ppm * 1e-6) upper = sps * (1 + config.max_rate_ppm * 1e-6) spline = CubicSpline(np.arange(len(z)), z) c0, c1, c2, c3 = spline.c def sample(position): cell = int(position) fraction = position - cell return ((c0[cell] * fraction + c1[cell]) * fraction + c2[cell]) * fraction + c3[cell] sync_centers = np.arange(start, min(stop, start + hold_symbols * sps), sps) power = max(float(np.mean(abs(spline(sync_centers)) ** 2)), 1e-30) # A clipped error is in [-2,2], so every update advances by at least this amount. minimum_step = lower - 2 * kp capacity = int(np.ceil((stop - start) / minimum_step)) + 1 symbols = np.empty(capacity, dtype=complex) centers = np.empty(capacity) rates = np.empty(capacity) errors = np.empty(capacity) t, omega, count = float(start), float(sps), 0 previous, previous_t = sample(t), t rate_limit_events, error_clip_events = 0, 0 while t < stop: current = sample(t) power = max(power + (abs(current) ** 2 - power) / 64, 1e-30) error = 0.0 if count >= hold_symbols: midpoint = sample((previous_t + t) / 2) raw_error = float(((previous - current) * midpoint.conjugate()).real / power) error = max(-2., min(2., raw_error)) error_clip_events += abs(raw_error) > 2 proposed = omega + ki * error rate_limit_events += proposed < lower or proposed > upper omega = max(lower, min(upper, proposed)) symbols[count], centers[count] = current, t rates[count], errors[count] = (omega / sps - 1) * 1e6, error previous, previous_t = current, t t += omega + kp * error count += 1 return dict(symbols=symbols[:count], centers=centers[:count], rate_ppm=rates[:count], detector_error=errors[:count], diagnostics=dict( method="NDA complex Gardner + power normalization + second-order PI NCO", bandwidth=config.bandwidth, max_rate_ppm=config.max_rate_ppm, damping=damping, detector_gain=detector_gain, kp_samples=kp, ki_samples=ki, hold_symbols=hold_symbols, rate_limit_events=rate_limit_events, error_clip_events=error_clip_events, estimated_rate_ppm=float(np.median(rates[max(0, count - 128):count])), rate_state_final_ppm=float(rates[count - 1]), lock_status="not_classified"))