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/__init__.py +15 -0
- wsprpool/__main__.py +5 -0
- wsprpool/_cli.py +241 -0
- wsprpool/_decode.py +238 -0
- wsprpool/_demod.py +197 -0
- wsprpool/_fano.py +88 -0
- wsprpool/_kiwi.py +193 -0
- wsprpool/_session.py +121 -0
- wsprpool/_sim.py +105 -0
- wsprpool/_spots.py +75 -0
- wsprpool/_version.py +3 -0
- wsprpool/_wspr.py +313 -0
- wsprpool-0.1.0.dist-info/METADATA +257 -0
- wsprpool-0.1.0.dist-info/RECORD +17 -0
- wsprpool-0.1.0.dist-info/WHEEL +4 -0
- wsprpool-0.1.0.dist-info/entry_points.txt +2 -0
- wsprpool-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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
|
+
[](https://github.com/Londopy/wsprpool/actions/workflows/ci.yml)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
[](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,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.
|