PREDICT(1)                KD2BD Software               PREDICT(1)



NAME
       predict  - Track and predict passes of satellites in Earth
       orbit

SYNOPSIS
       predict [-u tle_update_source] [-t tlefile]  [-q  qthfile]
       [-a  serial_port]  [-a1 serial_port] [-n network_port] [-f
       sat_name starting_date/time ending_date/time] [-p sat_name
       starting_date/time] [-o output_file] [-s]

DESCRIPTION
       PREDICT  is  a  multi-user  satellite tracking and orbital
       prediction program written under the Linux operating  sys-
       tem  by  John  A. Magliacane, KD2BD. PREDICT is free soft-
       ware. You can 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  of  the
       License or any later version.

       PREDICT is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY, without even  the  implied  war-
       ranty  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE. See the GNU General Public License for more details.

FIRST TIME USE
       PREDICT  tracks and predicts passes of satellites based on
       the geographical location of the ground station, the  cur-
       rent  date  and  time as provided by the computer system's
       clock, and Keplerian orbital data for  the  satellites  of
       interest  to  the ground station. First time users of PRE-
       DICT are provided  default  ground  station  location  and
       orbital data information files. These files are managed by
       the program, and are normally located  in  a  user's  home
       directory  under  a  hidden  subdirectory  named .predict.
       First time users will be prompted to supply  PREDICT  with
       their  geographical location (the same as selecting option
       [G] from the program's main menu) the first time the  pro-
       gram  is  run. Latitude is entered in degrees north. Lati-
       tudes south of the equator are entered  as  negative  num-
       bers.  Longitude is entered in degrees west.  Eastern lon-
       gitudes may be entered as negative numbers.  Latitudes and
       longitudes may be either entered in decimal degrees, or in
       degrees, minutes, seconds (DMS) format.  Station  altitude
       is  entered  as the number of meters the ground station is
       located above sea level.  This parameter is not very crit-
       ical.   If  unsure, make a realistic guess or simply enter
       0.

       Users of PREDICT  need  Keplerian  orbital  data  for  the
       satellites  they wish to track that is preferably no 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] from PREDICT's
       main menu and manually entering Keplerian  data  for  each
       satellite  in  the  program's  database,  or  by selecting
       option [U] and specifying a file containing recent  2-line
       Keplerian  element data sets that correspond to the satel-
       lites in the program's database.  Keplerian  orbital  data
       is   available   from  a  variety  of  sources,  including
       http://www.celestrak.com/ and http://www.amsat.org/.

PROGRAM OPERATION
       The start-up screen of PREDICT 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.

