SatelliteDataServer

We want to set up ad data server giving us various satellite data on OSC.

One possible method is using predict in server mode, fetching data with a script and broadcasting data in the form of OSC messages.

We are implementing this on the esc server.

- predict: http://www.qsl.net/kd2bd/predict.html is to be launched in "server mode" with "predict -s". TODO: using a cron job, update the TLE data frequently, see man predict:

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

For general information:

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:

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.