			=========================
			PREDICT's Socket Commands
			=========================

The network sockets feature of PREDICT allows the program to operate
as a server providing tracking data to client applications using the
UDP protocol.  It is even possible to have the PREDICT server and
client applications running on separate machines provided the
clients are connected to the server through a network.


System Configuration
====================
For the socket-based server features of PREDICT to function, the
following line needs to be added to the end your /etc/services file:

	predict   1210/udp

The port number (1210) can be changed if desired.  There is no need
to recompile the program if it is changed.  As of PREDICT version
2.1.5, an alternate port may be specified for use by PREDICT via
the -n command-line switch.


Program Operations
==================
Start PREDICT with the -s switch (predict -s) to start the program as a
socket-based server.  The program will start and automatically go into the
multi-satellite tracking mode.  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-tracking mode, tracking data for any of the
24 satellites in the program's database may be accessed by client programs.
When in single-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, the socket code 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 programs.


Client Program Interface
========================
The best way to write a client program is to use the demonstration program
(demo.c) included in this distribution of PREDICT 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 "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 command and arguments are in ASCII text format.

A sample client application written in Perl is included under the perl
subdirectory.


PREDICT Socket Command Summary
==============================
The following are the socket commands interpreted by PREDICT when the
program is running in either the single satellite or multi-satellite
tracking mode:

Command: GET_SAT
Argument: satellite name or object number
Purpose: To poll PREDICT for live tracking data.
Return value: Newline ('\n') delimited string of tracking data.
Example: GET_SAT SUNSAT
Data returned:

SUNSAT
52.66  
+57.28
31.51  
+5.93 
975795873
6063.75
2721.52
795.31 
26757.69
9339
D

Description: The values are identified by the order in which they are
returned.  Referring to the example above,

Name:		SUNSAT
Long:		52.66 (degrees West)
Lat:		57.28 (degrees North)
Az:		31.51 (degrees)
El:		+5.93 (degrees)
Next AOS/LOS:	975795873 (seconds since 01-Jan-1970) = Sat Dec 2 22:24:33 2000
Footprint:	6063.75 (kilometers)
Range:		2721.52 (kilometers)
Altitude:	795.31 (kilometers)
Velocity:	26757.69 (kilometers/hour)
Orbit Number:	9339 (revolutions)
Visibility:	D (Currently in Daylight)

If the satellite is in either a geostationary orbit or an orbit that
does not permit AOS to occur at the groundstation, a zero (0) is returned
for the next AOS/LOS time.  Otherwise, the next AOS time is provided for
satellites not currently in range of the ground station.  If the satellite
is in range, then the LOS time is provided.

The name provided as an argument to GET_SAT must match the full length
name contained in PREDICT's orbital database, and may contain spaces.
The command string passed to PREDICT must end with an end of line ('\n')
character.  The satellite's object number may be used in lieu of the
satellite name.

The visibility codes returned are the same as those displayed in PREDICT's
multi-satellite tracking mode.  An 'N' indicates the satellite is not in
sunlight, nor is it optically visible at the ground station.  A 'D'
indicates that the satellite is in sunlight, but not optically visible
at the ground station.  A 'V' indicates the satellite is in sunlight,
while the ground station is in darkness, meaning the satellite may be
optically visible at the ground station.

-----------------------------------------------------------------------------

Command: GET_DOPPLER
Argument: satellite name or object number
Purpose: To poll PREDICT for normalized Doppler shift information.
Return value: satname '\n' Doppler shift information.
Example: GET_DOPPLER OSCAR-27
Data returned:

961.742249

Description: The Doppler shift returned by PREDICT is a normalized to a
100 MHz downlink from the satellite, and must be scaled by the client to
the operating frequency of interest.  For example, to determine the amount
of Doppler shift experienced on a 435 MHz downlink, simply multiply the
value returned by 4.35.  To calculate the Doppler shift on a 146 MHz
uplink, multiply the amount by -1.46.  NOTE!!  The GET_DOPPLER command
no longer echos back the name of the satellite for which Doppler shift
information was requested.

-----------------------------------------------------------------------------

Command: GET_SUN
Argument: none
Purpose: To poll PREDICT for the Sun's current position.
Return value: The Sun's current azimuth and elevation headings.
Example: GET_SUN
Data returned:

