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.
@@ -0,0 +1,257 @@
1
+ Metadata-Version: 2.5
2
+ Name: wsprpool
3
+ Version: 0.1.0
4
+ Summary: Decode WSPR by adding the soft decisions of several KiwiSDRs
5
+ Project-URL: Homepage, https://github.com/Londopy/wsprpool
6
+ Project-URL: Repository, https://github.com/Londopy/wsprpool
7
+ Project-URL: Bug Tracker, https://github.com/Londopy/wsprpool/issues
8
+ Author: Londopy
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: diversity-combining,ham-radio,kiwisdr,sdr,wspr
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Communications :: Ham Radio
19
+ Requires-Python: >=3.11
20
+ Requires-Dist: numpy>=2.0
21
+ Requires-Dist: scipy>=1.13
22
+ Provides-Extra: dev
23
+ Requires-Dist: mypy; extra == 'dev'
24
+ Requires-Dist: pytest; extra == 'dev'
25
+ Requires-Dist: ruff; extra == 'dev'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # wsprpool
29
+
30
+ [![CI](https://github.com/Londopy/wsprpool/actions/workflows/ci.yml/badge.svg)](https://github.com/Londopy/wsprpool/actions/workflows/ci.yml)
31
+ [![License](https://img.shields.io/github/license/Londopy/wsprpool)](LICENSE)
32
+ [![Python](https://img.shields.io/badge/python-3.11%2B-3776AB)](pyproject.toml)
33
+
34
+ **Decode WSPR signals that no single receiver can hear, by pooling several of them.**
35
+
36
+ wsprpool records the 20 m WSPR segment from several KiwiSDRs at once, lines the streams up
37
+ with their GPS timestamps, and demodulates each one separately down to soft bits. It then
38
+ adds those log-likelihood ratios together before the error-correcting decoder runs. Phases
39
+ never have to match between sites, because only the confidence values are combined.
40
+
41
+ An excerpt from a real 8-minute session with three KiwiSDRs in the eastern US:
42
+
43
+ ```console
44
+ $ wsprpool decode test2.londopy
45
+ test2.londopy: 3 receivers at 14097.1 kHz
46
+
47
+ UTC MHz SNR dt drift metric message found by receivers alone / wspr.live reporters
48
+ 2026-11-19 20:30 14.097149 -21.2 0.18 -0.5 58.7 <K0CFW> EN34OQ 23 combined only - / 117
49
+ 2026-11-19 20:30 14.097153 -29.4 0.15 -1.0 20.4 N0STP EN34 30 combined only - / 93
50
+ 2026-11-19 20:34 14.097102 -29.0 1.34 -1.0 11.6 K5EMI EM13 33 combined only - / 43
51
+ 2026-11-19 20:36 14.097014 -21.1 -0.12 -1.5 118.9 K8EB EN73 23 both kiwisdr.k1ra.us-8073,kiwisdr.itfais.com-8073,sdr.k1vl.com-8077 / 88
52
+ ...
53
+ ```
54
+
55
+ ## Install
56
+
57
+ With Python 3.11 or newer, install the wheel from the
58
+ [latest release](https://github.com/Londopy/wsprpool/releases/latest). Its release page has
59
+ the exact command, for example:
60
+
61
+ ```console
62
+ pip install https://github.com/Londopy/wsprpool/releases/download/v0.1.0/wsprpool-0.1.0-py3-none-any.whl
63
+ ```
64
+
65
+ Or from source:
66
+
67
+ ```console
68
+ git clone https://github.com/Londopy/wsprpool
69
+ cd wsprpool
70
+ python -m venv .venv
71
+ .venv\Scripts\activate # or: source .venv/bin/activate
72
+ pip install -e .
73
+ ```
74
+
75
+ Recording uses `kiwirecorder.py` from [kiwiclient](https://github.com/jks-prv/kiwiclient),
76
+ which isn't on PyPI. Clone it anywhere and point wsprpool at it:
77
+
78
+ ```console
79
+ git clone https://github.com/jks-prv/kiwiclient
80
+ set WSPRPOOL_KIWIRECORDER=C:\path\to\kiwiclient\kiwirecorder.py
81
+ ```
82
+
83
+ `sim` and `decode` don't need kiwiclient.
84
+
85
+ ## Usage
86
+
87
+ ### Measure the gain on synthetic signals
88
+
89
+ ```console
90
+ wsprpool sim --receivers 1,2,4,8 --snr=-37:-27 --trials 20
91
+ wsprpool sim --receivers 1,2,4 --doppler 0.2
92
+ ```
93
+
94
+ Every receiver hears the same message with its own noise, a small frequency and timing
95
+ error, and with `--doppler`, its own Rayleigh fading. The table shows how often the
96
+ combination decodes at each SNR, then the 50% threshold for each receiver count and the
97
+ gain over one receiver. There is only one station per slot, so `sim` skips the
98
+ subtraction pass.
99
+
100
+ ### Record
101
+
102
+ ```console
103
+ wsprpool record kiwisdr.example.org:8073 other.example.net:8073 -o evening.londopy --minutes 10
104
+ ```
105
+
106
+ Before connecting, wsprpool checks each receiver's `/status` page. It skips any that are
107
+ offline, full, or without a GPS fix, since a receiver without GPS timestamps can't be lined
108
+ up with the others. Recording starts just before the next even minute and runs for
109
+ `--minutes`. The default `--freq 14097.1` kHz centres the 200 Hz-wide 20 m WSPR segment.
110
+
111
+ The result is one `.londopy` file holding every receiver's GPS-stamped IQ wav, so a
112
+ session can be shared and decoded again later. It's a zip with a `londopy.toml` and a
113
+ `session.toml` inside.
114
+
115
+ ### Decode
116
+
117
+ ```console
118
+ wsprpool decode evening.londopy
119
+ ```
120
+
121
+ Each 2-minute slot is decoded by every receiver alone and by the combination. Each spot is
122
+ marked:
123
+
124
+ - `both`: the combination and at least one receiver alone decoded it.
125
+ - `combined only`: only the combination decoded it. These are the interesting ones.
126
+ - `alone only`: a receiver alone decoded it but the combination didn't, usually because
127
+ another receiver had interference on that frequency.
128
+
129
+ Every spot is looked up on [wspr.live](https://wspr.live), and the count of other stations
130
+ that reported the same transmitter in the same slot is printed. A `combined only` spot
131
+ that others also heard is very unlikely to be a false decode. Pass `--no-check` to skip
132
+ the lookup, and `--csv spots.csv` to also get the table as a CSV file.
133
+
134
+ All three WSPR message types decode. Type 2 carries a compound call like `PJ4/K1ABC` and
135
+ no locator. Type 3 carries a 6-character locator and only a 15-bit hash of the call; it
136
+ shows as `<K1ABC> FN42AB 37` once the hash is matched to a call heard in another message
137
+ of the session, or to a wspr.live report from that locator, and as `<...>` until then.
138
+
139
+ ## Results so far
140
+
141
+ With 20 slots per point, each threshold below is good to about half a decibel.
142
+
143
+ **Simulated, independent Rayleigh fading at each receiver** (Watterson model, 0.2 Hz
144
+ Doppler spread): the SNR where half the slots decode drops from -28.2 dB with one
145
+ receiver to -30.6 dB with two (2.4 dB gain) and -33.0 dB with four (4.8 dB). Each site
146
+ fades at different times, so the combination rides through each one's fades.
147
+
148
+ **Simulated, plain noise:** the 50% point moves from -29.0 dB with one receiver to
149
+ -31.5 dB with two and -33.2 dB with four, a gain of 2.5 and 4.2 dB against an ideal of 3
150
+ and 6 dB. In a separate run eight receivers reached -34.7 dB against -29.5 dB for one,
151
+ a 5.2 dB gain against an ideal of 9. The shortfall is expected: each receiver
152
+ demodulates noncoherently on its own, and noncoherent detection loses more the weaker the
153
+ signal is at each site.
154
+
155
+ **Real, 2026-11-19 20:30 to 20:38 UTC**, 20 m, three KiwiSDRs (in the FN33, FM18 and EM96 grid squares),
156
+ four slots: 72 spots were decoded by at least one receiver alone and 72 by the combination.
157
+ Six spots were decoded only by the combination. Five of them were reported by 43 or more
158
+ other stations on wspr.live with the same grid and power: KN2M, N0STP, K5EMI, K7CMI, and
159
+ K0CFW's hashed type 3 message. The sixth, `7F3NQR JH81 57` at metric 11.4, was reported
160
+ by nobody and is almost certainly a false decode; a real spot in the same session scored
161
+ 11.6, so no metric cutoff separates the two (see Limits). Every other spot was reported by
162
+ at least 11 other stations. Six spots that one receiver decoded alone were missed by the
163
+ combination. In the cases examined, the other receivers were hearing a different station
164
+ close by in frequency and in step with it, and their confident bits for the wrong station
165
+ outvoted the right one.
166
+
167
+ The same session, decoded with fewer features:
168
+
169
+ | Decoder | Alone | Combined | Combined only |
170
+ |---|---|---|---|
171
+ | Type 1 only, one pass, no drift search | 54 | 49 | 2 |
172
+ | Plus subtraction and a second pass | 60 | 58 | 5 |
173
+ | Plus type 2 and 3 messages | 67 | 64 | 4 |
174
+ | Plus the drift search (this release) | 72 | 72 | 6 |
175
+
176
+ The combined-only count can drop as the decoder improves, because a better single-receiver
177
+ decode moves a spot from "combined only" to "both". Decoding the four slots took about
178
+ 8 minutes.
179
+
180
+ ## Be a good guest on other people's receivers
181
+
182
+ Each KiwiSDR serves only a handful of users, and the owners pay for them. Keep sessions
183
+ short, check the receiver's own page for time limits and rules, and don't leave long
184
+ recordings running on popular receivers. wsprpool connects with the user name
185
+ `wsprpool`, so owners can see what's connected.
186
+
187
+ ## How it works
188
+
189
+ 1. **Baseband.** Each recording is shifted and resampled to 375 Hz complex samples. Its
190
+ GPS block stamps give the true sample rate and the UTC time of the first sample.
191
+ 2. **Candidates.** Averaged spectra from all receivers are added together. Peaks of the
192
+ 4-tone-wide smoothed spectrum become candidates, so a signal too weak to see at any one
193
+ site can still show up in the sum. Each receiver's own peaks are added too.
194
+ 3. **Sync.** For each candidate, the 162-bit sync vector is correlated over a grid of
195
+ frequencies (±1 Hz), start times (0 to 5 s) and drifts (±4 Hz over the transmission),
196
+ and the scores are summed across receivers. Symbol powers are computed once on the
197
+ frequency grid; a drifting signal is a path across that grid, so each drift costs
198
+ only a lookup.
199
+ 4. **Soft bits.** At the best frequency and time, each receiver computes the exact
200
+ noncoherent 4-FSK log-likelihood ratio for every data bit. The noise level comes from
201
+ the two tones the sync bit rules out, and the signal level is tracked over 15 symbols.
202
+ A receiver in a fade, or one that hears nothing, therefore contributes almost nothing.
203
+ 5. **Combine and decode.** The LLRs are added, deinterleaved and fed to a Fano sequential
204
+ decoder for the K=32, rate 1/2 WSPR code. Adding true LLRs is the optimal combination
205
+ for independent receivers.
206
+ 6. **Subtract and decode again.** Each decoded message is re-encoded, and its tones are
207
+ fitted to every receiver's samples, tracking amplitude and phase over one-second
208
+ windows so fading is followed. A fit only counts if the known tone beats the tone for
209
+ the opposite data bit well above chance, so a neighbour can't be subtracted by mistake.
210
+ The fitted signals are removed and the whole search runs again on what's left. Each
211
+ receiver alone and the combination subtract only what they decoded themselves.
212
+
213
+ The encoder is checked symbol for symbol against the WSJT-X reference for
214
+ `K1ABC FN42 37`, and against values worked out from the WSJT-X sources for type 2 and 3
215
+ messages. The callsign hash matches the hashes real type 3 transmissions carried in the
216
+ session above.
217
+
218
+ ## Limits
219
+
220
+ - The decoder is pure Python. A slot with 18 signals and three receivers takes about two
221
+ minutes, nearly twice as long as without the second pass.
222
+ - Two stations close in frequency break the "independent noise" assumption: a receiver
223
+ that hears the other station loudly adds confident wrong bits. Subtraction recovers the
224
+ weaker one from about 0.5 Hz of separation up, but at 0.2 Hz the two can't be told
225
+ apart well enough to subtract.
226
+ - The metric column is the Fano path metric. Decodes below 10 are dropped, but in
227
+ simulation a weak signal near the decode threshold occasionally came out as a wrong
228
+ message scoring above 10, and the real session above has one such decode. Accepting
229
+ all three message types and searching drift both widen what noise can pass for, so
230
+ treat a `combined only` spot as real only when wspr.live confirms it.
231
+ - A hashed call shares its 15-bit hash with roughly one in 30,000 other calls, so a
232
+ type 3 message named in-session can name the wrong one. A wspr.live report with a
233
+ matching hash, locator and power overrides it.
234
+ - `wsprd` also decodes a rare type 3 form that carries a 4-character locator (a
235
+ compound call with a numbered suffix, like `<PA0SKT/2> JO33 40`). wsprpool drops it.
236
+ - The combination uses one frequency for every receiver. In the real session, three
237
+ GPS-locked Kiwis put the same strong signal up to 0.47 Hz apart, which costs some
238
+ sensitivity. A small per-receiver search around the joint peak helped some decodes and
239
+ hurt others in a quick test, so it isn't in yet.
240
+
241
+ ## Building from source
242
+
243
+ ```console
244
+ pip install -e ".[dev]"
245
+ ruff check .
246
+ mypy wsprpool
247
+ pytest -m "not slow"
248
+ pytest -m slow
249
+ ```
250
+
251
+ ## Contributing
252
+
253
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
254
+
255
+ ## License
256
+
257
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,17 @@
1
+ wsprpool/__init__.py,sha256=d7eLxqXeHHUYvH7diaoU_QNWOHg7C5dkbuFSsVlGF64,466
2
+ wsprpool/__main__.py,sha256=arq9FhDc5f2AZchKpqlkQwTT-bKvMcj3iAXJg8GRLCc,53
3
+ wsprpool/_cli.py,sha256=cx2Fkt9Yefp-TwfPz6hac0uknraw_sRpspippv6Ppqs,10233
4
+ wsprpool/_decode.py,sha256=cMpO9ViDYJDSkzvtqoqNaTspFmaCMmwjqfBXzMdo0ks,9035
5
+ wsprpool/_demod.py,sha256=nvr6yp3cx9Zu76SKiNsmdwXz70ilaJodgwou6OHr0rQ,8726
6
+ wsprpool/_fano.py,sha256=j8xXPDJOdH6afGrwC1sNIl23Y9P-G2Y5GeYORLNtKJk,2840
7
+ wsprpool/_kiwi.py,sha256=m34iTFHpPOblIfUWvgPmXsofzbW-xEu5QWLRrUVHEPI,7066
8
+ wsprpool/_session.py,sha256=85TseJxEv__e3j-NzchxB_QSNvEtfkIOQo6XVZcJ6nQ,4582
9
+ wsprpool/_sim.py,sha256=GozEtUywU3IcPEa0ABgKgYos8f4QHxJ9-7dG8lAx-sw,3948
10
+ wsprpool/_spots.py,sha256=_eeKqi-OPYKwwGiVgaAzpBaBNbd73BrBIewu4bwrmY4,3091
11
+ wsprpool/_version.py,sha256=uXXLHkKhug_EXYuaKusd3Ek1NF7itxpjEVb9ehzL8WU,74
12
+ wsprpool/_wspr.py,sha256=wCEgfi8k0RrqxjS3qym7XbyI9iVxqvJoiTfiWm5kXOU,10448
13
+ wsprpool-0.1.0.dist-info/METADATA,sha256=OlQsNhiXm5xGYGrOCDPB3CwKPYu81HIzfdB85YO3SFI,12369
14
+ wsprpool-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
15
+ wsprpool-0.1.0.dist-info/entry_points.txt,sha256=Sgt28DuT-hi7OAAMiNMs_Jqppzy4913UL14PaGz5qzI,48
16
+ wsprpool-0.1.0.dist-info/licenses/LICENSE,sha256=7gVIXWLaLViNmXGzD6OZ4w6UvOcH-yRc8U3xXG5y1nM,1064
17
+ wsprpool-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ wsprpool = wsprpool._cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Londopy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.