SatNOGS Client Ansible

Introduction

SatNOGS Client Ansible is the suggested method to install SatNOGS Client (and friends) to a system. It currently supports Raspbian and Debian (stretch and buster).

Raspbian

For Raspberry Pi, which is the reference platform for SatNOGS, a Raspbian image with SatNOGS Client Ansible pre-installed is available.

Debian

Skip this section if you are using SatNOGS Raspbian image and SatNOGS Client Setup. Follow these instructions if you are provisioning SatNOGS to Debian from another host or are installing on the same host.

These sections contain generic instructions for installing SatNOGS Client on a Debian system.

Prerequisites

• A target Debian system. To install Debian please follow the Debian Installation Guide and chose the net installer if you want to run a headless server. The target system can be the host itself.
• A user (referenced later as youruser) which is member of 'sudo' group exists on the target system.
• An SSH server running on the target system.
• A host system with Git and latest version of Ansible installed. To install Ansible on Debian, follow the Ansible Installation Guide.

Installation

On the host system run the following commands:

$ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
$ cd satnogs-client-ansible                              # Change to cloned repository directory
$ cp -r production.dist production                       # Copy dist configuration
$ vi production/inventory/hosts                          # Update file with your own target host e.g. 127.0.0.1, user and SSH password
$ ssh youruser@yourtargetsystem true                     # Test SSH connection to target system
$ ansible-playbook -i production/inventory -K site.yml   # Run Ansible playbook
$ ssh -t youruser@yourtargetsystem sudo satnogs-setup    # Setup SatNOGS client (see below)

SatNOGS Client Setup

satnogs-setup is a script for configuring a system installed with SatNOGS Client Ansible.

Initial Setup

Right after the first boot of the system, packages and the configuration tool itself must be updated. Follow the Updating instruction found below.

To configure a SatNOGS Client Ansible system:

1. SSH into the system and run sudo satnogs-setup; this will bring up the configuration menu
2. Set Basic Configuration (see below)
3. Select Apply and the Raspberry Pi will configure itself; this may take some time
4. Select Back to exit

You can always reconfigure the software by running sudo satnogs-setup again.

Basic Configuration

Setting	Description
SATNOGS_API_TOKEN	The API token assigned to your ground station on the SatNOGS Network website, please don’t share your api key as this can give access to anyone to upload and change things in network related to your station and its observations.
SATNOGS_RX_DEVICE	If you are using an RTL-SDR, this is rtlsdr. Other devices supported by gr-satnogs include usrpb200, usrp2, airspy/airspymini or hackrf; a complete list can be found here.
SATNOGS_STATION_ELEV	The height of your ground station above sea level in metres.
SATNOGS_STATION_ID	The numeric ID assigned to your station in the SatNOGS Network site when the groundstation was created.
SATNOGS_STATION_LAT	The latitude of your station. North is positive, south is negative.
SATNOGS_STATION_LON	The longitude of your station. East is positive, west is negative.
HAMLIB_UTILS_ROT_ENABLED	Whether or not to enable the Hamlibs rotator daemon. Rotctld is a software daemon that provides a network server to control a rotator on a serial port. If you don't have a rotator (like the No rotator setup), enter NO.
HAMLIB_UTILS_ROT_OPTS	Options for rotcld: For a yaesu rotator, use -m 601 -r /dev/ttyACM0 -s 9600 -T 0.0.0.0 For a SatNOGS rotator -m 204 -s 19200 -r /dev/ttyACM0 -C timeout=200 or -m 204 -s 19200 -r /dev/ttyUSB0 -C timeout=200

Advanced Setup

Changing these settings is not recommended unless you're developing SatNOGS.

A more detailed description on setting up a development environment using the SatNOGS reference setup is given in SatNOGS_Client_Development.

NOTE: To get your station online, you need to set SATNOGS_NETWORK_API_URL to https://network.satnogs.org/api/

Setting	Description
APT_REPOSITORY	This options allows you to change the SatNOGS packages repository. For example, to install unstable package builds use: deb http://download.opensuse.org/repositories/home:/librespace:/satnogs_unstable/Raspbian_10 ./
APT_KEY_URL	This options allows you to change the SatNOGS packages repository key URL. For example, to install unstable package builds use: http://download.opensuse.org/repositories/home:/librespace:/satnogs_unstable/Raspbian_10/Release.key
APT_KEY_ID	This options allows you to specify an alternative SatNOGS packages repository key ID.
SATNOGS_CLIENT_URL	If you to try a development version of satnogs-client, you can change the URL here. The URL needs to be in PIP format. Here are some examples: git+https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@master -- the 'master' branch (the current development version) of satnogs-client git+https://gitlab.com/jdoe/satnogs-client.git@new-feature -- the 'new-feature' branch of jdoe's fork of satnogs-client
SATNOGS_RADIO_GR_SATNOGS_VERSION	This options allows you to change the version of gr-satnogs package to be installed. For example: 1.5.1-1
RF_GAIN	RF Gain value for your SDR hardware. Defaults can be found here. For rtl-sdr possible values are the following: 0.0 0.9 1.4 2.7 3.7 7.7 8.7 12.5 14.4 15.7 16.6 19.7 20.7 22.9 25.4 28.0 29.7 32.8 33.8 36.4 37.2 38.6 40.2 42.1 43.4 43.9 44.5 48.0 49.6