PREDICTING SATELLITE PASSES
       Orbital  predictions are useful for determining in advance
       when a satellite is expected to come  within  range  of  a
       ground station. They can also be used to look back to pre-
       vious passes to help to confirm or identify past  observa-
       tions.

       PREDICT  includes  two orbital prediction modes to predict
       any pass above a ground station (main menu option [P]), or
       list  only  those passes that might be visible to a ground
       station through optical means (main menu option [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  nothing  and  hitting  simply the ENTER key when
       prompted to enter the starting date and time.

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

            DDMonYY HH:MM:SS

       Entering the time is optional.  If it is omitted, midnight
       (00:00:00) is assumed.  Once  complete,  orbital  calcula-
       tions  are started and prediction information is displayed
       on the screen.

       The date and time in UTC, along with the satellite's  ele-
       vation  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 space-
       craft  attitude  parameters  (ALAT,  ALON) are included in
       PREDICT's  transponder  database  file,  then   spacecraft
       antenna  squint angles are displayed instead of orbit num-
       bers 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 US Space  Shut-
       tles, and Hubble Space Telescope, and the Upper Atmosphere
       Research Satellite (UARS) 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 ENTER key, the 'Y'  key,  or  the  space  bar
       advances  the  orbital predictions to a screen listing the
       next available passes.  Pressing the 'L'  key  allows  the
       currently  displayed screen plus any subsequent screens to
       be logged to a text file in your  current  working  direc-
       tory.  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' key. Exiting the
       orbital prediction mode by pressing  'N'  or  hitting  the
       ESCape key will also close the log file. The log file will
       be appended with additional information if additional pre-
       dictions  are  conducted  for  the same satellite with the
       logging feature turned on.

       Selecting [V] from  PREDICT'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 pro-
       vides the option of breaking out of visual orbital predic-
       tion mode by pressing the [ESC]ape key 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 geostation-
       ary orbits. If a satellite is in  range  at  the  starting
       date  and time specified, PREDICT will adjust the starting
       date back in time until the point of AOS so that the  pre-
       diction  screen  displays  the  first pass in its entirety
       from start to finish.

SINGLE SATELLITE TRACKING MODE
       In addition to predicting satellite passes, PREDICT allows
       satellites to be tracked in real-time using PREDICT's Sin-
       gle Satellite Tracking Mode (main  menu  option  [T]),  or
       simultaneously as a group of 24 using the program's Multi-
       Satellite Tracking Mode (main menu option [M]).  The posi-
       tions of the Sun and Moon are also displayed when tracking
       satellites in real-time.

       Selecting option [T] from PREDICT'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 displayed.  The current date  and  time
       is  displayed  along  with  the  satellite'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 foot-
       print 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 station, the amount of  Doppler  shift  experi-
       enced on uplink and downlink frequencies, path loss, prop-
       agation delay, and echo times  are  also  displayed.   The
       expected time of LOS is also provided.

       Uplink  and  downlink  frequencies  are  held in PREDICT's
       transponder  database  file   predict.db   located   under
       $HOME/.predict.   A default file is provided with PREDICT.

       Transponders may be selected by pressing  the  SPACE  BAR.
       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 the SHIFT key.)

       If no transponder information is available, the data  dis-
       played 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 station TX frequency will be dis-
       played by PREDICT.

       Obviously, an accurate system clock and up-to-date orbital
       data are required 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'
       rather than a lowercase 't', PREDICT  will  make  periodic
       voice announcements stating the satellite's tracking coor-
       dinates in real-time. Announcements such as:

       "This is PREDICT.   Satellite  is  at  fifty  six  degrees
       azimuth and forty five degrees elevation, and is approach-
       ing.  Satellite is currently visible."

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

MULTI-SATELLITE TRACKING MODE
       Selecting [M] from PREDICT'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 the positions of the Sun
       and Moon. Tracking data for the satellites is displayed in
       two columns of 12 satellites each. The name, azimuth head-
       ing, elevation, sub-satellite point latitude  (in  degrees
       North)  and longitude (in degrees West) positions are pro-
       vided, along with the slant  range  distance  between  the
       satellite and the ground station (in kilometers).

       A  letter  displayed to the right of the slant range indi-
       cates the satellite's sunlight and eclipse conditions.  If
       the  satellite  is experiencing an eclipse period, an N is
       displayed. If the satellite is in sunlight and the  ground
       station  is  under the cover of darkness, a V is displayed
       to indicate the possibility that the satellite is  visible
       under  the current conditions. If the satellite is in sun-
       light while conditions at the ground station do not  allow
       the satellite to be seen, a D is displayed.  Satellites in
       range of the ground station are displayed in BOLD  letter-
       ing. 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.  Predictions are not made for satellites in geo-
       stationary  orbits or for satellites so low in inclination
       and/or altitude that they can never rise above the horizon
       of the ground station.

SOLAR ILLUMINATION PREDICTIONS
       Selecting  [S]  from  PREDICT'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  information  is  espe-
       cially  valuable  to  spacecraft  designers  and satellite
       ground station controllers  who  must  monitor  spacecraft
       power  budgets or thermal conditions on-board their space-
       craft due to sunlight and eclipse periods.  It can even be
       used  to  predict the optimum times for astronauts to per-
       form extra-vehicular activities in space. Solar  illumina-
       tion  predictions may be logged to a file in the same man-
       ner that orbital predictions may be  logged  (by  pressing
       L).

SOLAR AND LUNAR ORBITAL PREDICTIONS
       In  addition  to making orbital predictions of spacecraft,
       PREDICT can also predict transits  of   the  Sun  and  the
       Moon.   Lunar  predictions  are initiated by selecting [L]
       from PREDICT's Main Menu.  Solar predictions are  selected
       through Main Menu option [O].

       When  making  solar and lunar orbital predictions, PREDICT
       provides azimuth and elevation headings, the right  ascen-
       sion,  declination,  Greenwich  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 cor-
       responds to the speed and direction the object is  travel-
       ing 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
       experienced in Moon bounce communications is minimal.  The
       normalized  distance  corresponds  to  the object's actual
       distance to the ground station divided  its  average  dis-
       tance.   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.  In
       addition,  the data provided by PREDICT 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.

OPERATION UNDER THE X-WINDOW SYSTEM
       PREDICT may be run under the X-Window System  by  invoking
       it   through  the  xpredict  script  contained  with  this
       software. xpredict can invoke rxvt, xterm,  Eterm,  gnome-
       terminal,  or kvt, and display PREDICT in a virtual termi-
       nal window.  xpredict should be edited for  best  results.
       In  many  cases, holding down the SHIFT key while pressing
       the plus (+) and minus (-) keys allows PREDICT's window to
       be re-sized when started under xpredict.

COMMAND LINE ARGUMENTS
       By  default,  PREDICT  reads  ground  station location and
       orbital data information from a pair of files  located  in
       the  user's  home  directory  under  a hidden subdirectory
       named .predict. Ground  station  location  information  is
       held  in  a  file  named  predict.qth,  while orbital data
       information for 24 satellites is held in a file named pre-
       dict.tle.

       If  we  wish  to  run  PREDICT  using  data from alternate
       sources instead of these default files, the names of  such
       files  may  be  passed to PREDICT on the command line when
       the program is started. For example, if we  wish  to  read
       the  TLE  file  visual.tle  and  the  QTH file holiday.qth
       rather than the default files, we could start PREDICT  and
       pass  the names of these alternate files to the program in
       the following manner:

            predict -t visual.tle -q holiday.qth

       or

            predict -q holiday.qth -t visual.tle

       If the files specified are  not  located  in  the  current
       working  directory,  then their relative or absolute paths
       should also be specified along with their  names  (predict
       -t /home/kd2bd/orbs/visual.tle).

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

            predict -t visual.tle

       reads QTH information  from  the  default  ~/.predict/pre-
       dict.qth  location,  and  TLE information from visual.tle,
       while

            predict -q bobs.qth

       reads QTH information from bobs.qth  and  TLE  information
       from the default ~/.predict/predict.tle location.

QUIET ORBITAL DATABASE UPDATES
       It  is also possible to update PREDICT's satellite orbital
       database using another command line  option  that  updates
       the  database  from a NASA two-line element data set. PRE-
       DICT then quietly exits without displaying anything to the
       screen, thereby eliminating the need for entering the pro-
       gram and selecting  the  appropriate  menu  options.  This
       option is invoked using the -u command line switch as fol-
       lows:

            predict -u orbs248.tle

       This example updates PREDICT's  default  orbital  database
       with the Keplerian elements found in the file orbs248.tle.
       PREDICT may be updated from a list of files as well:

            predict -u amateur.tle visual.tle weather.tle

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

            predict -t oscar.tle -u amateur.tle

       This example updates the oscar.tle orbital  database  with
       the two-line element data contained in amateur.tle.

       These  options  permit  the  automatic update of PREDICT'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
       PREDICT's orbital database via the Internet:

          #!/bin/sh
          wget  -qr  www.celestrak.com/NORAD/elements/amateur.txt
       -O amateur.txt
          wget -qr www.celestrak.com/NORAD/elements/visual.txt -O
       visual.txt
          wget  -qr  www.celestrak.com/NORAD/elements/weather.txt
       -O weather.txt
          /usr/local/bin/predict   -u   amateur.txt    visual.txt
       weather.txt

       To  truly  automate  the  process of updating your orbital
       database, save the above commands to a file in  your  home
       directory  (such as kepupdate), and add the following line
       to your crontab (type crontab -e to edit your crontab):

            0 2 * * * kepupdate

       and PREDICT will automatically update its  database  every
       day at 2:00 AM.

AUTOMATIC ANTENNA TRACKING
       PREDICT  is  compatible  with  serial port antenna rotator
       interfaces conforming to the EasyComm 2 protocol standard.
       This includes the PIC/TRACK interface developed by Vicenzo
       Mezzalira,  IW3FOL   <http://digilander.iol.it/iw3fol/pic-
       track.html>,  TAPR's EasyTrak Jr.  (currently under devel-
       opment), and Suding Associates  Incorporated's  Dish  Con-
       trollers         <http://www.ultimatecharger.com/Dish_Con-
       trollers.html>.  The FODTRACK rotator  interface  is  sup-
       ported  through  the  use  of Luc Langehegermann's (LX1GT)
       fodtrack utility written for and included with PREDICT.

       Using any of these hardware interfaces, PREDICT can  auto-
       matically  control the position of AZ/EL antenna rotators,
       and keep antennas accurately pointed  toward  a  satellite
       being  tracked  by  PREDICT.   In operation, tracking data
       from PREDICT is directed  to  the  specified  serial  port
       using the -a command line option.  For example:

            predict -a /dev/ttyS0

       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: AZ241.0 EL26.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 -a1 option may be used:

            predict -a1 /dev/ttyS0


