The Sattool Manual ------------------ Tom Rothamel Prerelease 1 ------------------------------------------------------------------------------- Copyright Notice ---------------- Copyright (C) 1999 Tom Rothamel This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This is distributed in the hope that it will be useful, but _without any warranty_; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. A copy of the GNU General Public License is available on the World Wide Web at http://www.gnu.org/copyleft/gpl.html. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------- Contents -------- 1. Introduction 1.1. Lists of Things 1.2. Command Line Options 1.3. Environment Variables 2. Using Sattool For Visual Satellite Prediction 2.1. Predicting Passes 2.2. Filtering Passes 2.3. Displaying The Passes 2.4. Putting it All Together 2.5. The Live Display 3. Command Reference 3.1. cat 3.2. writetle 3.3. filter 3.4. marker 3.5. live 3.6. predict 3.7. passes 3.8. step 3.9. summary ------------------------------------------------------------------------------- 1. Introduction --------------- Sattool is a program for the prediction of the motion of artificial satellites. Support for predicting the visual magnitudes of these satellites is already in place, with support for predicting the radio frequencies coming soon. Sattool is structured as a set of small sub-programs, each of which does one task. In order to determine which sub-program to run, sattool first looks at the name it was called under. If that name is of the format sat, it calls the subprogram . Otherwise, it expects to be invoked as 'sattool ', with the program name available as the first argument. Generally, shell pipelines are used to connect the various steps in a prediction process together. This allows for maximum flexiblity and control of this process, even allowing the various steps to be run on different machines. (For example, running the computationally intensive prediction step on one machine, and the less demanding live tracking on a second machine.) Using the shell also encourages the creation of scripts to automate common tasks. 1.1. Lists of Things -------------------- Sattool works on lists of things. A thing is something like a satellite, a pass, a site, or an encounter. Many things can look like other things when appropriate. For example, if a Pass is used in a situation where a satellite is more appropriate, the satellite corresponding to the pass will be used rather than the pass itself. This may seem complicated, but usually results in sattool doing the right thing in most circumstances. 1.2. Command Line Options ------------------------- The following are the command line options that the various sattool sub-programs take. Not every option is relavent to every sub-program, but the ones that are relevant are obeyed consistently. -i , --infile Forces input to be read from , rather than from the default location of stdin. -t, --tle Specifies that the input is in TLE format, rather than sattool's native format. -o , --outfile Specifies a filename for output. If no filename is specified, this will default to stdout. -q, --quiet This engages quiet mode, suppressing the printing of progress messages. -v, --visual This selects visual mode. Some sub-programs will behave slightly differently if visual mode is selected. See the individual documentation below. 1.3. Environment Variables -------------------------- The following are environment variables that many of the sattool sub-programs take. There are also environment variables that are only relavant to one of the sub-programs... They're listed in the documentation for that sub-program. SATSITE This defines a site for prediction or live display. The variable itself contains an input list entry for an object. Usually, this is an earthsite entry, which has the format '(earthsite "" ")'. For example, for the author's observing site, this is set to '(eartsite "Northport, NY" 40.9037 -73.3455 0)'. ------------------------------------------------------------------------------- 2. Using Sattool For Visual Satellite Prediction ------------------------------------------------ This section is a tutorial on how to predict visual satellite passes using sattool. I've set this up as a set of steps. Please realize that the steps must be combined into a coherent whole to be useful. This is done either using pipes or using the -o and -i options to redirect the input and output into files. Please see the section "Putting it Together" for details on how to do this. This section assumes you have acquired a TLE file containing orbital elements and magnitude information. One such file is the mccants file, which can be dowloaded using the command 'gettle mccants.tle'. For the rest of this example, we'll be using mccants.tle to represent this file. Any elements file with similar magnitude information will work. 2.1. Predicting Passes ---------------------- The first step is to predict the visual passes. In order to do that, the 'sattool predict' command is used. Before it can be used, however, a site must be defined. For our purposes, we'll assume that the site chosen is one that's fixed to the earth's surface, which is the case for most observers. Such a site is defined by it's latitude, longitude, and altitude above the reference spheroid. (AKA the elevation). The site is defined by the SATSITE environment variable. The user's location must be substituted in. For example, to set a location of Northport, NY (which is at 40.9037 N, 73.3455 W, 0 km elevation), the command in a bash-like shell is export SATSITE='(earthsite "Northport, NY" 40.9037 -73.3455 0)' Once the site is set, prediction can occur. A sample command line is sattool predict -vti mccants.tle "noon today" "midnight today" This tells sattool to do visual prediction from noon to midnight on the day in which the command is issued. It'll read tle format elements from the file mccants.tle. The -v option tells sattool to calculate minimum magnitudes for each pass. Sattool will then send a list of passes to standard output, or to a file if the -o option was given. 2.2. Filtering Passes --------------------- Once a list of passes has been created, it must be filtered. The filter sub-program is what does that. The filter command takes an expression which defines which passes are allowed through. It's defining this expression which is important. In order to see a visual satellite, there are two major conditions that must be met. The first is that the satellite must be lit. This is accomplished using the filter expression 'lit'. The second condition is that the observer's site must be in darkness. Generally, brighter satellites can be seen when the sun is 6 degrees beneath the horizon. The corresponding filter expression is 'sunel lt -6'. (lt is short for less than.) In addition, it's useful to filter out passes with minimum magnitudes above a certain value. The choice of this value varies from user to user. The author uses 3.0 when he's at home or school, or 3.5 if he's looking for some dimmer satellites in a dedicated viewing session. The exact choice is dependant on user skill and local light pollution. Anyway, the filter expression is 'minmag lt 3.0'. (Or whatever, pick your own magnitude limit.) These expressions are combined using the 'and' keyword. It also helps to use -- on the command line, so the -6 isn't parsed as an option. The net command is: sattool filter -- lit and sunel lt -6 and minmag lt 3.0 -o passlist Please note that this command will read a list of passes from standard input and write one out to the passlist file. 2.3. Displaying The Passes -------------------------- Now that we have a list of passes that are visible, it's useful to have the passes displayed in a more readable form. The two commands that do this are passes and step. The passes command prints the list of passes in a human readable form. It displays the times of various events in a pass. For each pass event, it prints out the list entries in the format: 21147 91017A Lacrosse 2 Pass Start: 19991126 16:53:02 179.4 S 10.1 +5.6 2074 Pass Max Elev: 19991126 16:57:25 110.3 E 39.6 +3.0 987 Pass Min Mag: 19991126 16:57:49 97.5 E 38.7 +3.0 1003 Pass End: 19991126 17:01:47 42.7 NE 10.2 +4.5 2086 The first line of a pass display contains the satellite's norad number, its international designation, and its name. The other lines contain the event type, the date, the time, the azimuth, a compass bearing based on the azimuth, the elevation, the magnitude, and the range in kilometers. For example, the point of maximum elevation for this pass occurs at 4:57:25 pm on November 11th, 1999. At that time, the azimuth is 110.3 degrees, which is in the east. The elevation is 39.6 degrees high, and the magnitude at that time is +3.0. At that time, the satellite is 987 kilometers away. The command to invoke the passes sub-program is sattool passes -i passlist The other command for displaying passes is the step command. This displays the information given above every specified number of seconds. This is more useful for novices or people who want more details on the motion of the satellite. It only prints out passes matching a filter expression. (The filter expression can be 'true', which is true all the time, but it most be present.) The output looks like: 21147 91017A Lacrosse 2 (4.906 days old.) 19991126 16:54:55 166.1 S 22.2 +4.5 1432 19991126 16:55:25 159.9 S 26.4 +4.1 1289 19991126 16:55:55 151.6 SE 30.8 +3.8 1165 And the command is: sattool step 30 true where 30 is the number of seconds between each printed position. The expression is evaluated at every position, with one useful expression being 'mag lt 4', which will only print times where the satellite's magnitude is less than 4. 2.4. Putting it All Together ---------------------------- Now is the time for putting it all together. There are two ways to do this: using pipes or using the -i and -o options to connect the two files. Generally, a mix of these are used. For example, the command the author uses to find relatively bright satellites is: ./sattool predict -vti mccants.tle now midnight | \ ./sattool filter -o passlist -- lit and sunel lt -6 and minmag lt 3 ./sattool step -i passlist 30 mag lt 4.5 This reads elements from the file mccants.tle, and predicts the passes from the current time to the next midnight. It then pipes the list of passes to a filter, and saves the filtered list into the file passlist. It then steps the passes. It's generally useful to store the filtered passlist in a file, since that allows the passlist to be viewed in some of the other tools. (Most notably, the live display sub-program.) 2.5. The Live Display --------------------- The live display is invoked with the command ./sattool live -i passlist It's important that a file is used, as piping it to standard input causes standard input to be closed. That makes it impossible to give keyboard commands to the live display. Once the live display is up, press the 'v' key to call up a magnitude display. Then, the arrow keys can be use to move forwards and backwards through the passlist. Use the 'q' key to quit the live tracking display. More information about the list sub-program can be found in the command reference section below. ------------------------------------------------------------------------------- 3. Command Reference -------------------- 3.1. cat -------- The cat command simply copies the input list to the output list. It's only useful for converting from a TLE file to sattool's native format. Even at that, it isn't really all that useful. 3.2. writetle ------------- The writetle command attempts to parse each input list element as a Sgp4Sat. If it can do this, it outputs the element in TLE format. 3.3. filter ----------- Filter allows for filtering the input list based on arbitrary expressions. It's a fairly sophisticated expression parser, which allows expressions to be connected using 'and' and 'or' operators. It's also possible to use parenthesis to clarify your expression. Expressions contain keywords of two types. Boolean keywords return true if what it represents is true. Value keywords take an operator and something to compare it with, and they use that to determine the truth values. The operators allowed are '<', which can be written as 'lt'; '>', which can be written as 'gt'; and '='. The keywords are: false A boolean keyword that's always false. lit A boolean keyword that's true if the pass is lit at it's beginning or end. mag A value keyword that's the satellite's visual magnitude during an encounter. minmag A value keyword that's the satellite's minimum magnitude for the current pass. This is only defined if we're filtering a pass. norad A value keyword that represents the satellite's norad number. This works on satellites. sunel A value keyword that represents the sun's elevation at the time in question. (Which is either the cumulation of a pass or the time of an encounter.) true A boolean keyword that's always true. Sample filter expressions are: norad = 16609 or norad = 25544 lit and sunel lt -6 and minmag lt 3.56 It may be necessary to place a -- on the command line before the expression to prevent negative numbers from being parsed as options. 3.4. marker ----------- The marker command takes a list of sats for it's input, and takes as an argument a number of seconds. It also requires that an output file be specified with the -o option. Then, every number of seconds, it writes the current latitude and longitude to the file in a way compatible with the markerfile capabilites of xearth and xglobe. 3.5. live --------- The live command reads in an input list of objects (or equivalents), and displays it in realtime. Depending on what exactly is in the input list, more information may be displayed. For example, satellites also display their norad number and international designations, and passed display times of rise, set, cumulation, and maximum magnitude. Look angles, Latitude, Longitude, Altitude, and ECI vectors are always displayed. The units are km, km/s, or degrees, as appropriate. The live command only works properly if it's input is a file specified with the -i option. Here's a list of valid keystrokes. v Toggle visual mode. Visual mode consist of a display of magnitude information on the right stide of the screen. This is the default if the -v option is given. 1 This fixed the display time to the start of the current pass. 2 This fixed the display time to the cumulation of the current pass. 3 This fixed the display time to the end of the current pass. 1 This fixed the display time to real time. space This displays either the next pass that hasn't been completed yet, or the next satellite that's currently risen. + This increases the offset between the time of the data displayed on the screen and the current time. - This decreases the offset between the time of the data displayed on the screen and the current time. l This toggles a lock on a satellite. When lock is engaged, a pipe to the program defined in the environment variable SATLOCKPROG is established. Then, every SATLOCKSTEP seconds, the azimuth, elevation, and current satellite name is send down the pipe to that program. ; This decreases the offset between the time used to calculate look angles in a lock, and real time. ' This increases the offset between the time used to calculate look angles in a lock, and real time. down, right This moves the display to the next list element. up, left This moves the display to the previous list element. home, < This moves the display to the first list element. end, > This moves the display to the last list element. q This quits the live satellite display sub-program. 3.6. predict ------------ The predict command is used to predict when a satellite pass will be visible at a given site. A pass is defined as a time when the satellite is above a given elevation. If predict is invoked with one argument, that argument is the end time of the prediction. The start time is now. Otherwise, if two or more arguments are given, the first is the start time and the second is the end time. The time parser is fairly sophisticated. Some of the time specifications it can handle are: 1999-12-11 12:30 noon today midnight + 2 hours If no day is mentioned, the time is considered to be it's next occurance. For example if it's 19:30 today, the time specification 20:00 occurs on today, while 19:00 occurs tomorrow. (Unless a more specific date is mentioned.) It may be important to quote the time specifications so that they're not interpreted by the shell. There are also otional third and fourth arguments. The third argument is is the minimum pass elevation. This defaults to the contents of the SATMINELEV environment variable. If that's not set, and the -v option is given, the default is 10 degrees. Otherwise, it defaults to 0 degrees. The fourth option is a step time. This controls the accuracy of the pass predictions, and defaults to the value of SATPREDICTSTEP, or 10 seconds if that's undefined. The -v option is useful with predict. That option enables the prediction of visual pass information, namely the minimum magnitude found in a pass, as well as the time of that minimum magnitude. 3.7. passes ----------- The passes command displays information about every pass object that's piped to it. For a more complete description of this command, please see the section on "Displaying the Passes" above. 3.8. step --------- The step command takes two arguments. The first is a number of seconds, the second is an expression. The step command filters the encounter that occur every given number of seconds during the pass. It then prints out each encounter that matches the filter. For a more complete description of this command, please see the section on "Displaying the passes" above. 3.9. summary ------------ The summary command displays a one line summary of each of the passes in the input list. The summarries look like: 16609 86017A Mir Complex 11/30 17:56 58 -0.6 The fields in the display are, from left to right, the norad number, the international designation, the name, the date of the pass maximum, the time of the pass maximum, the maximum elevation in the pass, and the minimum magnitude during the pass. (The latter is omitted if no visual information is associated with the pass.) ------------------------------------------------------------------------------- The Sattool Manual Tom Rothamel Prerelease 1