Add developers information on README
This commit is contained in:
parent
14382ddc4f
commit
17f91dbb27
175
README.md
175
README.md
|
@ -1,11 +1,15 @@
|
||||||
# gr-satnogs: SatNOGS GNU Radio Out-Of-Tree Module
|
# gr-satnogs: SatNOGS GNU Radio Out-Of-Tree Module
|
||||||
gr-satnogs is an out-of-tree GNU Radio module that provides all the necessary tools
|
![gr-satnogs](docs/assets/gr-satnogs.png)
|
||||||
for decoding signals from various scientific and academic sattelites.
|
|
||||||
|
|
||||||
## Install
|
gr-satnogs is an out-of-tree GNU Radio module that provides all the necessary tools
|
||||||
|
for decoding signals from various scientific and academic satellites.
|
||||||
|
It also provides blocks for debugging and experimenting with known satellite
|
||||||
|
telecommunication schemes.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
### Requirements
|
### Requirements
|
||||||
* GNU Radio ( > 3.7.7 )
|
* GNU Radio ( > 3.7.11 )
|
||||||
* CMake ( > 3.1)
|
* CMake ( > 3.1)
|
||||||
* G++ (with C++11 support)
|
* G++ (with C++11 support)
|
||||||
* VOLK
|
* VOLK
|
||||||
|
@ -59,13 +63,13 @@ E.g:
|
||||||
`cmake -DCMAKE_INSTALL_PREFIX=/usr ..`
|
`cmake -DCMAKE_INSTALL_PREFIX=/usr ..`
|
||||||
|
|
||||||
Also, by default the build system enables a set of blocks used for debugging
|
Also, by default the build system enables a set of blocks used for debugging
|
||||||
during the development. The enable/disable switch is controled through the
|
during the development. The enable/disable switch is controlled through the
|
||||||
`INCLUDE_DEBUG_BLOCKS` boolean variable. If for example, you want to disable the
|
`INCLUDE_DEBUG_BLOCKS` boolean variable. If for example, you want to disable the
|
||||||
debugging blocks, the **CMake** command would be:
|
debugging blocks, the **CMake** command would be:
|
||||||
|
|
||||||
`cmake -DINCLUDE_DEBUG_BLOCKS=OFF ..`
|
`cmake -DINCLUDE_DEBUG_BLOCKS=OFF ..`
|
||||||
|
|
||||||
Another common control option is the library sugffix of the Linux distribution.
|
Another common control option is the library suffix of the Linux distribution.
|
||||||
There are distributions like Fedora, openSUSE, e.t.c that the their 64-bit version
|
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.
|
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
|
On the other hand, distributions like Ubuntu do the exact opposite. They use
|
||||||
|
@ -77,28 +81,165 @@ can be specified with the `LIB_SUFFIX` variable. For example:
|
||||||
|
|
||||||
will install the libraries at the `/usr/lib64` directory.
|
will install the libraries at the `/usr/lib64` directory.
|
||||||
|
|
||||||
## Website
|
## Development Guide
|
||||||
For more indormation about SatNOGS please visit our [site](https://satnogs.org/).
|
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.
|
||||||
|
|
||||||
## Release Policy
|
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.
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
```
|
||||||
|
decoder_status_t decode (const void *in, int len)
|
||||||
|
```
|
||||||
|
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.
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ 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.
|
||||||
|
Of course, this string should be in a JSON valid format.
|
||||||
|
|
||||||
|
### Release Policy
|
||||||
The `gr-satnogs` OOT module uses the `major.api-compatibility.minor`
|
The `gr-satnogs` OOT module uses the `major.api-compatibility.minor`
|
||||||
versioning scheme.
|
versioning scheme. is used by the
|
||||||
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](https://gitlab.com/librespacefoundation/satnogs/satnogs-client),
|
||||||
satnogs client is affected by the changes on the `gr-satnogs` software.
|
so the release and versioning policy is based on how the
|
||||||
|
`satnogs-client` is affected by the changes on the `gr-satnogs` software.
|
||||||
|
|
||||||
* Minor changes, bug fixes or improvements that do not affect in anyway
|
* Minor changes, bug fixes or improvements that do not affect in anyway
|
||||||
the `satnogs-client` advance the `minor` version.
|
the `satnogs-client` advance the `minor` version.
|
||||||
* The `api-compatibility` indicates changes that require modifications on `satnogs-client` but do not brake the backwards compatibility (e.g a new satallite decoder). In other words,
|
* The `api-compatibility` indicates changes that require modifications
|
||||||
the `satnogs-client` should continue to operate normally without any modifications.
|
on `satnogs-client` but do not brake the backwards compatibility
|
||||||
Changes on `satnogs-client` should be performed only to integrate the new features.
|
(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.
|
||||||
* `major` version advances when the changes break backwards compatibility with
|
* `major` version advances when the changes break backwards compatibility with
|
||||||
the `satnogs-client`.
|
the `satnogs-client`.
|
||||||
|
|
||||||
For every release change a tag with the corresponding version is created.
|
For every release change a tag with the corresponding version is created.
|
||||||
Releases can be retrieved by the [tags](https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/tags) page.
|
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.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
© 2016,2017,2018 [Libre Space Foundation](http://librespacefoundation.org).
|
![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).
|
||||||
|
|
||||||
Licensed under the [GPLv3](LICENSE).
|
Licensed under the [GPLv3](LICENSE).
|
||||||
|
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
After Width: | Height: | Size: 3.4 KiB |
Binary file not shown.
After Width: | Height: | Size: 8.6 KiB |
Loading…
Reference in New Issue