SatNOGS Client Setup

Introduction

satnogs-setup provides a set of scripts for configuring a SatNOGS Client system. satnogs-setup main function is to bring up a menu-driven console configuration utility and provision the system using Ansible.

Initial Setup

Before starting satnogs-setup, ensure the Raspberry Pi is up to date. This can be done with sudo apt update and then sudo apt upgrade.

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 system:

1. SSH into the system and run sudo satnogs-setup; this will bring up the configuration menu
2. Set all options in 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. To find your API token, log in to network.satnogs.org, click on the user icon at the top right corner and then click on the "Dashboard" option. On the top of the dashboard page right under the user icon click the button "API key" to show your API token.
SATNOGS_SOAPY_RX_DEVICE	If you are using an RTL-SDR, this is driver=rtlsdr. See pothosware/SoapyRTLSDR/wiki#modules for other SDR modules (linked in the navigation bar at the right side of the page). If multiple devices are attached to your station you should also specify the serial of the desired device here, e.g. driver=uhd,serial=3164495.
SATNOGS_ANTENNA	If you are using an RTL-SDR, this is RX. Use SoapySDRUtil --probe 2>&1| grep Antennas to get available antennas for other modules.
SATNOGS_RX_SAMP_RATE	Specify the receiver sampling rate. Recommended value for RTL-SDR: 2.048e6 (for 2Msps). Other devices will need different sample rates (Use SoapySDRUtil --probe 2>&1 | grep Sample to find out which rates are valid)
SATNOGS_RF_GAIN	RF Gain value for your SDR hardware. Run SoapySDRUtil --probe to see all possible gain values for your hardware. Example: For RTL-SDR without pre-amp, 32.8 is a good starting value. Follow Setting the gain to find a good gain value.
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.

Advanced Setup

Changes to the following settings may be required to optimise station performance, or enable support for additional features (e.g. rotator control)

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
SATNOGS_PPM_ERROR	The local oscillator frequency deviation in ppm.
SATNOGS_RX_BANDWIDTH	Soapy baseband filter bandwidth [1] of RX Channel 0 in Hz (only available on specific devices). TODO: Testing.
SATNOGS_DEV_ARGS	Soapy device arguments (currently only accepting the serial key successfully) and stream arguments. NOTE: This parameter / its meaning might change in the near future, see issue satnogs-client#373.
SATNOGS_GAIN_MODE	Choose the gain mode: "Overall" (default): Set the gain with the single value from SATNOGS_RF_GAIN "Settings Field": Ignore SATNOGS_RF_GAIN, use the settings from SATNOGS_OTHER_SETTINGS instead
SATNOGS_STREAM_ARGS
SATNOGS_TUNE_ARGS
SATNOGS_OTHER_SETTINGS	Only available if SATNOGS_GAIN_MODEis"Settings Field". Available gain settings can be retrieved using SoapySDRUtil --probe="driver=xxxx` Example for Airspy: Use"LNA=12,MIX=8,VGA=11"See also: Airspy support
SATNOGS_DC_REMOVAL
SATNOGS_BB_FREQ
SATNOGS_LO_OFFSET	Don't use this parameter to correct for the local oscillator frequency deviation, use SATNOGS_PPM_ERROR instead! To avoid the SDR carrier at the DC the LO is shifted from the actual frequency a little. Default: 100e3 (100 kHz)
SATNOGS_ROT_MODEL	Hamlib rotator model. If you don't have a rotator (like the No rotator setup), leave it empty. Use the macro name for your rotator model from this list of rotator models in Hamlib. If you are connecting to a separate rotctld instance, use ROT_MODEL_NETROTCTL
SATNOGS_ROT_BAUD	Baud rate for Hamlib rotator serial port, if using a serial-connected rotator.
SATNOGS_ROT_PORT	Serial port for Hamlib rotator, OR the network address of a rotctld instance (e.g. localhost:4533 )
SATNOGS_ROT_THRESHOLD	Rotator movement threshold, in degrees. If set, the rotator will only be commanded when the target has moved more than <threshold> degrees away from the current azimuth/elevation position. Default: 4 degrees
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.
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
SATNOGS_PRE_OBSERVATION_SCRIPTSATNOGS_POST_OBSERVATION_SCRIPT	Allows execution of a shell script either pre or post-observation. The following can be entered into the script path to enable passing of information to the script: {{FREQ}} - Observation Centre Frequency {{TLE}} - Target object TLE data, as a JSON-formatted object. {{TIMESTAMP}} - Start time of the observation, in the format: %Y-%m-%dT%H-%M-%S%z {{ID}} - Observation ID number. {{BAUD}} - Baud rate of the modulation used, if applicable. {{SCRIPT_NAME}} - The name of the demodulation flow-graph script in use.
EXPERIMENTAL	Install latest (experimental) versions of all software
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_FLOWGRAPHS_VERSION	This options allows you to change the version of satnogs-flowgraphs package to be installed. For example: 0.1-1
LOG_LEVEL	Define SatNOGS client log level, available values: ERROR, WARNING, INFO and DEBUG

