Difference between revisions of "SatNOGS Client Ansible"

From SatNOGS Wiki
m (on hamlib_utils_rot_enabled line of basic conf table, swapped "False" for "No" as that is the term used in the config tool)
(Mention skipping of instructions for provisioning from another host)
Line 1: Line 1:
−
= Intro =
+
=Intro=
  
 
'''SatNOGS Client Ansible''' is the suggested method to install '''SatNOGS Client''' (and friends) to a system. It currently supports Raspbian and Debian Stretch.
 
'''SatNOGS Client Ansible''' is the suggested method to install '''SatNOGS Client''' (and friends) to a system. It currently supports Raspbian and Debian Stretch.
  
−
= Raspbian =
+
=Raspbian=
  
 
For Raspberry Pi 3, which is the reference platform for SatNOGS, a [[Raspberry_Pi_3|Raspbian image]] with '''SatNOGS Client Ansible''' pre-installed is available.
 
For Raspberry Pi 3, which is the reference platform for SatNOGS, a [[Raspberry_Pi_3|Raspbian image]] with '''SatNOGS Client Ansible''' pre-installed is available.
  
−
= Debian =
+
=Debian=
  
−
These sections contain generic instructions for installing SatNOGS Client on a Debian Stretch system.
+
{{Warning|Skip this section if you are using [[Raspberry_Pi_3|SatNOGS Raspbian]] image and [[#SatNOGS Client Setup|SatNOGS Client Setup]]. Follow these instructions if you are provisioning SatNOGS to Debian from another host.}}These sections contain generic instructions for installing SatNOGS Client on a Debian Stretch system.
  
−
== Prerequisites ==
+
==Prerequisites==
  
−
* A user which is member of 'sudo' group exists on the target system
+
*A user which is member of 'sudo' group exists on the target system
−
* An SSH server running on the target system
+
*An SSH server running on the target system
−
* A host system with Git and latest version of Ansible installed
+
*A host system with Git and latest version of Ansible installed
  
−
== Instructions ==
+
==Instructions==
  
 
On the host system run the following commands:
 
On the host system run the following commands:
  
 
  <nowiki>
 
  <nowiki>
−
    $ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
+
    $ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
−
    $ cd satnogs-client-ansible                              # Change to cloned repository directory
+
    $ cd satnogs-client-ansible                              # Change to cloned repository directory
−
    $ cp -r production.dist production                      # Copy dist configuration
+
    $ cp -r production.dist production                      # Copy dist configuration
−
    $ vi production/inventory/hosts                          # Update file with your own target host, user and SSH password
+
    $ vi production/inventory/hosts                          # Update file with your own target host, user and SSH password
−
    $ ssh youruser@yourtargetsystem true                    # Test SSH connection to target system
+
    $ ssh youruser@yourtargetsystem true                    # Test SSH connection to target system
−
    $ ansible-playbook -i production/inventory -K site.yml  # Run Ansible playbook
+
    $ ansible-playbook -i production/inventory -K site.yml  # Run Ansible playbook
−
    $ ssh -t youruser@yourtargetsystem sudo satnogs-setup    # Setup SatNOGS client (see below)</nowiki>
+
    $ ssh -t youruser@yourtargetsystem sudo satnogs-setup    # Setup SatNOGS client (see below)</nowiki>
  
−
= SatNOGS Client Setup =
+
=SatNOGS Client Setup=
  
 
<code>satnogs-setup</code> is a script for configuring a system installed with '''SatNOGS Client Ansible'''.
 
<code>satnogs-setup</code> is a script for configuring a system installed with '''SatNOGS Client Ansible'''.
  
−
== Initial Setup ==
+
==Initial Setup==
  
 
Right after the first boot of the system, packages and the configuration tool itself '''must be updated'''. Follow the [[#Updating SatNOGS Client software|Updating]] instruction found below.
 
Right after the first boot of the system, packages and the configuration tool itself '''must be updated'''. Follow the [[#Updating SatNOGS Client software|Updating]] instruction found below.
Line 40: Line 40:
 
To configure a '''SatNOGS Client Ansible''' system:
 
To configure a '''SatNOGS Client Ansible''' system:
  
−
# SSH into the system and run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
+
#SSH into the system and run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
−
# Set '''Basic Configuration''' (see below)
+
#Set '''Basic Configuration''' (see below)
−
# Select <code>Apply</code> and the Raspberry Pi will configure itself; this may take some time
+
#Select <code>Apply</code> and the Raspberry Pi will configure itself; this may take some time
−
# Select <code>Back</code> to exit
+
#Select <code>Back</code> to exit
  
 
{{Message|You can always reconfigure the software by running <code>sudo satnogs-setup</code> again.}}
 
{{Message|You can always reconfigure the software by running <code>sudo satnogs-setup</code> again.}}
  
−
=== Basic Configuration ===
+
===Basic Configuration===
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 81: Line 81:
 
|}
 
|}
  
−
=== Advanced Setup ===
+
===Advanced Setup===
  
 
{{Warning|Changing these settings is ''not'' recommended unless you're developing SatNOGS.}}
 
{{Warning|Changing these settings is ''not'' recommended unless you're developing SatNOGS.}}
Line 91: Line 91:
 
|<code>SATNOGS_CLIENT_URL</code>
 
|<code>SATNOGS_CLIENT_URL</code>
 
|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><nowiki>git+https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@0</nowiki></code> -- the '0' 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/librespacefoundation/satnogs/satnogs-client.git@0</nowiki></code> -- the '0' 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>SATNOGS_RADIO_GR_SATNOGS_PACKAGE</code>
 
|<code>SATNOGS_RADIO_GR_SATNOGS_PACKAGE</code>
 
|This options allows you to change the installed package of gr-satnogs. For example, to install nightly development builds use:
 
|This options allows you to change the installed package of gr-satnogs. For example, to install nightly development builds use:
−
* <code><nowiki>https://gitlab.com/librespacefoundation/satnogs/gr-satnogs-package/-/jobs/artifacts/master/raw/build/debian/output/armhf/gr-satnogs_armhf.deb?job=nightly-armhf</nowiki></code>
+
 
 +
*<code><nowiki>https://gitlab.com/librespacefoundation/satnogs/gr-satnogs-package/-/jobs/artifacts/master/raw/build/debian/output/armhf/gr-satnogs_armhf.deb?job=nightly-armhf</nowiki></code>
 
|-
 
|-
 
|<code>RF_GAIN</code>
 
|<code>RF_GAIN</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].
 
|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].
−
* 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>
+
 
 +
*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>
 
|}
 
|}
  
−
== Updating SatNOGS Client software ==
+
==Updating SatNOGS Client software==
  
 
To update all Debian packages to the latest you can use the normal APT updating methods. SSH into the system and run the following commands:
 
To update all Debian packages to the latest you can use the normal APT updating methods. SSH into the system and run the following commands:
  
 
  <nowiki>
 
  <nowiki>
−
    $ sudo apt-get update
+
    $ sudo apt-get update
−
    $ sudo apt-get -y upgrade
+
    $ sudo apt-get -y upgrade
−
    $ sudo reboot</nowiki>
+
    $ sudo reboot</nowiki>
  
 
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
+
 
−
# Select <code>Update</code> to update the configuration tool
+
#SSH into the system and (re-)run <code>sudo satnogs-setup</code>; this will bring up the configuration menu
−
# Select <code>Apply</code> and the Raspberry Pi will update itself; this may take some time
+
#Select <code>Update</code> to update the configuration tool
−
# Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
+
#Select <code>Apply</code> and the Raspberry Pi will update itself; this may take some time
−
# Select <code>Back</code> to exit
+
#Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
 +
#Select <code>Back</code> to exit
  
 
'''WARNING: An update can potentially interrupt a running observation!'''
 
'''WARNING: An update can potentially interrupt a running observation!'''
  
−
== Verification of correct installation ==
+
==Verification of correct installation==
  
 
To see if satnogs-client has started successfully, check the logs with journalctl:
 
To see if satnogs-client has started successfully, check the logs with journalctl:

Revision as of 10:10, 19 May 2019

Intro

SatNOGS Client Ansible is the suggested method to install SatNOGS Client (and friends) to a system. It currently supports Raspbian and Debian Stretch.

Raspbian

For Raspberry Pi 3, which is the reference platform for SatNOGS, a Raspbian image with SatNOGS Client Ansible pre-installed is available.

Debian

Important.png
Skip this section if you are using SatNOGS Raspbian image and SatNOGS Client Setup. Follow these instructions if you are provisioning SatNOGS to Debian from another host.

These sections contain generic instructions for installing SatNOGS Client on a Debian Stretch system.

Prerequisites

  • A user which is member of 'sudo' group exists on the target system
  • An SSH server running on the target system
  • A host system with Git and latest version of Ansible installed

Instructions

On the host system run the following commands: 

     $ git clone https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git    # Clone SatNOGS Client Ansible repository
     $ cd satnogs-client-ansible                              # Change to cloned repository directory
     $ cp -r production.dist production                       # Copy dist configuration
     $ vi production/inventory/hosts                          # Update file with your own target host, user and SSH password
     $ ssh youruser@yourtargetsystem true                     # Test SSH connection to target system
     $ ansible-playbook -i production/inventory -K site.yml   # Run Ansible playbook
     $ ssh -t youruser@yourtargetsystem sudo satnogs-setup    # Setup SatNOGS client (see below)

SatNOGS Client Setup

satnogs-setup is a script for configuring a system installed with SatNOGS Client 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 Ansible system:

  1. SSH into the system and run sudo satnogs-setup; this will bring up the configuration menu
  2. Set 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.
SATNOGS_RX_DEVICE If you are using an RTL-SDR, this is rtlsdr. Other devices supported by gr-satnogs include usrpb200, usrp2, airspy or hackrf; a complete list can be found here.
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.
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. If you don't have a rotator (like the No rotator setup), enter NO.
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

Advanced Setup

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

Setting Description
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@0 -- the '0' 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_GR_SATNOGS_PACKAGE This options allows you to change the installed package of gr-satnogs. For example, to install nightly development builds use:
  • https://gitlab.com/librespacefoundation/satnogs/gr-satnogs-package/-/jobs/artifacts/master/raw/build/debian/output/armhf/gr-satnogs_armhf.deb?job=nightly-armhf
RF_GAIN RF Gain value for your SDR hardware. Defaults can be found here.
  • For rtl-sdr possible values are the following: 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

Updating SatNOGS Client software

To update all Debian packages to the latest you can use the normal APT updating methods. SSH into the system and run the following commands: 

     $ sudo apt-get update
     $ sudo apt-get -y upgrade
     $ sudo reboot

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
  3. Select Apply and the Raspberry Pi will update itself; this may take some time
  4. Before exit, check at the top that you have the latest satnogs-client and gr-satnogs versions
  5. Select Back to exit

WARNING: An update can potentially interrupt a running observation!

Verification of correct installation

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

journalctl -u satnogs-client.service

You should see entries running approximately once per minute that look like this: 

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

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

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