PREDICT(1)                      KD2BD Software                      PREDICT(1)



NNAAMMEE
       predict - Track and predict passes of satellites in Earth orbit.


SSYYNNOOPPSSIISS
       predict  [-u  _t_l_e___u_p_d_a_t_e___s_o_u_r_c_e]  [-t _t_l_e_f_i_l_e] [-q _q_t_h_f_i_l_e] [-d _d_b_f_i_l_e]
       [-a _s_e_r_i_a_l___p_o_r_t]  [-a1  _s_e_r_i_a_l___p_o_r_t]  [-n  _n_e_t_w_o_r_k___p_o_r_t]  [-f  _s_a_t___n_a_m_e
       _s_t_a_r_t_i_n_g___d_a_t_e_/_t_i_m_e  _e_n_d_i_n_g___d_a_t_e_/_t_i_m_e]  [-dp _s_a_t___n_a_m_e _s_t_a_r_t_i_n_g___d_a_t_e_/_t_i_m_e
       _e_n_d_i_n_g___d_a_t_e_/_t_i_m_e] [-p  _s_a_t___n_a_m_e  _s_t_a_r_t_i_n_g___d_a_t_e_/_t_i_m_e]  [-o  _o_u_t_p_u_t___f_i_l_e]
       [-s] [-east] [-west] [-north] [-south]


DDEESSCCRRIIPPTTIIOONN
       PPRREEDDIICCTT  is  a multi-user satellite tracking and orbital prediction ap‐
       plication created by John A. Magliacane, KD2BD, for execution under the
       Linux  operating  system.  PPRREEDDIICCTT  is  free software. It may be redis‐
       tributed and/or modified under the terms of the GNU General Public  Li‐
       cense as published by the Free Software Foundation, either version 2 of
       the License or any later version.

       PPRREEDDIICCTT provides real-time satellite tracking  and  orbital  prediction
       information  to  users  and client applications through the system con‐
       sole, through the command line, through a network socket,  and  through
       the generation of audio speech.

       Information such as a spacecraft's sub-satellite point, azimuth and el‐
       evation headings, Doppler shift, path loss, slant range, orbital  alti‐
       tude,  orbital  velocity, footprint diameter, orbital phase (mean anom‐
       aly), squint angle, eclipse depth, propagation delay, the time and date
       of  the  next  AOS (or LOS of the current pass), orbit number, and sun‐
       light and visibility information are provided  on  a  real-time  basis.
       PPRREEDDIICCTT can even track (or predict the position of) the Sun and Moon.

       PPRREEDDIICCTT also has the ability to control AZ/EL rotators to establish and
       maintain accurate antenna orientation toward the direction of  communi‐
       cation  satellites.  As  an  aid  in  locating  and tracking satellites
       through optical means, PPRREEDDIICCTT can  articulate  azimuth  and  elevation
       bearings  in addition to visibility information to users in the form of
       plain speech.

       PPRREEDDIICCTT has been successfully employed by the National Aeronautics  and
       Space  Administration where it provides orbital prediction and tracking
       data for VLBI radio telescope steering.  It is  used  by  the  European
       Space  Agency's Rutherford Appleton Laboratory where it provides track‐
       ing data and velocity profiles used to steer the 25 meter dish  antenna
       at  the Chilbolton Observatory.  PPRREEDDIICCTT also powers AMSAT-NA's on-line
       satellite prediction web page (_h_t_t_p_s_:_/_/_w_w_w_._a_m_s_a_t_._o_r_g_/_t_r_a_c_k_/),  and  has
       served  as  the  basis for a host of other derivative software applica‐
       tions.

       PPRREEDDIICCTT 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.


RREEQQUUIIRREEMMEENNTTSS
       PPRREEDDIICCTT  is written in 'C' and distributed as source code for Linux en‐
       vironments.  Compilation requires Bash, a C compiler  (gcc  or  clang),
       ncurses,  pthreads,  and  ALSA libraries.  PPRREEDDIICCTT can also be compiled
       and executed under an Android environment running Termux,  a  free  and
       open source Android terminal emulator and Linux environment app that is
       available through GitHub and F-Droid.

       The DOS version of PPRREEDDIICCTT includes a pre-compiled executable file that
       was  built  using GCC under a DJGPP environment powered by FreeDOS, and
       is distributed with a 32-bit DOS Protected Mode Interface.  While  PPRREE‐‐
       DDIICCTT's  capabilities are limited by those of DOS, it does function well
       under DOSEMU (using FreeDOS) and DOSBox, which can operate under Linux,
       OS/2, RISC OS, Windows, BeOS, and MacOS X.


