wsprpool 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
wsprpool/_demod.py ADDED
@@ -0,0 +1,197 @@
1
+ """Baseband conversion, signal search and soft symbols for one receiver's stream."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from fractions import Fraction
6
+
7
+ import numpy as np
8
+ from scipy.signal import resample_poly
9
+ from scipy.special import i0e
10
+
11
+ from ._wspr import NSYM, SYNC, TONE_SPACING
12
+
13
+ FS = 375.0
14
+ SPS = 256
15
+ WINDOW = int(120 * FS)
16
+ TONE_OFFSETS = (np.arange(4) - 1.5) * TONE_SPACING
17
+ SIGN = 2.0 * SYNC - 1.0
18
+ # each tone's offset from the centre, mixed down once for every window
19
+ _OFFSETS = np.exp(-2j * np.pi * np.outer(TONE_OFFSETS, np.arange(WINDOW)) / FS)
20
+
21
+
22
+ def baseband(iq: np.ndarray, fs: float, shift_hz: float = 0.0) -> tuple[np.ndarray, float]:
23
+ """Shift iq down by shift_hz and resample it to about 375 Hz.
24
+
25
+ Returns the samples and their exact rate. A Kiwi runs some 100 ppm off 12 kHz, which
26
+ is harmless within one slot but adds up over a long recording, so callers index time
27
+ with the returned rate rather than FS.
28
+ """
29
+ n = np.arange(len(iq))
30
+ x = iq * np.exp(-2j * np.pi * shift_hz * n / fs) if shift_hz else iq
31
+ ratio = Fraction(FS / fs).limit_denominator(4000)
32
+ out = resample_poly(x, ratio.numerator, ratio.denominator).astype(np.complex128)
33
+ return out, fs * ratio.numerator / ratio.denominator
34
+
35
+
36
+ def spectrum(x: np.ndarray, nfft: int = 512) -> tuple[np.ndarray, np.ndarray]:
37
+ """Time-averaged power spectrum, normalised so the noise floor sits at 1."""
38
+ hop = nfft // 2
39
+ frames = np.lib.stride_tricks.sliding_window_view(x, nfft)[::hop]
40
+ p = np.abs(np.fft.fftshift(np.fft.fft(frames * np.hanning(nfft), axis=1), axes=1)) ** 2
41
+ avg = p.mean(axis=0)
42
+ freqs = np.fft.fftshift(np.fft.fftfreq(nfft, 1 / FS))
43
+ inner = np.abs(freqs) < 130
44
+ return freqs, avg / np.median(avg[inner])
45
+
46
+
47
+ def peaks(freqs: np.ndarray, spec: np.ndarray, limit: float = 150.0,
48
+ sigmas: float = 4.0, most: int = 40) -> list[float]:
49
+ """Candidate centre frequencies: local maxima of the 4-tone-wide smoothed spectrum."""
50
+ width = int(round(4 * TONE_SPACING / (freqs[1] - freqs[0])))
51
+ sm = np.convolve(spec, np.ones(width) / width, mode="same")
52
+ inner = np.abs(freqs) < limit
53
+ base = np.median(sm[inner])
54
+ spread = 1.4826 * np.median(np.abs(sm[inner] - base))
55
+ cand = [
56
+ i for i in range(1, len(sm) - 1)
57
+ if inner[i] and sm[i] >= sm[i - 1] and sm[i] > sm[i + 1] and sm[i] > base + sigmas * spread
58
+ ]
59
+ cand.sort(key=lambda i: -sm[i])
60
+ return [float(freqs[i]) for i in cand[:most]]
61
+
62
+
63
+ def tone_sums(x: np.ndarray, f: float, lags: np.ndarray, drift: float = 0.0) -> np.ndarray:
64
+ """Complex symbol integrals, shape (4 tones, len(lags), 162), for a signal centred on f.
65
+
66
+ drift is how far the transmitter's frequency moves from the first symbol to the last.
67
+ """
68
+ # only the samples some lag's symbols cover
69
+ lo, hi = int(lags.min()), min(len(x), int(lags.max()) + NSYM * SPS)
70
+ n = np.arange(lo, hi)
71
+ phase = f * n
72
+ if drift:
73
+ mid = (lo + int(lags.max())) / 2 + NSYM * SPS / 2
74
+ phase = phase + drift / (NSYM * SPS) * (n - mid) ** 2 / 2
75
+ offsets = _OFFSETS[:, lo:hi] if hi <= WINDOW else np.exp(
76
+ -2j * np.pi * np.outer(TONE_OFFSETS, n) / FS)
77
+ y = offsets * (x[lo:hi] * np.exp(-2j * np.pi * phase / FS))
78
+ cs = np.concatenate([np.zeros((4, 1), complex), np.cumsum(y, axis=1)], axis=1)
79
+ starts = lags[:, None] - lo + SPS * np.arange(NSYM)[None, :]
80
+ return cs[:, starts + SPS] - cs[:, starts]
81
+
82
+
83
+ def noise_power(x: np.ndarray) -> float:
84
+ """Expected |symbol integral|^2 of the noise alone, from the robust spectral floor."""
85
+ nfft = 512
86
+ frames = np.lib.stride_tricks.sliding_window_view(x, nfft)[:: nfft // 2]
87
+ p = np.abs(np.fft.fft(frames, axis=1)) ** 2 / nfft
88
+ freqs = np.fft.fftfreq(nfft, 1 / FS)
89
+ per_sample = float(np.median(p.mean(axis=0)[np.abs(freqs) < 130]))
90
+ return per_sample * SPS
91
+
92
+
93
+ def sync_score(c: np.ndarray, sigma2: float) -> np.ndarray:
94
+ """Sync statistic for each lag, scaled so pure noise is roughly N(0, 1)."""
95
+ p = np.abs(c) ** 2 / sigma2
96
+ diff = (p[1] + p[3]) - (p[0] + p[2])
97
+ return (diff * SIGN).sum(axis=-1) / np.sqrt(4 * NSYM)
98
+
99
+
100
+ def _pairs(c: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
101
+ """Per symbol: integral for data bit 0, for data bit 1, and the two noise-only tones."""
102
+ i = np.arange(NSYM)
103
+ s = SYNC.astype(int)
104
+ return c[s, i], c[s + 2, i], np.stack([c[1 - s, i], c[3 - s, i]])
105
+
106
+
107
+ def soft_bits(c: np.ndarray, smooth: int = 15) -> tuple[np.ndarray, float]:
108
+ """LLRs for the 162 data bits (channel order) and the estimated SNR in 2500 Hz.
109
+
110
+ c is the (4, 162) tone matrix at the chosen frequency and lag. Noise comes from the two
111
+ tones the sync vector rules out in each symbol; signal power is tracked over a short
112
+ window so a fade lowers this receiver's say in the combination.
113
+ """
114
+ r0, r1, quiet = _pairs(c)
115
+ sigma2 = float(np.mean(np.abs(quiet) ** 2))
116
+ pw = np.abs(r0) ** 2 + np.abs(r1) ** 2 - 2 * sigma2
117
+ kernel = np.ones(smooth) / smooth
118
+ local = np.convolve(np.pad(pw, smooth // 2, mode="edge"), kernel, mode="valid")
119
+ a2 = np.clip(local, 0.02 * sigma2, None)
120
+ a = np.sqrt(a2)
121
+ x0 = 2 * a * np.abs(r0) / sigma2
122
+ x1 = 2 * a * np.abs(r1) / sigma2
123
+ llr = (np.log(i0e(x0)) + x0) - (np.log(i0e(x1)) + x1)
124
+ es = max(float(np.mean(pw)), 1e-9 * sigma2)
125
+ snr = 10 * np.log10(es / sigma2 * TONE_SPACING / 2500)
126
+ return llr, snr
127
+
128
+
129
+ def fit(x: np.ndarray, tones: np.ndarray, f: float, lag: int,
130
+ drift: float = 0.0) -> tuple[float, int, float]:
131
+ """Best frequency and start for a known transmission near (f, lag), and how sure it's there.
132
+
133
+ The last value is a z-score: how often the transmitted tone beats the tone the other
134
+ data bit would have used. An unrelated neighbouring station lands on either equally
135
+ often, so it doesn't fake a transmission the way raw tone energy would. A neighbour
136
+ sending a nearly identical message (same call and grid, say) still can.
137
+ """
138
+ i = np.arange(NSYM)
139
+ lags = np.arange(lag - 16, lag + 17)
140
+ lags = lags[(lags >= 0) & (lags + NSYM * SPS <= len(x))]
141
+ if not len(lags):
142
+ return f, lag, 0.0
143
+ best = (f, int(lags[0]), -np.inf)
144
+ for step in (np.arange(-0.25, 0.251, 0.05), np.arange(-0.04, 0.041, 0.01)):
145
+ for ff in best[0] + step:
146
+ known = (np.abs(tone_sums(x, ff, lags, drift)[tones, :, i]) ** 2).sum(axis=0)
147
+ j = int(np.argmax(known))
148
+ if known[j] > best[2]:
149
+ best = (float(ff), int(lags[j]), float(known[j]))
150
+ f, lag = best[0], best[1]
151
+ p = np.abs(tone_sums(x, f, np.array([lag]), drift)[:, 0, :]) ** 2
152
+ agree = int(np.sum(p[tones, i] > p[tones ^ 2, i]))
153
+ return f, lag, (agree - NSYM / 2) / np.sqrt(NSYM / 4)
154
+
155
+
156
+ def _smooth(env: np.ndarray, width: int) -> np.ndarray:
157
+ """Centred moving average that shrinks at the ends instead of padding with zeros."""
158
+ cs = np.concatenate([[0], np.cumsum(env)])
159
+ n = len(env)
160
+ lo = np.clip(np.arange(n) - width // 2, 0, n)
161
+ hi = np.clip(np.arange(n) + width - width // 2, 0, n)
162
+ return (cs[hi] - cs[lo]) / (hi - lo)
163
+
164
+
165
+ def _removed(x: np.ndarray, tones: np.ndarray, f: float, lag: int,
166
+ drift: float = 0.0) -> np.ndarray:
167
+ """The part of x[lag:] that follows the transmission's tones, as a slowly varying envelope."""
168
+ n = min(NSYM * SPS, len(x) - lag)
169
+ k = np.arange(NSYM * SPS) - NSYM * SPS / 2
170
+ inst = np.repeat(f + TONE_OFFSETS[tones], SPS) + drift * k / (NSYM * SPS)
171
+ ref = np.exp(2j * np.pi * np.cumsum(inst[:n]) / FS)
172
+ return _smooth(x[lag: lag + n] * np.conj(ref), int(FS)) * ref
173
+
174
+
175
+ def subtract(x: np.ndarray, tones: np.ndarray, f: float, lag: int, drift: float = 0.0,
176
+ min_z: float = 3.0) -> np.ndarray:
177
+ """x with a known transmission removed, or x unchanged if it isn't clearly there.
178
+
179
+ The frequency and start are fitted on x first, so a spot found at another receiver
180
+ can be removed here. The complex envelope is tracked with a one-second moving
181
+ average, which follows slow fading and any leftover frequency error. The start is
182
+ then trimmed to the sample by whichever leaves the least energy behind, since a few
183
+ samples off at every tone change limits the removal to about 20 dB.
184
+ """
185
+ f, lag, z = fit(x, tones, f, lag, drift)
186
+ if z < min_z:
187
+ return x
188
+ def gain(m: int) -> tuple[float, int, np.ndarray]:
189
+ r = _removed(x, tones, f, m, drift)
190
+ seg = x[m: m + len(r)]
191
+ return float(np.sum(np.abs(seg) ** 2) - np.sum(np.abs(seg - r) ** 2)), m, r
192
+
193
+ _, m, r = max((gain(m) for m in range(max(0, lag - 8), lag + 9)),
194
+ key=lambda g: g[0])
195
+ out = x.copy()
196
+ out[m: m + len(r)] -= r
197
+ return out
wsprpool/_fano.py ADDED
@@ -0,0 +1,88 @@
1
+ """Fano sequential decoder for the WSPR K=32, r=1/2 convolutional code, driven by soft LLRs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+
7
+ from ._wspr import NBITS, NDATA, POLY1, POLY2
8
+
9
+
10
+ def branch_metrics(llr: np.ndarray, bias: float = 0.5) -> np.ndarray:
11
+ """Fano metric, in bits, for each node and each pair of coded bits (index 2*c0 + c1).
12
+
13
+ llr is in deinterleaved order, positive meaning the coded bit is more likely 0.
14
+ """
15
+ lp = llr.reshape(NBITS, 2)
16
+ # log2(2 * P(c | r)) - bias, with P(c=0 | r) = 1 / (1 + exp(-L))
17
+ m0 = 1.0 - np.logaddexp(0.0, -lp) / np.log(2) - bias / 2
18
+ m1 = 1.0 - np.logaddexp(0.0, lp) / np.log(2) - bias / 2
19
+ out = np.empty((NBITS, 4))
20
+ out[:, 0] = m0[:, 0] + m0[:, 1]
21
+ out[:, 1] = m0[:, 0] + m1[:, 1]
22
+ out[:, 2] = m1[:, 0] + m0[:, 1]
23
+ out[:, 3] = m1[:, 0] + m1[:, 1]
24
+ return out
25
+
26
+
27
+ def _pair(reg: int) -> int:
28
+ return (((reg & POLY1).bit_count() & 1) << 1) | ((reg & POLY2).bit_count() & 1)
29
+
30
+
31
+ def fano(llr: np.ndarray, delta: float = 1.5, max_cycles: int = 10000,
32
+ bias: float = 0.5) -> tuple[int, float, int] | None:
33
+ """Decode 162 deinterleaved LLRs. Returns (50-bit value, path metric, cycles) or None."""
34
+ met = branch_metrics(np.asarray(llr, dtype=float), bias).tolist()
35
+ limit = max_cycles * NBITS
36
+
37
+ gamma = [0.0] * (NBITS + 1)
38
+ state = [0] * (NBITS + 1)
39
+ first = [0] * NBITS
40
+ second = [0.0] * NBITS
41
+ best = [0.0] * NBITS
42
+ choice = [0] * NBITS
43
+ path = [0] * NBITS
44
+
45
+ def expand(k: int) -> None:
46
+ reg = (state[k] << 1) & 0xFFFFFFFF
47
+ m0 = met[k][_pair(reg)]
48
+ if k >= NDATA:
49
+ first[k], best[k], second[k] = 0, m0, float("-inf")
50
+ return
51
+ m1 = met[k][_pair(reg | 1)]
52
+ if m0 >= m1:
53
+ first[k], best[k], second[k] = 0, m0, m1
54
+ else:
55
+ first[k], best[k], second[k] = 1, m1, m0
56
+
57
+ k = 0
58
+ t = 0.0
59
+ choice[0] = 0
60
+ expand(0)
61
+ for cycle in range(1, limit + 1):
62
+ bm = best[k] if choice[k] == 0 else second[k]
63
+ ng = gamma[k] + bm
64
+ if ng >= t:
65
+ if gamma[k] < t + delta:
66
+ while ng >= t + delta:
67
+ t += delta
68
+ bit = first[k] ^ choice[k]
69
+ path[k] = bit
70
+ gamma[k + 1] = ng
71
+ state[k + 1] = ((state[k] << 1) | bit) & 0xFFFFFFFF
72
+ k += 1
73
+ if k == NBITS:
74
+ value = int("".join(map(str, path[:NDATA])), 2)
75
+ return value, ng, cycle
76
+ choice[k] = 0
77
+ expand(k)
78
+ continue
79
+ while True:
80
+ if k == 0 or gamma[k - 1] < t:
81
+ t -= delta
82
+ choice[k] = 0
83
+ break
84
+ k -= 1
85
+ if k < NDATA and choice[k] == 0:
86
+ choice[k] = 1
87
+ break
88
+ return None
wsprpool/_kiwi.py ADDED
@@ -0,0 +1,193 @@
1
+ """Recording IQ from KiwiSDRs with kiwirecorder.py, and reading its GPS-stamped wav files."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import struct
7
+ import subprocess
8
+ import sys
9
+ import time
10
+ import urllib.request
11
+ from dataclasses import dataclass
12
+ from datetime import datetime, timezone
13
+ from pathlib import Path
14
+
15
+ import numpy as np
16
+
17
+ GPS_EPOCH = datetime(1980, 1, 6, tzinfo=timezone.utc).timestamp()
18
+ WEEK = 604800
19
+ NO_FIX = (254, 255)
20
+ GPS_UTC = 18
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class Receiver:
25
+ host: str
26
+ port: int = 8073
27
+
28
+ @property
29
+ def label(self) -> str:
30
+ return re.sub(r"[^a-z0-9.-]", "-", f"{self.host}-{self.port}".lower())
31
+
32
+ @classmethod
33
+ def parse(cls, text: str) -> Receiver:
34
+ host, _, port = text.rpartition(":") if ":" in text else (text, "", "8073")
35
+ return cls(host, int(port))
36
+
37
+
38
+ def status(rx: Receiver, timeout: float = 10.0) -> dict[str, str]:
39
+ """The key=value lines a KiwiSDR serves at /status."""
40
+ with urllib.request.urlopen(f"http://{rx.host}:{rx.port}/status", timeout=timeout) as r:
41
+ text = r.read().decode("utf-8", "replace")
42
+ return dict(line.split("=", 1) for line in text.splitlines() if "=" in line)
43
+
44
+
45
+ def unusable(st: dict[str, str]) -> str | None:
46
+ """Why a receiver can't be used right now, or None if it can."""
47
+ if st.get("offline") == "yes" or st.get("status", "active") != "active":
48
+ return "offline"
49
+ if int(st.get("gps_good", "0") or 0) <= 0:
50
+ return "no GPS fix, so its timestamps can't be lined up with the others"
51
+ if int(st.get("users", "0")) >= int(st.get("users_max", "0")):
52
+ return f"all {st.get('users_max')} slots in use"
53
+ return None
54
+
55
+
56
+ def record(
57
+ receivers: list[Receiver], freq_khz: float, minutes: int, out: Path, kiwirecorder: Path
58
+ ) -> dict[Receiver, Path]:
59
+ """Record every receiver at once, starting just before the next even minute.
60
+
61
+ Returns the wav file each receiver produced; receivers that failed are left out.
62
+ """
63
+ now = time.time()
64
+ start = (now // 120 + 1) * 120 - 8
65
+ if start - now < 2:
66
+ start += 120
67
+ time.sleep(start - now)
68
+ procs = {}
69
+ deadline = start + minutes * 60 + 120
70
+ try:
71
+ for rx in receivers:
72
+ d = out / rx.label
73
+ d.mkdir(parents=True, exist_ok=True)
74
+ cmd = [
75
+ sys.executable,
76
+ str(kiwirecorder),
77
+ "-s",
78
+ rx.host,
79
+ "-p",
80
+ str(rx.port),
81
+ "-f",
82
+ f"{freq_khz:.3f}",
83
+ "-m",
84
+ "iq",
85
+ "-w",
86
+ "--tlimit",
87
+ str(minutes * 60 + 20),
88
+ "-d",
89
+ str(d),
90
+ "-u",
91
+ "wsprpool",
92
+ "--connect-retries",
93
+ "2",
94
+ "--busy-retries",
95
+ "0",
96
+ ]
97
+ # kiwirecorder logs every GPS block; a pipe nobody reads fills up and stalls it
98
+ with open(d / "kiwirecorder.log", "w") as log:
99
+ procs[rx] = subprocess.Popen(cmd, stdout=log, stderr=subprocess.STDOUT)
100
+ for p in procs.values():
101
+ try:
102
+ p.wait(timeout=max(1.0, deadline - time.time()))
103
+ except subprocess.TimeoutExpired:
104
+ pass
105
+ finally:
106
+ # a stuck connection still holds one of the owner's few slots
107
+ for p in procs.values():
108
+ if p.poll() is None:
109
+ p.kill()
110
+ p.wait()
111
+
112
+ files = {}
113
+ for rx, p in procs.items():
114
+ # the work directory may hold wavs from an earlier run
115
+ wavs = [w for w in (out / rx.label).glob("*.wav") if w.stat().st_mtime >= start - 30]
116
+ if wavs:
117
+ files[rx] = max(wavs, key=lambda w: w.stat().st_mtime)
118
+ else:
119
+ log_text = (out / rx.label / "kiwirecorder.log").read_text(errors="replace")
120
+ tail = " | ".join(log_text.strip().splitlines()[-3:])
121
+ print(
122
+ f"{rx.host}:{rx.port} recorded nothing (exit {p.returncode}): {tail}",
123
+ file=sys.stderr,
124
+ )
125
+ return files
126
+
127
+
128
+ @dataclass
129
+ class KiwiWav:
130
+ iq: np.ndarray
131
+ rate: int
132
+ blocks: list[tuple[int, float, int]]
133
+
134
+
135
+ def parse_wav(data: bytes) -> KiwiWav:
136
+ """Parse a kiwirecorder -w file: a 'kiwi' GPS chunk before every 'data' chunk."""
137
+ if data[:4] != b"RIFF" or data[8:12] != b"WAVE":
138
+ raise ValueError("not a RIFF/WAVE file")
139
+ pos, rate, channels = 12, 0, 0
140
+ parts: list[np.ndarray] = []
141
+ blocks: list[tuple[int, float, int]] = []
142
+ pending: tuple[float, int] | None = None
143
+ count = 0
144
+ while pos + 8 <= len(data):
145
+ cid, size = struct.unpack_from("<4sI", data, pos)
146
+ body = data[pos + 8 : pos + 8 + size]
147
+ if cid == b"fmt ":
148
+ channels, rate = struct.unpack_from("<HI", body, 2)
149
+ elif cid == b"kiwi":
150
+ age, _, sec, nsec = struct.unpack_from("<BBII", body)
151
+ pending = (sec + 1e-9 * nsec, age)
152
+ elif cid == b"data":
153
+ s = np.frombuffer(body[: len(body) // 4 * 4], dtype="<i2")
154
+ if pending is not None:
155
+ blocks.append((count, pending[0], pending[1]))
156
+ pending = None
157
+ parts.append(s)
158
+ count += len(s) // 2
159
+ pos += 8 + size + (size & 1)
160
+ if channels != 2:
161
+ raise ValueError(f"expected 2-channel IQ, found {channels} channel(s)")
162
+ s = np.concatenate(parts) if parts else np.zeros(0, "<i2")
163
+ iq = (s[0::2].astype(np.float32) + 1j * s[1::2].astype(np.float32)) / 32768
164
+ return KiwiWav(iq.astype(np.complex64), rate, blocks)
165
+
166
+
167
+ def timebase(wav: KiwiWav, approx_start: float) -> tuple[float, float]:
168
+ """UTC time of the first sample and the true sample rate, from the GPS block stamps.
169
+
170
+ Kiwis send GPS seconds-of-week, 18 s ahead of UTC. The week is whichever puts the
171
+ start nearest the file's wall-clock time.
172
+ """
173
+ # kiwirecorder stamps the very first block with zeros before any GPS data arrives
174
+ good = [(i, t) for i, t, age in wav.blocks if age not in NO_FIX and t > 0]
175
+ if len(good) < 2:
176
+ raise ValueError("no GPS timestamps in this recording")
177
+ idx = np.array([i for i, _ in good], float)
178
+ tow = np.unwrap(np.array([t for _, t in good]), period=WEEK)
179
+ slope, tow0 = np.polyfit(idx, tow, 1)
180
+ base = GPS_EPOCH + (approx_start + GPS_UTC - GPS_EPOCH) // WEEK * WEEK
181
+ t0 = min((base + w * WEEK + tow0 - GPS_UTC for w in (-1, 0, 1)),
182
+ key=lambda t: abs(t - approx_start))
183
+ if abs(t0 - approx_start) > 60:
184
+ raise ValueError(f"GPS time is {t0 - approx_start:+.1f} s from the file's wall clock")
185
+ return t0, 1.0 / slope
186
+
187
+
188
+ def start_from_name(name: str) -> float:
189
+ """Wall-clock start that kiwirecorder writes into its default file names."""
190
+ m = re.match(r"(\d{8}T\d{6}Z)", name)
191
+ if not m:
192
+ raise ValueError(f"{name!r} doesn't start with a kiwirecorder timestamp")
193
+ return datetime.strptime(m.group(1), "%Y%m%dT%H%M%SZ").replace(tzinfo=timezone.utc).timestamp()
wsprpool/_session.py ADDED
@@ -0,0 +1,121 @@
1
+ """Recording sessions saved as .londopy files, and cutting them into aligned WSPR slots."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import re
7
+ import sys
8
+ import tomllib
9
+ import zipfile
10
+ from collections.abc import Iterator
11
+ from dataclasses import dataclass
12
+ from datetime import datetime, timezone
13
+ from pathlib import Path
14
+
15
+ import numpy as np
16
+
17
+ from ._version import __version__
18
+ from ._decode import LEAD
19
+ from ._demod import WINDOW, baseband
20
+ from ._kiwi import Receiver, parse_wav, start_from_name, timebase
21
+
22
+ FORMAT = 1
23
+ SCHEMA = 1
24
+ MAX_ENTRY = 4 << 30
25
+
26
+
27
+ def _iso(t: float) -> str:
28
+ return datetime.fromtimestamp(t, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
29
+
30
+
31
+ def _q(s: str) -> str:
32
+ return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
33
+
34
+
35
+ def save(path: Path, freq_khz: float, files: dict[Receiver, Path]) -> None:
36
+ """Write the recorded wavs and their metadata into one .londopy file."""
37
+ lines = [f"schema = {SCHEMA}", f"freq_khz = {freq_khz}", ""]
38
+ for rx, wav in files.items():
39
+ lines += ["[[receivers]]", f"label = {_q(rx.label)}", f"host = {_q(rx.host)}",
40
+ f"port = {rx.port}", f"wav = {_q(rx.label + '.wav')}",
41
+ f"started = {_q(_iso(start_from_name(wav.name)))}", ""]
42
+ manifest = "\n".join([
43
+ f"format = {FORMAT}", 'app = "wsprpool"', 'kind = "recording"',
44
+ f"title = {_q(f'WSPR {freq_khz:g} kHz, {len(files)} receivers')}",
45
+ f"app_version = {_q(__version__)}",
46
+ f"created = {_q(_iso(datetime.now(timezone.utc).timestamp()))}",
47
+ 'homepage = "https://github.com/Londopy/wsprpool"', "",
48
+ ])
49
+ tmp = path.with_name(path.name + ".tmp")
50
+ with zipfile.ZipFile(tmp, "w") as z:
51
+ z.writestr("londopy.toml", manifest, compress_type=zipfile.ZIP_STORED)
52
+ z.writestr("session.toml", "\n".join(lines), compress_type=zipfile.ZIP_DEFLATED)
53
+ for rx, wav in files.items():
54
+ z.write(wav, rx.label + ".wav", compress_type=zipfile.ZIP_DEFLATED)
55
+ os.replace(tmp, path)
56
+
57
+
58
+ def _entry(z: zipfile.ZipFile, name: str) -> bytes:
59
+ if ".." in name.split("/") or name.startswith(("/", "\\")) or re.match(r"^[A-Za-z]:", name):
60
+ raise ValueError(f"refusing entry name {name!r}")
61
+ info = z.getinfo(name)
62
+ if info.file_size > MAX_ENTRY:
63
+ raise ValueError(f"{name} is {info.file_size} bytes, over the {MAX_ENTRY} byte limit")
64
+ return z.read(info)
65
+
66
+
67
+ @dataclass
68
+ class Stream:
69
+ label: str
70
+ start: float
71
+ x: np.ndarray
72
+ rate: float
73
+
74
+ @property
75
+ def end(self) -> float:
76
+ return self.start + len(self.x) / self.rate
77
+
78
+
79
+ def load(path: Path) -> tuple[float, list[Stream]]:
80
+ """Read a recording session: its frequency and each receiver's 375 Hz baseband."""
81
+ with zipfile.ZipFile(path) as z:
82
+ head = tomllib.loads(_entry(z, "londopy.toml").decode())
83
+ if head.get("app") != "wsprpool" or head.get("kind") != "recording":
84
+ raise ValueError(f"{path} is a {head.get('app')} {head.get('kind')} file, "
85
+ "not a wsprpool recording")
86
+ if head.get("format", 0) > FORMAT:
87
+ raise ValueError(f"{path} was written by a newer wsprpool; update to read it")
88
+ meta = tomllib.loads(_entry(z, "session.toml").decode())
89
+ streams = []
90
+ for r in meta["receivers"]:
91
+ wav = parse_wav(_entry(z, r["wav"]))
92
+ approx = datetime.strptime(r["started"], "%Y-%m-%dT%H:%M:%SZ").replace(
93
+ tzinfo=timezone.utc).timestamp()
94
+ try:
95
+ t0, rate = timebase(wav, approx)
96
+ except ValueError as e:
97
+ print(f"skipping {r['label']}: {e}", file=sys.stderr)
98
+ continue
99
+ streams.append(Stream(r["label"], t0, *baseband(wav.iq, rate)))
100
+ if not streams:
101
+ raise ValueError(f"{path} has no receiver with usable GPS timestamps")
102
+ return float(meta["freq_khz"]), streams
103
+
104
+
105
+ def window(s: Stream, minute: float) -> np.ndarray | None:
106
+ i = int(round((minute - LEAD - s.start) * s.rate))
107
+ if i < 0 or i + WINDOW > len(s.x):
108
+ return None
109
+ return s.x[i: i + WINDOW]
110
+
111
+
112
+ def slots(streams: list[Stream]) -> Iterator[tuple[float, dict[str, np.ndarray]]]:
113
+ """Every even minute that at least one stream fully covers, with the covering windows."""
114
+ first = min(s.start for s in streams)
115
+ last = max(s.end for s in streams)
116
+ minute = (first + LEAD) // 120 * 120
117
+ while minute <= last:
118
+ ws = {s.label: w for s in streams if (w := window(s, minute)) is not None}
119
+ if ws:
120
+ yield minute, ws
121
+ minute += 120