ADDITIONAL OPTIONS
       The -f command-line option, when followed by  a  satellite
       name  or object number and starting date/time, allows PRE-
       DICT to respond  with  satellite  positional  information.
       This  feature  allows  PREDICT  to be invoked within other
       applications that need to  determine  the  location  of  a
       satellite at a particular point in time, such as the loca-
       tion of where a CCD camera image was  taken  by  a  Pacsat
       satellite based on its timestamp.

       The  information  produced  includes the date/time in Unix
       format (the number of seconds since midnight UTC  on  Jan-
       uary 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
       (N) and longitude (W)  of  the  satellite's  sub-satellite
       point at the time specified, the slant range to the satel-
       lite 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 pro-
       duced.  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 resolution.  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:

            predict -f ISS 977446390 977446400 -o datafile

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

            predict -f ISS +10

       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:

            predict -f ISS +10m

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

       The -p option allows orbital predictions for a single pass
       to be generated by  PREDICT  via  the  command-line.   For
       example:

            predict -p OSCAR-11 1003536767

       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, PREDICT pro-
       duces an output consisting of the date/time in  Unix  for-
       mat,  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, and  the  spacecraft's  sunlight  visibility
       information.  For example:

       1003611710  Sat  20Oct01 21:01:50   11    6  164   51   72
       1389  16669 *

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


SERVER MODE
       PREDICT'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 PREDICT  server
       and  client applications running on separate machines pro-
       vided the clients are connected to the  server  through  a
       functioning network connection.

       The -s switch is used to start PREDICT in server mode:

            predict -s

       By  default, PREDICT uses socket port 1210 for communicat-
       ing with client applications.   Therefore,  the  following
       line needs to be added to the end your /etc/services file:

            predict   1210/udp

       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  PREDICT  in
       server  mode  on  a single host, an alternate port must be
       specified when invoking the additional instances  of  PRE-
       DICT.  This can be accomplished by using the -n switch:

            predict -n 1211 -t other_tle_file -s

       When  invoked  in  server mode, PREDICT immediately enters
       Multi-Satellite Tracking Mode,  and  makes  live  tracking
       data  available  to clients.  Clients may poll PREDICT 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  satellites  in  the  program's  database  may  be
       accessed by client applications.  When in Single-Satellite
       Tracking  mode,  only  live  tracking  data for the single
       satellite being tracked may be accessed.  Either  tracking
       mode may be ended at any time.  When this is done, PREDICT
       will return the last calculated  satellite  tracking  data
       until  the  program is again put into a real-time tracking
       mode.  This allows the user to return 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 distribu-
       tion of PREDICT as a guide.  The sample program  has  com-
       ments  to explain how each component operates.  It is use-
       ful to pipe the output of this  program  through  less  to
       easily browse through the data returned (demo | less).

       In operation, a character array is filled with the command
       and arguments to be sent to PREDICT.  A socket  connection
       is  then  opened,  the  request  is  sent,  a  response is
       received, and the socket connection is closed.   The  com-
       mand and arguments are in ASCII text format.

       Several excellent network client applications are included
       in this release of PREDICT, and may  be  found  under  the
       predict/clients directory.


ADDING SATELLITES
       One  of  the most frequently asked questions is how satel-
       lites in PREDICT's orbital database may  be  added,  modi-
       fied,  or  replaced.   As  it turns out, there are several
       ways in which this can be done.  Probably the  easiest  is
       to  manually  edit  your  ~/.predict/predict.tle file, and
       replace an existing satellite's entry with  2-line  Keple-
       rian  data  for the new satellite.  If this method is cho-
       sen, 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 PREDICT's Main Menu.  Select Auto Update,  and
       then enter the filename containing the 2-line element data
       for your favorite new satellite.  The new  satellite  data
       should  be  detected  by PREDICT, and the orbital data for
       the old satellite will be overwritten by the new data.

NEAT TRICKS
       In addition to tracking and predicting  passes  of  satel-
       lites,  PREDICT  may  also be used to generate a NASA two-
       line Keplerian element data set from data entered via key-
       board.  For  example,  let's say you're listening to Space
       Shuttle audio re-broadcasts via WA3NAN and Keplerian  ele-
       ments  for  the  Space  Shuttle's  orbit  are given by the
       announcer. The orbital data provided by WA3NAN  in  verbal
       form  may  be  manually  entered  into  PREDICT's  orbital
       database using option [E] of the program's main menu (Key-
       board  Edit of Orbital Database). The orbital data for the
       Space Shuttle in NASA two-line element form  can  then  be
       found  in  your orbital database file, and may imported to
       any other satellite tracking program that accepts two-line
       element files or distributed to others electronically.

       It is also possible to run PREDICT as a background process
       and direct its display to an  unused  virtual  console  by
       using the following command:

               predict < /dev/tty8 > /dev/tty8 &

       Switching  to  virtual  console  number  8 (ALT-F8 in text
       mode) will allow PREDICT to be  controlled  and  displayed
       even  after  you've  logged out.  This is especially handy
       when running PREDICT in server mode on a remote machine.

