			=========================
			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).

An interactive program is also included (demo-i.c) to allow socket
commands to be sent to the PREDICT server via the keyboard, and their
output displayed to the screen.

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.


Error Handling
==============
New error handling routines were added to PREDICT version 2.2.3.
Sending an invalid socket command to a PREDICT server now results
in the server returning the string:

Huh?\n

In earlier versions, nothing would be returned, leaving the client
waiting forever for a response.  (Not that a client would ever send
an invalid command to PREDICT anyway...)

The exceptions to this are the "PREDICT" and "GET_SAT_POS" socket
commands, whose output EOFs are marked by a CONTROL-Z character.
Invalid syntax used in conjunction with these commands return
nothing but the ending CONTROL-Z character, as in earlier versions.


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 ECHO
Data returned:

ECHO
151.79 
-70.04
203.75 
-60.01
1126395990
5988.49
11881.33
773.71 
7.47   
6292
D
279.37 
-32.42 
360.00 

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

Name:		ECHO
Long:		151.79 (degrees West)
Lat:		-70.04 (degrees North)
Az:		203.75 (degrees)
El:		-60.01 (degrees)
Next AOS/LOS:	1126395990 (seconds since 01-Jan-1970)=Sat Sep 10 23:46:30 2005
Footprint:	5988.49 (kilometers)
Range:		11881.33 (kilometers)
Altitude:	773.71 (kilometers)
Velocity:	7.47 (kilometers/hour)
Orbit Number:	6292 (revolutions)
Visibility:	D (see below)
Orbital Phase:	279.37 (degrees)
Eclipse Depth:	-32.42 (degrees)
Squint:		360.00 (degrees, or 360.0 if squint is not applicable)

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.

If the satellite has decayed, the Next AOS/LOS time will be reported
as 0.  All other values will also be set to zero.  The visibility code
will be set to 'N'.

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

Command: GET_DOPPLER
Argument: satellite name or object number
Purpose: To poll PREDICT for normalized Doppler shift information.
Return value: 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.

As of version 2.2.3, GET_DOPPLER now returns data even if the satellite
is below the horizon.  Clients can use this information to correctly
tune transmitters and receivers in prior to the time of AOS.

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

Command: GET_SUN
Argument: none
Purpose: To poll PREDICT for the Sun's current position.
Return value: The Sun's positional data.
Example: GET_SUN
Data returned:

283.48 
-23.71
-5.51  
190.61 
347.15 

Description: Current azimuth is returned first, followed by elevation,
declination, Greenwich hour angle, and right ascension, all in degrees.

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

Command: GET_MOON
Argument: none
Purpose: To poll PREDICT for the Moon's current position.
Return value: The Moon's positional data.
Example: GET_MOON
Data returned:

267.22 
+16.98
8.79   
149.22 
28.55  

Description: Current azimuth is returned first, followed by elevation,
declination, Greenwich hour angle, and right ascension, all in degrees.

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

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-7
OSCAR-11
PACSAT
LUSAT
OSCAR-20
ITAMSAT
OSCAR-27
OSCAR-29
OSCAR-32
OSCAR-41
OSCAR-46
OSCAR-50
CUTE-1
RS-15
RS-20
PCSAT
ECHO
HAMSAT
NOAA-14
NOAA-15
NOAA-17
UARS
HUBBLE
ISS

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.2.3\n
Description: Allows clients to determine what version of PREDICT they're
talking to.  This command can also be used as a "ping" command to test
the connectivity to the PREDICT server prior to sending more important
queries to the server.

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

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 NASA Two-Line Keplerian orbital data.
Example: GET_TLE OSCAR-27
Data returned:

OSCAR-27
1 22825U 93061C   03 59.55562140  .00000055  00000-0  38039-4 0  4973
2 22825  98.2745  88.7439 0007588 226.4709 133.5846 14.28945788491306

Description: The satellite's Keplerian orbital data in the standard
NASA Two-Line element format.

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

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:

1126375569

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 Sep 10 18:06:09 2005

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-7" 1046998422 +10m
Data returned:

1046998422 Fri 07Mar03 00:53:42  -50  165  175  -64   39  11488  29525 *
1046998482 Fri 07Mar03 00:54:42  -48  165  177  -61   42  11253  29525 *
1046998542 Fri 07Mar03 00:55:42  -46  165  180  -58   45  11011  29525 *
1046998602 Fri 07Mar03 00:56:42  -44  165  182  -55   47  10760  29525 *
1046998662 Fri 07Mar03 00:57:42  -42  165  184  -53   49  10501  29525 *
1046998722 Fri 07Mar03 00:58:42  -40  165  186  -50   51  10234  29525 *
1046998782 Fri 07Mar03 00:59:42  -38  166  189  -47   53   9959  29525 *
1046998842 Fri 07Mar03 01:00:42  -36  166  191  -44   54   9678  29525 *
1046998902 Fri 07Mar03 01:01:42  -34  166  193  -41   56   9389  29525 *
1046998962 Fri 07Mar03 01:02:42  -32  166  195  -38   57   9094  29525 *
1046999022 Fri 07Mar03 01:03:42  -30  167  197  -35   58   8792  29525 *

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, even when there is
only a single line of data.  An end-of-data condition is identified
upon receipt 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 1126375569:
Data returned:

1126378996 Sat 10Sep05 19:03:16    0  183  240   22   75   2135  38914 *
1126379060 Sat 10Sep05 19:04:21    3  174  243   25   72   1794  38914 *
1126379125 Sat 10Sep05 19:05:26    7  160  246   28   69   1517  38914 *
1126379189 Sat 10Sep05 19:06:30    9  142  249   31   66   1346  38914 *
1126379253 Sat 10Sep05 19:07:34   10  122  252   34   63   1324  38914 *
1126379318 Sat 10Sep05 19:08:38    8  103  255   36   59   1454  38914 *
1126379382 Sat 10Sep05 19:09:42    5   88    2   39   55   1705  38915 *
1126379447 Sat 10Sep05 19:10:47    1   78    5   42   51   2032  38915 *
1126379469 Sat 10Sep05 19:11:10    0   75    6   42   49   2157  38915 *

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.

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

Command: GET_MODE
Argument: none
Purpose: To determine PREDICT's current tracking mode.
Return value: String containing program mode information.
Example: GET_MODE
Data returned:

OSCAR-11\n

Description: GET_MODE returns the string "MULTI\n" if PREDICT is currently
operating in Multi-Satellite tracking mode.  A list of available satellites
can then be obtained through use of the GET_LIST command.  If PREDICT
is operating in Single Satellite tracking mode, then the name of the
satellite currently being tracked is returned followed by a '\n' character.
If PREDICT is not currently tracking satellites, then "NONE\n" is returned.