FFIIRRSSTT TTIIMMEE UUSSEE
       PPRREEDDIICCTT  predicts  passes of satellites based on the geographical loca‐
       tion of the ground station, the current date and time provided  by  the
       computer  system's  clock/calendar,  and Keplerian orbital data for the
       satellites of interest to the ground station.  First time users of PPRREE‐‐
       DDIICCTT  are provided default ground station location and orbital data in‐
       formation files. These files are managed by the program  and  are  nor‐
       mally  located  in  a user's home directory under a hidden subdirectory
       named _._p_r_e_d_i_c_t.

       First time users will be prompted to supply  PPRREEDDIICCTT  with  their  geo‐
       graphical location the first time the program is executed.  This infor‐
       mation can be changed at any later date by selecting  option  [[GG]]  from
       the program's Main Menu.

       Latitude is normally expressed in degrees North with latitudes south of
       the equator expressed in negative degrees. Longitude  is  normally  ex‐
       pressed in degrees West (0-360 degrees).  Eastern longitudes can be ex‐
       pressed in negative degrees. This behavior can be modified  by  passing
       the _-_e_a_s_t or _-_s_o_u_t_h commmand line switches to PPRREEDDIICCTT.

       Latitudes  and  longitudes  may  be  entered  either in decimal degrees
       (41.716905) or in degree, minute, second (DMS)  format  (41  43  0.84).
       Station altitude is accepted as the number of meters the ground station
       is located above sea level.  This parameter is not very  critical.   If
       unsure, make a realistic guess or simply enter 0.

       PPRREEDDIICCTT employs a line editor that normally operates in Overwrite Mode.
       Overwrite Mode can be toggled to Insert Mode (and vice versa)  by  tap‐
       ping  the Insert key.  The cursor (and current editing position) can be
       moved left or right by pressing the corresponding  cursor  arrow  keys.
       The insertion point can be moved to the beginning of the line by press‐
       ing the Home key.  Selecting the End key will move the insertion  point
       to the end of the line.  The Delete key deletes the character currently
       under the cursor.  The Backspace Key will delete the character  to  the
       right of the cursor.  Pressing Enter, the Tab key, or clicking the left
       mouse button will terminate the editing process and accept  the  edited
       line  exactly  as  it appears.  Pressing the EESSCCape key or clicking the
       right mouse button will also terminate the editing function,  but  will
       discard any changes made to the line.

       Users  of  PPRREEDDIICCTT  need Keplerian orbital data for the satellites they
       wish to track that is preferably not older than one month. The  default
       orbital  data  supplied with the program is liable to be quite old, and
       so must be brought up to date if accurate results are to  be  expected.
       This  may  be  accomplished by selecting option [[EE]] from PPRREEDDIICCTT''ss Main
       Menu and manually entering Keplerian data for  each  satellite  in  the
       program's  database.   Updates can also be made by selecting option [[UU]]
       and specifying a file containing recent 2-line Keplerian  element  data
       sets that correspond to the satellites in the program's database.  Kep‐
       lerian orbital data is available from a variety of  sources,  including
       _h_t_t_p_s_:_/_/_c_e_l_e_s_t_r_a_k_._o_r_g_/, _h_t_t_p_:_/_/_w_w_w_._s_p_a_c_e_-_t_r_a_c_k_._o_r_g_/, and _h_t_t_p_:_/_/_w_w_w_._a_m_‐
       _s_a_t_._o_r_g_/.

       It is possible to replace an existing satellite in PPRREEDDIICCTT's  Keplerian
       element  orbital  database with a different one by manually editing all
       the Keplerian data for that satellite.  Howewver, it is often easier to
       simply  edit  the  name and object number of an existing satellite with
       corresponding information for the new  satellite  of  interest.   Then,
       follow  Main  Menu option [[UU]] and specify a file containing a Keplerian
       element set for the new satellite of interest that is more recent  than
       that of the satellite you wish to replace.

       Uplink and downlink frequencies are held in PPRREEDDIICCTT''ss transponder data‐
       base file _p_r_e_d_i_c_t_._d_b located under _$_H_O_M_E_/_._p_r_e_d_i_c_t.  A default  file  is
       provided with PPRREEDDIICCTT.  The database may be viewed or edited by select‐
       ing the [[BB]] Main Menu option.  Up to ten transponders, uplink, or down‐
       link  frequencies  may  be  specified for each satellite.  In addition,
       Bahn Coordinates for each satellite may be entered to permit the proper
       determination of squint angles in Single Satellite Tracking Mode.


PPRROOGGRRAAMM OOPPEERRAATTIIOONN
       The  start-up  screen  of  PPRREEDDIICCTT  lists the program's main functions.
       Several tracking and orbital prediction modes are available, as well as
       several utilities to manage the program's orbital database.


PPRREEDDIICCTTIINNGG SSAATTEELLLLIITTEE PPAASSSSEESS
       Orbital predictions are useful for determining in advance when a satel‐
       lite is expected to come within range of a  ground  station.  They  can
       also  be  used  to  look  back to previous passes to help to confirm or
       identify past observations.

       PPRREEDDIICCTT includes two orbital prediction modes to predict any pass above
       a ground station (Main Menu option [[PP]]), or list only those passes that
       might be visible to a ground station through optical means  (Main  Menu
       option [[VV]]). In either mode, the user is asked to select a satellite of
       interest from a menu, and then asked to enter the  date  and  time  (in
       UTC) at which prediction calculations should start.

       The  current date and time may be selected by default by entering noth‐
       ing and hitting simply the ENTER key when prompted to enter the  start‐
       ing date and time.

       Otherwise, the starting date and time should be entered in the form:

            _D_D_M_o_n_Y_Y _H_H_:_M_M_:_S_S

       Entering  the  time is optional.  If it is omitted, midnight (00:00:00)
       is assumed.  Once complete, orbital calculations are started  and  pre‐
       diction information is displayed on the screen.

       The  date  and  time in UTC, along with the satellite's elevation above
       ground, azimuth heading, modulo 256 orbital phase, sub-satellite  point
       latitude  and longitude, slant range between the ground station and the
       satellite, and the satellite's orbit  number  are  all  displayed.   If
       spacecraft  attitude  parameters (ALAT, ALON) are included in PPRREEDDIICCTT''ss
       transponder database file, then spacecraft antenna  squint  angles  are
       displayed instead of orbit numbers in the orbital prediction output.

       An  asterisk  (*)  displayed to the right of the orbit number or squint
       angle means the satellite is in sunlight at the date and time listed on
       the  line.  A  plus symbol (+) means the satellite is in sunlight while
       the ground station is under the cover of darkness at the time and  date
       listed.   Under  good  viewing conditions, large satellites such as the
       International Space Station (ISS), the Hubble  Space  Telescope  (HST),
       and  many  others are visible to the naked eye. If no symbol appears to
       the right of each line, then the satellite is in the Earth's shadow  at
       the time and date listed and is not receiving any illumination from the
       sun.

       Pressing the EENNTTEERR key, the 'YY' key, the space  bar,  or  clicking  the
       left  mouse  button  will  advance  the orbital predictions to a screen
       listing the next available passes.  Pressing the  'LL'  key  allows  the
       currently  displayed screen plus any subsequent screens to be logged to
       a text file in your current working directory. The name given  to  this
       file is the name of the satellite plus a ".txt" extension.  Any slashes
       or spaces appearing in the satellite name are replaced  by  the  under‐
       score  (_) symbol. The logging feature may be toggled on and off at any
       time by pressing the 'LL' key. Exiting the orbital  prediction  mode  by
       pressing  'NN', hitting the EESSCCape key, or clicking the right mouse but‐
       ton will also close the log file. The log file will  be  appended  with
       additional  information if additional predictions are conducted for the
       same satellite with the logging feature turned on.

       Selecting [[VV]] from PPRREEDDIICCTT''ss Main Menu will permit a ground station  to
       only predict passes for satellites that are potentially visible through
       optical means. Since all other passes are filtered out  in  this  mode,
       and  since  some satellites may never arrive over a ground station when
       optical viewing conditions are possible, the program provides  the  op‐
       tion  of breaking out of visual orbital prediction mode by pressing the
       [[EESSCC]]ape key or clicking the right mouse  button  as  calculations  are
       made.  A  prompt  is displayed at the bottom of the screen to alert the
       user of this option.

       In either orbital prediction mode, predictions will  not  be  attempted
       for  satellites that can never rise above the ground station's horizon,
       or for satellites in geostationary orbits. If a satellite is  in  range
       at the starting date and time specified, PPRREEDDIICCTT will adjust the start‐
       ing date back in time until the point of AOS  so  that  the  prediction
       screen displays the first pass in its entirety from start to finish.


