STaR

From PlanetaryImaging.org Wiki
Jump to navigation Jump to search
User screen shot (METOP processing)
User screen shot (NOAA processing)
"maker" PI314RIG prototype antenna

Satellite Track and Read (STaR) is a general satellite scheduling and tracking program with modular motion control and signal processing for polar orbiting direct broadcasts.

STaR is released under the GNU General Public License GPLV3 as published by the Free Software Foundation. Third party components carry their own licenses.

This is a beta release and is under construction.

Description

STaR graphical interface

Written in Python on Gnu/Linux, the package is capable of incorporating different motion control regimes by sharing a common rotor interface. STaR can also use independent Software Defined Radio (SDR) programs or hardware decoders to process different satellite signals. Current modules used in STaR are linked below.

STaR is currently driving a "maker" rig with the PI314MC and PI314LB boxes, a flat multi-patch L-band antenna and can read NOAA-18,19, and METOP-A,B,C satellites for available sounder and AVHRR data.

Maritime antenna retrofitted for terrestrial use

STaR has also driven a maritime rig (w/protoype PI314MC) retrofitted for terrestrial use and it read the same set of satellites.

Recent satellite images can viewed here and the delivery is fully automated through our scripts and third party code such as GnuRadio,Terrenus HRPT/CoastWatch, SSEC/Polar2Grid, and EUMETSAT/AAPP.

This project's status is beta operational.

Install

Installing STaR is done by copying the source directories and editing files for your location and motion control and signal processing scripts. There is no "pip", automated, or wizard installation, yet.

Requisites

   - Recent Linux (tested on 64-bit 8-core AMD Mint19)
   - Python 3.4 or greater
   - Synaptic packages used (be sure to include "dev" files, if provided): 
     - Python3-wxgtk4.0 wxPython(phoenix) for graphical interface
     - Python3-ephem 3.7.6.0 (newer releases may break next_pass() routine see here for more info)
       - DO NOT INSTALL https://pypi.org/project/ephemeris/#files. This is unrelated.
       - you can install Gpredict (from package manager) to verify that pyephem is working by comparing satellite predictions.
     - Installing advanced third party code (eg.CoastWatch,AAPP,etc.) will have their own requirements.

Copying from Source

NOTE: There is no version assignation yet, please revisit the STaR repository for updates.

   - Use a terminal and change into a directory to untar or clone the "star" directory into.
     eg. > cd /home/pi, so your working directory would be /home/pi/star after installing.
   - Use the command "tar xvf star.tar" or "git clone https://gitlab.com/planetaryimaging/star" to install the star directory.

STaR Directories

Brief description of the installed directories follows and is presented before the configuration instructions as a preface.

aux

Holds sun tracking code for antenna alignment and miscellaneous scripts, mostly for orbital elements (TLE) retrieval and crontab jobs. Edit the given scripts for your location as described below. Use your location configuration file for sun alignment and be aware that any comments in that file will disappear if suntrack.py saves the alignment values (for now). To point the antenna to the sun use:

 > cd $STAR_HOME/aux
 > ./suntrack.py ../conf/myconf.conf

Use "suntrack.py" to align your antenna to the sun with adjustable lead time, azimuth and elevation offsets. If your antenna can physically be rotated in the azimuth, set az_offset=0.0 in the configuration file and adjust the azimuth physically. Make sure the antenna is level. In this implementation, the antenna must have a way to cast a shadow to the focal point. I use a velcroed plastic stick with circular planes on both ends for flat antennas. Adjusting the antenna with suntrack.py to remove the shadow cast by the top circle indicates alignment. Stay tuned for how to find sun alignment on prime and side focus antennae (not yet implemented).

conf

This is a configuration directory for files describing rig, location, tracking, and processing specifics. Sample configuration files are given to customize from. A configuration file does not have to reside in this directory as its location can be specified in the STaR program command line argument. A description of configuration file entries is given below:

     - [satellites] # Section 