Obsolete Setup Variables

The following options were available in previous versions of the SatNOGS client system and have no effect on the latest stable version.

Setting	Description
SATNOGS_RX_DEVICE	If you are using an RTL-SDR, this is rtlsdr. Other devices supported by gr-satnogs include usrpb200, usrp2, airspy/airspymini, lime, or hackrf.
SATNOGS_PPM_ERROR (available again)	gr-satnogs: The PPM correction [2]
SATNOGS_DEV_ARGS (available again)	gr-satnogs: SDR device specific arguments [3] Note: This variable was re-purposed to set soapy device and stream arguments, so it's not obsolete anymore.
SATNOGS_IF_GAIN	gr-satnogs: Intermediate frequency gain [4]
SATNOGS_BB_GAIN	gr-satnogs: Baseband gain [5]
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

Updating SatNOGS Client Software

An update can potentially interrupt a running observation!

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 Update to update the configuration tool and all distribution packages to the latest
3. If you are prompt for a reboot during the upgrade, once the upgrade is finished, select Reboot, SSH back into the system and re-run satnogs-setup to continue to the next step
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

You can check your current version of client (and other client software) at the top of window after running sudo satnogs-setup; alternatively you can generate the support report by going at Advanced -> Support.

Client version on SatNOGS Network is updated after the first observation with the new client.

Upgrading from Debian 'stretch' to 'buster'

Debian stretch is no longer supported. If you have already installed an older version of Debian or Raspbian SatNOGS image based on stretch (releases <= 2018080300), you must upgrade to buster otherwise it will be impossible to receive updates or upgrades in the future.

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 satnogs-upgrade (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 and select Update to update the tool itself and then select Apply. This may inform you that the current distribution is not supported and exit. If not, select Exit to exit the tool.
4. Run sudo satnogs-upgrade to update all distribution packages to the latest; this will also prompt you for a distribution upgrade, if it detects that one is needed
5. Keep an eye on the upgrade progress; dpkg may prompt for changes
6. Once the upgrade is completed run sudo sync; sudo reboot
7. After the reboot, SSH back into the system and make sure you are on the correct release by running lsb_release -a
8. Run sudo rm -f /root/.satnogs/.bootstrapped; sudo satnogs-setup and select Update and then Apply; this may take some time
9. Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
10. Select Back to exit

Verification of correct installation

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

$ systemctl status satnogs-client

You should see an output that looks like this:

● satnogs-client.service - SatNOGS client

  Loaded: loaded (/etc/systemd/system/satnogs-client.service; enabled; vendor preset: enabled)
  Active: active (running) since Wed 2020-03-04 19:30:56 GMT; 6min ago
Main PID: 6309 (satnogs-client)
   Tasks: 11 (limit: 2200)
  Memory: 37.9M
  CGroup: /system.slice/satnogs-client.service
          └─6309 /var/lib/satnogs/bin/python3 /var/lib/satnogs/bin/satnogs-client

Mar 04 19:30:56 raspberrypi systemd[1]: Started SatNOGS client.

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

See also

• SatNOGS Client Ansible