Project Horus's Telemetry Demodulator Library
 
 
 
 
 
Go to file
Mark Jessop 02058a6d38 Add SP9RKF 2024-03-24 13:54:47 +10:30
.github/workflows Add workflow to build images, modify git/dockerignore 2023-04-12 09:30:37 +02:00
doc Add Horus V2 packet format diagram 2023-06-14 15:17:00 +10:00
horusdemodlib Handle 202 responses from Sondehub better. 2024-02-03 15:56:02 +10:30
samples Added v2 sample and test, removed assert for rtty decoder, added option to use local lists for uploader 2021-09-04 17:26:25 +09:30
scripts Narrow allowed payload-system time window, add warnings for various issues. 2023-07-28 21:30:06 +09:30
src Merge pull request #145 from kng/docker 2023-04-12 18:02:38 +09:30
.dockerignore Add workflow to build images, modify git/dockerignore 2023-04-12 09:30:37 +02:00
.gitignore Add workflow to build images, modify git/dockerignore 2023-04-12 09:30:37 +02:00
.travis.yml Update travis to only build on tags 2020-07-11 21:16:18 +09:30
CMakeLists.txt Added v2 sample and test, removed assert for rtty decoder, added option to use local lists for uploader 2021-09-04 17:26:25 +09:30
Dockerfile Add rx_tools and soapysdr support 2023-01-14 13:13:50 +01:00
LICENSE Initial commit 2020-06-15 18:10:57 +09:30
README-Docker.md Add docker readme, update compose and env example 2023-04-11 17:49:26 +02:00
README.md Add SOLARBAG 2023-08-10 17:11:34 +09:30
TESTING.md Update horus gen test bits to produce 32-byte v2 golay-encoded frames 2021-08-25 20:26:47 +09:30
custom_field_list.json add custom data for SP9SKP 2024-02-25 09:07:01 +10:30
docker-compose.yml Add docker readme, update compose and env example 2023-04-11 17:49:26 +02:00
mingw-w64-x86_64.cmake Add in cross compiling and github releases 2020-07-09 21:29:07 +10:00
payload_id_list.txt Add SP9RKF 2024-03-24 13:54:47 +10:30
pyproject.toml Handle 202 responses from Sondehub better. 2024-02-03 15:56:02 +10:30
requirements.txt Add Sondehub Amateur uploader. 2022-02-05 16:02:53 +10:30
setup.py Fix setup.py, bump version 2020-07-04 20:12:30 +09:30
start_dual_4fsk.sh Narrow allowed payload-system time window, add warnings for various issues. 2023-07-28 21:30:06 +09:30
start_dual_rtty_4fsk.sh Narrow allowed payload-system time window, add warnings for various issues. 2023-07-28 21:30:06 +09:30
start_gqrx.sh Add command-line uploader functionality, and startup helper scripts. 2020-07-18 15:05:05 +09:30
start_rtlsdr.sh Narrow allowed payload-system time window, add warnings for various issues. 2023-07-28 21:30:06 +09:30
user.cfg.example Disable habitat uploader, add warning when uploading 4FSKTEST telemetry 2022-12-18 17:14:22 +10:30
user.env.example Narrow allowed payload-system time window, add warnings for various issues. 2023-07-28 21:30:06 +09:30

README.md

Project Horus's Telemetry Demodulator Library

Horus Binary Modem FFT Above: Spectrogram of the Horus Binary 4-FSK modem signal.

What is it?

This repository contains:

  • libhorus - A C library containing a high performance 2/4-FSK-demodulator (originally developed as part of the Codec2 project by David Rowe), along with Golay and LDPC forward-error correction algorithms.
  • horus_demod - A command-line version of the FSK demodulator.
  • horusdemodlib - A Python library which wraps libhorus, and provides additional functions to decode telemetry into formats suitable for uploading to the Habhub tracker and other services.

In particular, this library provides a decoder for the 'Horus Binary' telemetry system, which is the primary tracking system used in Project Horus's High-Altitude Balloon launches.

The modem in this library can also decode the standard UKHAS RTTY telemetry used on many other high-altitude balloon flights.

For the latest information on how and why to use this library, please visit the wiki pages.

If you're looking for a way to decode telemetry from a Horus Binary (or even an old-school RTTY) High-Altitude Balloon payload, read the guides available here.

Authors

Written by:

HorusDemodLib C Library

This contains the demodulator portions of horuslib, which are written in C.

Building

The library can be built and installed using:

$ git clone https://github.com/projecthorus/horusdemodlib.git
$ cd horusdemodlib && mkdir build && cd build
$ cmake ..
$ make
$ sudo make install

Refer to the install guide for a more complete guide, including what dependencies are required.

Testing

Unit tests for the various demodulators can be run using:

$ cd build
$ ctest

Updates

In most cases, you can update this library by running:

$ git pull

and then following the build steps above from the cd horusdemodlib line.

API Reference

The main demodulator API is horus_api.h. An example of it in use in a C program is available in horus_demod.c

A Python wrapper is also available (via the horusdemodlib Python library which is also part of this repository). An example of its use is available here.

HorusDemodLib Python Library

The horusdemodlib Python library contains decoders for the different Project Horus telemetry formats, including:

  • Horus Binary v1 (Legacy 22-byte Golay-encoded format)
  • Horus Binary v2 (Golay-encoded 32-byte format)

It also contains a wrapper around the C library (mentioned above), which contains the Horus modem demodulators.

The easiest way to install horusdemodlib is via pypi:

$ pip install horusdemodlib

If you want to install directly from this repository, you can run:

$ pip install -r requirements.txt
$ pip install -e .

(Note - this has some issues relating to setuptools currently... use pip)

Updating

If you have installed horusdemodlib via pypi, then you can run (from within your venv, if you are using one):

$ pip install -U horusdemodlib

This will also install any new dependencies.

If you have installed 'directly', then you will need to run:

$ git stash 
$ git pull
$ pip install -r requirements.txt
$ pip install -e .

(Note - this has some issues relating to setuptools currently... use pip)

Further Reading

Here are some links to projects and blog posts that use this code:

  1. Horus-GUI - A cross-platform high-altitude balloon telemetry decoder.
  2. Testing HAB Telemetry, Horus binary waveform
  3. Wenet - high speed SSTV images from balloons at the edge of space.
  4. Wenet High speed SSTV images