lora-receiver 0.1.0__tar.gz

lora_receiver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShayanMajumder
+
+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.

lora_receiver-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: lora-receiver
+Version: 0.1.0
+Summary: LoRa satellite receiver - sync, demodulate, and decode
+Author: ShayanMajumder
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ShayanMajumder/lora-sat-receiver
+Project-URL: Repository, https://github.com/ShayanMajumder/lora-sat-receiver
+Project-URL: Bug Tracker, https://github.com/ShayanMajumder/lora-sat-receiver/issues
+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: 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
+Dynamic: license-file
+
+# lora-receiver
+
+A pure-Python LoRa satellite receiver implementing the 3-stage synchronization algorithm from [Xhonneux, Dallemagne, et al. (2021)](https://arxiv.org/abs/2106.03022).
+
+## Features
+
+- **Preamble detection** in complex baseband IQ recordings
+- **3-stage synchronizer**: Carrier Frequency Offset (CFO) and Symbol Timing Offset (STO) estimation and correction
+- **Demodulation** of LoRa symbols from corrected signals
+- **Packet decoding** with both explicit headers (standard LoRa) and implicit headers (no header, forced parameters)
+- **Multi-packet detection** using a sliding-window approach across a single IQ recording
+- **CRC-16 verification** for payload integrity
+
+## Installation
+
+```bash
+pip install lora-receiver
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+```python
+import numpy as np
+from lora_receiver import LoRaDecoder
+
+# Load IQ samples (complex64)
+iq = np.fromfile("recording.iq", dtype=np.complex64)
+
+# Create decoder for SF=10, BW=125 kHz, fs=125 kHz, fc=437 MHz
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=125_000, fc=437e6)
+
+# Run full decode pipeline
+result = decoder.full_decode(iq)
+
+# Inspect results
+print("Payload (raw):", result["payload_bytes"])
+print("Payload (text):", result.get("payload_text", ""))
+print("CRC passed:", result["crc_ok"])
+```
+
+### Multi-packet decoding
+
+```python
+from lora_receiver import detect_packets
+
+results = detect_packets(iq, sf=10, bw=125_000, fs=125_000, fc=437e6)
+for i, r in enumerate(results):
+    print(f"Packet {i}: CRC={'PASS' if r['crc_ok'] else 'FAIL'}, "
+          f"start={r['sample_start']}, SNR={r.get('snr_est', 'N/A')}")
+```
+
+## API Overview
+
+### `LoRaDecoder(sf, bw, fs, fc, ...)`
+
+| Parameter | Description |
+|-----------|-------------|
+| `sf` | Spreading factor (7-12) |
+| `bw` | Bandwidth in Hz |
+| `fs` | Sampling rate in Hz |
+| `fc` | Center frequency in Hz |
+| `N_detect` | Preamble detection windows (default: 4) |
+| `N_preamble_up` | Number of preamble upchirps (default: 8) |
+| `N_netid` | Net ID upchirps (default: 0) |
+| `N_sfd_down` | SFD downchirps (default: 2.25) |
+
+### `LoRaDecoder.full_decode(iq)` -> dict
+
+Returns a dict with keys: `sf`, `bw`, `payload_bytes`, `payload_text`, `crc_ok`, `crc_calculated`, `header`, `sync_results`, `snr_est`, `sample_start`.
+
+### `LoRaDecoder.sync(iq)` -> (corrected_iq, sync_results)
+
+Runs the 3-stage synchronizer and returns frequency-corrected, time-aligned IQ.
+
+### `detect_packets(iq, sf, bw, fs, fc, ...)` -> list[dict]
+
+Sliding-window multi-packet detector. Returns a list of `full_decode` result dicts.
+
+## Dependencies
+
+- `numpy` -- array operations and FFT
+- `scipy` -- signal resampling
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

lora_receiver-0.1.0/README.md

@@ -0,0 +1,88 @@
+# lora-receiver
+
+A pure-Python LoRa satellite receiver implementing the 3-stage synchronization algorithm from [Xhonneux, Dallemagne, et al. (2021)](https://arxiv.org/abs/2106.03022).
+
+## Features
+
+- **Preamble detection** in complex baseband IQ recordings
+- **3-stage synchronizer**: Carrier Frequency Offset (CFO) and Symbol Timing Offset (STO) estimation and correction
+- **Demodulation** of LoRa symbols from corrected signals
+- **Packet decoding** with both explicit headers (standard LoRa) and implicit headers (no header, forced parameters)
+- **Multi-packet detection** using a sliding-window approach across a single IQ recording
+- **CRC-16 verification** for payload integrity
+
+## Installation
+
+```bash
+pip install lora-receiver
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+```python
+import numpy as np
+from lora_receiver import LoRaDecoder
+
+# Load IQ samples (complex64)
+iq = np.fromfile("recording.iq", dtype=np.complex64)
+
+# Create decoder for SF=10, BW=125 kHz, fs=125 kHz, fc=437 MHz
+decoder = LoRaDecoder(sf=10, bw=125_000, fs=125_000, fc=437e6)
+
+# Run full decode pipeline
+result = decoder.full_decode(iq)
+
+# Inspect results
+print("Payload (raw):", result["payload_bytes"])
+print("Payload (text):", result.get("payload_text", ""))
+print("CRC passed:", result["crc_ok"])
+```
+
+### Multi-packet decoding
+
+```python
+from lora_receiver import detect_packets
+
+results = detect_packets(iq, sf=10, bw=125_000, fs=125_000, fc=437e6)
+for i, r in enumerate(results):
+    print(f"Packet {i}: CRC={'PASS' if r['crc_ok'] else 'FAIL'}, "
+          f"start={r['sample_start']}, SNR={r.get('snr_est', 'N/A')}")
+```
+
+## API Overview
+
+### `LoRaDecoder(sf, bw, fs, fc, ...)`
+
+| Parameter | Description |
+|-----------|-------------|
+| `sf` | Spreading factor (7-12) |
+| `bw` | Bandwidth in Hz |
+| `fs` | Sampling rate in Hz |
+| `fc` | Center frequency in Hz |
+| `N_detect` | Preamble detection windows (default: 4) |
+| `N_preamble_up` | Number of preamble upchirps (default: 8) |
+| `N_netid` | Net ID upchirps (default: 0) |
+| `N_sfd_down` | SFD downchirps (default: 2.25) |
+
+### `LoRaDecoder.full_decode(iq)` -> dict
+
+Returns a dict with keys: `sf`, `bw`, `payload_bytes`, `payload_text`, `crc_ok`, `crc_calculated`, `header`, `sync_results`, `snr_est`, `sample_start`.
+
+### `LoRaDecoder.sync(iq)` -> (corrected_iq, sync_results)
+
+Runs the 3-stage synchronizer and returns frequency-corrected, time-aligned IQ.
+
+### `detect_packets(iq, sf, bw, fs, fc, ...)` -> list[dict]
+
+Sliding-window multi-packet detector. Returns a list of `full_decode` result dicts.
+
+## Dependencies
+
+- `numpy` -- array operations and FFT
+- `scipy` -- signal resampling
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