SSIINNGGLLEE SSAATTEELLLLIITTEE TTRRAACCKKIINNGG MMOODDEE
       In  addition  to predicting satellite passes, PPRREEDDIICCTT allows satellites
       to be tracked in real-time using PPRREEDDIICCTT''ss  Single  Satellite  Tracking
       Mode  (Main  Menu option [[TT]]), or simultaneously as a group of 24 using
       the program's Multi-Satellite Tracking Mode  (Main  Menu  option  [[MM]]).
       The  bearings to the Sun and Moon are also displayed when tracking sat‐
       ellites in real-time.

       Selecting option [[TT]] from PPRREEDDIICCTT''ss Main Menu  places  the  program  in
       Single Satellite Tracking Mode. The user will be prompted to select the
       satellite of interest, after which a screen  will  appear  and  display
       tracking positions for the satellite selected.

       In  Single  Satellite Tracking Mode, a wealth of information related to
       tracking a spacecraft and communicating through its transponder is dis‐
       played.   The  current date and time is displayed along with the satel‐
       lite's sub-satellite point, its orbital altitude in both kilometers and
       statute  miles, the slant range distance between the ground station and
       the satellite in both kilometers and statute miles, the current azimuth
       and  elevation  headings  toward the satellite, the orbital velocity of
       the satellite in both kilometers per hour and statute miles  per  hour,
       the  footprint  of  the satellite in both kilometers and statute miles,
       the modulo 256 orbital phase of the satellite, the eclipse  depth,  the
       spacecraft  antenna  squint angle, and orbital model in use, as well as
       the current orbit number are also displayed.  The date and time for the
       next AOS is also provided.

       Additionally, if the satellite is currently in range of the ground sta‐
       tion, the amount of Doppler shift experienced on  uplink  and  downlink
       frequencies, path loss, propagation delay, and echo times are also dis‐
       played.  The expected time of LOS is also provided.

       Normally, the transponder displayed when Single Satellite Tracking Mode
       is  started  will  be  the first transponder defined in the transponder
       database.  However, if a particular transponder is defined to be active
       at  the  current orbital phase or day of the week when Single Satellite
       Tracking Mode is started, then _t_h_a_t specific transponder  will  be  the
       first one displayed.  PPRREEDDIICCTT will not change the transponder displayed
       in Single Satellite Tracking  Mode  without  user  intervention.  (That
       would be rude.)

       Transponders  may be sequenced in ascending order by pressing the SPACE
       BAR, the Right Arrow Cursor Key, or by left clicking the mouse over the
       transponder's name.  Pressing the Left Arrow Cursor Key or right click‐
       ing the mouse over the transponder's name sequences the transponders in
       reverse  order.   Pressing  the Home Key or the Up Arrow Cursor Key se‐
       lects first transponder in PPRREEDDIICCTT's database.  Pressing the End Key or
       the Down Arrow Cursor Key selects the last.

       The  passband  of  the  transponder may be tuned in 1 kHz increments by
       pressing the << and >> keys.  100 Hz tuning is possible using the ,, and ..
       keys.   (These  are  simply the << and >> keys without pressing the SHIFT
       key.)

       If no transponder information is available, the data displayed  on  the
       tracking screen is abbreviated.

       The  features  available  in the Single Satellite Tracking Mode make it
       possible to accurately determine the proper uplink frequency to yield a
       given downlink frequency, or vice versa.  For example, if one wishes to
       communicate with a station heard  on  435.85200  MHz  via  FO-29,  then
       435.85200 MHz can be selected via the keyboard as an RX frequency using
       the tuning keys while tracking FO-29, and the corresponding ground sta‐
       tion TX frequency will be displayed by PPRREEDDIICCTT.

       Obviously, an accurate system clock and up-to-date orbital data are re‐
       quired for the best tuning accuracy.

       If a sound card is present on your machine  and  the  Single  Satellite
       Tracking Mode is invoked with an uppercase 'TT', PPRREEDDIICCTT will make peri‐
       odic voice announcements stating the satellite's  tracking  coordinates
       in real-time.  If Single Satellite Tracking Mode is invoked with a low‐
       ercase 'tt' or by left clicking over the Single Satellite Tracking  Mode
       option in PPRREEDDIICCTT's Main Menu, announcements can be initiated by press‐
       ing the letter 'tt' once the tracking mode has begun.  Announcements can
       be suspended by pressing the 'ss' key.

       Once initiated, announcements such as:

       _"_T_h_i_s  _i_s _P_R_E_D_I_C_T_.  _S_a_t_e_l_l_i_t_e _i_s _a_t _f_i_f_t_y _s_i_x _d_e_g_r_e_e_s _a_z_i_m_u_t_h _a_n_d _f_o_r_t_y
       _f_i_v_e _d_e_g_r_e_e_s _e_l_e_v_a_t_i_o_n_, _a_n_d _i_s  _a_p_p_r_o_a_c_h_i_n_g_.   _S_a_t_e_l_l_i_t_e  _i_s  _c_u_r_r_e_n_t_l_y
       _v_i_s_i_b_l_e_._"

       are  made at intervals that are a function of how quickly the satellite
       is moving across the sky. Announcements can occur as frequently as  ev‐
       ery  50 seconds for satellites in low earth orbits such as the Interna‐
       tional Space Station (370 km), or as infrequently as  every  8  minutes
       for  satellites  in  very  high orbits, such as the AMC-6 geostationary
       satellite (35780 km). Voice announcements are performed  as  background
       processes  so as not to interfere with tracking calculations as the an‐
       nouncements are made. Alarms and special announcements  are  made  when
       the  satellite being tracked enters into or out of eclipse. Regular an‐
       nouncements can be forced by pressing the 'TT' key in  Single  Satellite
       Tracking Mode.