GLOSSARY OF TERMS
       The following terms are  frequently  used  in  association
       with satellite communications and space technology:

AOS:
       Acquisition of Signal - the time at which a ground station
       first acquires radio signals  from  a  satellite.  PREDICT
       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 sig-
       nals are first heard.

Apogee:
       Point in a satellite's orbit when the satellite is at  its
       farthest distance from the earth's surface.

Anomalistic Period:
       A  satellite orbital parameter specifying the time between
       successive perigees.

Ascending Node:
       Point in a satellite's orbit when its sub-satellite  point
       crosses the equator moving south to north.

Azimuth:
       The  compass direction measured clockwise from true north.
       North = 0 degrees, East = 90 degrees, South = 180 degrees,
       and West = 270 degrees.

Descending Node:
       Point  in a satellite's orbit when its sub-satellite point
       crosses the equator moving north to south.

Doppler Shift:
       The motion of a satellite in its orbit around  the  earth,
       and  in  many  cases  the  rotational  motion of the earth
       itself, causes radio signals generated by satellites to be
       received  on  Earth at frequencies slightly different than
       those upon which they were transmitted. PREDICT calculates
       what  effect  these  motions  have  upon  the reception of
       satellites transmitting on the 146 MHz and 435 MHz Amateur
       Radio bands.