active= lets STaR know which satellites to use. Names MUST match those in associated TLE file and list is comma delimited. eg. active = NOAA 18,NOAA 19,METOP-B,METOP-C,METOP-A
num_passes= number of passes to predict into the future for each satellite. Refreshed after each pass. eg. num_passes = 5
zenith_min= minimal satellite zenith elevation to consider in degrees. This value is shown in the GUI path panel as a blue circle. eg. zenith_min = 25
sig_elev= elevation (degrees) to trigger signal reception, shown in the GUI path panel as a green circle. eg. sig_elev = 15
- [NOAA 18] # Specified satellite section (NOAA 18 is an example here) from active list. # Name must match the designation in the TLE file.
tle_file= location of TLE (orbital elements) file. TLE file must be refreshed frequently. See below for cron implementation.
read_script= location of signal reading script with parameters.
proc_script= location of post processing scripts with parameters.
- [rotor] # Section
lead= lead time in seconds for rotors to get to position from time of command, usually 0.5 to 3.0 seconds.
name= name given to rig setup.
module= address of python rotor driver to load. eg. module = /home/pi/star/rotors/dummy
az_offset= azimuth offset in degrees to align w/sun
el_offset= elevation offset in degrees to align w/sun
- [location] # Section, use decimal degrees
latitude= use + values for north, - values for south of equator
longitude= use + values for east, - values for west of Greenwich note: not all longitude ranges have been tested.
altitude= use meters
name= name of ground station

main

This directory holds the primary set of classes and executables for STaR. Executables are:

 - star.py command line version and contains the star class.
 eg. > ./star.py ../conf/some.conf [logfile] 
- stargui.py is the graphical interface version and uses star.py as a class. eg. > ./stargui.py ../conf/some.conf [logfile]

Log file is optional.

orbits

Handy place for Keplerian two line orbital elements (TLE) files, although locations can specified anywhere in the configuration file.

rotors

Holds dynamically loadable modules for specific rotors which derive from the "rotor.py" abstract class in the main directory. Rotor modules can be anywhere, as long as the PYTHONPATH environment variable and configuration file point to them. Refer to "dummy.py", it is simple and instructive. More complicated rotors, such the PI314_GRBL11, give a more practical example.

You should customize and load your own rotor methods (move_azel, get_azel, etc.), as the internal mechanics will be specific to different rotors, controllers, and communications. Each rotor controller and antenna has its qwerks and so it becomes necessary customize with separate communication and tracking class as well (has to do with motion ranges, etc.). See the released rotor modules for examples. Remember to include "__init__.py" file in the module directory (even if zero bytes) to indicate and load the custom rotor package. Communication classes (eg.serial) shared by more than one module are generally found in the base rotor directory.

scripts

Holds the satellite specific signal and data processing scripts. This directory is typically split into signal reading and processing directories, although the scripts can be specified anywhere in the configuration file.

Configuration

There are different levels of configuration depending on target applications, automation, and usage.

Generally, these configurations involve operating system concerns, requisite software, input data retrieval, and delivery of results (images and data). To exemplify this range, a dummy configuration is given first (TODO:and then followed by a real life prototype PI314 Rig with GnuRadio reading METOP and NOAA satellites).

Dummy Implementation

Configuring and testing the "dummy" implementation is the first step in validating the STaR installation.
Consider the topics in the sub-sections below::

User environment variables

You must set STaR environment variables and point to the STaR Python modules in the PYTHONPATH variable. It is recommended to set this in your ".bash_profile", only from experience and for reasons not yet understood (has to do with login shells, non-login shells, system persistence, etc.). Examples settings can be found in the $STAR_HOME/aux directory. Be sure to run STaR programs with these additional environmental variable active.

Time