MMUULLTTII--SSAATTEELLLLIITTEE TTRRAACCKKIINNGG MMOODDEE
       Selecting  [[MM]]  from  PPRREEDDIICCTT''ss Main Menu places the program in a real-
       time multi-satellite tracking mode. In this mode, all 24 satellites  in
       the  program's  database are tracked simultaneously along with bearings
       to the Sun and Moon. Tracking data for the satellites is  displayed  in
       two  columns  of  12 satellites each. The name, azimuth heading, eleva‐
       tion, sub-satellite point latitude (in degrees North) and longitude (in
       degrees  West)  positions are provided, along with the slant range dis‐
       tance between the satellite and the ground station (in kilometers).

       A letter displayed to the right of the slant range indicates the satel‐
       lite's  sunlight and eclipse conditions. If the satellite is experienc‐
       ing an eclipse period, an NN is displayed. If the satellite is  in  sun‐
       light  and  the  ground  station is under the cover of darkness, a VV is
       displayed to indicate the possibility that the satellite is visible un‐
       der  the current conditions. If the satellite is in sunlight while con‐
       ditions at the ground station do not allow the satellite to be seen,  a
       DD  is  displayed.   Satellites  in range of the ground station are dis‐
       played in BBOOLLDD lettering. The AOS dates and times for  the  next  three
       satellites  predicted to come into range are displayed on the bottom of
       the screen between the tracking coordinates of the Sun and Moon.   Pre‐
       dictions  are  not  made  for satellites in geostationary orbits or for
       satellites so low in inclination and/or altitude that  they  can  never
       rise above the horizon of the ground station.

       A  left mouse click over any satellite displayed in the Multi-Satellite
       Tracking list will bring the user into Single Satellite  Tracking  Mode
       for  more  detailed  tracking  information on the chosen spacecraft.  A
       right click on the background of the  Single  Satellite  Tracking  Mode
       window will return the user back to Multi-Satellite Tracking Mode.


SSOOLLAARR IILLLLUUMMIINNAATTIIOONN PPRREEDDIICCTTIIOONNSS
       Selecting  [[SS]]  from  PPRREEDDIICCTT''ss Main Menu will allow solar illumination
       predictions to be made.  These predictions indicate how much sunlight a
       particular  satellite  will receive in a 24 hour period.  This informa‐
       tion is especially  valuable  to  spacecraft  designers  and  satellite
       ground station controllers who must monitor spacecraft power budgets or
       thermal conditions  on-board  their  spacecraft  due  to  sunlight  and
       eclipse  periods.  It can even be used to predict the optimum times for
       astronauts to perform extra-vehicular activities in space. Solar  illu‐
       mination  predictions  may  be logged to a file in the same manner that
       orbital predictions may be logged (by pressing LL).


SSOOLLAARR AANNDD LLUUNNAARR OORRBBIITTAALL PPRREEDDIICCTTIIOONNSS
       In addition to making orbital predictions of  spacecraft,  PPRREEDDIICCTT  can
       also  predict transits of  the Sun and the Moon.  Lunar predictions are
       initiated by selecting [[LL]] from PPRREEDDIICCTT's Main Menu.  Solar predictions
       are selected through Main Menu option [[OO]].

       When  making  solar and lunar orbital predictions, PPRREEDDIICCTT provides az‐
       imuth and elevation headings, the right ascension, declination,  Green‐
       wich Hour Angle (GHA), radial velocity, and normalized distance (range)
       to the Sun or Moon.  Declination and Greenwich Hour Angle correspond to
       the  latitude  and  longitude of the object's sub-satellite point above
       the Earth's surface.  The radial velocity corresponds to the speed  and
       direction  the  object  is  traveling  toward  (+) or away (-) from the
       ground station, and is expressed in meters per second.  When the radial
       distance  of the Moon is close to zero, the amount of Doppler shift ex‐
       perienced in Moonbounce communications is minimal.  The normalized dis‐
       tance corresponds to the object's actual distance to the ground station
       divided its average distance.  In practice, the normalized distance can
       range  from about 0.945 to 1.055 for the Moon, and about 0.983 to 1.017
       for the Sun.

       Note that the effects of atmospherics are ignored  in  determining  the
       elevation  angles  for the Sun and Moon. Furthermore, the data provided
       by PPRREEDDIICCTT corresponds to the object's center, and  not  the  upper  or
       lower limb, as is sometimes done when predicting the rising and setting
       times of these celestial objects.


OOPPEERRAATTIIOONN UUNNDDEERR TTHHEE XX--WWIINNDDOOWW SSYYSSTTEEMM
       PPRREEDDIICCTT may be run under the X-Window System by invoking it through the
       _x_p_r_e_d_i_c_t script contained with this software. _x_p_r_e_d_i_c_t can invoke _r_x_v_t,
       _x_t_e_r_m, _E_t_e_r_m, _g_n_o_m_e_-_t_e_r_m_i_n_a_l, or _k_v_t, and display PPRREEDDIICCTT in a  virtual
       terminal  window.  _x_p_r_e_d_i_c_t should be edited for best results.  In many
       cases, holding down the SHIFT key while pressing the plus (+) and minus
       (-)  keys  allows  PPRREEDDIICCTT''ss  window  to be re-sized when started under
       _x_p_r_e_d_i_c_t.


