Difference between revisions of "SatNOGS Client Setup"

From SatNOGS Wiki
(→‎Reflashing and reinstalling)
 
(64 intermediate revisions by 9 users not shown)
Line 3: Line 3:
  
 
==Initial Setup==
 
==Initial Setup==
−
Right after the first boot of the system, packages and the configuration tool itself '''must be updated'''. Follow the [[SatNOGS Client Setup#Updating SatNOGS Client Software|Updating]] instruction found below.
+
Before starting <code>satnogs-setup</code>, ensure the Raspberry Pi is up to date. This can be done with <code>sudo apt update</code> and then <code>sudo apt upgrade</code>.
 +
 
 +
{{Message| In case of getting a similar error to this:
 +
<code>W: An error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://download.opensuse.org/repositories/home:/librespace:/satnogs/Raspbian_10 ./ InRelease: The following signatures were invalid: EXPKEYSIG 8BD3901736A40B6C home:librespace OBS Project <home:librespace@build.opensuse.org>
 +
</code>
 +
Check at https://wiki.satnogs.org/Troubleshooting#Invalid_Signature_for_download.opensuse.org on how to solve it}}In case of getting a similar error to "Newer kernel available" annoying message after running sudo apt update:
 +
 
 +
Package configuration 
 +
 
 +
┌──────────┤ Pending kernel upgrade ├─────────────────────┐
 +
 
 +
│                                                                                                                              │
 +
 
 +
│ Newer kernel available                                                                                        │
 +
 
 +
│                                                                                                                              │
 +
 
 +
│ The currently running kernel version is 4.19.97-v7l+ which is not the                │
 +
 
 +
│ expected kernel version 4.19.93-v8+.                                                                │
 +
 
 +
│                                                                                                                            │
 +
 
 +
│ Restarting the system to load the new kernel will not be handled                      │
 +
 
 +
│ automatically, so you should consider rebooting.                                              │
 +
 
 +
│                                                                                                                            │
 +
 
 +
│                                <Ok>                                                                                  │
 +
 
 +
│                                                                                                                            │
 +
 
 +
└─────────────────────────────────────────────────|
 +
 
 +
Do a "sudo apt purge needrestart" after doing a reboot after doing a "sudo apt update"{{Message| In case of getting a similar error to this:
 +
<code>
 +
E: Repository 'http://archive.raspberrypi.org/debian buster InRelease' changed its 'Suite' value from 'testing' to 'oldstable'
 +
 
 +
N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.
 +
 
 +
E: Repository 'http://raspbian.raspberrypi.org/raspbian buster InRelease' changed its 'Suite' value from 'stable' to 'oldstable'
 +
 
 +
N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.
 +
</code>
 +
Run <code>sudo apt-get update --allow-releaseinfo-change</code> instead of just <code>sudo apt-get update</code>}}
 +
 
 +
(See: [[Troubleshooting#apt-get update: connection failed]] ).
 +
 
 +
After the first boot of the system, packages and the configuration tool itself '''must be updated'''. Follow the [[SatNOGS Client Setup#Updating SatNOGS Client Software|Updating]] instruction found below.
  
 
To configure a '''SatNOGS Client''' system:
 
To configure a '''SatNOGS Client''' system:
Line 19: Line 68:
 
|<code>SATNOGS_API_TOKEN</code>
 
|<code>SATNOGS_API_TOKEN</code>
 
|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.
 
|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 [https://network.satnogs.org 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.
 
|-
 
|-
−
|<code>SATNOGS_RX_DEVICE</code>
+
|<code>SATNOGS_SOAPY_RX_DEVICE</code>
−
|If you are using an RTL-SDR, this is <code>rtlsdr</code>. Other devices supported by gr-satnogs include <code>usrpb200</code>, <code>usrp2</code>, <code>airspy/airspymini</code> or <code>hackrf</code>; a complete list can be found [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/blob/master/apps/flowgraphs/satellites/README.md here].
+
|If you are using an RTL-SDR, this is <code>driver=rtlsdr</code>. For other devices tested configurations can be found at [[Software_Defined_Radio]].
 +
 
 +
 
 +
See [https://github.com/pothosware/SoapyRTLSDR/wiki#modules 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. <code>driver=uhd,serial=3164495</code>.
 +
|-
 +
|<code>SATNOGS_ANTENNA</code>
 +
|If you are using an RTL-SDR, this is <code>RX</code>. For other devices tested configurations can be found at [[Software_Defined_Radio]].
 +
 
 +
 
 +
If your device is not listed there yet, use <code><nowiki>SoapySDRUtil --probe 2>&1| grep Antennas</nowiki></code> to get available antennas.
 +
|-
 +
|<code>SATNOGS_RX_SAMP_RATE</code>
 +
|Specify the receiver sampling rate. Recommended value for RTL-SDR: <code>2.048e6</code> (for 2Msps), other devices will need different sample rates described at [[Software_Defined_Radio]] .
 +
 
 +
 
 +
The command <code><nowiki>SoapySDRUtil --probe 2>&1 | grep Sample</nowiki></code> can be used to find all valid sample rates.
 +
|-
 +
|<code>SATNOGS_RF_GAIN</code>
 +
|RF Gain value for your SDR hardware.
 +
 
 +
 
 +
Run <code>SoapySDRUtil --probe</code> to see all possible gain values for your hardware.
 +
Example: For RTL-SDR without pre-amp, 32.8 is a good starting value. Follow [[Omnidirectional Station How To#Setting the gain|Setting the gain]] to find a good gain value.
 
|-
 
|-
 
|<code>SATNOGS_STATION_ELEV</code>
 
|<code>SATNOGS_STATION_ELEV</code>
Line 34: Line 108:
 
|<code>SATNOGS_STATION_LON</code>
 
|<code>SATNOGS_STATION_LON</code>
 
|The longitude of your station.  East is positive, west is negative.
 
|The longitude of your station.  East is positive, west is negative.
 +
|}
 +
 +
==Advanced Setup==
 +
{{Warning|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/
 +
{| class="wikitable"
 +
!Setting
 +
!Description
 +
|-
 +
|<code>SATNOGS_PPM_ERROR</code>
 +
|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
 +
|-
 +
|<code>SATNOGS_RX_BANDWIDTH</code>
 +
|Soapy baseband filter bandwidth [https://github.com/pothosware/SoapySDR/blob/a489f3dca9d3ccd9b276b95a608ac3ef0299f635/include/SoapySDR/Device.hpp#L904-L910] of RX Channel 0 in Hz (only available on specific devices). TODO: Testing.
 +
|-
 +
|<code>SATNOGS_DEV_ARGS</code>
 +
|Soapy device arguments (currently only accepting the <code>serial</code> key successfully) and stream arguments.
 +
NOTE: This parameter / its meaning might change in the near future, see issue [https://gitlab.com/librespacefoundation/satnogs/satnogs-client/-/issues/373 satnogs-client#373].
 +
|-
 +
|<code>SATNOGS_GAIN_MODE</code>
 +
|Choose the gain mode:
 +
 +
*<code>"Overall"</code> (default): Set the gain with the single value from <code>SATNOGS_RF_GAIN</code>
 +
*<code>"Settings Field"</code>: Ignore <code>SATNOGS_RF_GAIN</code>, use the settings from <code>SATNOGS_OTHER_SETTINGS</code> instead
 +
|-
 +
|<code>SATNOGS_STREAM_ARGS</code>
 +
|
 +
|-
 +
|<code>SATNOGS_TUNE_ARGS</code>
 +
|
 +
|-
 +
|<code>SATNOGS_OTHER_SETTINGS</code>
 +
|Only available if <code>SATNOGS_GAIN_MODE</code>is<code>"Settings Field"</code>.
 +
Available gain settings can be retrieved using <code>SoapySDRUtil --probe="driver=xxxx`</code>
 +
 +
Example for Airspy: Use<code>"LNA=12,MIX=8,VGA=11"</code>See also: [[SDR#Airspy|Airspy support]]
 +
|-
 +
|<code>SATNOGS_DC_REMOVAL</code>
 +
|
 +
|-
 +
|<code>SATNOGS_BB_FREQ</code>
 +
|
 +
|-
 +
|<code>SATNOGS_LO_OFFSET</code>
 +
|Don't use this parameter to correct for the local oscillator frequency deviation, use <code>SATNOGS_PPM_ERROR</code> instead!
 +
To avoid the SDR carrier at the DC the LO is shifted from the actual frequency a little. Default: <code>100e3</code> (100 kHz)
 +
|-
 +
|
 +
|
 +
|-
 +
|<code>SATNOGS_ROT_MODEL</code>
 +
|Hamlib rotator model. If you don't have a rotator (like the [[No rotator|No rotator setup]]), leave it empty.
 +
Use the macro name for your rotator model from this [https://gist.github.com/kerel-fs/2354ff9c082cd3c1594afc38c67bc32a#hamlib-release-33 list of rotator models in Hamlib]. If you are connecting to a separate rotctld instance, use <code>ROT_MODEL_NETROTCTL</code>
 +
|-
 +
|<code>SATNOGS_ROT_BAUD</code>
 +
|Baud rate for Hamlib rotator serial port, if using a serial-connected rotator.
 +
|-
 +
|<code>SATNOGS_ROT_PORT</code>
 +
|Serial port for Hamlib rotator, OR the network address of a rotctld instance (e.g. <code>localhost:4533</code> )
 +
|-
 +
|<code>SATNOGS_ROT_THRESHOLD</code>
 +
|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
 +
|-
 +
|
 +
|
 
|-
 
|-
 
|<code>HAMLIB_UTILS_ROT_ENABLED</code>
 
|<code>HAMLIB_UTILS_ROT_ENABLED</code>
−
|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|No rotator setup]]), enter <code>NO</code>.
+
|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.
 
|-
 
|-
 
|<code>HAMLIB_UTILS_ROT_OPTS</code>
 
|<code>HAMLIB_UTILS_ROT_OPTS</code>
Line 43: Line 192:
  
 
For a SatNOGS rotator <code>-m 204 -s 19200 -r /dev/ttyACM0 -C timeout=200</code> or <code>-m 204 -s 19200 -r /dev/ttyUSB0 -C timeout=200</code>
 
For a SatNOGS rotator <code>-m 204 -s 19200 -r /dev/ttyACM0 -C timeout=200</code> or <code>-m 204 -s 19200 -r /dev/ttyUSB0 -C timeout=200</code>
−
|}
+
|-
−
==Advanced Setup==
+
|
−
{{Warning|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]].
+
|
 +
|-
 +
|<code>SATNOGS_PRE_OBSERVATION_SCRIPT</code><code>SATNOGS_POST_OBSERVATION_SCRIPT</code>
 +
|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:
 +
<code><nowiki>{{FREQ}}</nowiki></code> - Observation Centre Frequency
 +
 
 +
<code><nowiki>{{TLE}}</nowiki></code> - Target object TLE data, as a JSON-formatted object.
 +
 
 +
<code><nowiki>{{TIMESTAMP}}</nowiki></code> - Start time of the observation, in the format: %Y-%m-%dT%H-%M-%S%z
 +
 
 +
<code><nowiki>{{ID}}</nowiki></code> - Observation ID number.
 +
 
 +
<code><nowiki>{{BAUD}}</nowiki></code> - Baud rate of the modulation used, if applicable.
  
−
NOTE: To get your station online, you need to set SATNOGS_NETWORK_API_URL to https://network.satnogs.org/api/
+
<code><nowiki>{{SCRIPT_NAME}}</nowiki></code> - The name of the demodulation flow-graph script in use.
−
{| class="wikitable"
+
|-
−
!Setting
+
|
−
!Description
+
|
 +
|-
 +
|<code>EXPERIMENTAL</code>
 +
|Install latest (experimental) versions of all software
 
|-
 
|-
 
|<code>APT_REPOSITORY</code>
 
|<code>APT_REPOSITORY</code>
 
|This options allows you to change the SatNOGS packages repository. For example, to install unstable package builds use:
 
|This options allows you to change the SatNOGS packages repository. For example, to install unstable package builds use:
−
<code>deb <nowiki>http://download.opensuse.org/repositories/home:/librespace:/satnogs_unstable/Raspbian_10</nowiki> ./</code>
+
<code>deb <nowiki>http://download.opensuse.org/repositories/home:/librespace:/satnogs-unstable/Raspbian_10</nowiki> ./</code>
 
|-
 
|-
 
|<code>APT_KEY_URL</code>
 
|<code>APT_KEY_URL</code>
 
|This options allows you to change the SatNOGS packages repository key URL. For example, to install unstable package builds use:
 
|This options allows you to change the SatNOGS packages repository key URL. For example, to install unstable package builds use:
−
<code><nowiki>http://download.opensuse.org/repositories/home:/librespace:/satnogs_unstable/Raspbian_10/Release.key</nowiki></code>
+
<code><nowiki>http://download.opensuse.org/repositories/home:/librespace:/satnogs-unstable/Raspbian_10/Release.key</nowiki></code>
 
|-
 
|-
 
|<code>APT_KEY_ID</code>
 
|<code>APT_KEY_ID</code>
Line 66: Line 230:
 
|If you to try a development version of satnogs-client, you can change the URL here.  The URL needs to be in [https://pip.pypa.io/en/stable/reference/pip_install PIP format].  Here are some examples:
 
|If you to try a development version of satnogs-client, you can change the URL here.  The URL needs to be in [https://pip.pypa.io/en/stable/reference/pip_install PIP format].  Here are some examples:
  
−
*<code>git+https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@master</code> -- the 'master' branch (the current development version) of satnogs-client
+
*<code>git+<nowiki>https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@master</nowiki></code> -- the 'master' branch (the current development version) of satnogs-client
 
*<code><nowiki>git+https://gitlab.com/jdoe/satnogs-client.git@new-feature</nowiki></code> -- the 'new-feature' branch of jdoe's fork of satnogs-client
 
*<code><nowiki>git+https://gitlab.com/jdoe/satnogs-client.git@new-feature</nowiki></code> -- the 'new-feature' branch of jdoe's fork of satnogs-client
 
|-
 
|-
−
|<code>SATNOGS_RADIO_GR_SATNOGS_VERSION</code>
+
|<code>SATNOGS_RADIO_FLOWGRAPHS_VERSION</code>
−
|This options allows you to change the version of gr-satnogs package to be installed. For example:
+
|This options allows you to change the version of satnogs-flowgraphs package to be installed. For example:
−
<code>1.5.1-1</code>
+
<code>0.1-1</code>
 +
|-
 +
|
 +
|
 +
|-
 +
|<code>LOG_LEVEL</code>
 +
|Define SatNOGS client log level, available values: <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code> and <code>DEBUG</code>
 +
|-
 +
|
 +
|-
 +
|<code>SATNOGS_ARTIFACTS_ENABLED</code>
 +
|Enable generation and uploading of HDF5 artifacts files to SatNOGS DB. (added in satnogs-client 1.7)
 
|-
 
|-
−
|<code>RF_GAIN</code>
+
|<code>SATNOGS_ARTIFACTS_API_TOKEN</code>
−
|RF Gain value for your SDR hardware. Defaults can be found [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/blob/master/python/hw_settings.py here].
+
|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)
 +
|}
  
−
*For rtl-sdr possible values are the following: <code>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</code>
+
==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.
 +
{| class="wikitable"
 +
!Setting
 +
!Description
 +
|-
 +
|<code>SATNOGS_RX_DEVICE</code>
 +
|If you are using an RTL-SDR, this is <code>rtlsdr</code>. Other devices supported by gr-satnogs include <code>usrpb200</code>, <code>usrp2</code>, <code>airspy/airspymini</code>, <code>lime</code>, or <code>hackrf</code>.
 
|-
 
|-
−
|<code>SATNOGS_SOAPY_RX_DEVICE</code>
+
|<code>SATNOGS_PPM_ERROR</code> (available again)
−
|(only applicable if '''EXPERIMENTAL=True''') If you are using an RTL-SDR, this is <code>driver=rtlsdr</code> (TODO:confirm!).  See [https://github.com/pothosware/SoapyRTLSDR/wiki#modules pothosware/SoapyRTLSDR/wiki#modules] for other SDR modules (linked in the navigation bar at the right side of the page).
+
|gr-satnogs: The PPM correction [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/-/blob/v1.5.1/apps/flowgraphs/README.md#execution-arguements-interface]
−
 
+
|-
−
 
+
|<code>SATNOGS_DEV_ARGS</code> (available again)
−
If multiple devices are attached to your station you should also specify the serial of the desired device here, e.g. <code>driver=uhd,serial=3164495</code>.
+
|gr-satnogs: SDR device specific arguments [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/-/blob/v1.5.1/apps/flowgraphs/README.md#execution-arguements-interface]
 +
Note: This variable was re-purposed to set soapy device and stream arguments, so it's not obsolete anymore.
 
|-
 
|-
−
|<code>SATNOGS_RF_GAIN</code>
+
|<code>SATNOGS_IF_GAIN</code>
−
|(only applicable if '''EXPERIMENTAL=True''') RF Gain value for your SDR hardware. Run <code>SoapySDRUtil --probe</code> to see all possible gain values for your hardware.
+
|gr-satnogs: Intermediate frequency gain [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/-/blob/v1.5.1/apps/flowgraphs/README.md#execution-arguements-interface]
 
|-
 
|-
−
|<code>SATNOGS_RX_BANDWIDTH</code>
+
|<code>SATNOGS_BB_GAIN</code>
−
|(only applicable if '''EXPERIMENTAL=True''') TODO.
+
|gr-satnogs: Baseband gain [https://gitlab.com/librespacefoundation/satnogs/gr-satnogs/-/blob/v1.5.1/apps/flowgraphs/README.md#execution-arguements-interface]
 
|-
 
|-
−
|<code>SATNOGS_ANTENNA</code>
+
|<code>SATNOGS_RADIO_GR_SATNOGS_VERSION</code>
−
|(only applicable if '''EXPERIMENTAL=True''') TODO.
+
|This options allows you to change the version of gr-satnogs package to be installed. For example: <code>1.5.1-1</code>
 
|}
 
|}
 +
 
==Updating SatNOGS Client Software==
 
==Updating SatNOGS Client Software==
 +
{{Warning| An update can potentially interrupt a running observation!}}
 
To update SatNOGS software, including the configuration tool itself:
 
To update SatNOGS software, including the configuration tool itself:
  
 
#SSH into the system and (re-)run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
 
#SSH into the system and (re-)run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
 
#Select <code>Update</code> to update the configuration tool and all distribution packages to the latest
 
#Select <code>Update</code> to update the configuration tool and all distribution packages to the latest
−
#If you are prompt for a reboot during the upgrade, once the upgrade is finished, select <code>Reboot</code>, SSH back into the system and re-run <code>satnogs-config</code> to continue to the next step
+
#If you are prompted for a reboot during the upgrade, once the upgrade is finished, select <code>Reboot</code>, SSH back into the system and re-run <code>satnogs-setup</code> to continue to the next step
 
#Select <code>Apply</code> and the Raspberry Pi will update itself; this may take some time
 
#Select <code>Apply</code> and the Raspberry Pi will update itself; this may take some time
 
#Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
 
#Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
 
#Select <code>Back</code> to exit
 
#Select <code>Back</code> to exit
  
−
'''WARNING: An update can potentially interrupt a running observation!'''
+
{{Message|You can check your current version of client (and other client software) at the top of window after running <code>sudo satnogs-setup</code>; alternatively you can generate the support report by going at <code>Advanced -> Support</code>.}}
−
===Upgrading from Debian 'stretch' to 'buster'===
+
{{Message|Client version on SatNOGS Network is updated after the first observation with the new client.}}
−
Debian <code>stretch</code> is no longer supported. If you have already installed an older version of Debian or Raspbian SatNOGS image based on <code>stretch</code> (releases <= [https://gitlab.com/librespacefoundation/satnogs/satnogs-pi-gen/-/tags/2018080300 2018080300]), you must upgrade to <code>buster</code> otherwise it will be impossible to receive updates or upgrades in the future.
+
===Upgrading from Debian 'stretch' or 'buster', to 'bullseye'===
−
====Method 1: Reflashing and reinstalling (recommended)====
+
Debian <code>stretch</code> and <code>buster</code> are no longer supported. If you have already installed an older version of Debian or Raspbian SatNOGS image based on <code>buster</code> or  <code>stretch</code> (releases <= [https://gitlab.com/librespacefoundation/satnogs/satnogs-pi-gen/-/tags/2020122700 2020122700]), you must upgrade to <code>bullseye</code> otherwise it will be impossible to receive updates or upgrades in the future.
−
The recommended method to upgrade to <code>buster</code> is reflashing the latest Raspbian SatNOGS image (or reinstalling latest Debian). Follow [[Raspberry Pi|Raspberry Pi]] installation instructions and reinstall from scratch.
+
====Reflashing and reinstalling====
−
====Method 2: Release upgrade using the configuration tool (advanced)====
+
The recommended method to upgrade to <code>bullseye</code> is reflashing the latest Raspbian SatNOGS image (or reinstalling latest Debian). Follow [[Raspberry Pi|Raspberry Pi]] installation instructions and reinstall from scratch.
−
{{Warning|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:
+
==Verification of correct installation==
 +
To see if satnogs-client has started successfully, check the logs with <code>systemctl</code>:<pre>
 +
$ systemctl status satnogs-client
 +
</pre>You should see an output that looks like this:<pre>
 +
● 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
  
−
#SSH into the system
+
Mar 04 19:30:56 raspberrypi systemd[1]: Started SatNOGS client.
−
#Make sure you have enough free space on your SD card (>2GiB) by running <code>df -h /</code> on the console
+
</pre>If you see that, great -- you're ready to [[Operation|schedule your first observation]]! If not, check out the [[Troubleshooting]] page.
−
#Run <code>sudo satnogs-setup</code> to bring up the configuration menu
+
 
−
#Select <code>Update</code> to update the configuration tool and all distribution packages to the latest; this will also prompt you for a distribution upgrade, if it detects that one is needed
+
==Backup & Restore the configuration==
−
#Keep an eye on the upgrade progress; <code>dpkg</code> may prompt for changes
+
The configuration of your SatNOGS station is stored at <code>/etc/ansible/host_vars/localhost</code>. If your station software is broken (e.g. due to a corrupt SD card) or if you want to downgrade from the experimental software back to the stable releases, you can perform the following steps:
−
#Once the upgrade is completed select <code>Reboot</code>
 
−
#After the reboot, SSH back into the system and make sure you are on the correct release by running <code>lsb_release -a</code>
 
−
#Re-run <code>sudo satnogs-setup</code> and select <code>Update</code> and then <code>Apply</code>; this may take some time
 
−
#Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
 
−
#Select <code>Back</code> to exit
 
  
−
==Verification of correct installation==
+
#Backup the configuration file at <code>/etc/ansible/host_vars/localhost</code>
−
To see if satnogs-client has started successfully, check the logs with journalctl:<pre>
+
#Re-flash the SD card with a fresh image
−
$ journalctl -u satnogs-client.service
+
#Restore the configuration file
−
</pre>You should see entries running approximately once per minute that look like this:<pre>
+
#Run <code>sudo satnogs-setup</code> and select <code>Update</code> to update the tool itself and then select <code>Apply</code>
−
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
 
−
</pre>If you see that, great -- you're ready to [[Operation|schedule your first observation]]! If not, check out the [[Troubleshooting]] page.
 
  
 
==See also==
 
==See also==

Latest revision as of 17:24, 10 September 2022

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.

Idea.png
In case of getting a similar error to this:

W: An error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://download.opensuse.org/repositories/home:/librespace:/satnogs/Raspbian_10 ./ InRelease: The following signatures were invalid: EXPKEYSIG 8BD3901736A40B6C home:librespace OBS Project <home:librespace@build.opensuse.org>

Check at https://wiki.satnogs.org/Troubleshooting#Invalid_Signature_for_download.opensuse.org on how to solve it

In case of getting a similar error to "Newer kernel available" annoying message after running sudo apt update:

Package configuration

┌──────────┤ Pending kernel upgrade ├─────────────────────┐

│ │

│ Newer kernel available │

│ │

│ The currently running kernel version is 4.19.97-v7l+ which is not the │

│ expected kernel version 4.19.93-v8+. │

│ │

│ Restarting the system to load the new kernel will not be handled │

│ automatically, so you should consider rebooting. │

│ │

│ <Ok> │

│ │

└─────────────────────────────────────────────────|

Do a "sudo apt purge needrestart" after doing a reboot after doing a "sudo apt update"

Idea.png
In case of getting a similar error to this:

E: Repository 'http://archive.raspberrypi.org/debian buster InRelease' changed its 'Suite' value from 'testing' to 'oldstable'

N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.

E: Repository 'http://raspbian.raspberrypi.org/raspbian buster InRelease' changed its 'Suite' value from 'stable' to 'oldstable'

N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.

Run sudo apt-get update --allow-releaseinfo-change instead of just sudo apt-get update

(See: Troubleshooting#apt-get update: connection failed ).

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
Idea.png
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. 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

Important.png
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 (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_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
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 Client Software

Important.png
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 prompted 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
Idea.png
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.
Idea.png
Client version on SatNOGS Network is updated after the first observation with the new client.

Upgrading from Debian 'stretch' or 'buster', to 'bullseye'

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

Reflashing and reinstalling

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

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.

Backup & Restore the configuration

The configuration of your SatNOGS station is stored at /etc/ansible/host_vars/localhost. If your station software is broken (e.g. due to a corrupt SD card) or if you want to downgrade from the experimental software back to the stable releases, you can perform the following steps:

  1. Backup the configuration file at /etc/ansible/host_vars/localhost
  2. Re-flash the SD card with a fresh image
  3. Restore the configuration file
  4. Run sudo satnogs-setup and select Update to update the tool itself and then select Apply

See also

Retrieved from "https://wiki.satnogs.org/index.php?title=SatNOGS_Client_Setup&oldid=3855"
  • Creative Commons Attribution-ShareAlike
  • Powered by MediaWiki