299.58
-54.09

Description: Azimuth is returned first, followed by elevation.

-----------------------------------------------------------------------------

Command: GET_MOON
Argument: none
Purpose: To poll PREDICT for the Moon's current position.
Return value: The Moon's current azimuth and elevation headings.
Example: GET_MOON
Data returned:

148.72
+55.83

Description: Azimuth is returned first, followed by elevation.

-----------------------------------------------------------------------------

Command: GET_LIST
Argument: none
Purpose: To poll PREDICT for the satellite names in the current database.
Return value: String containing all satellite names in PREDICT's database.
Example: GET_LIST
Data returned:

OSCAR-10
OSCAR-11
OSCAR-14
PACSAT
LUSAT
OSCAR-20
OSCAR-22
OSCAR-23
OSCAR-25
ITAMSAT
OSCAR-27
OSCAR-29
OSCAR-36
OSCAR-40
RS-12/13
RS-15
NOAA-12
NOAA-14
NOAA-15
UARS
HUBBLE
ISS
PCSAT
STARSHINE 3

Description: Names are returned as a string that must be parsed by the
client to pull out individual names.  NOTE!!!  Versions of PREDICT prior
to 2.1.3 returned ONLY ONE name at a time, and had to be invoked 24 times
to download the entire list.  This has since changed!  Since satellite
names returned by PREDICT are no longer abbreviated (as they were in
earlier versions), a 625 byte buffer is now required to store the
results of this command.

-----------------------------------------------------------------------------

Command: RELOAD_TLE
Argument: none
Purpose: To force a re-read of PREDICT's orbital database file.
Return value: NULL
Example: RELOAD_TLE
Data returned:
Description: Forces PREDICT to re-read the orbital database file.  Useful
after the database has been updated by something other than the running
version of the program (i.e. predict -u filename), and eliminates the
need to re-start PREDICT under these conditions to force a re-read of
the database.

-----------------------------------------------------------------------------

Command: GET_VERSION
Argument: none
Purpose: To determine what version of PREDICT is running as a server.
Return value: String containing the version number.
Example: GET_VERSION
Data returned: 2.1.5\n
Description: Allows clients to determine what version of PREDICT they're
talking to.

-----------------------------------------------------------------------------

Command: GET_QTH
Argument: none
Purpose: To determine the groundstation location (QTH) information.
Return value: String containing the info stored in the user's predict.qth file.
Example: GET_QTH
Data returned:
 
W1AW
41.716905
72.727083
25

Description: The groundstation callsign, latitude, longitude, and altitude
above sea level are returned.  Useful for plotting the user's location on
a map.

-----------------------------------------------------------------------------

Command: GET_TLE
Argument: satellite name or catalog number
Purpose: To read the Keplerian elements for a particular satellite.
Return value: String containing Keplerian orbital data.
Example: GET_TLE OSCAR-25
Data returned:

OSCAR-25
22828
00 306.69662848
98.3880
359.3791
0.0009012
197.6165
162.4707
14.28826398
6.76e-06
33830

Description: The satellite name, object number, reference epoch, inclination,
right ascension at ascending node, eccentricity, argument of perigee,
mean anomaly, mean motion, decay rate, and orbit number for the satellite
in question are returned.

-----------------------------------------------------------------------------

Command: GET_TIME
Argument: none
Purpose: To read the system date/time from the PREDICT server.
Return value: Number of seconds since midnight UTC on January 1, 1970.
Example: GET_TIME
Data returned:

977533528

Description: Unix Time is returned by the server.  This command allows
clients to display clock/calendar information or sync their system
clocks with that of the server.

-----------------------------------------------------------------------------

Command: GET_TIME$
Argument: none
Purpose: To read the system date/time from the PREDICT server.
Return value: UTC Date/Time as an ASCII string.
Example: GET_TIME$
Data returned:

Sat Dec 23 01:05:28 2000

Description: Returns an ASCII representation of the current date/time
in UTC.  Useful for displaying the current date/time in client applications
if the local system clock cannot be synced using the GET_TIME command.

-----------------------------------------------------------------------------