CCOOMMMMAANNDD LLIINNEE AARRGGUUMMEENNTTSS
       By default, PPRREEDDIICCTT reads ground station location, orbital  data,  annd
       transponder information from a pair of files located in the user's home
       directory under a hidden subdirectory named  _._p_r_e_d_i_c_t.  Ground  station
       location information is held in a file named _p_r_e_d_i_c_t_._q_t_h, while orbital
       data information for 24 satellites is held in a file named _p_r_e_d_i_c_t_._t_l_e.
       Satellite  transponder  information,  if available, is stored in a file
       named _p_r_e_d_i_c_t_._d_b.

       If we wish to run PPRREEDDIICCTT using data from alternate sources instead  of
       these  default  files, the names of such files may be passed to PPRREEDDIICCTT
       on the command line when the program is started.  For  example,  if  we
       wish  to  read the TLE file _v_i_s_u_a_l_._t_l_e and the QTH file _b_e_a_c_h___h_o_u_s_e_._q_t_h
       rather than the default files, we could  start  PPRREEDDIICCTT  and  pass  the
       names of these alternate files to the program in the following manner:

            _p_r_e_d_i_c_t _-_t _v_i_s_u_a_l_._t_l_e _-_q _b_e_a_c_h___h_o_u_s_e_._q_t_h

       or

            _p_r_e_d_i_c_t _-_q _b_e_a_c_h___h_o_u_s_e_._q_t_h _-_t _v_i_s_u_a_l_._t_l_e

       or

            _p_r_e_d_i_c_t _-_t _a_m_a_t_e_u_r_._t_l_e _-_d _o_s_c_a_r_._d_b

       If  the  files  specified are not located in the current working direc‐
       tory, then their relative or absolute paths should  also  be  specified
       along with their names (_p_r_e_d_i_c_t _-_t _/_h_o_m_e_/_k_d_2_b_d_/_o_r_b_s_/_v_i_s_u_a_l_._t_l_e).

       It  is also possible to specify only one alternate file while using the
       default for the others. For example,

            _p_r_e_d_i_c_t _-_t _v_i_s_u_a_l_._t_l_e

       reads QTH information from the default _p_r_e_d_i_c_t_._q_t_h location, TLE infor‐
       mation  from _v_i_s_u_a_l_._t_l_e, and transponder database information from _p_r_e_‐
       _d_i_c_t_._d_b while

            _p_r_e_d_i_c_t _-_q _b_o_b_s_._q_t_h

       reads QTH information from _b_o_b_s_._q_t_h and TLE information  from  the  de‐
       fault _~_/_._p_r_e_d_i_c_t_/_p_r_e_d_i_c_t_._t_l_e location.


QQUUIIEETT OORRBBIITTAALL DDAATTAABBAASSEE UUPPDDAATTEESS
       It  is also possible to update PPRREEDDIICCTT''ss satellite orbital database us‐
       ing another command line option that updates the database from  a  NASA
       two-line  element data set. PPRREEDDIICCTT then quietly exits without display‐
       ing anything to the screen, thereby eliminating the need  for  entering
       the  program and selecting the appropriate menu options. This option is
       invoked using the _-_u command line switch as follows:

            _p_r_e_d_i_c_t _-_u _o_r_b_s_2_4_8_._t_l_e

       This example updates PPRREEDDIICCTT''ss default orbital database with the Keple‐
       rian  elements  found  in  the file _o_r_b_s_2_4_8_._t_l_e. PPRREEDDIICCTT may be updated
       from a list of files as well:

            _p_r_e_d_i_c_t _-_u _a_m_a_t_e_u_r_._t_l_e _v_i_s_u_a_l_._t_l_e _w_e_a_t_h_e_r_._t_l_e

       If an alternate datafile requires updating, it may also be specified on
       the command line using the _-_t switch as follows:

            _p_r_e_d_i_c_t _-_t _o_s_c_a_r_._t_l_e _-_u _a_m_a_t_e_u_r_._t_l_e

       This  example  updates the _o_s_c_a_r_._t_l_e orbital database with the two-line
       element data contained in _a_m_a_t_e_u_r_._t_l_e.

       These options permit the automatic update  of  PPRREEDDIICCTT''ss  orbital  data
       files  using  Keplerian  orbital  data obtained through automatic means
       such as FTP, HTTP, or pacsat satellite download.

       For example, the following script can be used to update  PPRREEDDIICCTT''ss  or‐
       bital database via the Internet:


          _#_!_/_b_i_n_/_s_h
          _w_g_e_t   _-_q_r  _h_t_t_p_s_:_/_/_w_w_w_._a_m_s_a_t_._o_r_g_/_t_l_e_/_c_u_r_r_e_n_t_/_n_a_s_a_b_a_r_e_._t_x_t  _-_O  _a_m_a_‐
       _t_e_u_r_._t_x_t
          _w_g_e_t  _-_q_r  _h_t_t_p_s_:_/_/_c_e_l_e_s_t_r_a_k_._o_r_g_/_N_O_R_A_D_/_e_l_e_m_e_n_t_s_/_v_i_s_u_a_l_._t_x_t  _-_O  _v_i_s_‐
       _u_a_l_._t_x_t
          _w_g_e_t    _-_q_r    _h_t_t_p_s_:_/_/_c_e_l_e_s_t_r_a_k_._o_r_g_/_N_O_R_A_D_/_e_l_e_m_e_n_t_s_/_w_e_a_t_h_e_r_._t_x_t   _-_O
       _w_e_a_t_h_e_r_._t_x_t
          _/_u_s_r_/_l_o_c_a_l_/_b_i_n_/_p_r_e_d_i_c_t _-_u _a_m_a_t_e_u_r_._t_x_t _v_i_s_u_a_l_._t_x_t _w_e_a_t_h_e_r_._t_x_t

       If duplicate entries exist among the downloaded files, PPRREEDDIICCTT will use
       the most recent element set to update it's Keplerian database.

       A  script  called  _k_e_p_u_p_d_a_t_e  containing the commands illustrated above
       have been included with PPRREEDDIICCTT.  A call to this script can be made  as
       a  crontab entry to automate the process of updating PPRREEDDIICCTT''ss database
       at regular intervals.  Simply include a line such as the  following  in
       your crontab (type _c_r_o_n_t_a_b _-_e to edit your crontab):

            _0 _2 _* _* _* _k_e_p_u_p_d_a_t_e

       and  PPRREEDDIICCTT  will  automatically update its database every day at 2:00
       AM.


