wsprpool 0.1.0__tar.gz

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,24 @@
1
+ # https://editorconfig.org
2
+ root = true
3
+
4
+ [*]
5
+ charset = utf-8
6
+ end_of_line = lf
7
+ insert_final_newline = true
8
+ trim_trailing_whitespace = true
9
+ indent_style = space
10
+ indent_size = 4
11
+
12
+ [*.py]
13
+ indent_size = 4
14
+ max_line_length = 100
15
+
16
+ [*.{js,ts,json,svelte,css,html,yml,yaml}]
17
+ indent_size = 2
18
+
19
+ [*.md]
20
+ # Markdown uses trailing double-space for hard line breaks.
21
+ trim_trailing_whitespace = false
22
+
23
+ [Makefile]
24
+ indent_style = tab
@@ -0,0 +1,21 @@
1
+ # Normalise line endings to LF everywhere, in the repository *and* in the
2
+ # working tree, on every platform. Without this, Git on Windows defaults to
3
+ # core.autocrlf=true and checks files out with CRLF, which breaks byte-exact
4
+ # test fixtures and shell scripts ("bad interpreter: /bin/sh^M").
5
+ # Modern Windows editors all handle LF, so forcing it costs nothing.
6
+ * text=auto eol=lf
7
+ *.sh text eol=lf
8
+ # batch files are the exception: cmd.exe misreads labels and long lines in
9
+ # LF-only .cmd/.bat files, so they check out with CRLF
10
+ *.cmd text eol=crlf
11
+ *.bat text eol=crlf
12
+
13
+ # Binary assets
14
+ *.png binary
15
+ *.ico binary
16
+ *.icns binary
17
+ *.gif binary
18
+ *.msi binary
19
+ *.exe binary
20
+ *.londopy binary
21
+ *.wav binary
@@ -0,0 +1,23 @@
1
+ .DS_Store
2
+ Thumbs.db
3
+ desktop.ini
4
+ .idea/
5
+ .vscode/
6
+ *.swp
7
+
8
+ __pycache__/
9
+ *.egg-info/
10
+ .venv/
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
14
+ dist/
15
+ build/
16
+
17
+ # recordings are large; share sessions as release assets or elsewhere
18
+ *.wav
19
+ *.londopy
20
+ *-wav/
21
+
22
+ .env
23
+ *.key
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ All notable changes to wsprpool are listed here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The section for a version is
6
+ what appears on its GitHub release page. Validated in CI by
7
+ [patchnotes](https://github.com/Londopy/patchnotes).
8
+
9
+ ## [Unreleased]
10
+
11
+ ## [0.1.0] - 2026-11-19
12
+
13
+ ### Added
14
+
15
+ - WSPR type 1 encoder, a soft-decision 4-FSK demodulator and a Fano decoder.
16
+ - Decoding of one 2-minute slot from several receivers alone and with their log-likelihood
17
+ ratios added together.
18
+ - `wsprpool sim`: decode rate and combining gain on synthetic signals, with optional fading.
19
+ - `wsprpool record`: simultaneous GPS-timestamped IQ recordings from several KiwiSDRs, saved as
20
+ one `.londopy` session file.
21
+ - `wsprpool decode`: decodes a session alone and combined, and looks every spot up on
22
+ wspr.live.
23
+ - A second decode pass: decoded signals are fitted, subtracted from each receiver, and the
24
+ rest is decoded again, which finds weak stations half a hertz or more from strong ones.
25
+ Each receiver alone, and the combination, only subtract what they decoded themselves.
26
+ - The Fano metric is printed with every spot. The default cutoff is 10.
27
+ - Simulated fading follows the Watterson model's Gaussian Doppler spectrum.
28
+ - All three WSPR message types: compound calls like PJ4/K1ABC (type 2) and 6-character
29
+ locators with a hashed call (type 3). A hashed call is named from any other message in
30
+ the session, or from a wspr.live report whose call has the same hash.
31
+ - A drift search of up to 4 Hz over the transmission, with the drift printed for each spot.
32
+ - `wsprpool decode --csv` writes the spots to a CSV file as well.
33
+
34
+ [Unreleased]: https://github.com/Londopy/wsprpool/compare/v0.1.0...HEAD
35
+ [0.1.0]: https://github.com/Londopy/wsprpool/releases/tag/v0.1.0
wsprpool-0.1.0/CLA.md ADDED
@@ -0,0 +1,91 @@
1
+ # wsprpool Contributor License Agreement
2
+
3
+ Thank you for contributing to wsprpool. This agreement clarifies the rights
4
+ you grant on the material you contribute, so that the project can accept it,
5
+ distribute it, and keep its license. You keep the copyright in your
6
+ contribution; you are not asked to assign it.
7
+
8
+ wsprpool is released under the MIT License (`LICENSE`). This agreement lets the
9
+ project continue to distribute your contribution under that license, and, if
10
+ it ever needs to, under another open-source license approved by the Open
11
+ Source Initiative; it does not let the project take your contribution
12
+ private.
13
+
14
+ By opening a pull request and confirming the agreement in the pull request
15
+ (the CLA check asks you to), you accept the terms below for that
16
+ contribution and every later one you make to this repository.
17
+
18
+ ## 1. Definitions
19
+
20
+ "You" is the person or legal entity accepting this agreement. "Contribution"
21
+ is any original work of authorship, including changes to existing work, that
22
+ you intentionally submit to wsprpool for inclusion: code, documentation,
23
+ examples, tests, translations. "Submit" means sending it to the project by
24
+ pull request, issue, or another channel the maintainers use. "Londopy" is
25
+ the project's copyright holder and maintainer.
26
+
27
+ ## 2. Copyright license
28
+
29
+ You grant Londopy and every recipient of wsprpool a perpetual, worldwide,
30
+ non-exclusive, royalty-free, irrevocable copyright license to reproduce your
31
+ Contribution, prepare derivative works of it, display it, perform it,
32
+ sublicense it, and distribute it and the derivative works, under the
33
+ MIT License or another OSI-approved open-source license.
34
+
35
+ ## 3. Patent license
36
+
37
+ You grant Londopy and every recipient of wsprpool a perpetual, worldwide,
38
+ non-exclusive, royalty-free, irrevocable patent license to make, use, sell,
39
+ offer to sell, import, and otherwise transfer your Contribution, alone or
40
+ combined with wsprpool, for any patent claims you can license that your
41
+ Contribution alone or in that combination necessarily infringes. If anyone
42
+ starts patent litigation claiming that your Contribution or wsprpool infringes
43
+ a patent, the patent licenses granted to that party under this agreement end
44
+ on the day the litigation is filed.
45
+
46
+ ## 4. What you represent
47
+
48
+ - You are entitled to grant these licenses. If your employer has rights in
49
+ your Contribution, your employer has permitted you to submit it, or has
50
+ waived those rights, or has signed this agreement for you.
51
+ - The Contribution is your original work, except for material you clearly
52
+ identify as someone else's, together with its license and any
53
+ restrictions you know of. Third-party material must be under a license
54
+ compatible with the MIT License.
55
+ - You will tell the maintainers if you learn that any of the above is no
56
+ longer accurate.
57
+
58
+ ## 5. AI-assisted contributions
59
+
60
+ If you used an AI tool (a code generator, a language model, an assistant of
61
+ any kind) to produce any part of a Contribution, then:
62
+
63
+ - you disclose it in the pull request, in the form the pull request template
64
+ asks for: which tool, and what it did;
65
+ - you have read and understood what the tool produced, and you submit it as
66
+ your own work under this agreement, with the same representations as for
67
+ anything you wrote yourself; the tool is not a party to this agreement and
68
+ is not an author of the Contribution;
69
+ - you have not included output that reproduces someone else's work under a
70
+ license incompatible with the MIT License, or that you have no right to license.
71
+
72
+ The project accepts AI-assisted contributions on these terms and rejects
73
+ undisclosed ones. Authorship in commits and files names people; a tool is
74
+ not listed as an author or co-author.
75
+
76
+ ## 6. No warranty, no obligation
77
+
78
+ Your Contribution is provided as is, without warranty of any kind, unless
79
+ you say otherwise in writing. You are not required to support it, and the
80
+ project is not required to accept it: the maintainers decide what merges.
81
+
82
+ ## 7. Signing
83
+
84
+ The CLA check on your first pull request asks you to comment with the
85
+ sentence it shows; that comment is your acceptance, recorded with your
86
+ GitHub account on the `cla-signatures` branch of this repository. A company
87
+ contributing on behalf of its employees can instead open an issue naming
88
+ the covered GitHub accounts, or contact the maintainer (Londopy) through
89
+ GitHub.
90
+
91
+ Questions go in an issue.
@@ -0,0 +1,53 @@
1
+ # Contributing to wsprpool
2
+
3
+ Issues and pull requests are welcome.
4
+
5
+ ## Before you open a pull request
6
+
7
+ - Set up: `python -m venv .venv`, then `pip install -e ".[dev]"`.
8
+ - Test: `pytest -m "not slow"`, and `pytest -m slow` when you touch the demodulator or decoder.
9
+ - Lint: `ruff check .` and `mypy wsprpool`.
10
+ - Add a line under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) if the change is
11
+ something a user would notice. The changelog is checked in CI by
12
+ [patchnotes](https://github.com/Londopy/patchnotes).
13
+ - Fill in the pull request template, including the **AI tools** section.
14
+ - Sign the [CLA](CLA.md) when the check asks (once).
15
+
16
+ ## AI-assisted contributions
17
+
18
+ You may use AI tools to help write a contribution. Three rules, which the
19
+ CLA makes binding:
20
+
21
+ - **Say so in the pull request.** The template has a section for it: which
22
+ tool, and what it did (drafted the change, wrote the tests, explained the
23
+ code, translated the docs, wrote the description). "None" is a fine answer.
24
+ A check on every pull request fails until the section is filled in.
25
+ - **You are the author.** Read and understand everything the tool produced
26
+ before you submit it; you are answerable for it in review exactly as for
27
+ code you typed. A pull request whose author cannot explain a change is
28
+ sent back. Commits and files name people, not tools: an AI tool is never
29
+ listed as an author or co-author, and commits carry no "Generated with"
30
+ footers. The check rejects both.
31
+ - **No laundering.** Do not submit output that reproduces someone else's
32
+ work under a license incompatible with this project's license, or that you
33
+ have no right to license. If a tool hands you a recognizable chunk of
34
+ another project, leave it out.
35
+
36
+ An undisclosed AI-assisted contribution is closed when discovered, whatever
37
+ its quality. Disclosed ones are reviewed like any other, and labeled
38
+ `ai-assisted`: the tests are the bar.
39
+
40
+ The same goes for issues: if an AI tool wrote or summarized a bug report,
41
+ say so in it.
42
+
43
+ ## Contributor License Agreement
44
+
45
+ Your first pull request gets a comment from the CLA check asking you to
46
+ accept [`CLA.md`](CLA.md) by replying with one sentence. You keep the
47
+ copyright in your work; the agreement gives the project a license to
48
+ distribute it under its license (or another OSI-approved license, never a
49
+ proprietary one) and a patent license for what your contribution
50
+ necessarily uses, and it records that the work is yours to give,
51
+ AI-assisted or not. Every author of a commit in the pull request signs once,
52
+ and that covers all their later pull requests. Companies contributing on
53
+ behalf of employees can open an issue naming the covered accounts instead.
wsprpool-0.1.0/LICENSE ADDED
@@ -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.
@@ -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).