Setting the computer time is critical for satellite tracking. Synchronize computer time with the "ntpdate" daemon or manually. The system program "ntpdate" must be run as root in a crontab job if the daemon is not running; see the example root cronfile in $STAR_HOME/aux directory. Also, see the note on rc.local below to set the time on a computer re-boot. For the immediate purpose of exercising "stargui.py" you can manually run "ntpdate time.nist.gov" as root.

Orbital Elements

Keplerian orbital Two-Line Elements (TLEs) must be initially and periodically updated for target satellites. These coefficients are necessary to predict the orbital paths. Be sure to periodically retrieve the TLEs with a crontab job; see the $STAR_HOME/aux directory for an example user crontab file. Review the orbit directory location in the "$STAR_HOME/aux/getelements" script and manually run to retrieve the necessary TLEs for immediate use.

 > $STAR_HOME/aux/getelements
Configuration File

Edit $STAR_HOME/conf/dummy.conf and insert your location in decimal degrees. You can use GoogleEarth, or GPS derived co-ordinates. You can also select satellites to track. Be aware that the METOP and NOAA satellites can overlap in which case passes are included in the scheduling on a first come basis.

  # use decimal degrees and meters
  latitude = DD.dddddd
  longitude = -DDD.dddddd
  altitude = MMMM
  name = ground station name
  NOTE: 
  Longitudes east of Greenwich are given as  DDD.dddddd but full range not tested
  Longitudes west of Greenwich are given as -DDD.dddddd but full range not tested 
  Latitudes north of the equator are given as  DD.dddddd but full range not tested
  Latitudes south of the equator are given as -DD.dddddd but full range not tested

General Notes

The $STAR_HOME/aux directory contains an rc.local file for STaR initialization on computer reboot. Not all GNU/Linux distributions implement the rc.local file on reboot. If the rc.local is not used, make sure that the time is set and TLEs are retrieved in some other way on reboot. Look at the rc.local file for guidance.

Depending on the setup, root crontab jobs also need to be considered. See the $STAR_HOME/aux/cronfile_root as an example.

For rotors using serial ports (even USB to serial) add the "dialout" group to user account in order to enable the port.

Don't forget the udev permissions for the SDR receivers.

GUI Interface

STaR graphical interface

The "stargui.py" is a graphical implementation of the class "star", found in the program "star.py". For a practical demonstration configure the dummy configuration as above and run the program with:

 > cd $STAR_HOME/main
 > ./stargui.py ../conf/dummy.conf [logfile.log]

A log file can be specified on the command line, otherwise "star.log" is used. The log file is overwritten with each session, so rename the old log if you want to save it before running the program again.

The GUI display should look like the image to the right.

The display shows a schedule of specified satellite predicted passes and log messages in text panels. In addition, there is a panel which shows the sky path of a scheduled satellite pass. Click on a scheduled pass in the text window to see its sky path, in terms of azimuth and elevation coordinates. Black circles show 0, 30, and 60 degree elevation while straight line show azimuth coordinates (North,South,East,West).

The path panel also reports the rotor position of the antenna with a cross cursor and text values. The user can interactively move the antenna rotor position by clicking the left button over the sky "dome", ie.,the area enclosed by the outer circle which represents the local horizons. Hovering the mouse over the dome reports its angular position.

The GUI path panel also indicates the minimum zenith and signal read elevation values specified in the configuration file, and are shown in blue and green circles respectively. When tracking a satellite, the cross-cursor representing rotor position will follow its sky path. Interactive antenna movement, described above, is disabled while tracking a satellite. The green dot shows the start position of the satellite sky path (rise) and the red dot shows the end of the path (set).

Module and Component Overview

Current Hardware Modules

Coming Soon!

Motion Control Boxes

Coming Soon!

PI314MC

Coming Soon!

Signal Boxes

Coming Soon!

PI314LB

Coming Soon!

Current SDR Modules

NOAA-18,19

Coming Soon!

METOP-A,B,C

Coming Soon!

PI314RIG

Soon to Come!

PI314RIG "maker" antenna