AAUUTTOOMMAATTIICC AANNTTEENNNNAA TTRRAACCKKIINNGG
       PPRREEDDIICCTT is compatible with serial port antenna rotator interfaces  con‐
       forming  to  the  EasyComm  2  protocol  standard.   This  includes the
       PIC/TRACK interface developed by Vicenzo Mezzalira, IW3FOL <http://dig‐
       ilander.iol.it/iw3fol/pictrack.html>,          TAPR's          EasyTrak
       <https://web.tapr.org/~n7hpr/easytrak/>. The FODTRACK rotator interface
       is  supported  through the use of Luc Langehegermann's (LX1GT) ffooddttrraacckk
       utility written for and included with PPRREEDDIICCTT.

       Using any of these hardware interfaces, PPRREEDDIICCTT can automatically  con‐
       trol  the  position  of AZ/EL antenna rotators, and keep antennas accu‐
       rately pointed toward a satellite being tracked by PPRREEDDIICCTT.  In  opera‐
       tion,  tracking  data  from PPRREEDDIICCTT is directed to the specified serial
       port using the _-_a command line option.  For example:

            _p_r_e_d_i_c_t _-_a _/_d_e_v_/_t_t_y_S_0

       will send AZ/EL tracking data to the first serial port when the program
       is  tracking  a  satellite  in the Single Satellite Tracking Mode.  The
       data sent to the serial port is of the form: _A_Z_2_4_1_._0 _E_L_2_6_._0 using  9600
       baud,  8-data bits, 1-stop bit, no parity, and no handshaking.  Data is
       sent to the interface if the azimuth or elevation  headings  change  by
       one  degree  or  more.   For  interfaces requiring keepalive updates at
       least once per second whether the AZ/EL headings have  changed  or  not
       (such as the ones by SAI), the _-_a_1 option may be used:

            _p_r_e_d_i_c_t _-_a_1 _/_d_e_v_/_t_t_y_S_0


AADDDDIITTIIOONNAALL OOPPTTIIOONNSS
       The _-_f command-line option, when followed by a satellite name or object
       number and starting date/time, allows PPRREEDDIICCTT to respond with satellite
       positional  information.   This  feature  allows  PPRREEDDIICCTT to be invoked
       within other applications that need to determine the location of a sat‐
       ellite  at  a particular point in time, such as the location of where a
       CCD camera image was taken by a Pacsat satellite  based  on  its  time‐
       stamp.

       The  information  produced  includes  the date/time in Unix format (the
       number of seconds since midnight UTC on January 1, 1970), the date/time
       in  ASCII (UTC), the elevation of the satellite in degrees, the azimuth
       heading of the satellite, the orbital phase (modulo 256), the  latitude
       and longitude of the satellite's sub-satellite point at the time speci‐
       fied, the slant range to the satellite in kilometers  with  respect  to
       the  ground  station's location, the orbit number, and the spacecraft's
       sunlight visibility information.

       The date/time must be specified in Unix format (number of seconds since
       midnight  UTC  on  January  1, 1970).  If no starting or ending time is
       specified, the current date/time is assumed and a single line of output
       is  produced.   If  a starting and ending time are specified, a list of
       coordinates beginning at the starting time/date  and  ending  with  the
       ending time/date will be returned by the program with a one second res‐
       olution.  If the letter _m is appended to the ending time/date, then the
       data returned by the program will have a one minute resolution.  The _-_o
       option allows the program to write the calculated  data  to  an  output
       file rather than directing it to the standard output device if desired.

       The proper syntax for this option is as follows:

            _p_r_e_d_i_c_t _-_f _I_S_S _9_7_7_4_4_6_3_9_0 _9_7_7_4_4_6_4_0_0 _-_o _d_a_t_a_f_i_l_e

       or

            _p_r_e_d_i_c_t _-_f _2_5_5_4_4 _9_7_7_4_4_6_3_9_0 _9_7_7_4_4_6_4_0_0 _-_o _d_a_t_a_f_i_l_e

       Note  that  referencing a satellite by its object number rather than by
       its name is the preferred practice when the name is especially long.

       A list of coordinates starting at the current date/time and  ending  10
       seconds later may be produced by the following command:

            _p_r_e_d_i_c_t _-_f _I_S_S _+_1_0

       If a list of coordinates specifying the position of the satellite every
       minute for the next 10 minutes is desired, the following command may be
       used:

            _p_r_e_d_i_c_t _-_f _I_S_S _+_1_0_m

       If  a  satellite name contains spaces, then the entire name must be en‐
       closed by "quotes".

       The _-_p option allows orbital predictions for a single pass to be gener‐
       ated by PPRREEDDIICCTT via the command-line.

       For example:

            _p_r_e_d_i_c_t _-_p _O_S_C_A_R_-_1_1 _1_0_0_3_5_3_6_7_6_7

       starts  predictions  for  the  OSCAR-11  satellite  at  a  Unix time of
       1003536767 (Sat 20Oct01 00:12:47 UTC).  If the  starting  date/time  is
       omitted,  the  current  date/time  is  used.   If  a pass is already in
       progress at the starting date/time specified, orbital  predictions  are
       moved  back  to  the beginning of AOS of the current pass, and data for
       the entire pass from AOS to LOS is provided.

       When either the _-_f or _-_p options are used, PPRREEDDIICCTT produces  an  output
       consisting  of the date/time in Unix format, the date and time in ASCII
       (UTC), the elevation of the satellite in degrees, the  azimuth  of  the
       satellite  in degrees, the orbital phase (modulo 256), the latitude (N)
       and longitude (W) of the satellite's  sub-satellite  point,  the  slant
       range  to  the  satellite (in kilometers), the orbit number, the space‐
       craft's sunlight visibility information, and, if the  satellite  is  in
       range, 100 MHz-normalized downlink Doppler shift information.

       For example:

       1589489403  Thu 14May20 20:50:03   20   65  209   45   57   1766  38901
       * 74.989726

       The output isn't annotated, but then again, it's meant to  be  read  by
       other software.

       The  Unix "date" command can be used to determine the Unix time if only
       a human-readable date and time string are known.

       For example:

            _d_a_t_e _-_d _"_O_c_t _1_2 _2_0_2_0 _1_2_:_0_0_:_0_0 _E_D_T_" _+_%_s

       returns a value of 1602518400 seconds for Unix time.  Any time zone un‐
       derstood by the "date" command can be used.  The "date" commmand can be
       combined in a call to PPRREEDDIICCTT by enclosing its invocation within a pair
       of grave quotes (` `) as follows:

            _p_r_e_d_i_c_t _-_p _I_S_S _`_d_a_t_e _-_d _"_O_c_t _1_2 _2_0_2_0 _1_6_:_0_0_:_0_0 _U_T_C_" _+_%_s_`


       The _-_d_p option produces a quick orbital prediction for the next pass of
       a specified satellite, including 100 MHz downlink Doppler shift  infor‐
       mation, in CSV format.  For example:

            _p_r_e_d_i_c_t _-_d_p _I_S_S

       produces:

       1525500165,Sat 05May18 06:02:45,701.256856
       1525500169,Sat 05May18 06:02:49,678.755942
       1525500172,Sat 05May18 06:02:52,656.033048
       1525500176,Sat 05May18 06:02:56,633.093151
       1525500179,Sat 05May18 06:02:59,609.940999
       1525500183,Sat 05May18 06:03:03,586.582443
       1525500186,Sat 05May18 06:03:06,563.022553
       <... output trimmed ...>
       1525500367,Sat 05May18 06:06:07,-733.663728
       1525500370,Sat 05May18 06:06:10,-755.793182
       1525500374,Sat 05May18 06:06:14,-777.690366
       1525500377,Sat 05May18 06:06:17,-799.351435
       1525500381,Sat 05May18 06:06:21,-820.773340
       1525500384,Sat 05May18 06:06:24,-841.952820
       1525500388,Sat 05May18 06:06:28,-862.887147


       where  the Unix time is followed by the UTC date/time and 100 MHz down‐
       link-referenced Doppler shift.  The satellite name or object number can
       be  followed by a starting date/time and ending date/time much like the
       _-_f option.