Command: GET_SAT_POS
Argument: satellite name or object number, starting date/time, ending
date/time (optional).
Purpose: To obtain the location of a satellite at a specified date/time.
Return value: Sub-satellite point and local azimuth and elevation headings.
Example: GET_SAT_POS OSCAR-10 1003536767 1003537367m
Data returned:

1003536767 Sat 20Oct01 00:12:47   37  245  171   13  115  33990  11004 +
1003536827 Sat 20Oct01 00:13:47   37  245  172   13  115  33928  11004 +
1003536887 Sat 20Oct01 00:14:47   37  245  172   13  115  33866  11004 +
1003536947 Sat 20Oct01 00:15:47   37  245  173   13  115  33803  11004 +
1003537007 Sat 20Oct01 00:16:47   37  246  173   14  115  33740  11004 +
1003537067 Sat 20Oct01 00:17:47   37  246  173   14  116  33675  11004 +
1003537127 Sat 20Oct01 00:18:47   37  246  174   14  116  33611  11004 +
1003537187 Sat 20Oct01 00:19:47   37  246  174   14  116  33545  11004 +
1003537247 Sat 20Oct01 00:20:47   37  246  174   14  116  33479  11004 +
1003537307 Sat 20Oct01 00:21:47   37  246  175   14  116  33413  11004 +
1003537367 Sat 20Oct01 00:22:47   37  246  175   14  116  33346  11004 +

Description: 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 (N) and
longitude (W) of the satellite's sub-satellite point at the time
specified, the slant range to the satellite in kilometers with
respect to the ground station's location, and the spacecraft's
sunlight visibility information.

If the ending time is omitted, only a single line of data is returned.
If the starting time is omitted, the current date/time is assumed.  If
the starting date/time is replaced by a number (n) preceded by a '+'
symbol (ie. +10), output is produced starting at the current date/time,
and ending the current date/time plus 'n' seconds.  If an 'm' is
appended to the ending time (+10m or 1003537367m as shown above),
then the data produced corresponds to the position of the satellite
every minute for 'n' minutes.

When multiple lines of data are generated, they are returned a line
at a time rather than as a single string containing the entire output
(as is the case with most other socket commands).  As a result, the
socket connection must remain open, and data must be read a line at
a time until an end-of-data condition is reached.  An end-of-data
condition is identified upon reception of a control-Z character
by the client.

-----------------------------------------------------------------------------

Command: PREDICT
Argument: satellite name or object number, starting date/time (optional).
Purpose: To obtain orbital predictions for a single pass starting at the
specified date/time, or earlier if the satellite is already in range.
Return value: Satellite orbital prediction information.
Example: PREDICT ISS 1003536767
Data returned:

1003539925 Sat 20Oct01 01:05:26    0  297  180   46  100   2325  16656 +
1003539994 Sat 20Oct01 01:06:35    4  292  183   44   95   1878  16656 +
1003540063 Sat 20Oct01 01:07:44   10  284  186   42   90   1456  16656  
1003540131 Sat 20Oct01 01:08:52   17  270  190   39   86   1096  16656  
1003540197 Sat 20Oct01 01:09:58   24  243  193   37   82    870  16656  
1003540260 Sat 20Oct01 01:11:01   24  209  195   34   78    866  16656  
1003540324 Sat 20Oct01 01:12:04   18  183  198   31   75   1073  16656  
1003540389 Sat 20Oct01 01:13:10   10  169  201   28   71   1416  16656  
1003540457 Sat 20Oct01 01:14:18    5  160  205   25   68   1827  16656  
1003540526 Sat 20Oct01 01:15:26    0  155  208   22   65   2269  16656

Description: 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 (N) and
longitude (W) of the satellite's sub-satellite point at the time
specified, the slant range to the satellite in kilometers with
respect to the ground station's location, and the spacecraft's
sunlight visibility information.

If the starting time is omitted, the current date/time is assumed.
If a pass is already in progress at the starting date/time specified,
orbital calculations are moved back to the beginning of AOS of the
current pass, and data for the entire pass from AOS to LOS is
provided.

As in the case of the GET_SAT_POS command, prediction information is
returned a line at a time, not as as a single string containing the
entire output of the command.  As a result, the socket connection must
remain open between server and client, and data must be read a line
at a time until an end-of-data condition is reached.  An end-of-data
condition is identified upon reception of a control-Z character
by the client.

