hubble-satnet-decoder

Hubble PHY v-1 / v1 preamble detector, FSK decoder, and spectrogram computation — extracted as a standalone, pip-installable library.

Install

pip install hubble-satnet-decoder

Or for development:

git clone https://github.com/hubblenetwork/hubble-satnet-decoder.git
cd hubble-satnet-decoder
pip install -e ".[dev]"

Quick start

import numpy as np
from hubble_satnet_decoder import decode_signal, configure

# (optional) override the default sample rate
configure(sample_rate=781_250)

# Load 1 second of IQ data (complex64)
iq = np.load("capture.npy")

packets, detections, attempts = decode_signal(iq)
for pkt in packets:
    print(f"Device 0x{pkt['ntw_id']:08X}  seq={pkt['seq_num']}  "
          f"chipset={pkt.get('chipset', 'v-1')}")

API reference

decode_signal(signal) -> (packets, detections, attempts)

Full dual-protocol decode pipeline on a 1-second IQ chunk.

detect_preambles(spec_img, t_det, f_det) -> (time, freq, scores, phy_ver)

Dual-template preamble detection via OpenCV + NMS.

compute_spec_chunk(iq_chunk) -> Sxx_dB

Compute a visualisation spectrogram (freq × time) for an IQ chunk.

configure(sample_rate=None)

Recompute all sample-rate-dependent derived values.

Constants

from hubble_satnet_decoder import (
    SYNTH_RES,             # per-chipset synthesiser resolution (Hz)
    CHANNEL_SPACING,       # nominal channel spacing (Hz)
    DEVICE_CHANNEL_SPACING,# actual per-device channel spacing
    HOPPING_SEQS,          # frequency hopping sequences
    RS_N_V1, RS_K_V1,      # Reed-Solomon block sizes (v1)
    PREAMBLE_CODE_V1,      # v1 preamble code [63,0,63,0,63,0,63,63]
)

Chipset statistics

from hubble_satnet_decoder import get_chipset_stats, reset_chipset_stats

stats = get_chipset_stats()   # {"nordic": {"detected": 5, "ok": 4, ...}, ...}
reset_chipset_stats()

Releasing

1. Bump the version in pyproject.toml (e.g. version = "1.0.2")
2. Write release notes in release-notes.md — categorise commits since the last tag under Added, Fixed, Documentation, Tests, and Maintenance headings
3. Commit:

   git add pyproject.toml release-notes.md
   git commit -m "chore: release X.Y.Z"

4. Tag and push:

   git tag vX.Y.Z
   git push origin main
   git push origin vX.Y.Z

5. Approve the publish — the tag push triggers the GitHub Actions workflow which runs tests, builds the package, and publishes to PyPI. Approve the publish step in the GitHub Actions UI (the pypi environment gate).

Tip: The /release Claude Code skill automates steps 1–4.

License

Apache-2.0 — see LICENSE.