lora_receiver-0.1.0/lora_receiver/__init__.py

@@ -0,0 +1,4 @@
+from lora_receiver.decoder import LoRaDecoder
+from lora_receiver.multi_packet import detect_packets
+
+__all__ = ['LoRaDecoder', 'detect_packets']

lora_receiver-0.1.0/lora_receiver/chirp.py

@@ -0,0 +1,8 @@
+import numpy as np
+
+
+def generate_chirps(N):
+    n = np.arange(N, dtype=float)
+    upchirp = np.exp(1j * 2 * np.pi * (n**2 / (2 * N) - n / 2))
+    downchirp = np.exp(-1j * 2 * np.pi * (n**2 / (2 * N) - n / 2))
+    return upchirp, downchirp

lora_receiver-0.1.0/lora_receiver/coding.py

@@ -0,0 +1,248 @@
+import warnings
+import numpy as np
+
+
+# ===== GRAY CODING (RX) =====
+
+def gray_coding_rx(symbols, sf, is_header=False, ldro=False):
+    symbols = np.array(symbols, dtype=float)
+    symbols = symbols % (2**sf)
+    if is_header:
+        symbols = np.floor(symbols / 4)
+    elif ldro:
+        symbols = np.floor(symbols / 4)
+    else:
+        symbols = (symbols - 1) % (2**sf)
+    s = symbols.astype(np.uint16)
+    return np.array([int(x ^ (x >> 1)) for x in s], dtype=np.uint16)
+
+
+# ===== DEINTERLEAVE =====
+
+def deinterleave(symbols, sf, cr, is_header, ldro=False):
+    sf_app = (sf - 2) if (is_header or ldro) else sf
+    cw_len = 8 if is_header else (cr + 4)
+    symbols = np.asarray(symbols, dtype=np.uint16)[:cw_len]
+    bits = np.zeros((cw_len, sf_app), dtype=np.uint8)
+    for i in range(sf_app):
+        bits[:, i] = (symbols >> (sf_app - 1 - i)) & 1
+    deinter = np.zeros((sf_app, cw_len), dtype=np.uint8)
+    for i in range(cw_len):
+        for j in range(sf_app):
+            deinter[(i - j - 1) % sf_app, i] = bits[i, j]
+    out = np.zeros(sf_app, dtype=np.uint8)
+    for i in range(sf_app):
+        val = 0
+        for b in range(cw_len):
+            val = (val << 1) | int(deinter[i, b])
+        out[i] = np.uint8(val)
+    return out
+
+
+# ===== HAMMING DECODE =====
+
+def _int2bits(value, n_bits):
+    return [bool((value >> (n_bits - 1 - i)) & 1) for i in range(n_bits)]
+
+
+def _bits2int(bits):
+    r = 0
+    for b in bits:
+        r = (r << 1) | int(b)
+    return r
+
+
+def _apply_syndrome(data_nibble, syndrome):
+    correction = {5: 3, 7: 2, 3: 1, 6: 0}
+    if syndrome in correction:
+        idx = correction[syndrome]
+        data_nibble[idx] = not data_nibble[idx]
+
+
+def hamming_decode(codewords, cr, is_header):
+    cr_app = 4 if is_header else cr
+    cw_len = cr_app + 4
+    codewords = np.asarray(codewords, dtype=np.uint8)
+    n = len(codewords)
+    out = np.zeros(n, dtype=np.uint8)
+    for i in range(n):
+        cw = _int2bits(int(codewords[i]), cw_len)
+        data_nibble = [cw[3], cw[2], cw[1], cw[0]]
+        if cr_app == 4:
+            if not (sum(cw) % 2):
+                out[i] = _bits2int(data_nibble)
+                continue
+            s0 = cw[0] ^ cw[1] ^ cw[2] ^ cw[4]
+            s1 = cw[1] ^ cw[2] ^ cw[3] ^ cw[5]
+            s2 = cw[0] ^ cw[1] ^ cw[3] ^ cw[6]
+            _apply_syndrome(data_nibble, int(s0) | (int(s1) << 1) | (int(s2) << 2))
+        elif cr_app == 3:
+            s0 = cw[0] ^ cw[1] ^ cw[2] ^ cw[4]
+            s1 = cw[1] ^ cw[2] ^ cw[3] ^ cw[5]
+            s2 = cw[0] ^ cw[1] ^ cw[3] ^ cw[6]
+            _apply_syndrome(data_nibble, int(s0) | (int(s1) << 1) | (int(s2) << 2))
+        out[i] = _bits2int(data_nibble)
+    return out
+
+
+# ===== DEWHITEN =====
+
+_WHITEN_LEN = 510
+_WHITEN_SEQ = [
+    0x0102291EA751AAFF, 0xD24B050A8D643A17, 0x5B279B671120B8F4,
+    0x032B37B9F6FB55A2, 0x994E0F87E95E2D16, 0x7CBCFC7631984C26,
+    0x281C8E4F0DAEF7F9, 0x1741886EB7733B15,
+]
+_OFS = [6, 4, 2, 0]
+
+
+def _whiten_bit(pos):
+    pos = pos % _WHITEN_LEN
+    return (_WHITEN_SEQ[pos >> 6] >> (pos & 63)) & 1
+
+
+def _nibble_whiten(k):
+    val = 0
+    for b, ofs in enumerate(_OFS):
+        val |= _whiten_bit(ofs + k) << b
+    return val
+
+
+_WHITENING_BYTES = [(_nibble_whiten(2*i+1) << 4) | _nibble_whiten(2*i) for i in range(255)]
+
+
+def dewhiten(nibbles, payload_len, crc_presence=False):
+    nibbles = np.asarray(nibbles, dtype=np.uint8)
+    needed = 2 * (payload_len + (2 if crc_presence else 0))
+    if len(nibbles) < needed:
+        raise ValueError(
+            f'dewhiten: need {needed} nibbles for payload_len={payload_len}, '
+            f'crc={crc_presence}, but only have {len(nibbles)}'
+        )
+    payload = np.zeros(payload_len, dtype=np.uint8)
+    for i in range(payload_len):
+        ws = _WHITENING_BYTES[i]
+        low = (nibbles[2*i] ^ (ws & 0x0F)) & 0x0F
+        high = (nibbles[2*i+1] ^ (ws >> 4)) & 0x0F
+        payload[i] = (high << 4) | low
+    crc_bytes = np.zeros(0, dtype=np.uint8)
+    if crc_presence:
+        for j in range(2):
+            i = payload_len + j
+            low = nibbles[2*i] & 0x0F
+            high = nibbles[2*i+1] & 0x0F
+            crc_bytes = np.append(crc_bytes, np.uint8((high << 4) | low))
+    return payload, crc_bytes
+
+
+def nibbles_to_bytes(nibbles):
+    num_bytes = min(255, len(nibbles) // 2)
+    out = np.zeros(num_bytes, dtype=np.uint8)
+    for i in range(num_bytes):
+        out[i] = nibbles[2*i] | (nibbles[2*i+1] << 4)
+    return out
+
+
+# ===== HEADER CHECKSUM MATRIX =====
+
+_HCSM = np.array([
+    [1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 1],
+    [0, 1, 0, 0, 1, 0, 0, 1, 1, 0, 1, 0],
+    [0, 0, 1, 0, 0, 1, 0, 1, 0, 1, 1, 1],
+    [0, 0, 0, 1, 0, 0, 1, 0, 1, 1, 1, 1],
+], dtype=np.uint8)
+
+
+def decode_symbols(symbols, sf, cr, is_header, ldro=False):
+    grayed = gray_coding_rx(symbols, sf, is_header=is_header, ldro=ldro)
+    codewords = deinterleave(grayed, sf, cr, is_header, ldro)
+    nibbles = hamming_decode(codewords, cr, is_header)
+    return nibbles
+
+
+# ===== PAYLOAD SYMBOL CALC =====
+
+def calc_payload_sym_num(payload_len, has_crc, sf, cr, ldro=False, impl_header=False):
+    total_bytes = payload_len + (2 if has_crc else 0)
+    total_nibbles = total_bytes * 2
+    header_data_nibbles = (sf - 2) if impl_header else 3
+    sf_eff = (sf - 2) if ldro else sf
+    rdd = cr + 4
+    remaining = max(0, total_nibbles - header_data_nibbles)
+    blocks = (remaining + sf_eff - 1) // sf_eff
+    return 8 + blocks * rdd
+
+
+# ===== HEADER DECODE =====
+
+def decode_header(hdr_syms, sf):
+    hdr_nib = decode_symbols(hdr_syms, sf, cr=1, is_header=True)
+    if len(hdr_nib) < 5:
+        raise ValueError('Header decode failed: insufficient nibbles')
+    payload_len = int(hdr_nib[0] * 16 + hdr_nib[1])
+    has_crc = bool(hdr_nib[2] & 1)
+    cr = int(hdr_nib[2] >> 1)
+    if payload_len > 255 or payload_len < 1 or cr < 1 or cr > 4:
+        raise ValueError(
+            f'Invalid header: payload_len={payload_len}, cr={cr}'
+        )
+    hc = np.zeros(5, dtype=np.uint8)
+    hc[0] = hdr_nib[3] & 1
+    for i in range(4):
+        hc[i+1] = (hdr_nib[4] >> (3-i)) & 1
+    nb = np.zeros(12, dtype=np.uint8)
+    for i in range(3):
+        for j in range(4):
+            nb[i*4+j] = (hdr_nib[i] >> (3-j)) & 1
+    if not np.array_equal(hc, np.dot(_HCSM, nb) % 2):
+        warnings.warn(
+            f'Invalid header checksum '
+            f'(decoded hc={list(hc)}, '
+            f'expected={list(np.dot(_HCSM, nb) % 2)})'
+        )
+    return payload_len, has_crc, cr, hdr_nib
+
+
+# ===== FULL DECODE =====
+
+def decode(data_symbols, sf=10, impl_header=False,
+           forced_payload_len=None, forced_has_crc=True, forced_cr=1):
+    if impl_header:
+        if forced_payload_len is None or forced_payload_len < 1 or forced_payload_len > 255:
+            raise ValueError(f'Invalid forced_payload_len={forced_payload_len}')
+        if forced_cr < 1 or forced_cr > 4:
+            raise ValueError(f'Invalid forced_cr={forced_cr}')
+        first_nibbles = decode_symbols(data_symbols[:8], sf, cr=1, is_header=True)
+        data_nibbles = list(first_nibbles)
+        payload_len = forced_payload_len
+        has_crc = forced_has_crc
+        cr = forced_cr
+    else:
+        payload_len, has_crc, cr, hdr_nib = decode_header(data_symbols[:8], sf)
+        data_nibbles = list(hdr_nib[5:])
+
+    rdd = cr + 4
+    for i in range(0, len(data_symbols[8:]) - rdd + 1, rdd):
+        block = data_symbols[8+i:8+i+rdd]
+        nibs = decode_symbols(block, sf, cr, is_header=False)
+        data_nibbles.extend(nibs)
+    return dewhiten(np.array(data_nibbles, dtype=np.uint8), payload_len, has_crc) + ({'payload_len': payload_len, 'has_crc': has_crc, 'cr': cr},)
+
+
+# ===== CRC-16 =====
+
+def calc_lora_crc16(payload):
+    if len(payload) < 2:
+        return np.array([0, 0], dtype=np.uint8)
+    crc = 0x0000
+    for byte in payload[:-2]:
+        b = int(byte)
+        for _ in range(8):
+            if ((crc & 0x8000) >> 8) ^ (b & 0x80):
+                crc = ((crc << 1) ^ 0x1021) & 0xFFFF
+            else:
+                crc = (crc << 1) & 0xFFFF
+            b <<= 1
+    crc = crc ^ int(payload[-1]) ^ (int(payload[-2]) << 8)
+    return np.array([crc & 0xFF, (crc >> 8) & 0xFF], dtype=np.uint8)