horusdemodlib/README.md

110 wiersze
4.6 KiB
Markdown
Czysty Zwykły widok Historia

2020-07-18 10:45:59 +00:00
# Project Horus's Telemetry Demodulator Library
2020-06-15 08:51:16 +00:00
2020-07-18 10:45:59 +00:00
![Horus Binary Modem FFT](https://github.com/projecthorus/horusdemodlib/raw/master/doc/modem_fft.jpg)
Above: Spectrogram of the Horus Binary 4-FSK modem signal.
2020-06-15 08:51:16 +00:00
2020-07-18 10:45:59 +00:00
## 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](https://github.com/drowe67/codec2) project by [David Rowe](http://rowetel.com)), 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](http://tracker.habhub.org) and other services.
2020-06-15 08:51:16 +00:00
2020-07-18 10:45:59 +00:00
In particular, this library provides a decoder for the 'Horus Binary' telemetry system, which is the primary tracking system used in [Project Horus's](https://www.areg.org.au/archives/category/activities/project-horus) 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.](https://github.com/projecthorus/horusdemodlib/wiki)**
**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.](https://github.com/projecthorus/horusdemodlib/wiki#how-do-i-receive-it)**
2020-06-15 08:45:54 +00:00
2020-07-18 10:56:59 +00:00
### Authors
Written by:
* Python Library - Mark Jessop <vk5qi@rfhead.net>
* FSK Modem - [David Rowe](http://rowetel.com)
* FSK Modem Python Wrapper - [XSSFox](https://twitter.com/xssfox)
* LDPC Codes - [Bill Cowley](http://lowsnr.org/)
2020-07-04 09:42:23 +00:00
## HorusDemodLib C Library
This contains the demodulator portions of horuslib, which are written in C.
2020-07-05 05:34:48 +00:00
### Building
The library can be built and installed using:
2020-06-15 08:45:54 +00:00
2020-07-05 05:34:48 +00:00
```console
2020-07-04 09:42:23 +00:00
$ git clone https://github.com/projecthorus/horusdemodlib.git
$ cd horusdemodlib && mkdir build && cd build
2020-06-15 08:51:16 +00:00
$ cmake ..
2020-06-15 08:45:54 +00:00
$ make
2021-08-20 12:50:15 +00:00
$ sudo make install
2020-06-15 08:45:54 +00:00
```
2021-08-20 12:50:15 +00:00
Refer to the [install guide](https://github.com/projecthorus/horusdemodlib/wiki/1.2--Raspberry-Pi-'Headless'-RX-Guide) for a more complete guide, including what dependencies are required.
2020-07-05 05:34:48 +00:00
### Testing
Unit tests for the various demodulators can be run using:
2020-06-15 08:45:54 +00:00
2020-07-05 05:34:48 +00:00
```console
2020-07-04 09:42:23 +00:00
$ cd build
2020-06-15 08:45:54 +00:00
$ ctest
```
2022-02-05 08:20:42 +00:00
### 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.
2020-07-05 05:34:48 +00:00
### API Reference
The main demodulator API is [horus_api.h](https://github.com/projecthorus/horusdemodlib/blob/master/src/horus_api.h). An example of it in use in a C program is available in [horus_demod.c](https://github.com/projecthorus/horusdemodlib/blob/master/src/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](https://github.com/projecthorus/horusdemodlib/blob/master/horusdemodlib/demod.py#L379).
## 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 (LDPC-Encoded 16 and 32-byte formats)
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
```
2020-07-04 09:42:23 +00:00
2020-07-05 05:34:48 +00:00
If you want to install directly from this repository, you can run:
2020-07-04 09:42:23 +00:00
```
$ pip install -r requirements.txt
$ pip install -e .
```
2022-02-05 08:27:06 +00:00
(Note - this has some issues relating to setuptools currently... use pip)
2020-07-04 09:42:23 +00:00
2022-02-05 08:20:42 +00:00
### Updating
2022-02-05 08:27:06 +00:00
If you have installed horusdemodlib via pypi, then you can run (from within your venv, if you are using one):
2022-02-05 08:20:42 +00:00
```
$ pip install -U horusdemodlib
```
This will also install any new dependencies.
2022-02-05 08:27:06 +00:00
2022-02-05 08:20:42 +00:00
If you have installed 'directly', then you will need to run:
```
$ git stash
$ git pull
$ pip install -r requirements.txt
$ pip install -e .
```
2022-02-05 08:27:06 +00:00
(Note - this has some issues relating to setuptools currently... use pip)
2022-02-05 08:20:42 +00:00
2020-07-04 09:42:23 +00:00
2020-06-15 08:45:54 +00:00
## Further Reading
2020-07-18 10:45:59 +00:00
Here are some links to projects and blog posts that use this code:
2020-06-15 08:45:54 +00:00
2020-07-18 10:45:59 +00:00
1. [Horus-GUI](https://github.com/projecthorus/horus-gui) - A cross-platform high-altitude balloon telemetry decoder.
2020-06-15 08:45:54 +00:00
1. [Testing HAB Telemetry, Horus binary waveform](http://www.rowetel.com/?p=5906)
2020-07-18 10:45:59 +00:00
1. [Wenet](https://github.com/projecthorus/wenet) - high speed SSTV images from balloons at the edge of space.
2020-06-15 08:45:54 +00:00
1. [Wenet High speed SSTV images](http://www.rowetel.com/?p=5344)