hubble-satnet-decoder

CI License

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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for paul-hubble from gravatar.com paul-hubble Avatar for rkatkov from gravatar.com rkatkov

Credits

Author: Hubble Network

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hubble_satnet_decoder-1.2.0.tar.gz (21.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hubble_satnet_decoder-1.2.0-py3-none-any.whl (24.1 kB view details)

Uploaded Python 3

File details

Details for the file hubble_satnet_decoder-1.2.0.tar.gz.

File metadata

  • Download URL: hubble_satnet_decoder-1.2.0.tar.gz
  • Upload date:
  • Size: 21.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for hubble_satnet_decoder-1.2.0.tar.gz
Algorithm Hash digest
SHA256 333ff22a973f609a81cbd9e13546741666b5dc41e7c9a9f21e5e2e875ce5178d
MD5 4ab475003629d1b37c6b72b628273fb0
BLAKE2b-256 086732946cc1d641e31b091a1e1626137adaa0f5448115c6b573a1fc1395c617

See more details on using hashes here.

Provenance

The following attestation bundles were made for hubble_satnet_decoder-1.2.0.tar.gz:

Publisher: release.yml on HubbleNetwork/hubble-satnet-decoder

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hubble_satnet_decoder-1.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for hubble_satnet_decoder-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 35b63c32ac1b6d697a53bff7b6419533a2d7c4e28ab711cb3781286fcba6c5fd
MD5 53bc26700c58d16d7ad61994e624ce3e
BLAKE2b-256 aab581e582ae8c401ab5cbf87aa0710d312a8f2a8c794a7a75873cf18fe08fee

See more details on using hashes here.

Provenance

The following attestation bundles were made for hubble_satnet_decoder-1.2.0-py3-none-any.whl:

Publisher: release.yml on HubbleNetwork/hubble-satnet-decoder

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 files

1.1.2

2 files

1.1.1

2 files

1.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page