SatNOGS Setup

Introduction

satnogs-setup provides a set of scripts for provisioning and configuring SatNOGS. satnogs-setup main function is to bring up a menu-driven console configuration utility and provision the system using Ansible. Instruction on this page assumes that you have successfully established console access on the host machine intended to run SatNOGS.

Initial Setup

The satnogs-setup configuration tool is automatically executed during the installation process. However, if needed, you can reconfigure the software at any time by running it again:

$ satnogs-setup

Configuration

Configuring SatNOGS can potentially interrupt a running observation!

The configuration is divided into Basic and Advanced submenus. The Basic Configuration includes the essential settings required to get the station up and running, while further optimization or customization can be done through the Advanced Configuration. The Show menu item displays the current configuration in a single view, and the Reset option deletes all existing configurations. Lastly, the About menu item provides information about the tool itself. Once the configuration is completed, exiting the utility will apply the changes. Please note that this process may take several minutes, depending on the modifications made.

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 into 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. For other devices tested configurations can be found at Software_Defined_Radio. 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. For other devices tested configurations can be found at Software_Defined_Radio. If your device is not listed there yet, use SoapySDRUtil --probe 2>&1| grep Antennas to get available antennas.
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 described at Software_Defined_Radio . The command SoapySDRUtil --probe 2>&1 | grep Sample can be used to find all valid sample rates.
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.

Radio

Setting	Description
SATNOGS_PPM_ERROR	The local oscillator frequency deviation in ppm (value will be rounded to integer). Available with the following modules: SoapyRTLSDR SoapySDRPlay Not available with the following modules: SoapyUHD SoapyPluto
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_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_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_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_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

Rotator

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

Artifacts

Setting	Description
SATNOGS_ARTIFACTS_ENABLED	Enable generation and uploading of HDF5 artifacts files to SatNOGS DB. (added in satnogs-client 1.7)
SATNOGS_ARTIFACTS_API_TOKEN	SatNOGS DB API token associated with an account in SatNOGS DB. This token is secret. It is used to upload artifacts to SatNOGS DB. It can be found in SatNOGS DB user page. (added in satnogs-client 1.7)

Scripts

Setting	Description
SATNOGS_PRE_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.
SATNOGS_POST_OBSERVATION_SCRIPT

Hamlib

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

Development

Setting	Description
EXPERIMENTAL	Install latest (experimental) versions of all software

Debug

Setting	Description
SATNOGS_LOG_LEVEL	Define SatNOGS client log level, available values: ERROR, WARNING, INFO and DEBUG

Obsolete Settings

The following options were available in previous versions of SatNOGS 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_IF_GAIN	gr-satnogs: Intermediate frequency gain [2]
SATNOGS_BB_GAIN	gr-satnogs: Baseband gain [3]
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
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

Updating SatNOGS Software

An update can potentially interrupt a running observation!

The software is updated automatically when satnogs-setup is executed.

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

Upgrading from legacy software

IMPORTANT: Some essential features from the previous version are currently unavailable in the newer version. Please review the Missing Features Table before proceeding with the upgrade. If any of the missing features are critical to your setup, follow the Legacy Software Installation Guide to install the legacy software.

Missing features

Feature	Description	Related issue
Rotator support	No access to serial devices.	satnogs-ansible#146
Installation of experimental software	This feature is currently unimplemented.	satnogs-ansible#156
Post and pre-observation scripts	No path is defined or mounted.	satnogs-ansible#184
	Double curly braces are broken.	satnogs-ansible#176
Component versions in support report	The versions of components in the support report is not available.	satnogs-config#68
Cannot modify running software	Containers are read-only.	satnogs-ansible#157

To update from the legacy SatNOGS software execute the normal installation command:

$ curl -sfL https://satno.gs/install | sh -s --

The command will clean-up the old software, install the new one and then bring up the SatNOGS configuraion menu-driver utility.

Verification of correct installation

To verify that the software is set up correctly, execute:

$ sudo docker ps -f 'name=^satnogs_' --format "table {{.Names}}\t{{.Status}}"

You should see an output that looks like this:

NAMES                    STATUS
satnogs_satnogs-client   Up 31 seconds
satnogs_rigctld          Up 31 seconds

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

Backup & Restore the configuration

The configuration of your SatNOGS station is stored at /var/lib/docker-bindmounts/ansible/etc/ansible/host_vars/ansible. If your station software is broken (e.g. due to a corrupt SD card), you can perform the following steps:

1. Backup the configuration file
2. Re-flash the SD card with a fresh image
3. Restore the configuration file
4. Execute $ curl -sfL https://satno.gs/install | sh -s --

See also

• SatNOGS Ansible