SSEERRVVEERR MMOODDEE
       PPRREEDDIICCTT''ss network socket interface allows the program to operate  as  a
       server  capable  of  providing  tracking  data and other information to
       client applications using the UDP protocol.  It  is  even  possible  to
       have the PPRREEDDIICCTT server and client applications running on separate ma‐
       chines provided the clients are connected to the server through a func‐
       tioning  network connection.  The _-_s switch is used to start PPRREEDDIICCTT in
       server mode:

            _p_r_e_d_i_c_t _-_s

       By default, PPRREEDDIICCTT uses socket port 1210 for communicating with client
       applications.   Therefore,  the following line needs to be added to the
       end your _/_e_t_c_/_s_e_r_v_i_c_e_s file:

            _p_r_e_d_i_c_t   _1_2_1_0_/_u_d_p

       The port number (1210) can be changed to  something  else  if  desired.
       There  is  no  need  to recompile the program if it is changed.  To run
       more than one instance of PPRREEDDIICCTT in server mode on a single  host,  an
       alternate port must be specified when invoking the additional instances
       of PPRREEDDIICCTT.  This can be accomplished by using the _-_n switch:

            _p_r_e_d_i_c_t _-_n _1_2_1_1 _-_t _o_t_h_e_r___t_l_e___f_i_l_e _-_s

       When invoked in server mode, PPRREEDDIICCTT immediately enters Multi-Satellite
       Tracking  Mode  and  makes  live  tracking  data  available to clients.
       Clients may poll PPRREEDDIICCTT for tracking data when the program is  running
       in  either the Multi-Satellite or Single Satellite Tracking Mode.  When
       in Multi-Satellite Tracking mode, tracking data for any of the 24  sat‐
       ellites  in  the  program's database may be accessed by client applica‐
       tions.  When in Single-Satellite Tracking mode, only live tracking data
       for  the single satellite being tracked may be accessed.  Either track‐
       ing mode may be ended at any time.  When this is done, PPRREEDDIICCTT will re‐
       turn  the  last calculated satellite tracking data until the program is
       again put into a real-time tracking mode.  This allows the user to  re‐
       turn  to  the  Main Menu, and use other features of the program without
       sending potentially harmful data to client applications.

       The best way to write a client application is to use the  demonstration
       program  (demo.c)  included in this distribution of PPRREEDDIICCTT as a guide.
       The sample program has comments to explain how each component operates.
       It  is useful to pipe the output of this program through _l_e_s_s to easily
       browse through the data returned (_d_e_m_o _| _l_e_s_s).

       In operation, a character array is filled with the  command  and  argu‐
       ments  to  be sent to PPRREEDDIICCTT.  A socket connection is then opened, the
       request is sent, a response is received, and the socket  connection  is
       closed.  The command and arguments are in ASCII text format.

       Several  excellent network client applications are included in this re‐
       lease of PPRREEDDIICCTT, and may be found under the _p_r_e_d_i_c_t_/_c_l_i_e_n_t_s directory.


AADDDDIINNGG SSAATTEELLLLIITTEESS
       One of the most frequently asked questions is how  satellites  in  PPRREE‐‐
       DDIICCTT''ss  orbital  database  may  be added, modified, or replaced.  As it
       turns out, there are several ways in which this can be done.   Probably
       the  easiest  is to manually edit your _~_/_._p_r_e_d_i_c_t_/_p_r_e_d_i_c_t_._t_l_e file, and
       replace an existing satellite's entry with 2-line  Keplerian  data  for
       the  new  satellite.  If this method is chosen, however, just make sure
       to include ONLY the two line data, and nothing else.

       Another way is to is select the Keyboard Edit option from the program's
       Main  Menu,  select a satellite you wish to replace.  Edit the name and
       object number (replacing the old information with the new information).
       Just hit ENTER, and accept all the other orbital parameters shown.  Get
       back to PPRREEDDIICCTT''ss Main Menu.  Select Auto Update, and  then  enter  the
       filename  containing the 2-line element data for your favorite new sat‐
       ellite.  The new satellite data should be detected by PPRREEDDIICCTT, and  the
       orbital data for the old satellite will be overwritten by the new data.


