|
|
| (14 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | =Intro= | + | ==Introduction== |
| | | | |
| − | '''SatNOGS Client Ansible''' is the suggested method to install '''SatNOGS Client''' (and friends) to a system. It currently supports Raspbian and Debian (stretch and buster).
| + | {{Warning|Follow these instructions only if you are provisioning SatNOGS to Debian from another host or are installing on the same host. }} |
| | | | |
| − | =Raspbian=
| + | '''SatNOGS Client Ansible''' makes the actual provisioning of the '''SatNOGS Client''' system. It is called, under the hood, when applying the configuration using [[SatNOGS Client Setup|SatNOGS Client Setup utility]]. It currently supports Raspbian and Debian (stretch and buster). |
| | | | |
| − | For Raspberry Pi, which is the reference platform for SatNOGS, a [[Raspberry_Pi_3|Raspbian image]] with '''SatNOGS Client Ansible''' pre-installed is available.
| + | ==Raspbian== |
| | | | |
| − | =Debian=
| + | For Raspberry Pi, which is the reference platform for SatNOGS, a custom Raspbian image with '''SatNOGS Client Ansible''' pre-installed is available. Installation instructions are given in the [[Raspberry_Pi| Raspberry Pi Setup Guide]]. |
| | | | |
| − | {{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 or are installing on the same host.}}These sections contain generic instructions for installing SatNOGS Client on a Debian system.
| + | ==Debian== |
| | | | |
| − | ==Prerequisites== | + | These sections contain generic instructions for installing SatNOGS Client on a Debian system. |
| | + | |
| | + | ==Other distributions== |
| | + | |
| | + | Other distributions are not supported by '''SatNOGS Client Ansible''', as the pre-built packages won't be compatible. Thus, while derived from Debian, '''SatNOGS Client Ansible''' is known to break for Ubuntu and Linux Mint. If you are an experienced user, a manual installation of all components could be possible. |
| | + | |
| | + | ==Installation Guide== |
| | + | ===Prerequisites=== |
| | | | |
| | *A target Debian system. To install Debian please follow the [https://www.debian.org/releases/stretch/installmanual Debian Installation Guide] and chose the net installer if you want to run a headless server. The target system can be the host itself. | | *A target Debian system. To install Debian please follow the [https://www.debian.org/releases/stretch/installmanual Debian Installation Guide] and chose the net installer if you want to run a headless server. The target system can be the host itself. |
| − | *A user (referenced later as ''youruser'') which is member of 'sudo' group exists on the target system. | + | *A user (referenced later as ''youruser'') which is member of 'sudo' group exists on the target system. Don't use the username `satnogs` when you install the Debian 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. To install Ansible on Debian, follow the [https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#latest-releases-via-apt-debian Ansible Installation Guide]. | + | *Install installation dependencies: `sudo apt-get install ansible git sshpass python-setuptools` |
| | | | |
| − | ==Installation== | + | ===Installation=== |
| | | | |
| | On the host system run the following commands: | | On the host system run the following commands: |
| | $ git clone <nowiki>https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git</nowiki> # Clone SatNOGS Client Ansible repository | | $ git clone <nowiki>https://gitlab.com/librespacefoundation/satnogs/satnogs-client-ansible.git</nowiki> # 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 | + | $ git checkout stable # Optionally, check out stable (Debian Buster 10) branch |
| − | $ vi production/inventory/hosts # Update file with your own target host e.g. 127.0.0.1, user and SSH password | + | $ cp -r production.dist production # Copy dist configuration |
| − | $ ssh youruser@yourtargetsystem true # Test SSH connection to target system | + | $ vi production/inventory/hosts # Update file with your own target host e.g. 127.0.0.1, user and SSH password |
| − | $ ansible-playbook -i production/inventory -K site.yml # Run Ansible playbook | + | $ ssh youruser@yourtargetsystem true # Test SSH connection to target system |
| − | $ ssh -t youruser@yourtargetsystem sudo satnogs-setup # Setup SatNOGS client (see below) | + | $ ansible-playbook -i production/inventory/hosts -K site.yml # Run Ansible playbook |
| − | | + | $ ssh -t youruser@yourtargetsystem sudo satnogs-setup # Setup SatNOGS client (see below) |
| − | =SatNOGS Client Setup=
| |
| − | | |
| − | <code>satnogs-setup</code> 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 SatNOGS Client software|Updating]] instruction found below.
| |
| − | | |
| − | 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
| |
| − | #Set '''Basic Configuration''' (see below)
| |
| − | #Select <code>Apply</code> and the Raspberry Pi will configure itself; this may take some time
| |
| − | #Select <code>Back</code> to exit
| |
| − | | |
| − | {{Message|You can always reconfigure the software by running <code>sudo satnogs-setup</code> again.}}
| |
| − | | |
| − | ===Basic Configuration===
| |
| − | | |
| − | {| class="wikitable"
| |
| − | !Setting
| |
| − | !Description
| |
| − | |-
| |
| − | |<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.
| |
| − | |-
| |
| − | |<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> 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].
| |
| − | |-
| |
| − | |<code>SATNOGS_STATION_ELEV</code>
| |
| − | |The height of your ground station above sea level in metres.
| |
| − | |-
| |
| − | |<code>SATNOGS_STATION_ID</code>
| |
| − | |The '''numeric ID''' assigned to your station in the SatNOGS Network site when the groundstation was created.
| |
| − | |-
| |
| − | |<code>SATNOGS_STATION_LAT</code>
| |
| − | |The latitude of your station. North is positive, south is negative.
| |
| − | |-
| |
| − | |<code>SATNOGS_STATION_LON</code>
| |
| − | |The longitude of your station. East is positive, west is negative.
| |
| − | |-
| |
| − | |<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 [https://wiki.satnogs.org/No_rotator No rotator setup]), enter <code>NO</code>.
| |
| − | |-
| |
| − | |<code>HAMLIB_UTILS_ROT_OPTS</code>
| |
| − | |Options for rotcld:
| |
| − | For a yaesu rotator, use <code>-m 601 -r /dev/ttyACM0 -s 9600 -T 0.0.0.0</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]].
| |
| − | {| class="wikitable"
| |
| − | !Setting
| |
| − | !Description
| |
| − | |-
| |
| − | |<code>APT_REPOSITORY</code>
| |
| − | |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>APT_KEY_URL</code>
| |
| − | |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>APT_KEY_ID</code>
| |
| − | |This options allows you to specify an alternative SatNOGS packages repository key ID.
| |
| − | |-
| |
| − | |<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:
| |
| − | | |
| − | *<code>git+https://gitlab.com/librespacefoundation/satnogs/satnogs-client.git@master</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>SATNOGS_RADIO_GR_SATNOGS_VERSION</code>
| |
| − | |This options allows you to change the version of gr-satnogs package to be installed. For example:
| |
| − | <code>1.5.1-1</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].
| |
| − | | |
| − | *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==
| |
| − | | |
| − | 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>Upgrade</code> to upgrade all distribution packages to the latest; this may require a reboot. If this option is not available, running an <code>Update</code> will make it show up
| |
| − | #Select <code>Update</code> to update the configuration tool
| |
| − | #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
| |
| − | #Select <code>Back</code> to exit
| |
| − | | |
| − | '''WARNING: An update can potentially interrupt a running observation!'''
| |
| − | | |
| − | ==Upgrading from 'stretch' to 'buster'==
| |
| − | 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]), it is recommended to upgrade to <code>buster</code>. Support for <code>stretch</code> will be dropped with the next release of <code>gr-satnogs</code>.
| |
| − | | |
| − | ===Method 1: Reflashing and reinstalling (recommended)===
| |
| − | The recommended method to upgrade to <code>buster</code> is reflashing the latest Raspbian SatNOGS image (or reinstalling latest Debian). Follow [[Raspberry Pi 3|Raspberry Pi]] installation instructions and reinstall from scratch.
| |
| − | | |
| − | ===Method 2: Release upgrade using the configuration tool (advanced)===
| |
| − | {{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:
| |
| − | | |
| − | #SSH into the system
| |
| − | #Make sure you have enough free space on your SD card (>2GiB) by running <code>df -h /</code> on the console
| |
| − | #Run <code>sudo satnogs-setup</code> to bring up the configuration menu
| |
| − | #On the Advanced menu, enable <code>SATNOGS_SETUP_RELEASE_UPGRADE_ENABLED</code> option, in case there isn't an option like that available run first <code>Update</code> and then try again to enable it.
| |
| − | #On the Main menu, select <code>Apply</code> and let Ansible apply the configuration
| |
| − | #On the Main menu, select <code>Upgrade</code>. The script will check if there is a new release upgrade and ask you to proceed
| |
| − | #Keep an eye on the upgrade progress; <code>dpkg</code> may prompt for changes
| |
| − | #Once the upgrade is completed, <code>satnogs-setup</code> will ask for a reboot
| |
| − | #After the reboot, 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>
| |
| − | | |
| − | ==Verification of correct installation==
| |
| − | | |
| − | To see if satnogs-client has started successfully, check the logs with journalctl:
| |
| | | | |
| − | <pre> | + | <br /> |
| − | $ journalctl -u satnogs-client.service
| |
| − | </pre>
| |
| | | | |
| − | You should see entries running approximately once per minute that look like this:
| + | ===Next Steps=== |
| | | | |
| − | <pre>
| + | Follow [[SatNOGS_Client_Setup|SatNOGS Client Setup]] to configure your system and SatNOGS station. |
| − | 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.
| + | [[Category:Build]] |
| | + | [[Category:Software]] |
