Skip to content

Commit 74668d0

Browse files
LC-LinkousLC-Linkous
authored
Merge pull request #1 from LC-Linkous/FM_RX_issue
Fm rx issue added documentation, proper gitattributes, CI, ruff tests, etc. This should make it easier to catch some of the test bugs and setup that slipped through before.
2 parents 3470434 + 918b12a commit 74668d0

115 files changed

Lines changed: 7724 additions & 481 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Line-ending policy. Committing this does NOT rewrite existing files -- the
2+
# tree is currently mixed (mostly CRLF, some LF). A dedicated normalization
3+
# commit (`git add --renormalize .`) should follow, on its own, so its large
4+
# whitespace-only diff never mixes with a logic change.
5+
#
6+
# After renormalization: text files are LF in the repo, checked out native on
7+
# each platform, so a Linux checkout gets working `#!` shebangs (CRLF shebangs
8+
# fail to exec) and Windows still sees CRLF in the editor.
9+
10+
* text=auto eol=lf
11+
12+
# Explicit text types (belt and suspenders; text=auto covers most)
13+
*.py text eol=lf
14+
*.md text eol=lf
15+
*.toml text eol=lf
16+
*.cfg text eol=lf
17+
*.txt text eol=lf
18+
*.json text eol=lf
19+
*.csv text eol=lf
20+
*.yml text eol=lf
21+
*.yaml text eol=lf
22+
*.sigmf-meta text eol=lf
23+
24+
# Binary: never touched, never diffed as text
25+
*.iq binary
26+
*.sigmf-data binary
27+
*.wav binary
28+
*.npy binary
29+
*.png binary
30+
*.svg text eol=lf

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
name: Bug report
2+
description: Something isn't working as documented
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for the report.
9+
10+
**Please try the capture check first.** Most "it ran fine but the output
11+
is silent / empty / noise" reports turn out to be the recording, not the
12+
DSP — an antenna that wasn't connected, gain set too low, or a capture
13+
tuned somewhere with nothing on it. Before filing, run:
14+
15+
```bash
16+
uv run python examples/inspect_capture.py your_capture.iq
17+
```
18+
19+
If it reports the capture sitting at the noise floor, or only a few ADC
20+
counts of range in use, that's your answer. If it looks healthy and the
21+
problem persists, please file — and include that output below.
22+
23+
- type: textarea
24+
id: what-happened
25+
attributes:
26+
label: What happened
27+
description: What did you expect, and what happened instead?
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: repro
33+
attributes:
34+
label: Steps to reproduce
35+
description: |
36+
The exact command or minimal script. If it's an example, the full
37+
command line including flags.
38+
render: shell
39+
validations:
40+
required: true
41+
42+
- type: dropdown
43+
id: reproduces-with-sample-data
44+
attributes:
45+
label: Does it reproduce with the shipped sample data?
46+
description: |
47+
`sample_data/` ships recordings specifically so problems can be
48+
reproduced without your hardware. This is the single most useful field
49+
in the form — it separates "the library is broken" from "this capture
50+
is unusual."
51+
options:
52+
- "Yes — reproduces with sample_data"
53+
- "No — only with my own capture"
54+
- "Not applicable (no capture involved)"
55+
- "Haven't tried"
56+
validations:
57+
required: true
58+
59+
- type: textarea
60+
id: capture-details
61+
attributes:
62+
label: Capture details
63+
description: |
64+
If your own recording is involved. The SigMF sidecar has most of this —
65+
pasting the `.sigmf-meta` is the easiest way. Otherwise fill in what you
66+
know.
67+
value: |
68+
- sample rate:
69+
- datatype (ci8 / cf32_le / other):
70+
- center frequency:
71+
- capture length (samples or seconds):
72+
- recorded with (HackRF via hackrfpy / other SDR / synthetic):
73+
- has a matching .sigmf-meta sidecar: yes / no
74+
render: markdown
75+
validations:
76+
required: false
77+
78+
- type: dropdown
79+
id: area
80+
attributes:
81+
label: Area
82+
options:
83+
- "core: filters / resampling"
84+
- "core: spectral (PSD, spectrogram)"
85+
- "core: demod (FM/AM/SSB/OOK/ASK/FSK/PSK/QAM/spread)"
86+
- "core: modulate / pulse shaping"
87+
- "core: measure / detect / sync"
88+
- "core: AGC / calibration / channel / channelize"
89+
- "framing / link protocol / ARQ"
90+
- "sources (FileSource, ArraySource)"
91+
- "sinks (WAV, IQ, plot, TX)"
92+
- "io / SigMF reading and writing"
93+
- "stream / Pipeline"
94+
- "examples"
95+
- "docs"
96+
- "Other / not sure"
97+
validations:
98+
required: true
99+
100+
- type: input
101+
id: os
102+
attributes:
103+
label: Operating system
104+
placeholder: "e.g. Windows 11 23H2 / Ubuntu 24.04 / macOS 14"
105+
validations:
106+
required: true
107+
108+
- type: input
109+
id: python
110+
attributes:
111+
label: Python version
112+
placeholder: "output of: uv run python --version"
113+
validations:
114+
required: true
115+
116+
- type: input
117+
id: version
118+
attributes:
119+
label: sdr_dsp version
120+
description: |
121+
Not on PyPI yet, so this is a commit — `git rev-parse --short HEAD`.
122+
placeholder: "e.g. local checkout at a1b2c3d"
123+
validations:
124+
required: true
125+
126+
- type: input
127+
id: numpy-scipy
128+
attributes:
129+
label: numpy / scipy versions
130+
description: |
131+
scipy designs filter coefficients and acts as the test oracle, so
132+
version differences can matter for numerical reports.
133+
placeholder: "output of: uv run python -c \"import numpy,scipy;print(numpy.__version__,scipy.__version__)\""
134+
validations:
135+
required: false
136+
137+
- type: textarea
138+
id: logs
139+
attributes:
140+
label: Output / traceback
141+
description: The full terminal output, including any traceback.
142+
render: shell
143+
validations:
144+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Example catalog
4+
url: https://github.com/LC-Linkous/sdr_dsp_python/blob/main/docs/EXAMPLES.md
5+
about: Every example script and what it demonstrates. Check here first — there are 40+, and one is usually close to what you want.
6+
- name: Technical reference
7+
url: https://github.com/LC-Linkous/sdr_dsp_python/blob/main/docs/sdr_dsp_REFERENCE.md
8+
about: The deep reference for the DSP itself — what each operation does and how it's verified.
9+
- name: SigMF specification
10+
url: https://github.com/sigmf/SigMF
11+
about: Captures and their .sigmf-meta sidecars follow SigMF. Questions about the format itself belong upstream.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: Feature request
2+
description: Suggest a new capability or improvement
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Before filing, two scope notes that decide most requests:
9+
10+
**This is a library, not a framework.** There is no runtime, scheduler,
11+
flowgraph engine, or GUI, and there won't be — you import functions and
12+
orchestrate the pipeline yourself in plain Python. GNU Radio is the
13+
right tool for large real-time flowgraphs; `sdr_dsp` is for direct,
14+
scriptable DSP. Requests for a flowgraph layer or a GUI are out of
15+
scope.
16+
17+
**The core is device-agnostic by structure.** Core DSP operates on
18+
`complex64` arrays and knows nothing about any radio. Device adapters
19+
belong in user code — see `examples/hackrf_capture.py` and
20+
`examples/hackrf_sink.py` as references for each side. A request to add
21+
a device dependency to the core is out of scope; a request for a new
22+
*example* adapter is welcome.
23+
24+
In scope: new DSP operations, new demodulators/modulators, measurement
25+
and detection, better examples, and documentation.
26+
27+
- type: textarea
28+
id: problem
29+
attributes:
30+
label: Problem / use case
31+
description: What are you trying to do that the library doesn't currently support?
32+
validations:
33+
required: true
34+
35+
- type: textarea
36+
id: proposal
37+
attributes:
38+
label: Proposed solution
39+
description: |
40+
What would the function or class look like? A sketch of the signature
41+
helps — including what goes in and what comes out (array shapes and
42+
dtypes, units of any scalar).
43+
render: python
44+
validations:
45+
required: false
46+
47+
- type: dropdown
48+
id: area
49+
attributes:
50+
label: Area
51+
options:
52+
- "core: filters / resampling"
53+
- "core: spectral (PSD, spectrogram)"
54+
- "core: demod"
55+
- "core: modulate / pulse shaping"
56+
- "core: measure / detect / sync"
57+
- "core: AGC / calibration / channel / channelize"
58+
- "framing / link protocol / ARQ"
59+
- "sources / sinks / io"
60+
- "stream / Pipeline"
61+
- "examples"
62+
- "docs"
63+
- "Other"
64+
validations:
65+
required: true
66+
67+
- type: textarea
68+
id: verification
69+
attributes:
70+
label: How would it be verified?
71+
description: |
72+
Everything in the core is tested against either a scipy oracle or a
73+
synthetic signal with known ground truth. If you know how the proposed
74+
operation could be checked — a scipy equivalent to compare against, or
75+
a signal whose correct answer is known in advance — say so here. If you
76+
don't, that's fine; leave it blank.
77+
validations:
78+
required: false
79+
80+
- type: textarea
81+
id: alternatives
82+
attributes:
83+
label: Alternatives considered
84+
description: Existing workarounds, or how you're doing it today.
85+
validations:
86+
required: false