NNEEAATT TTRRIICCKKSS
       In  addition  to  tracking and predicting passes of satellites, PPRREEDDIICCTT
       may also be used to generate a NASA two-line Keplerian element data set
       from data entered through the keyboard by using PPRREEDDIICCTT''ss Main Menu op‐
       tion [[EE]].  The 2-Line orbital data for the satellite(s) in question may
       be  found  in  your  orbital  database file, and can be imported to any
       other satellite tracking program that accepts two-line element files or
       distributed to others electronically in this format.

       PPRREEDDIICCTT can be run as a background process while having its display re-
       directed to an unused virtual console by using the following command:

               _p_r_e_d_i_c_t _< _/_d_e_v_/_t_t_y_8 _> _/_d_e_v_/_t_t_y_8 _&

       Switching to virtual console number 8 (ALT-F8 in text mode) will  allow
       PPRREEDDIICCTT  to  be  controlled and displayed even after you've logged out.
       This is especially handy when running PPRREEDDIICCTT in server mode on  a  re‐
       mote machine.


GGLLOOSSSSAARRYY OOFF TTEERRMMSS
       The  following  terms are frequently used in association with satellite
       communications and space technology:


AAOOSS::
       Acquisition of Signal - the time at which a ground  station  first  ac‐
       quires  radio signals from a satellite. PPRREEDDIICCTT defines AOS as the time
       when the satellite being tracked comes within +/- 0.03 degrees  of  the
       local  horizon,  although  it  may have to rise higher than this before
       signals are first heard.

AAppooggeeee::
       Point in a satellite's orbit when the satellite is at its farthest dis‐
       tance from the earth's surface.

AAnnoommaalliissttiicc PPeerriioodd::
       A  satellite  orbital  parameter specifying the time between successive
       perigees.

AAsscceennddiinngg NNooddee::
       Point in a satellite's orbit when its sub-satellite point  crosses  the
       equator moving south to north.

AAzziimmuutthh::
       The  compass  direction  measured clockwise from true north.  North = 0
       degrees, East = 90 degrees, South = 180 degrees, and  West  =  270  de‐
       grees.

BBaahhnn CCoooorrddiinnaatteess::
       A  pair  of  angles  (Alat/Alon) that describe a spin-stabilized satel‐
       lite's inertial orientation in space.

DDeesscceennddiinngg NNooddee::
       Point in a satellite's orbit when its sub-satellite point  crosses  the
       equator moving north to south.

DDoopppplleerr SShhiifftt::
       The  motion  of  a satellite in its orbit around the earth, and in many
       cases the rotational motion of the earth itself, causes radio  communi‐
       cation  links  between the earth and a satellite to undergo a frequency
       shift due to the Doppler Effect.  PPRREEDDIICCTT calculates what effect  these
       motions  have  on satellite communication links, and displays real-time
       Doppler-corrected uplink and downlink frequencies in  Single  Satellite
       Tracking Mode.

EElleevvaattiioonn::
       The  angle between the local horizon and the position of the satellite.
       A satellite that appears directly above a particular location  is  said
       to be located at an elevation of 90 degrees. A satellite located on the
       horizon of a particular location is said to be located at an  elevation
       of 0 degrees.  A satellite with an elevation of less than zero is posi‐
       tioned below the local horizon, and radio communication with  a  satel‐
       lite in such a position is not possible under normal circumstances.

FFoooottpprriinntt::
       Diameter  of  the Earth's surface visible from a satellite.  The higher
       the satellite's orbital altitude, the greater the  footprint,  and  the
       wider the satellite's communications service area.

LLOOSS::
       Loss of Signal - the time at which a ground station loses radio contact
       with a satellite. PPRREEDDIICCTT defines LOS as the time  when  the  satellite
       being tracked comes within +/- 0.03 degrees of the local horizon.

OOrrbbiittaall PPhhaassee::
       An  orbital  "clock" that describes a satellite's orbital position with
       respect to perigee. Orbital Phase may be modulo 256, or modulo 360, and
       is sometimes referred to as mean anomaly when speaking of amateur radio
       satellites in elliptical orbits.  Orbital phase is zero at perigee.

PPaatthh LLoossss::
       The apparent attenuation a radio signal undergoes as it travels a given
       distance.  This attenuation is the result of the dispersion radio waves
       experience as they propagate between transmitter and receiver using an‐
       tennas  of finite gain. Free space path loss is technically an oxymoron
       since free space is loss free.

PPeerriiggeeee::
       Point in a satellite's orbit when the satellite is at its closest  dis‐
       tance to the earth's surface.

NNooddaall PPeerriioodd::
       A  satellite  orbital  parameter specifying the time between successive
       ascending nodes.

SSllaanntt RRaannggee::
       The straight line distance between the ground station and the satellite
       at a given time.

SSuubb--SSaatteelllliittee PPooiinntt::
       The latitude and longitude specifying the location on the Earth that is
       directly below the satellite.


AADDDDIITTIIOONNAALL IINNFFOORRMMAATTIIOONN
       Detailed information on the operation of PPRREEDDIICCTT''ss UDP socket-based in‐
       terface as well as sample code for writing your own client applications
       is available in the _p_r_e_d_i_c_t_/_c_l_i_e_n_t_s_/_s_a_m_p_l_e_s subdirectory.   The  latest
       news  is  available  through the official PPRREEDDIICCTT software web page lo‐
       cated at: <http://www.qsl.net/kd2bd/predict.html>.

FFIILLEESS
       ~/.predict/predict.tle
              Default database of orbital data

       ~/.predict/predict.db
              Default satellite transponder database file

       ~/.predict/predict.qth
              Default ground station location information


AAUUTTHHOORRSS
       PPRREEDDIICCTT was written by John  A.  Magliacane,  KD2BD  <kd2bd@amsat.org>.
       The   socket  server  code  was  contributed  by  Ivan  Galysh,  KD4HBO
       <galysh@juno.nrl.navy.mil>.  The PIC/TRACK serial port antenna  rotator
       controller  code  was  contributed  by  Vittorio Benvenuti, I3VFJ <ben‐
       scosm@iol.it>.  SGP4/SDP4 code was derived from Pacsal routines written
       by  Dr.  T.S.  Kelso,  and converted to 'C' by Neoklis Kyriazis, 5B4AZ.
       See the CREDITS file for additional information.




KD2BD Software                   09 June 2023                       PREDICT(1)
