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.
- wsprpool-0.1.0/.editorconfig +24 -0
- wsprpool-0.1.0/.gitattributes +21 -0
- wsprpool-0.1.0/.gitignore +23 -0
- wsprpool-0.1.0/CHANGELOG.md +35 -0
- wsprpool-0.1.0/CLA.md +91 -0
- wsprpool-0.1.0/CONTRIBUTING.md +53 -0
- wsprpool-0.1.0/LICENSE +21 -0
- wsprpool-0.1.0/PKG-INFO +257 -0
- wsprpool-0.1.0/README.md +230 -0
- wsprpool-0.1.0/pyproject.toml +59 -0
- wsprpool-0.1.0/tests/test_cli.py +32 -0
- wsprpool-0.1.0/tests/test_decode.py +104 -0
- wsprpool-0.1.0/tests/test_fano.py +28 -0
- wsprpool-0.1.0/tests/test_recording.py +120 -0
- wsprpool-0.1.0/tests/test_sim.py +16 -0
- wsprpool-0.1.0/tests/test_subtract.py +41 -0
- wsprpool-0.1.0/tests/test_wspr.py +136 -0
- wsprpool-0.1.0/wsprpool/__init__.py +15 -0
- wsprpool-0.1.0/wsprpool/__main__.py +5 -0
- wsprpool-0.1.0/wsprpool/_cli.py +241 -0
- wsprpool-0.1.0/wsprpool/_decode.py +238 -0
- wsprpool-0.1.0/wsprpool/_demod.py +197 -0
- wsprpool-0.1.0/wsprpool/_fano.py +88 -0
- wsprpool-0.1.0/wsprpool/_kiwi.py +193 -0
- wsprpool-0.1.0/wsprpool/_session.py +121 -0
- wsprpool-0.1.0/wsprpool/_sim.py +105 -0
- wsprpool-0.1.0/wsprpool/_spots.py +75 -0
- wsprpool-0.1.0/wsprpool/_version.py +3 -0
- wsprpool-0.1.0/wsprpool/_wspr.py +313 -0
|
@@ -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.
|
wsprpool-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|