Elevation:
       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 positioned below the local horizon, and radio com-
       munication with a satellite in such a position is not pos-
       sible under normal circumstances.

Footprint:
       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 communica-
       tions coverage.

LOS:
       Loss of Signal - the time at which a ground station  loses
       radio contact with a satellite. PREDICT defines LOS as the
       time when the satellite being  tracked  comes  within  +/-
       0.03 degrees of the local horizon.

Orbital Phase:
       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,  such  as  the  Phase  3  satellites.
       Orbital phase is zero at perigee.

Path Loss:
       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 antennas of finite
       gain. Free space path  loss  is  technically  an  oxymoron
       since free space is loss free.

Perigee:
       Point  in a satellite's orbit when the satellite is at its
       closest distance to the earth's surface.

Nodal Period:
       A satellite orbital parameter specifying the time  between
       successive ascending nodes.

Slant Range:
       The  straight line distance between the ground station and
       the satellite at a given time.

Sub-Satellite Point:
       The latitude and longitude specifying the location on  the
       Earth that is directly below the satellite.


ADDITIONAL INFORMATION
       Detailed  information  on  the  operation of PREDICT's UDP
       socket-based interface as well as sample code for  writing
       your  own  client  applications  is  available in the pre-
       dict/clients/samples subdirectory.   The  latest  news  is
       available  through  the official PREDICT software web page
       located at: <http://www.qsl.net/kd2bd/predict.html>.

FILES
       ~/.predict/predict.tle
              Default database of orbital data

       ~/.predict/predict.db
              Satellite transponder database file

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


AUTHORS
       PREDICT  was  written  by  John   A.   Magliacane,   KD2BD
       <kd2bd@amsat.org>.   he 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.



KD2BD Software            07 March 2003                PREDICT(1)
