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

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_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_MODE`is`"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`
`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)

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

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:

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