Updating SatNOGS Client Software

To update SatNOGS software, including the configuration tool itself:

1. SSH into the system and (re-)run sudo satnogs-setup; this will bring up the configuration menu
2. Select Upgrade to upgrade all distribution packages to the latest; this may require a reboot. If this option is not available, running an Update will make it show up
3. Select Update to update the configuration tool
4. Select Apply and the Raspberry Pi will update itself; this may take some time
5. Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
6. Select Back to exit

WARNING: An update can potentially interrupt a running observation!

Upgrading from Debian 'stretch' to 'buster'

If you have already installed an older version of Debian or Raspbian SatNOGS image based on stretch (releases <= 2018080300), it is recommended to upgrade to buster. Support for stretch will be dropped with the next release of gr-satnogs.

Method 1: Reflashing and reinstalling (recommended)

The recommended method to upgrade to buster is reflashing the latest Raspbian SatNOGS image (or reinstalling latest Debian). Follow Raspberry Pi installation instructions and reinstall from scratch.

Method 2: Release upgrade using the configuration tool (advanced)

Make sure you have a stable connection to the internet and your SatNOGS client during this process. Release upgrades can consume a lot of time, data and storage.

To upgrade from stretch to buster using the configuration tool:

1. SSH into the system
2. Make sure you have enough free space on your SD card (>2GiB) by running df -h / on the console
3. Run sudo satnogs-setup to bring up the configuration menu
4. On the Advanced menu, enable SATNOGS_SETUP_RELEASE_UPGRADE_ENABLED option, in case there isn't an option like that available run first Update and then try again to enable it.
5. On the Main menu, select Apply and let Ansible apply the configuration
6. On the Main menu, select Upgrade. The script will check if there is a new release upgrade and ask you to proceed
7. Keep an eye on the upgrade progress; dpkg may prompt for changes
8. Once the upgrade is completed, satnogs-setup will ask for a reboot
9. After the reboot, make sure you are on the correct release by running lsb_release -a
10. Re-run sudo satnogs-setup and select Update and then Apply

Verification of correct installation

To see if satnogs-client has started successfully, check the logs with journalctl:

$ journalctl -u satnogs-client.service

You should see entries running approximately once per minute that look like this:

Oct 01 23:02:13 raspberrypi satnogs-client[6695]:  * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
Oct 01 23:02:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:02:14,466 - satnogsclient - INFO - [LD] Downlink thread waiting for first downlink packet
Oct 01 23:03:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:14,450 - apscheduler.executors.default - INFO - Running job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:03:14 UTC)" (scheduled at 2017-10-01 23:03:14.423393+00:00)
Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,324 - satnogsclient - DEBUG - Opening TCP socket: 127.0.0.1:5011
Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,325 - satnogsclient - DEBUG - Sending message: []
Oct 01 23:03:47 raspberrypi satnogs-client[6695]: 2017-10-01 23:03:47,327 - apscheduler.executors.default - INFO - Job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:04:14 UTC)" executed successfully
Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,453 - apscheduler.executors.default - INFO - Running job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:04:14 UTC)" (scheduled at 2017-10-01 23:04:14.423393+00:00)
Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,484 - apscheduler.executors.default - INFO - Running job "post_data (trigger: interval[0:02:00], next run at: 2017-10-01 23:04:14 UTC)" (scheduled at 2017-10-01 23:04:14.436367+00:00)
Oct 01 23:04:14 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:14,489 - apscheduler.executors.default - INFO - Job "post_data (trigger: interval[0:02:00], next run at: 2017-10-01 23:04:14 UTC)" executed successfully
Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,627 - satnogsclient - DEBUG - Opening TCP socket: 127.0.0.1:5011
Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,628 - satnogsclient - DEBUG - Sending message: []
Oct 01 23:04:15 raspberrypi satnogs-client[6695]: 2017-10-01 23:04:15,629 - apscheduler.executors.default - INFO - Job "get_jobs (trigger: interval[0:01:00], next run at: 2017-10-01 23:05:14 UTC)" executed successfully

If you see that, great -- you're ready to schedule your first observation! If not, check out the Troubleshooting page.