‎.github/ISSUE_TEMPLATE/question.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Question / usage help
2+
description: How do I use this library to do something?
3+
labels: ["question"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
For questions about **this library**. Two pointers that may be faster
9+
than waiting for a reply:
10+
11+
- `docs/EXAMPLES.md` catalogs every example script and what it
12+
demonstrates. There are 40+, and one is usually close to what you want.
13+
- `docs/sdr_dsp_REFERENCE.md` is the deep technical reference for the
14+
DSP itself.
15+
16+
For questions about **radio or DSP in general** — how FM stereo works,
17+
what deviation to expect, why a constellation looks the way it does —
18+
those are welcome here, but you'll get better answers faster from a
19+
dedicated SDR community. This is a personal project with one maintainer.
20+
21+
- type: textarea
22+
id: question
23+
attributes:
24+
label: What are you trying to do?
25+
description: The goal, plus what you've tried so far. Code welcome.
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: signal
31+
attributes:
32+
label: What signal are you working with?
33+
description: |
34+
If relevant — modulation, roughly what bandwidth, sample rate, and
35+
whether it's a live capture, a file, or synthetic. Signal-processing
36+
questions are usually unanswerable without this.
37+
validations:
38+
required: false
39+
40+
- type: input
41+
id: setup
42+
attributes:
43+
label: Setup
44+
placeholder: "e.g. Ubuntu 24.04, Python 3.12, sdr_dsp at commit a1b2c3d, HackRF One"
45+
validations:
46+
required: false

0 commit comments

Comments
 (0)