[amsat-bb] How to tame gr-satellites?

Tue Sep 17 23:15:59 UTC 2019

Hi Hans,

I'm taking your email as constructive criticism, so I'll discuss on
ideas about how to improve the documentation or procedures rather than
on how many people use GNU Radio or gr-satellites and whether this is
satisfactory.

One problem is that some things that might seem so obvious when you are
really involved with some software/framework are not obvious at all for
newcomers. With these things, many times a few extra sentences in the
documentation can help a lot. And usually the best advice comes from
newcomers: the pitfalls they found and how to help others avoid them.

This said, answers to particular points below.

El 17/9/19 a las 8:58, Hans BX2ABT escribió:

> On the gr-satellites github page it says you need to fulfill some
> dependency requirements before compiling gr-satellites.
> 
> [quote]
> 
>   * Phil Karn's KA9Q |libfec|. A fork that builds in modern linux
>     systems can be found here <https://github.com/daniestevez/libfec>.
>   * construct <https://construct.readthedocs.io/en/latest/>, at least
>     version 2.9.
>   * requests <https://pypi.org/project/requests/2.7.0/>.
>   * swig <http://www.swig.org/>
> 
> [/unquote]
> 
> The above is very ambiguous. It indicates "why" but not "how".
> 
> 1) Do I have to compile and install all this myself, or can they be
> found in my distro's repositories?
> 
> 2) Are they all installed with ./configure, make, make install or are
> there other methods?
> 
> The answers are (I think, but not sure):
> 
> 1) You do have to compile and install the first three, but you can use
> swig from you distro's repository.
> 
> 2) libfec is compiled with ./configure, make, make install. Construct
> and requests can be found in distro's repositories but are probably
> older versions and they are called (on Debian systems) python-construct
> and python requests. So the best way to go is to install by using pip.

The problem with this is that it depends a lot on what particular
distribution or setup you are using. Maybe your distribution ships a
recent version of GNU Radio and you installed that. Maybe you compiled
it from source. Maybe swig came as a dependency as you installed GNU
Radio. Maybe not and you need to install it explicitly. Maybe your
distribution has packaged recent enough versions of construct or
requests. Maybe not and you are better off using pip. Or maybe you
Python installation is based on Anaconda, so you install all Python
packages using conda. Or maybe you used PyBOMBs to install GNU Radio and
gr-satellites instead of your distributions' package manager. Or maybe
you are using Arch, which has an AUR package for gr-satellites.

Certainly it is hard (especially for a single person) to give precise
instructions covering all these use cases.

However, I see a couple possible solutions:

1) Identify the case that typically should work for most people. This is
more or less what you said: install GNU Radio, SWIG and requests through
your package's manager, install construct through pip, install libfec
from source, and install gr-satellites from source.

I think this would be the recommended steps in Ubuntu 19.04, which seems
the most popular distribution, and is also what I'm doing on Gentoo.

2) Try to get help from the community to describe precise installation
steps for different distributions and/or setups. Actually Github
supports Wiki pages for the repositories. I'm not currently using this
feature, but perhaps it could be useful to open up an "Installation"
wiki page where people can detail installation steps for different distros.

I think option 2) might be more desirable, but I'm not sure if I could
get enough people to engage and maintain good quality and up to date
instructions (this is important as new distros get released).

Option 1) might be much easier to set up and could be accomplished by
adding an "Installation of dependencies" section to the README.

I agree that having some installation instructions that you can simply
copy & paste onto the command line can save time and effort even to very
experienced people.

> Another example. I've got GNU Radio and gr-satellites installed and I
> figured out where the .grc files were hiding. I open one and am greeted
> with loads of red because of missing blocks. There is also another
> warning that says "Port is not connected". I've been reading and
> searching the web for two hours already, but still haven't got a clue
> about the "why" and certainly not about "how" to proceed now. I don't
> mind trouble shooting, but then I need at least some hints to get
> started. Right now I haven't.

This might be because you haven't installed the hierarchical flowgraphs.
It is described in the README. Ideally I would like this step to run
automatically from CMake, but I haven't been able to find how.
Therefore, it needs to be run manually. Maybe with the updated CMake
infrastructure in GNU Radio 3.8 it will be easier to do this automatically.

If you have indeed installed the hierarchical flowgraphs and are getting
missing blocks, please detail which blocks are missing.

> Third example: last year I did have a working GNURadio/gr-satellites
> setup with pyBOMBS (before that broke). I did see some telemetry rolling
> down a terminal window, but the last block in every flow graph is always
> this SatNogs Telemetry Forwarder. Tried to figure out if it was actually
> forwarding, where it ended up, where I could see my forwarded data.
> Couldn't figure it out, couldn't find any documentation or examples, so
> I gave up.

There is also either a telemetry parser block or a debug message block
as last block (in parallel with the telemetry forwarder) which is in
charge of printing the telemetry values that appear in the terminal window.

Regarding the SatNOGS telemetry forwarder, this is documented in the
README, in a section called "Submitting telemetry to SatNOGS", which I
think already answers some of your questions.

As you'll see, you need to specify your callsign and location to submit
telemetry to SatNOGS, so unless you did set these, then the forwarder
was simply doing nothing.

The questions that occur to me that are not explicitly treated in the
documentation are:

* How do I know if this is working? It happens that the forwarder will
print nothing when a frame is submitted correctly. However, if there is
some error, the forwarder will print an error message. I figured out
this was the most useful approach, as it would be too verbose to print
out a message anytime that a packet is submitted successfully. However,
as this design choice is not obvious, perhaps a sentence should be added
to the documentation.

* Where do the frames end up in SatNOGS DB. Of course the answer is that
you need to got to SatNOGS DB webpage, select the particular satellite,
scroll to the bottom, and there you have some links to download the
frames in the database (which in my experience might or might not work
depending on how much data you request). However, I think that this
functionality should be documented from SatNOGS side rather than from
the gr-satellites side. Somehow, in the 2Submitting telemetry to
SatNOGS" section of the README it is assumed that you know what SatNOGS
DB is.

So to wrap up:

It is possible to create a Wiki page on Github were people can
contribute with documentation to help others (installation instructions,
setup descriptions, interfacing with other software). I can set this up.
Would be people interested in contributing?

Regarding the README, I'm open for pull requests with improvements or
with concreted ideas about how to improve it.

73,

Dani.