SatNOGS Client Setup

From SatNOGS Wiki
Revision as of 12:24, 22 March 2020 by Kerel+satnogs (talk | contribs) (Advanced Setup: Airspy: Add useful gain settings example)


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

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 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, 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).
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

Setting Description
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_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

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 ./

APT_KEY_URL This options allows you to change the SatNOGS packages repository key URL. For example, to install unstable package builds use:

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+ -- the 'master' branch (the current development version) of satnogs-client
  • git+ -- 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:


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

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

WARNING: An update can potentially interrupt a running observation!

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-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
  4. Keep an eye on the upgrade progress; dpkg may prompt for changes
  5. Once the upgrade is completed run sudo sync; sudo reboot
  6. After the reboot, SSH back into the system and make sure you are on the correct release by running lsb_release -a
  7. Run sudo rm -f /root/.satnogs/.bootstrapped; sudo satnogs-setup and select Update and then Apply; this may take some time
  8. Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
  9. 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