Thanks for taking my writing in stride and you are right: being deeply involved in something might narrow one's vision, especially compared to people not in the know. But from your reaction I am confident we're getting ahead in making gr-satellites even more accessible.
Your suggestion for a Wiki on GitHub is a good one and I will certainly be a contributor. I am not sure if this Wiki will need an administrator or moderator, but if it does then I'm willing to help out there, too, if no better candidate is available.
As for the README, I'm not very familiar with GitHub and how to create a pull request, but I'll look into it tonight. As you can tell from my previous post I do have some ideas on how to improve it.
I'll leave it at that for now. 73 de Hans
On 09/18/2019 07:15 AM, Daniel Estévez wrote:
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.
- 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/
The above is very ambiguous. It indicates "why" but not "how".
- Do I have to compile and install all this myself, or can they be
found in my distro's repositories?
- Are they all installed with ./configure, make, make install or are
there other methods?
The answers are (I think, but not sure):
- You do have to compile and install the first three, but you can use
swig from you distro's repository.
- 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:
- 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.
- 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.