Outernet L-band on Raspbian¶
This guide shows how to deploy Outernet software on a Raspberry Pi using the stock Raspbian image, for use with Outernet’s global L-band service.
Warning
This guide is a work in progress and may contain wrong and/or incomplete information. Please use the issue tracker or our forums to discuss any problems you encounter.
version | 1.0a2 |
status | unstable/draft |
Guide contents¶
Requirements¶
In order to follow this guide, you will need:
- Raspberry Pi
- 4GB or larger microSD card with a Raspbian image
- SDR radio dongle
- LNA
- antenna with sufficient gain
- Internet connection configured on Raspbian
- knowledge of Linux command line
The radio, LNA, and antenna, can be purchased through Outernet either individually or as a kit. You may also want to have:
- HDMI monitor
- HDMI cable
- USB or wireless keyboard
- USB or wireless mouse
This guide is written against the following version of Raspbian:
Raspbian version | May 2016 |
Kernel version | 4.4 |
Download URL | http://bit.ly/raspbian-jessie-2016-05-27 |
Note
We will not go into the details of how the Raspbian microSD cards are created. That is left as an exercise for the reader.
Introduction¶
While the image is downloading, let’s take a brief tour of how the L-band service works.
The files that are datacast by Outernet are encoded, modulated, and sent to several Inmarsat satellites. These satellites transmit the radio waves in the L band frequency range. The waves are received by a radio on your receiver and then passed on to the software demodulator. The demodulator turns the analog signal into bits and then passes them onto the decoder, which extracts the file information from the data and reconstructs the files on local storage.
The software components involved in this process are:
- the demodulator (sdr100)
- the decoder (ondd)
- file indexer (FSAL)
- web-based UI (Librarian)
Despite all this software coming from a single vendor, they don’t come as a single package for the reasons of flexibility and so that various components can be replaced by others with same or similar functionality in future. Because of this, much of this guide is going to be about ensuring that these pieces of software work together.
Note
Although these pieces of software are all part of the Outernet software eco-system, which is predominantly open-source, some of the executables are closed-source.
Virtually all of the software involved in this set-up is meant to be used as long-running background processes (a.k.a. daemons). Some of the programs already provide features that let them run as proper well-behaved daemons, while others do not. Where appropriate, we will use screen as a quick-and-dirty workaround (i.e., poor man’s daemonization) solution.
Software installation¶
In this section, we will install all the necessary software and ensure the system is prepared to run it. The next section will discuss the programs’ usage.
Preparing the device¶
Connect your Raspberry Pi to a router either using WiFi (Raspberry Pi 3) or LAN cable (all versions). Also plug in the SDR (software defined radio; rtlsdr dongle), and attach the LNA and antenna. If you want to use a keyboard and a monitor, hook those up as well.
Downloading the installer kit¶
The installer and its files are now distributed as part of the Outernet L-band Service on Raspberry Pi respository on GitHub. Download the latest stable version and extract it:
$ tar xvf master.tar.gz
Running the installer¶
Enter the unpacked directory and run the installer:
$ cd outernet-rpi-lband-master
$ sudo ./installer.sh
The installer will ask you a few things.
Configure udev¶
The radio devices are accessible only to root user by default. If you wish to
run the Outernet software as a non-root user (recommended), you should answer
y
to this question. Udev will be reconfigured so that the radio device is
accessible to non-root users.
Note
If you choose to have the installer reconfigure udev, you will also need to reconnect the radio for the changes to take effect.
Choose cache and storage paths¶
Cache path is where the decoder stores partial downloads. The storage directory is where completed downloads will be written. If you wish to customize these paths, then enter the correct paths. Otherwise, press Enter to accept the defaults.
You can also have the installer create these paths for you. When you choose
this option, the directories are created, and also set to 777 permissions. You
can either answer with n
to this question, and create the paths yourself
with appropriate permissions, or answer y
to have the installer take care
of it.
Install the web-based interface¶
The installer can install and configure the web-based interface called
Librarian. This is not necessary to receive
files, and you can always set up your own methods of accessing the files (e.g.,
FTP, HTTP server, etc). If you wish to try Librarian out, answer y
to this
question.
Warning
If you choose to install the web-based interface, your Raspbian install will be upgraded to Jessie testing. The process may take a while to complete, and many packages that are completely unrelated will be upgraded (e.g., Libre Office). Also note that build tools will be installed in the process. This is a requirement for some of the packages that Librarian depends on.
Uninstalling the software¶
To uninstall the software, run the installer and pass uninstall
argument:
$ cd outernet-rpi-lband-master
$ sudo ./installer.sh uninstall
Note
Uninstalling does not remove downloaded files or settings.
Running the software stack¶
Although the individual commands can be run directly in the terminal, we will use screen so the programs can be run in the background even after we log out of the system.
Screen basics¶
Screen is a terminal multiplexer. Once started, you will be in a shell that does not look much different than the normal shell. The special key combination Ctrl-A can be used to give special screen-specific commands.
To create more shells (called ‘windows’), press Ctrl-A Ctrl-C. To switch between open shells, use Ctrl-A Ctrl-A (switches between the current and last used shell), or Ctrl-A Ctrl-‘ to get a list of shells to switch to.
To exit screen without closing any of the open shells, press Ctrl-A Ctrl-D. To
reattach to the closed shells, run screen with screen -rD
command.
Type man screen
for complete usage documentation and/or use Ctrl-A Ctrl-?
to get information about screen shortcuts.
Running the programs¶
Programs are run in this order:
- demodulator (demod)
- decoder (decoder)
- web based interface (librarian)
Let’s start screen. We will name this session ‘outernet’ so we can refer to it in future.
$ screen -S outernet
If you haven’t reconfigured udev during installation, you will need to run screen as root:
$ sudo screen -S outernet
Running the demodulator¶
In the first shell, let’s start the demodulator. We first need to find out the
profile we should use. To do this run demod-presets
without any arguments.
Once we know the profile name (in this example, we will use ‘euraf’), we run
the following command:
$ demod-presets euraf
Running the decoder¶
Now we need to create another shell with Ctrl-A Ctrl-C. In the new shell, we will run the decoder.
$ decoder
Starting the indexer¶
After creating a new shell with Ctrl-A Ctrl-C, the indexer is started using the
fsal
command:
$ fsal --conf /etc/fsal.ini
Starting the web UI¶
We create yet another shell with Ctrl-A Ctrl-C. In this shell, we will start Librarian:
$ librarian --conf /etc/librarian.ini
Within less than a minute, the server will start responding on the port 8080.
Detaching from the screen session¶
After starting all the software, we may now detach from the screen session by using the Ctrl-A Ctrl-D combination. This session will continue to run in the background as long as the device has power and is not rebooted.
At some later time, if we wish to see what the programs are doing, we can
reattach to the session with screen -rDS outernet
.