softlora 0.3.0__tar.gz

softlora-0.3.0/CONTRIBUTORS.txt

@@ -0,0 +1,4 @@
+# Contributors
+
+Hamza <hamza.mohammed.hasan@gmail.com>
+Shayan <shayan.majumder2@gmail.com>

softlora-0.3.0/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

softlora-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CONTRIBUTORS.txt
+recursive-include tests *.py
+recursive-include examples *.py *.md
+recursive-include docs *.md
+recursive-include softlora *.py *.pyi py.typed

softlora-0.3.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: softlora
+Version: 0.3.0
+Summary: LoRa satellite receiver - sync, demodulate, and decode
+Author-email: LibreCube <info@librecube.org>, Hamza Hassan <hamza.mohammed.hasan@gmail.com>
+License: MIT License
+Project-URL: Homepage, https://gitlab.com/librecube/prototypes/gsoc-lora-sat-receiver
+Project-URL: Repository, https://gitlab.com/librecube/prototypes/gsoc-lora-sat-receiver
+Project-URL: Bug Tracker, https://gitlab.com/librecube/prototypes/gsoc-lora-sat-receiver/-/issues
+Project-URL: Documentation, https://librecube.gitlab.io/prototypes/gsoc-lora-sat-receiver/
+Keywords: lora,satellite,sdr,chirp-spread-spectrum,gnuradio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: Topic :: Communications :: Ham Radio
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# SoftLoRa
+
+[![Google Summer of Code 2026](https://img.shields.io/badge/Google%20Summer%20of%20Code-2026-fbb040?logo=google&logoColor=white)]()
+
+Decode LoRa packets from radio recordings and live SDR streams, in pure Python.
+
+Point it at an IQ recording and it finds the packets, corrects the frequency and
+timing errors introduced by the radio link, and gives you back the payload.
+No GNU Radio or C++ needed — just `numpy` and `scipy`.
+
+It was built for satellite downlinks, where signals are weak and Doppler-shifted,
+and is tested on synthetic data, over-the-air captures and real satellite passes.
+
+Developed for Google Summer of Code 2026 with [LibreCube](https://librecube.org/).
+
+
+## Install
+
+```bash
+pip install softlora
+```
+
+Python 3.9+.
+
+## Decode a recording
+
+```python
+from softlora import LoRaDecoder
+
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=125_000, fc=437e6)
+
+for packet in decoder.decode_file("recording.wav"):
+    print(packet.payload_text, packet.crc_valid)
+```
+
+The four arguments describe the signal you are decoding:
+
+| Argument | Meaning |
+|---|---|
+| `sf` | Spreading factor, 7–12 |
+| `bw` | LoRa bandwidth in Hz |
+| `fs` | Sample rate of *your recording* in Hz |
+| `fc` | Center frequency in Hz |
+
+`.wav`, `.cfile`, `.dat` and `.bin` files are supported. A recording may hold
+several packets, so you always get a list back.
+
+## Decode a live stream
+
+Feed IQ chunks as they arrive from an SDR. Packets are returned as soon as they
+are complete, even when one spans two chunks:
+
+```python
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=250_000, fc=437e6)
+
+while receiving:
+    for packet in decoder.decode_stream(read_iq_from_sdr(8192)):
+        print(packet.payload_text)
+
+for packet in decoder.flush():      # decode whatever is left in the buffer
+    print(packet)
+```
+
+## Reading the result
+
+Every decode path returns [`Packet`](softlora/packet.py) objects. The
+fields you will usually want:
+
+```python
+packet.payload_bytes   # the data
+packet.payload_text    # the same data decoded as UTF-8
+packet.crc_valid       # True when the payload passed its checksum
+packet.snr_est         # signal-to-noise estimate in dB
+packet.ok              # a packet was found and demodulated
+```
+
+`ok` and `crc_valid` answer different questions. `ok=True, crc_valid=False`
+means a packet arrived but was corrupted on the way. Filter on
+`packet.crc_valid is True` when you only want trustworthy payloads.
+
+## A LoRa packet
+
+Each packet starts with a preamble of plain upchirps, then a sync word, then a
+2.25-symbol start-of-frame delimiter (SFD) made of downchirps, and finally the
+header, payload and CRC. All four regions are visible below.
+
+<div align="center">
+
+| <img src="docs/images/lora_packet.png" width="600"> |
+|:---:|
+| *A real LoRa packet received from the Polytech Universe-3 (PU-3) satellite (SF8, 62.5 kHz bandwidth). The payload is truncated for display.* |
+
+</div>
+
+## Going further
+
+| Topic | Where |
+|---|---|
+| Runnable examples | [`examples/`](examples/README.md) |
+| Packets without a header | [Quick start](docs/quickstart.md) |
+| Tuning the decoder (`DecoderSettings`) | [The decode pipeline](docs/guide/pipeline.md) |
+| Rescuing weak packets with Chase decoding | [Chase guide](docs/guide/chase.md) |
+| Live SDR chain via GNU Radio | [`examples/README.md`](examples/README.md#live-sdr-via-gnu-radio) |
+| Doppler and carrier offset for satellites | [Ground-station use](docs/guide/satellites.md) |
+| Benchmarks across SF 7–12 | [Performance](docs/guide/performance.md) |
+| How synchronization works | [Sync algorithm](docs/guide/sync-algorithm.md) |
+| Full API reference | [Documentation site](https://gsoc-lora-sat-receiver-7e5f4f.gitlab.io/) |
+
+## References
+
+[1] M. Xhonneux, O. Afisiadis, D. Bol, and J. Louveaux, "A Low-Complexity LoRa
+Synchronization Algorithm Robust to Sampling Time Offsets," *IEEE Internet of
+Things Journal*, 2021. [arXiv:1912.11344](https://arxiv.org/abs/1912.11344)
+
+[2] J. Tapparel, O. Afisiadis, P. Mayoraz, A. Balatsoukas-Stimming, and A. Burg,
+"An Open-Source LoRa Physical Layer Prototype on GNU Radio," *SPAWC*, 2020.
+
+## License
+
+MIT — see [LICENSE](LICENSE) and [CONTRIBUTORS.txt](CONTRIBUTORS.txt).

softlora-0.3.0/README.md

@@ -0,0 +1,120 @@
+# SoftLoRa
+
+[![Google Summer of Code 2026](https://img.shields.io/badge/Google%20Summer%20of%20Code-2026-fbb040?logo=google&logoColor=white)]()
+
+Decode LoRa packets from radio recordings and live SDR streams, in pure Python.
+
+Point it at an IQ recording and it finds the packets, corrects the frequency and
+timing errors introduced by the radio link, and gives you back the payload.
+No GNU Radio or C++ needed — just `numpy` and `scipy`.
+
+It was built for satellite downlinks, where signals are weak and Doppler-shifted,
+and is tested on synthetic data, over-the-air captures and real satellite passes.
+
+Developed for Google Summer of Code 2026 with [LibreCube](https://librecube.org/).
+
+
+## Install
+
+```bash
+pip install softlora
+```
+
+Python 3.9+.
+
+## Decode a recording
+
+```python
+from softlora import LoRaDecoder
+
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=125_000, fc=437e6)
+
+for packet in decoder.decode_file("recording.wav"):
+    print(packet.payload_text, packet.crc_valid)
+```
+
+The four arguments describe the signal you are decoding:
+
+| Argument | Meaning |
+|---|---|
+| `sf` | Spreading factor, 7–12 |
+| `bw` | LoRa bandwidth in Hz |
+| `fs` | Sample rate of *your recording* in Hz |
+| `fc` | Center frequency in Hz |
+
+`.wav`, `.cfile`, `.dat` and `.bin` files are supported. A recording may hold
+several packets, so you always get a list back.
+
+## Decode a live stream
+
+Feed IQ chunks as they arrive from an SDR. Packets are returned as soon as they
+are complete, even when one spans two chunks:
+
+```python
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=250_000, fc=437e6)
+
+while receiving:
+    for packet in decoder.decode_stream(read_iq_from_sdr(8192)):
+        print(packet.payload_text)
+
+for packet in decoder.flush():      # decode whatever is left in the buffer
+    print(packet)
+```
+
+## Reading the result
+
+Every decode path returns [`Packet`](softlora/packet.py) objects. The
+fields you will usually want:
+
+```python
+packet.payload_bytes   # the data
+packet.payload_text    # the same data decoded as UTF-8
+packet.crc_valid       # True when the payload passed its checksum
+packet.snr_est         # signal-to-noise estimate in dB
+packet.ok              # a packet was found and demodulated
+```
+
+`ok` and `crc_valid` answer different questions. `ok=True, crc_valid=False`
+means a packet arrived but was corrupted on the way. Filter on
+`packet.crc_valid is True` when you only want trustworthy payloads.
+
+## A LoRa packet
+
+Each packet starts with a preamble of plain upchirps, then a sync word, then a
+2.25-symbol start-of-frame delimiter (SFD) made of downchirps, and finally the
+header, payload and CRC. All four regions are visible below.
+
+<div align="center">
+
+| <img src="docs/images/lora_packet.png" width="600"> |
+|:---:|
+| *A real LoRa packet received from the Polytech Universe-3 (PU-3) satellite (SF8, 62.5 kHz bandwidth). The payload is truncated for display.* |
+
+</div>
+
+## Going further
+
+| Topic | Where |
+|---|---|
+| Runnable examples | [`examples/`](examples/README.md) |
+| Packets without a header | [Quick start](docs/quickstart.md) |
+| Tuning the decoder (`DecoderSettings`) | [The decode pipeline](docs/guide/pipeline.md) |
+| Rescuing weak packets with Chase decoding | [Chase guide](docs/guide/chase.md) |
+| Live SDR chain via GNU Radio | [`examples/README.md`](examples/README.md#live-sdr-via-gnu-radio) |
+| Doppler and carrier offset for satellites | [Ground-station use](docs/guide/satellites.md) |
+| Benchmarks across SF 7–12 | [Performance](docs/guide/performance.md) |
+| How synchronization works | [Sync algorithm](docs/guide/sync-algorithm.md) |
+| Full API reference | [Documentation site](https://gsoc-lora-sat-receiver-7e5f4f.gitlab.io/) |
+
+## References
+
+[1] M. Xhonneux, O. Afisiadis, D. Bol, and J. Louveaux, "A Low-Complexity LoRa
+Synchronization Algorithm Robust to Sampling Time Offsets," *IEEE Internet of
+Things Journal*, 2021. [arXiv:1912.11344](https://arxiv.org/abs/1912.11344)
+
+[2] J. Tapparel, O. Afisiadis, P. Mayoraz, A. Balatsoukas-Stimming, and A. Burg,
+"An Open-Source LoRa Physical Layer Prototype on GNU Radio," *SPAWC*, 2020.
+
+## License
+
+MIT — see [LICENSE](LICENSE) and [CONTRIBUTORS.txt](CONTRIBUTORS.txt).

softlora-0.3.0/docs/api/chase.md

@@ -0,0 +1,3 @@
+# Chase
+
+::: softlora.chase

softlora-0.3.0/docs/api/chirp.md

@@ -0,0 +1,3 @@
+# Chirp
+
+::: softlora.chirp

softlora-0.3.0/docs/api/coding.md

@@ -0,0 +1,3 @@
+# Coding
+
+::: softlora.coding

softlora-0.3.0/docs/api/decoder.md

@@ -0,0 +1,29 @@
+# LoRaDecoder
+
+The main entry point: constructed once with all decode parameters, then used
+to decode files, in-memory buffers, or live streams.
+
+::: softlora.decoder.LoRaDecoder
+    options:
+      show_docstring_parameters: true
+      members:
+        - decode
+        - decode_file
+        - decode_iq
+        - decode_stream
+        - estimate_carrier_offset
+        - flush
+        - reset
+        - sync
+        - demodulate
+
+# DecoderSettings
+
+Advanced/internal decoder parameters, passed to `LoRaDecoder` via
+`settings=`.  It isolates everything that is not a radio/tunable parameter:
+the sync algorithm, the decode mode, Chase tuning, the streaming gates and
+the gr-lora-sdr SFO search.
+
+::: softlora.decoder.DecoderSettings
+    options:
+      show_docstring_parameters: true

softlora-0.3.0/docs/api/io.md

@@ -0,0 +1,3 @@
+# I/O helpers
+
+::: softlora.io

softlora-0.3.0/docs/api/packet.md

@@ -0,0 +1,3 @@
+# Packet
+
+::: softlora.packet

softlora-0.3.0/docs/api/sync.md

@@ -0,0 +1,3 @@
+# Sync
+
+::: softlora.sync

softlora-0.3.0/docs/api/utils.md

@@ -0,0 +1,3 @@
+# Utils
+
+::: softlora.utils

softlora-0.3.0/docs/changelog.md

@@ -0,0 +1,152 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- **README packet spectrogram** — `scripts/plot_pktA_spectrogram.py` renders the
+  PU-3 packet from the packet-A sample recording as a single labelled
+  spectrogram strip (preamble, sync, SFD down-chirps, header + payload + CRC),
+  used as README Figure 1.
+- **`gr-lora-sdr` streaming** — `decode_stream` / `flush` now work with
+  `sync_algorithm='gr-lora-sdr'`: a new `_GrFrameStream` scanner runs the
+  native-rate dechirp run detection incrementally over arbitrary-sized chunks
+  (bounded memory) and decodes each candidate as soon as its window is
+  buffered.  `decode_file` / `decode_iq` reuse the same scanner, so both sync
+  algorithms now stream.
+
+### Changed
+
+- **`save_packets` prettier output** — besides `packet_XXXX.bin` payloads and
+  the append-only `metadata.jsonl`, `save_packets` now writes a readable
+  `packets.txt` summary with each packet's `Packet.__str__` detail table.
+
+### Removed
+
+- **Chase diagnosis fields dropped from `Packet`** — `chase_used`,
+  `chase_attempts` and `chase_stage` are no longer exposed on the result type;
+  Chase remains a decoder mode and its outcome is read from `ok` / `crc_valid`
+  as before.  The `chase_flip_frac` / `chase_attempts_avg` metrics were removed
+  from `perf/awgn_chase_vs_hard.py` accordingly.
+
+## v0.3.0 (2026-08-23)
+
+### Added
+
+- **Automatic carrier offset estimation** — `decode_file` / `decode_iq` /
+  `decode` accept `carrier_offset_hz='auto'`, which scans the recording for
+  preamble runs and resolves the offset from the preamble upchirp and the
+  first SFD downchirp (the timing term cancels, so the estimate is
+  unambiguous over `±fs/2`).  See `LoRaDecoder.estimate_carrier_offset`.
+- **`DecoderSettings.sfo_ppm`** — optional clock-offset override for the
+  `gr-lora-sdr` sync: a fixed ppm value, `None` (derive from residual CFO), or
+  `'auto'` (default) to sweep `sfo_ppm_search` and accept the first frame
+  whose CRC validates.
+- **`DecoderSettings.max_os_factor`** — the `gr-lora-sdr` sync band-limits and
+  decimates high-oversampled input down to at most this `fs/bw` before running
+  the native-rate `frame_sync` port.
+- **Header checksum verification** — explicit headers are now validated with
+  the LoRa 5-bit checksum (`verify_header_checksum`) before their fields are
+  trusted.
+- **Sub-sample timing refinement** — when the hard decode of a fully buffered
+  packet fails, the xhonneux sync probes `timing_search` sub-sample
+  alignments and the surrounding symbol positions before giving up.
+
+### Changed
+
+- **`sync.py` now implements Algorithm 1 of Xhonneux et al. exactly**:
+  - Fractional CFO from the **last two** upchirp pairs (Eq. 14) instead of an
+    average over all preamble pairs.
+  - Stage 2 uses the **first** post-detection window for `s_tilde_up` and the
+    paper's `M_tilde = N - s_tilde_up`.
+  - Stage 3 demodulates the **single** final upchirp (U7) and **single** first
+    SFD downchirp (D1) instead of averaged windows.
+  - Integer offsets via Eq. 17/18, with the integer STO unwrapped into
+    `[-N/2, N/2)` so a slightly negative STO no longer pushes the payload a
+    full symbol early.
+- **`gr-lora-sdr` sync no longer returns failed candidates** — `decode_file`
+  / `decode_iq` with `sync_algorithm='gr-lora-sdr'` now drop runs whose frame
+  never synchronized (false-positive preamble detections on noise), matching
+  the `xhonneux` path which already filtered them.
+- **`Packet.__str__` renders a detail table** — `print(packet)` shows an
+  aligned key/value table with the full payload hex (wrapped at 32 bytes per
+  line), full payload text, positions, SNR, frequency offset and CRC status.
+  `__repr__` keeps the compact one-line summary for lists and logs.
+- `calc_payload_sym_num` now uses the SF-dependent explicit-header spare
+  nibbles (`sf - 7`) instead of a fixed 3, fixing symbol-count undercounts
+  for SF < 10 (gr-lora_sdr packets at SF 7-9 previously dewhitened one
+  nibble short).
+- `apply_time_shift` fractional delays are zero-padded so the FFT wrap cannot
+  alias into the signal.
+- **Short preambles** — stage 3 now demodulates the final preamble upchirp
+  from `l + min(4, N_preamble_up - N_detect)` instead of the paper's fixed
+  U7 (`l+4`), so preambles with only 6 upchirps (6 up + 2 sync + 2.25 SFD)
+  decode correctly when configured with `N_preamble_up=6`.
+- **Header checksum fix** — the `c0` checksum bit used `bit0(n1)` where
+  gr-lora_sdr's algorithm uses `bit3(n2)`; valid headers were being rejected.
+- **`decode_file` small-chunk performance** — the sub-sample timing probe is
+  only run once a packet is fully buffered, removing the per-chunk repeat
+  cost while a packet is still streaming in.
+- **Packaging** — license and authorship follow the LibreCube convention
+  (MIT, `CONTRIBUTORS.txt`); wheel and source distribution rebuilt for 0.3.0.
+
+### Fixed
+
+- Explicit-header checksum validation (see Changed).
+
+### Tests
+
+- Reference OTA packet-start positions updated for the unwrapped-STO sync.
+- `tests/test_sync_paper.py` — estimator identities (Eq. 19 = Eq. 20 at
+  `M_hat=0`), Eq. 17/18 round-trips, noiseless fractional CFO/STO recovery,
+  and end-to-end decode with injected integer/fractional CFO and STO.
+- `scripts/gr_ref.py`, `scripts/gr_packet_test.py` — generate packets with
+  gr-lora_sdr's TX (SF 7-10, CR 1/2/4, with/without CRC, with/without offsets)
+  and verify the payload against the transmitted ground truth and gr-lora_sdr's
+  RX chain.
+- `scripts/ota_test.py` — decode the OTA capture `dataset/lora_capture2.dat`
+  (4× "Hi from Shayan") at the reference positions and cross-check the payload
+  with gr-lora_sdr's RX.
+- `docs/guide/sync-algorithm.md` — equation-by-equation mapping of the
+  algorithm, the preamble-length generalization, and the `N/2` disambiguation.
+
+## v0.2.0 (2026-08-06)
+
+Breaking: the decoder now returns `Packet` objects on every path, and the
+streaming API replaces the old `detect_packets`.
+
+### Added
+
+- **`Packet` result type** — stable schema with `ok` / `error` / `crc_valid`,
+  `snr_est`, `freq_offset_hz`, sample positions and diagnostics; `to_dict()`
+  for JSON serialization.
+- **`LoRaDecoder.decode_stream` / `flush` / `reset`** — live chunked decoding;
+  packets may straddle chunk boundaries and memory stays bounded.
+- **`decode_file` streams from disk** — new `iter_iq_chunks` reader
+  (raw float32/int16 + stereo WAV) keeps memory bounded for multi-GB files.
+- **`estimate_snr`** — preamble-based SNR estimator (previously documented
+  but never implemented).
+- **`load_iq` / `save_packets` / `sample_rate`** I/O helpers.
+- Stateful linear-phase FIR decimator, preamble gate, and pending/truncation
+  handling in the streaming scan.
+
+### Removed
+
+- `detect_packets` (replaced by `decode_iq`) and the `multi_packet` module.
+
+### Changed
+
+- `full_decode` returns a `Packet` instead of a dict.
+- Constructor gains implicit-header, chase and streaming tuning parameters.
+- `decode_file` / `decode_iq` always return `list[Packet]`.
+
+### Tests
+
+- Streaming equivalence across chunk sizes, packet splits across chunk
+  boundaries, synthetic implicit-header round-trips at SF 7–12, SNR estimator,
+  and I/O helpers (46 tests).
+
+## v0.1.0 (initial)
+
+- Pure-Python LoRa receiver with the 3-stage Xhonneux et al. synchronizer.
+- GNU Radio TX/RX flowgraphs and AWGN performance sweeps.