2016-01-07 20:24:51 +01:00
|
|
|
# gr-satnogs: SatNOGS GNU Radio Out-Of-Tree Module
|
2019-09-03 15:23:39 +02:00
|
|
|
![gr-satnogs](docs/assets/gr-satnogs.png)
|
|
|
|
|
2016-01-07 20:24:51 +01:00
|
|
|
gr-satnogs is an out-of-tree GNU Radio module that provides all the necessary tools
|
2019-09-03 15:23:39 +02:00
|
|
|
for decoding signals from various scientific and academic satellites.
|
|
|
|
It also provides blocks for debugging and experimenting with known satellite
|
|
|
|
telecommunication schemes.
|
2016-01-07 20:24:51 +01:00
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
## Installation
|
2016-01-07 20:24:51 +01:00
|
|
|
|
|
|
|
### Requirements
|
2019-09-03 15:23:39 +02:00
|
|
|
* GNU Radio ( > 3.7.11 )
|
2016-10-26 19:36:07 +02:00
|
|
|
* CMake ( > 3.1)
|
|
|
|
* G++ (with C++11 support)
|
|
|
|
* VOLK
|
2018-01-03 00:34:32 +01:00
|
|
|
* libogg
|
2017-03-23 02:22:08 +01:00
|
|
|
* libvorbis
|
2017-10-09 15:16:32 +02:00
|
|
|
* libpng
|
2018-01-03 00:34:32 +01:00
|
|
|
* libpng++
|
2019-09-01 21:30:57 +02:00
|
|
|
* libjsoncpp
|
2016-10-26 19:36:07 +02:00
|
|
|
* git
|
2019-06-05 13:36:58 +02:00
|
|
|
* swig
|
2017-03-23 02:22:08 +01:00
|
|
|
|
|
|
|
**Optional**
|
2016-10-26 19:36:07 +02:00
|
|
|
* gr-osmocom (for using the flowgraphs with real SDR hardware)
|
2018-01-31 21:53:45 +01:00
|
|
|
* libfec (it will automatically installed if not present)
|
2016-01-07 20:24:51 +01:00
|
|
|
|
2018-11-30 17:32:10 +01:00
|
|
|
#### Debian / Ubuntu
|
2019-09-12 17:13:25 +02:00
|
|
|
```bash
|
2018-11-30 17:32:10 +01:00
|
|
|
apt install -y build-essential cmake gnuradio g++ \
|
|
|
|
python-mako python-six libogg-dev \
|
2019-06-05 13:36:58 +02:00
|
|
|
libvorbis-dev libpng-dev libpng++-dev \
|
2019-09-01 21:30:57 +02:00
|
|
|
swig libjsoncpp-dev
|
2018-11-30 17:32:10 +01:00
|
|
|
cd /tmp
|
|
|
|
git clone https://github.com/gnuradio/volk.git
|
|
|
|
cd volk
|
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
cmake ..
|
2019-06-05 13:36:58 +02:00
|
|
|
make -j $(nproc --all)
|
2018-11-30 17:32:10 +01:00
|
|
|
sudo make install
|
|
|
|
```
|
|
|
|
|
2018-12-01 23:51:46 +01:00
|
|
|
### Installation from source
|
2016-01-07 20:24:51 +01:00
|
|
|
|
2019-09-12 17:13:25 +02:00
|
|
|
```bash
|
|
|
|
git clone https://gitlab.com/librespacefoundation/satnogs/gr-satnogs.git
|
|
|
|
cd gr-satnogs
|
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
cmake ..
|
|
|
|
make -j $(nproc --all)
|
|
|
|
sudo make install
|
|
|
|
```
|
2016-01-07 20:24:51 +01:00
|
|
|
|
|
|
|
If this is the first time you are building the gr-satnogs module run
|
|
|
|
`sudo ldconfig`
|
|
|
|
|
2016-10-12 01:45:21 +02:00
|
|
|
#### Advanced
|
|
|
|
By default, the **SatNOGS** module will use the default installation prefix.
|
|
|
|
This highly depends on the Linux distribution. You can use the `CMAKE_INSTALL_PREFIX`
|
|
|
|
variable to alter the default installation path.
|
2018-01-03 00:34:32 +01:00
|
|
|
E.g:
|
2016-10-12 01:45:21 +02:00
|
|
|
|
|
|
|
`cmake -DCMAKE_INSTALL_PREFIX=/usr ..`
|
|
|
|
|
2016-10-26 19:36:07 +02:00
|
|
|
Also, by default the build system enables a set of blocks used for debugging
|
2019-09-03 15:23:39 +02:00
|
|
|
during the development. The enable/disable switch is controlled through the
|
2016-10-26 19:36:07 +02:00
|
|
|
`INCLUDE_DEBUG_BLOCKS` boolean variable. If for example, you want to disable the
|
2016-10-12 01:45:21 +02:00
|
|
|
debugging blocks, the **CMake** command would be:
|
|
|
|
|
|
|
|
`cmake -DINCLUDE_DEBUG_BLOCKS=OFF ..`
|
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
Another common control option is the library suffix of the Linux distribution.
|
2016-10-12 01:45:21 +02:00
|
|
|
There are distributions like Fedora, openSUSE, e.t.c that the their 64-bit version
|
|
|
|
use the `lib64` folder to store the 64-bit versions of their dynamic libraries.
|
|
|
|
On the other hand, distributions like Ubuntu do the exact opposite. They use
|
|
|
|
`lib` directory for the libraries of the native architecture and place the 32-bit versions
|
|
|
|
on the `lib32` directory. In any case the correct library directory suffix
|
|
|
|
can be specified with the `LIB_SUFFIX` variable. For example:
|
|
|
|
|
|
|
|
`cmake -DLIB_SUFFIX=64 -DCMAKE_INSTALL_PREFIX=/usr -DINCLUDE_DEBUG_BLOCKS=OFF ..`
|
|
|
|
|
|
|
|
will install the libraries at the `/usr/lib64` directory.
|
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
## Development Guide
|
|
|
|
The development is performed on the `master` branch.
|
|
|
|
For special cases where a team of developers should work an a common feature,
|
|
|
|
maintainers may add a special branch on the repository.
|
|
|
|
However, it will be removed at the time it will be merged on the `master` branch.
|
|
|
|
All developers should derive the `master` branch for their feature branches and merge
|
|
|
|
requests should also issued at this branch.
|
|
|
|
Developers should ensure that do **not** alter the CMake version tags in any
|
|
|
|
way.
|
|
|
|
It is a responsibility of the maintainers team.
|
|
|
|
|
|
|
|
Before submitting a new merge request, rebase the `master` branch and
|
|
|
|
confirm that the automated CI tests have successfully completed for all platforms
|
|
|
|
mandated by the `.gitlab-ci.yml` recipe.
|
|
|
|
|
2019-09-12 18:45:45 +02:00
|
|
|
### Coding style
|
|
|
|
For the C++ code, `gr-satnogs` uses a slightly modified version of the
|
|
|
|
**Stroustrup** style, which is a nicer adaptation of the well known K&R style.
|
|
|
|
In addition, we decided to decrease the indentation from 4 to 2 spaces.
|
|
|
|
This choice was made mainly to avoid braking statements with long namespaces.
|
|
|
|
We also found ourselves, that with smaller indentation we use more descriptive
|
|
|
|
variable names, avoiding frustrating abbreviations without phoenixes etc.
|
|
|
|
|
|
|
|
At the root directory of the project there is the `astyle` options
|
|
|
|
file `.astylerc` containing the proper configuration.
|
|
|
|
Developers can import this configuration to their favorite editor.
|
|
|
|
In addition the `hooks/pre-commit` file contains a Git hook,
|
|
|
|
that can be used to perform before every commit, code style formatting
|
|
|
|
with `astyle` and the `.astylerc` parameters.
|
|
|
|
To enable this hook developers should copy the hook at their `.git/hooks`
|
|
|
|
directory.
|
|
|
|
Failing to comply with the coding style described by the `.astylerc`
|
|
|
|
will result to failure of the automated tests running on our CI services.
|
|
|
|
So make sure that you either import on your editor the coding style rules
|
|
|
|
or use the `pre-commit` Git hook.
|
|
|
|
|
|
|
|
|
|
|
|
Regarding the naming of files and variables, we use the underscore naming
|
|
|
|
convention (`do_this`) instead of camel cases (`DoNotDoThis`).
|
|
|
|
Exception to this rule is the CMake module filenames. In addition,
|
|
|
|
all private variables of a C++ class, should start with the prefix
|
|
|
|
`d_` allowing the developers to spot easily private members of the object.
|
|
|
|
|
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
### Adding a new Satellite Demodulator
|
|
|
|
Demodulators are responsible for filtering, resampling and demodulating an
|
|
|
|
analog signal and converting it into suitable form, for a decoder to be able
|
|
|
|
to extract the frame and its data. In most cases this is a simple bit stream.
|
|
|
|
|
|
|
|
If the existing demodulators (FSK, AFSK, BPSK, DUV) do not meet
|
|
|
|
the requirements of a satellite, you may submit your custom demodulator.
|
|
|
|
Please make sure that you put the GNU Radio Companion files in the `apps/flowgraphs`
|
|
|
|
directory.
|
|
|
|
|
|
|
|
### Adding a new Satellite Decoder
|
|
|
|
With the new architecture, adding a new satellite has become an easy and straight
|
|
|
|
forward task.
|
|
|
|
The decoders are implemented using the following approach.
|
|
|
|
|
|
|
|
There is a generic block called `frame_decoder`.
|
|
|
|
This block should not be altered at any case. If you find yourself in a situation
|
|
|
|
that you need to apply modifications on this block, raise an issue on the
|
|
|
|
[issue tracker](https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/issues)
|
|
|
|
The `frame_decoder` block accepts two parameters. A `satnogs::decoder`
|
|
|
|
object and the item size of the input stream. Internally, the `frame_decoder`
|
|
|
|
invokes the `decode()` method of the `satnogs::decoder` class.
|
|
|
|
|
|
|
|
The `satnogs::decoder` class, is a virtual class providing a generic API that
|
|
|
|
every derived decoder class should implement.
|
|
|
|
The core of this class is the
|
|
|
|
|
2019-09-12 18:45:45 +02:00
|
|
|
```cpp
|
|
|
|
decoder_status_t
|
|
|
|
decode(const void *in, int len)
|
2019-09-03 15:23:39 +02:00
|
|
|
```
|
|
|
|
method. This method accepts an input buffer `in`. The type of the items depends
|
|
|
|
on the implementation. It also takes the `len` argument specifying the number
|
|
|
|
of items available in the `in` buffer.
|
|
|
|
The method returns a `decoder_status_t` class object.
|
|
|
|
|
2019-09-12 18:45:45 +02:00
|
|
|
```cpp
|
2019-09-03 15:23:39 +02:00
|
|
|
class decoder_status
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
int consumed;
|
|
|
|
bool decode_success;
|
|
|
|
pmt::pmt_t data;
|
|
|
|
|
|
|
|
decoder_status () :
|
|
|
|
consumed(0),
|
|
|
|
decode_success(false),
|
|
|
|
data(pmt::make_dict())
|
|
|
|
{
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
typedef class decoder_status decoder_status_t;
|
|
|
|
```
|
|
|
|
The class contains three fields that allow the `frame_decoder` block to operate
|
|
|
|
continuously, without any further assistance. It is responsibility of the derived
|
|
|
|
decoder class to properly set the values to these fields.
|
|
|
|
|
|
|
|
* The `consumed` class should contain the number of items consumed during the
|
|
|
|
`decode()` method invocation. It is ok to consume 0, less than `len` or `len`
|
|
|
|
items but not more.
|
|
|
|
* `decode_success` should be set to true only if a frame was successfully
|
|
|
|
decoded and its data are available on the `data` field.
|
|
|
|
* `data` field is a `pmt::pmt_t` dictionary containing the decoded data and other
|
|
|
|
information regarding it, using the `gr-satnogs` metadata format. More about them
|
|
|
|
in the [Metadata](#metadata) section
|
|
|
|
|
2019-09-12 17:13:25 +02:00
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
### Metadata
|
|
|
|
Each decoder generates a `pmt::pmt_t` dictionary containing the decoded data and
|
|
|
|
other information regarding the decoded frame.
|
|
|
|
The `gr::satnogs::metadata` class provides a set of commonly used metadata
|
|
|
|
keys.
|
|
|
|
The table below describes some of them:
|
|
|
|
|
|
|
|
| Key | Description |
|
|
|
|
| --- | ----------- |
|
|
|
|
| pdu | This string field contains the decoded data in base64 form |
|
|
|
|
| time | The time at which the frame was received. Time is represented in an ISO 8601 string with microsecond accuracy |
|
|
|
|
| crc_valid | Boolean indicating if the CRC check has been successfully passed |
|
|
|
|
| freq_offset | Float value indicating the frequency offset observed |
|
|
|
|
| corrected_bits | `uint64_t` with the number of corrected bits |
|
|
|
|
| symbol_erasures | `uint64_t` with the number of erased symbols |
|
|
|
|
| sample_start | `uint64_t` with the sample index at which the decoder identified the start of the frame |
|
|
|
|
| sample_cnt | `uint64_t` with the number of samples of a valid frame. `sample_start + sample_cnt` specify the length of a frame in samples |
|
|
|
|
|
|
|
|
The method `Json::Value
|
|
|
|
metadata::to_json(const pmt::pmt_t& m)` is converts the dictionary `m`
|
|
|
|
into a valid JSON object. There is also the `std::string
|
|
|
|
metadata::keys()` static method which returns a list with the available
|
|
|
|
metadata keys. This method is also available in Python through the Swig interface.
|
|
|
|
For example:
|
|
|
|
|
2019-09-12 18:45:45 +02:00
|
|
|
```python
|
2019-09-03 15:23:39 +02:00
|
|
|
$ python
|
|
|
|
>>> import satnogs
|
|
|
|
>>> satnogs.metadata.keys()
|
|
|
|
'[pdu, crc_valid, freq_offset, corrected_bits, time, sample_start, sample_cnt, symbol_erasures]'
|
|
|
|
>>>
|
|
|
|
```
|
|
|
|
|
|
|
|
Using the `json_converter` block, developers can convert a `pmt::pmt_t`
|
|
|
|
dictionary of a decoder into a `pmt::pmt_t` blob,
|
|
|
|
containing the raw bytes of the JSON string, which then can be passed to a UDP
|
|
|
|
sink targeting the `satnogs-client`.
|
|
|
|
The `json_converter` block accepts also a string that may be used to inject
|
|
|
|
an arbitrary number of additional information under the `extra` JSON field.
|
2019-09-12 18:45:45 +02:00
|
|
|
Of course, this string should be in a JSON valid format.
|
|
|
|
|
|
|
|
For example, such a JSON string with information on the extra field could be like
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"corrected_bits" : 0,
|
|
|
|
"extra" :
|
|
|
|
{
|
|
|
|
"x" : 3,
|
|
|
|
"y" : "test"
|
|
|
|
},
|
|
|
|
"pdu" : "igAg7nRAOCAniUMAtIoAAAAAAAAAAAAAAABNJ4kfAFD4wwAfAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
|
|
|
|
"symbol_erasures" : 0,
|
|
|
|
"time" : "2019-09-11T15:39:13.514138Z"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-01-07 20:24:51 +01:00
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
### Release Policy
|
2018-11-30 12:11:43 +01:00
|
|
|
The `gr-satnogs` OOT module uses the `major.api-compatibility.minor`
|
2019-09-03 15:23:39 +02:00
|
|
|
versioning scheme. is used by the
|
|
|
|
[satnogs-client](https://gitlab.com/librespacefoundation/satnogs/satnogs-client),
|
|
|
|
so the release and versioning policy is based on how the
|
|
|
|
`satnogs-client` is affected by the changes on the `gr-satnogs` software.
|
2018-07-18 12:39:00 +02:00
|
|
|
|
|
|
|
* Minor changes, bug fixes or improvements that do not affect in anyway
|
|
|
|
the `satnogs-client` advance the `minor` version.
|
2019-09-03 15:23:39 +02:00
|
|
|
* The `api-compatibility` indicates changes that require modifications
|
|
|
|
on `satnogs-client` but do not brake the backwards compatibility
|
|
|
|
(e.g a new satellite decoder).
|
|
|
|
In other words, the `satnogs-client` should continue to operate normally
|
|
|
|
without any modifications. Changes on `satnogs-client` should be performed
|
|
|
|
only to integrate the new features.
|
2018-07-18 12:39:00 +02:00
|
|
|
* `major` version advances when the changes break backwards compatibility with
|
|
|
|
the `satnogs-client`.
|
|
|
|
|
|
|
|
For every release change a tag with the corresponding version is created.
|
2019-09-03 15:23:39 +02:00
|
|
|
Releases can be retrieved by the
|
|
|
|
[tags](https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/tags) page.
|
|
|
|
|
|
|
|
## Website and Contact
|
|
|
|
For more information about SatNOGS please visit our [site](https://satnogs.org/)
|
|
|
|
and our [community forums](https://community.libre.space).
|
|
|
|
You can also chat with the SatNOGS community at
|
|
|
|
[https://riot.im/app/#/room/#satnogs:matrix.org](https://riot.im/app/#/room/#satnogs:matrix.org),
|
|
|
|
or on IRC at `#satnogs` on Freenode.
|
|
|
|
For chatting around the development and for watching the changes in project's gitlab repositories,
|
|
|
|
join in [https://riot.im/app/#/room/#satnogs-dev:matrix.org](https://riot.im/app/#/room/#satnogs-dev:matrix.org)
|
|
|
|
or the IRC channel `#satnogs-dev` on Freenode.
|
2018-07-18 12:39:00 +02:00
|
|
|
|
2016-01-07 20:24:51 +01:00
|
|
|
## License
|
|
|
|
|
2019-09-03 15:23:39 +02:00
|
|
|
![SatNOGS](docs/assets/SatNOGS-logo-vertical-black.png)
|
|
|
|
![Libre Space Foundation](docs/assets/LSF_HD_Horizontal_Color1-300x66.png)
|
|
|
|
© 2016-2019 [Libre Space Foundation](https://libre.space).
|
2016-01-07 20:24:51 +01:00
|
|
|
|
2018-01-03 00:34:32 +01:00
|
|
|
Licensed under the [GPLv3](LICENSE).
|
2019-09-03 15:23:39 +02:00
|
|
|
|