Add developers information on README
This commit is contained in:
Manolis Surligas
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 is an out-of-tree GNU Radio module that provides all the necessary tools
|
||||
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
|
||||
* GNU Radio ( > 3.7.7 )
|
||||
* GNU Radio ( > 3.7.11 )
|
||||
* CMake ( > 3.1)
|
||||
* G++ (with C++11 support)
|
||||
* VOLK
|
||||
|
|
@ -59,13 +63,13 @@ E.g:
|
|||
`cmake -DCMAKE_INSTALL_PREFIX=/usr ..`
|
||||
|
||||
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
|
||||
debugging blocks, the **CMake** command would be:
|
||||
|
||||
`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
|
||||
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
|
||||
|
|
@ -77,28 +81,165 @@ can be specified with the `LIB_SUFFIX` variable. For example:
|
|||
|
||||
will install the libraries at the `/usr/lib64` directory.
|
||||
|
||||
## Website
|
||||
For more indormation about SatNOGS please visit our [site](https://satnogs.org/).
|
||||
## 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.
|
||||
|
||||
## 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`
|
||||
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.
|
||||
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.
|
||||
|
||||
* Minor changes, bug fixes or improvements that do not affect in anyway
|
||||
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 `satnogs-client` should continue to operate normally without any modifications.
|
||||
Changes on `satnogs-client` should be performed only to integrate the new features.
|
||||
* 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.
|
||||
* `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.
|
||||
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
|
||||
|
||||
© 2016,2017,2018 [Libre Space Foundation](http://librespacefoundation.org).
|
||||
|
||||
|
||||
© 2016-2019 [Libre Space Foundation](https://libre.space).
|
||||
|
||||
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