VersaTrack V1.2 =============== 1.0 HISTORY, COPYRIGHTS, RESTRICTIONS AND DISCLAIMERS ------------------------------------------------- VersaTrack is a derived work, based in part on other similiar work as described below. It started life as a pet project mostly to learn, among other things, Windows-NT. My background in programming has been almost exclusively in Unix, but I use a PC clone running Windows NT at home. That, combined with the lack of moderately nice, native windows-based satellite tracking software (free or cheap), opted me to work on VersaTrack. Since I am not an experienced "Windows" or "OOP" programmer, the code will most probably neither be efficient, nor optimal in many ways. It is provided "as is" for your hacking pleasure. As to the accuracy of the results produced by the pragram, all I can say is that they seem to be adequate for my purposes and jive with some other freeware that are known to give good results. VersaTrack was intended to be a learning tool more than anything else, and as such, I hope that it will be used in that spirit. I welcome any and all comments, refinements, or complaints that anyone might have. I also hope that others will pick up where I have left off, to make the code more efficient, and to add more features, specially with respect to external modules (i.e, executable programs) for radio and rotator control, for which I've provided complete (or at least near complete) built-in support. Versatrack orbit calculations are based on those that appear in Dr. Manfred Bester's fine sattrack program (versions 1 and 2, circa 1992 forward). The data from which the maps where generated come from "xsat", an X-Windows program by David A. Curry (N9MSW). Site coordinates come from various sources, including a couple of World Almanacs, and also from both of the programs mentioned above. The following are authors' applicable copyright notices: ********** SATTRACK (UNIX VERSION) ********* Copyright (c) 1992, 1993, 1994 Manfred Bester. All Rights Reserved. Permission to use, copy, modify, and distribute this software and its documentation for educational, research and non-profit purposes, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and the following three paragraphs appear in all copies. Permission to incorporate this software into commercial products may be obtained from the author, Dr. Manfred Bester, 1636 M. L. King Jr. Way, Berkeley, CA 94709, USA. IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. ******** XSAT (for X-Windows) *********** Copyright 1992 by David A. Curry Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. David A. Curry, N9MSW Purdue University Engineering Computer Network 1285 Electrical Engineering Building West Lafayette, IN 47907 davy@ecn.purdue.edu ******** VERSATRACK ********** VersaTrack Copyright (c) 1993, 1994 Siamack Navabpour. All Rights Reserved. Permission is hereby granted to copy, modify and distribute VersaTrack in whole, or in part, for educational, non-profit and non-commercial use only, free of charge or obligation, and without agreement, provided that all copyrights and restrictions noted herein are observed and followed, and additionally, that this and all other copyright notices listed herein appear unaltered in all copies and in all derived work. This notice shall not in any way void or superceed any of the other authors rights or privilages. VersaTrack IS PRESENTED FREE AND "AS IS", WITHOUT ANY WARRANTY OR SUPPORT. YOU USE IT AT YOUR OWN RISK. The author(s) shall not be liable for any direct, indirect, incidental, or consequential damage, loss of profits or other tangible or intangible losses or benefits, arising out of or related to its use, even if the author(s) has(have) been advised of the possibility of such occurance. VersaTrack carries no warranty, explicit or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Siamack Navapbour 12342 Hunter's Chase Dr. #2114 Austin, TX 78729 sia@bga.com -or- sia@realtime.com 2.0 PROGRAM REQUIREMENTS AND RESTRICTIONS ------------------------------------- VersaTrack V1.2 runs under Microsoft's Windows-NT and uses Windows-NT-specific features. IT WILL NOT RUN UNDER WINDOWS 3.xx. It was developed with MS WIN32 SDK under Windows NT 3.1 and subsequently moved to Windows NT 3.5. If you need to make the current version run under 3.1, you have to recompile it with the the corresponding flag set in the makefile. Little emphasis has been placed on memory conservation, or CPU utilization, so your system should have plenty of memory and preferrably a floating point processor. A mouse (or equivalent) pointing device is also required. There are two sets of maps supplied with the present version. One set is intended for an 800x600 display and the other for 640x480 display. Both should be used in 256 (or more) color modes. They may or may not work with other resolutions or color combinations. The 640x480 mode is not much recommended. The maps do not show the up to date political boundaries of some of the world countries at the present time. My regrests for that, but I had no other readily accessible source of data to generate more pollitically correct maps. In order to use VersaTrack effectively, you need fresh (or at least fairly fresh) satellite elements. The provided element set may be too old by the time you begin to use this program, so you should try to obtain a new set. They are priodically posted over the Usenet news groups and are also available from AMSAT, ARRL and various other BBSs. VersaTrack can only use the NASA 2-line element set format. I hope someone will add support for the AMSAT format. 3.0 FEATURES -------- o It is free and unrestricted (with copyright restrictions) for non-profit use. Source are provided. o Real-time display of position of any satellite from any site. Number of satellite-site combinations restricted only by system CPU power and amount of available memory. o Tabular report and graphical display of ground track for any selected satellite. o Real-time display or ground track report times can be independently chosen for each satellite-site pair to be in UTC, "local time", or "site local time". o "Next" rise (AOS) /set (LOS) times display for any chosen satellite/site pair, with display of duration, maximum elevation on the pass, and the (approximate) direction of travel. o Two user selectable maps ("U.S.A." and "World"). Options for adding custom maps (needs a bit of programming.) o Easy, one-step selection of options and parameters. There are no confusing menu traversal, dialog hierarchy, etc. o User selectable colors for display of ground tracks, sub-satellite points, and annotations. o Uses "editable" regular ASCII text files for all data bases. o Fully integrated support for utilization of external modules (i.e., programs) for remote control of devices such as rotators and radios. 5.0 KNOWN CAVEATS, BUGS AND GOTCHAS ------------------------------- 1) Versatrack uses cpu power and memory liberally. For example, if you decide to have it display in real-time, 50 satellite/site pairs with short update intervals, be prepared to let go of a few megs of memory and a good portion (if not all) of your system's CPU juice. 2) Once in a long while, during a real-time display, the sub-satellite point display of a satellite does not get erased (or updated) properly, leaving a smudge behind. This problem occurs very rarely and a "re-draw" takes care of it. 3) User selectable colors are limitted to 16. 4) Only 800x600- and 640x480-bit resoultion maps are provided. 5) If external control servers are activated at the same time (or "close" together), no data may be sent to either one. 6) There is currently no help file avilable. 7) The "More.." and "simulate" buttons in the "Settings" dialog box are virtual no-ops. 8) AMSAT orbit parameter's format is not supported in current version. It can make a nice little extension project. 9) Some of the time zone offsets given in the sites data file may be wrong. You should verify and correct (edit) the data for your favorite site(s). 10) When the "hide icon" attribute is selected, the icon will be hidden, but the icon title text will not! 6.0 INSTALLATION AND SETUP ---------------------- As distributed, VersaTrack is fully functional and has no time restrictions, etc. It is free for educational, hobby, and non-commercial use. However, remember that is a copyrighted derived work and you must read, understand and observe the terms and conditions associated with its usage as set forth in this document (See Section 1.0.) To Install verSatrack (sources & executables) you need about 2.7 megabytes of free disk space. After unpacking the distribution archive, place the files in a directory that is listed as part of your PATH environment variable. Then run VERSATRACK.EXE from the command line or via the "run" command of program manager's File menu. Make sure your system has a mouse or equivalent pointing device. When Versatrack is run for the first time, it will prompt you for installation. If you choose to install, you are prompted for names of data files, the default map to be displayed, the directory where VersaTrack can find its files, the name of your locale and its time zone information. The installation is on a "per username" basis. After all the questions have been answered and verfied, VersaTrack proceeds to create entries under the following key in the system registry: \HKEY_CURRENT_USER\Software\VersaTrack\Versatrack 1.2 When answering questions during the installation, observe the following guidelines: - Avoid misspellings. - Make sure any directory name you enter already exists. - If your site's name is more than one word (i.e., has spaces), enter only *one* space between words. You must also make sure that the name you enter appears in exactly the same way in the sites file. If it doesn't or they differ in spelling, you must edit the entry in the sites file or re-install. - Make sure the entry for your site as specified in the site's file has the correct time zone name and UTC offset. You should edit the site's file and correct these if necessary. Your system must be able to allocate roughly about 1.5 megabytes of memory before VersaTrack can sucessfully start up. Throughout its execution, VersaTrack attaches (loads) its dynamic link library (DLL) on an as needed basis to conserve some memory. If no errors are detected during the installation steps, and if all the data files are found, VersaTrack displays a map and awaits commands. If you have not read the copyright notices and usage terms, click on "Copyright". NOTE: THE PRESENT VERSION OF VERSATRACK DOES NOT KNOW ABOUT TIME ZONES AND DAYLIGHT SAVINGS TIME FOR ANY LOCALE, EXCEPT FOR WHAT IS SPECIFIED DURING INSTALLATION AND IN THE SITES FILE. IF DAYLIGHT SAVINGS TIME CHANGES, YOU SHOULD UN-INSTALL AND THEN RE-INSTALL VersaTrack, AND ALSO EDIT THE SITES FILE TO MODIFY ANY RELEVANT UTC OFFSETS AND TIME ZONE NAMES. 7.0 OPERATION --------- 7.1 Your System Clock or Timer -------------------------- Be sure to set your system clock or timer as accurately as possible. Based on the load on your system, it may become necessary to set the clock a few seconds ahead. This skew may compensate for processing delays and other load on the system and may yield slightly more accurate results. 7.2 Initialization When you run VersaTrack after it has been installed, it reads the system registry to determine where where it can find its data files. It then proceeds to open and read its satellites data base, sites data base, a "modes" file that may have additional information about one or more of the satellites, the file containing the "active list", and two rather small files that contain information regarding external modules with which VersaTrack can optionally communicate. After all these files are read, VersaTrack proceeds to read and display a file containing a map. One the initialization phase is finished and the map is displayed, VersaTrack waits for user commands. 7.3 The Active List and Primary Selection VersaTrack operates on what from here on we will call a "satellite-site pair", or an "entry". Any number of satellite-site pairs can be chosen by the user. The list of all such satellite-site pairs is called the active list and can be stored in an a disk file (the default name of the active lists file is "active.dat"). Any satellite can be paired with any site, and vice versa. At any given time, one of the satellite-site pairs in the active list will be "the primary selection" or "the primary pair". Right after startup, the primary selection will be the very first entry in the active list. It will not be remembered from a previous execution. For this reason, it is a good idea to make sure the first entry in the active list belongs to your "favorite" satellite and site. You can edit the active list file and move your favorite entry to the beginning. This file is read only once during VersaTrack's initialization. During normal operation, you can change the primary selection by first clicking on the "Settings" button, and then clicking on one of the entries listed in the box titled "Active List". See Section 8.5 for another method of changing the primary selection. Except for one, all VersaTrack commands operate on the primary selection of the active list. The exception is when you click on "RTD" in VersaTrack's main window menu. RTD stands for "Real-time Display". RTD will always operate on all items of the active list. To see and manipulate the active list you should use the "Settings" dialog box by clicking on the button labeled "Settings" at the top of VersaTrack's main window. The active list appears in the lower right hand corner of the "Settings" dialog box. For each satellite-site pair in the active list, VersaTrack keeps a set of attributes. These attributes are the parameters and flags that are needed during other VersaTrack operations. For example, the value for "minimum elevation" is used to determine if a satellite is "visible" from its paired site. By "visible" we loosely mean "radio visible". Of course in reality natural or man-made obstructions may affect the "actual" visibility (either in the optical spectrum or otherwise). Another attribute or parameter is the time format in which a satellite's position is reported. In the "Settings" dialog box, you can also see the list of all the available satellites and sites. 7.4 Manipulating the Active List To add an entry to the active list, regardless of whether or not there are other entries in it, simply choose a satellite and a site, fill in or click on the values or flags as appropriate, select the time formats and then click on "Add". If another entry with the same satellite and the same site does not exist, a new entry will be created. Note however, that any changes you make will not be stored to disk unless you click on "Save". To delete an entry from the active list, first select the entry by clicking on the desired entry, in the list box labeled "Active List". Then click on "Delete". To modify an entry (i.e., a satellite-site pair), select it from the list box labeled "Active List", then change the attributes as necessary, and then click on "Modify". Pressing ENTER or RETURN after typing in a value or a name will cause verification of that what you just entered to be performed immediately, otherwise all values will be checked for validity when you click on "Modify", and you may see several error boxes pop up one after another. Whenever you enter the name of a site or a satellite, via the edit boxes labeled "Site" or "Satellite" the associated list box will roll back and forth as you type in the letters. You can have VersaTrack attempt to complete your "typing" for you by hitting the RETURN or ENTER key early on. In other words, if the name of the satellite is DO-17, and you have entered "DO", hitting the RETURN or ENTER keys will finish the entry and make it "DO-17", provided that no conflicts are detected. Since the first parts of many of the entries in the satellite and site lists are the same, this method will not always give you the actual entry you wanted, but occasionally it can be convenient. Whenever you see an asterisk "*" for a value in one of the controls in the "Settings" dialog box, it means "use the default value". You can also enter an astrisk if you want VersaTrack to use the default value for an attribute. The default value for duration is 1 day, for minimum elevation it is 0 degrees, for start time it is "the time at the point when a VersaTrack command is executed that needs the start time", for ground track step time, it is 30 seconds, and for position update it is 30 seconds. You can save the active list by clicking on the button labeled "Save". This will re-write the active list file, destroying its previous contents, so be careful. -- IMPORTANT -- Whenever you actually type in a value (numerical or otherwise), in one of the controls, be sure to press the RETURN (or ENTER) key when you are finished. The value you enter will not take effect (i.e., will not be fully read) unless you press the RETURN (or ENTER) key. The entries in active list are stored in the active list file (default "active.dat") as regular ASCII text records. You can edit this file and change the entries. VersaTrack does not perform a lot of validity checks on the contents of its data files, so be very careful, as errors in the data files may cause the program to behave in an unpredictable fashion, crash, hang, etc. 8.0 MAIN MENU COMMAND BUTTONS ------------------------- 8.1 Maps Versatrack will try to display the highest resolution map available for a given display (with a given name). To do this, it will append one of the following strings, depending on the present display resolution, to the name of the default map (specified during installation): "17" for 1024x768 bit resolution, "86" for 800x600, "54" for 640x480, "oem" for any other resolution. The suffix ".map" is also added. The two standard map names are "world" and "USA", however, if you wish to display other maps, you can prepare them using your modified version of mapadj.c, and then specifying the base name during installation. The current version of VersaTrack has one set of maps ("world" and "U.S.A.") for 640x480 bit displays and another set for the 800x600 bit displays. These maps may actually need a bit more "re-touching" to make them more accurate, but for most practical purposes they are adequate as they are. If a map's width and/or height is more than the current display size, a warning message will be issued by VersaTrack, but an attempt will be made to display the map anyway. All the maps are in Windows standard .DIB format but they have a VersaTrack-specific trailer. If you modify them using a painting/drawing tool, you must run mapadj.exe to add the trailer. You can also add your own maps if they are written in the standard .DIB format and you append the VersaTrack trailer. The trailer specifies the min. and max. latitude and longitude information for a given map file. 8.1 World Map Clicking on this button will cause VersaTrack to draw the world map. If Real-time Display (RTD) is active, the operation of the real-time display will be frozen for the duration of the drawing operation. Any previous ground track image will be erased. 8.2 U.S.A. Map Clicking on this button will cause VersaTrack to draw the map of the United States. If Real-time Display (RTD) is active, the operation of the real-time display will be frozen for the duration of the drawing operation. Any ground track image that may have been drawn prior to this command will be erased. 8.3 Redraw Map Clicking on this button will redraw the current map. Any previous ground track image will be erased. If the Real-time Display is active, its operation will be frozen for the duration of the re-drawing operation. 8.4 GTR (Ground Track Report) When this button is clicked, VersaTrack draws the ground track for the satellite for the primary selection using the "Start Time", "Duration", "Ground Trk Step Time", and "Min. Elevation". At the same time, a tabular human readable report is also generated and written to a disk file. The default name of the file is "GTR.OUT", but you can change it via the "GTR Filename" button. For the tabular report, the "Minimun Elevation" parameter associated with the primary selection is used to limit the lenght of the report. Only portions of the ground track that are visible from the associated site will be written out to the file. The time in the tabular report is converted to reflect the format selected for the entry (via "Report Ground Track Time in:" in the "Selections" dialog box.) The resolution of the graphical, as well as the tabular format is determined by the "Step Time" attribute of the entry. If a map of a "small" area is being displayed, the computation step time should be chosen small enough to produce a continous and smooth graph. The Color of the graph can be changed by going through the "Colors" dialog box. Activating "GTR" while the real-time display is running, will cancel (and terminate) the real-time display. Clicking on "STOP" button, in the menu on VersaTrack's main window will cancel an on-going Ground Track Report. A warning note will be written to the tabular report to indicate early termination of the report. 8.5 RTD (Real-time Display) When this button is clicked, VersaTrack will start displaying annotated sub-satellite points for all the entries of the active list. Also, for each entry, a dialog box will be created and displayed. RTD is a resource intensive operation. For each entry of the active list, VersaTrack creates a separate execution thread, allocates several Kbytes of memory, and creates a separate window. At intervals approximately equal to the "Pos. Update" attribute of each entry, the corresponding thread will run set of CPU and FPP intensive operations. You can have VersaTrack open up the icon for a given satellite-site pair when the satellite becomes visible from the site, by choosing from the "On Approach:" box, the "Pop up Icon" attribute for the entry. Similarly, you can have VersaTrack generate an audiable chirp (an octave's worth) when the satellite becomes visible. The default dispositions of each of the created dialog boxes (that is to say, whether you want them to be normally iconic, or opened up) can be chosen by toggling the "Keep Iconic" attribute. If the dialog box is to be displayed iconically, you can have VersaTrack blink its title bar upon visibility, by toggling the "Blick Icon" attribute. Toggling the "Blink on Map" attribute will enable or disable the continuous blinking of the sub satellite point on the map during the real-time display. The reported time is adjusted according the the format selected for the item in the "Real-time Display Time in:" attribute. The "Hide Icon" attribute when selected will inhibit the display of the icon for a given entry. There is a bug in the current version that causes some anomalous display of the icon's title bar (!!) when this attribute is turned on, but nonetheless, it can avoid some of the clutter if you have a large number of entries in the active list. When a satellite is not visible, VersaTrack still displays the values for Azimuth, Elevation, Doppler, etc. in the Real-time Display dialog box for that satellite. These values, although mathematically correct, have virtually no practical use. You can stop the real-time display of one or more entries by opening the icon (i.e., double clicking on the icon), and then clicking on the button labeled "Stop". To restart the real-time display for all the "stopped" entries, simply click on "RTD" again. Currently there's no provision for *selectively starting* the real-time display for individual entries of the active list. Whenever the real-time display is running, you can change your primary selection by moving the cursor over the sub-satellite point and clicking. This will not only toggle the state of the real-time display dialog box for that entry (iconic or opened up), but it also will make that entry the "primary entry". This is the second method of changing the primary selection (as opposed to going through the "Settings" dialog box.) Note, however, that double-clicking on the an icon (to open it up) does not change the primary selection. To stop the real-time display for all entries, click on "STOP" in VersaTrack's main window menu. "Please Wait..." will appear in the window title and RTD will be terminated for all entries of the active list. If you to stop the real-time display for individual entries, you should first open the the desired icons and click on the "STOP" button in each of the "opened-up" dialog boxes. If you click on "GTR" while the real-time display is active, the real-time display will be canceled (i.e., stopped), and the Ground Track Report will subsequently commence. In such cases, if you need the real-time display, you must re-start it manually. 8.6 Rise/Set Times Clicking on this button will display a dialog box that will show the next AOS/LOS times for the primary entry. As you click on the "Next" button in that dialog box, the next AOS/LOS times, the pass duration and the predicted maximum elevation and approximate direction of travel (relative to the site) will be displayed. This operation is independent of GTR or RTD and can be done while either one of them is in progress. The "Next" operation is limited by the "Duration" attribute of the primary selection. The computation of the Rise/Set times starts at the time specified for the "Start Time" attribute of the primary entry. The displayed time is adjusted to reflect the time format chosen for "Ground Track Report Time". The duration is displayed in days:hours:minutes:seconds. If you activate this option while the satellite is in view, and the selected "Start Time" for the entry is "*" (i.e, "now"), then the rise or (AOS) time will not be the time that the bird's elevation went above the entry's threshold ("Min Elevation"). It will be the time when you clicked the "Rise/Set Times" button. 8.7 STOP Clicking this button will terminate any on-going real-time display or ground track report operation. Otherwise it has no effect. It will not affect the service thread that may have been previously started for connection to an external module (rotator / radio server, etc). 8.8 GTR File Name Clicking this button will display a dialog box that lets you change the name of the disk file into which VersaTrack writes the tabular Ground Track Report. 8.8 Colors You can change the colors of the sub-satellite points and the satellite annotations during RTD, or the color of the ground track trace on the map, by clicking on this button. You can only do this if the Real-time Display or the Ground Track Report operations are not in progress. During the Real-time Display, the chosen color for "satellite" and "satellite annoations" will be XOR'ed with the displayed map colors and what you see will be the resulting colors. 8.9 Uninstall Clicking this button will remove the entries that VersaTrack has previously entered into Windows-NT system Registry, effectively uninstalling VersaTrack for the current user. The program will then terminate. 8.10 Starting External Modules Two of the buttons on VersaTrack's main menu are used for invoking external "servers" to which VersaTrack can send data for the primary selection during the Real-time Display. The lables that will appear on these buttons are specified via the tokens given in the default files "radio.dat" and "rotator.dat". Refer to Section 10 for more details about the operation of the external modules. 8.11 Copyrights Clicking on this button will display the copyright information, distribution and usage rights and restrictions, etc. 8.12 Help Clicking on this button will launch help32.exe passing to it "versatrack.hlp". Unfortunately, version 1.2 does not have a help file! 9.0 UNITS OF MEASURE ---------------- Unless otherwise noted, VersaTrack uses the following units in its displays: INTERVAL TIME: Seconds. The "Next Rise/Set Time" command uses days:hours:minutes:seconds for its display. ELEVATION: Degrees [ -90..90 ] Local Horizon = 0.0 AZIMUTH: Degrees [ 0..360 ) North = 0.0, East = 90.0 LATTITUDE: Degrees [ -90..90 ] South of Equator < 0 LONGITUDE: Degrees ( -180..180 ) West of Greenwich < 0 OTHER ANGLES: Degrees DISTANCE: Kilometers DATE: Month/Day/Year Hours:Minutes:Seconds [TimeZoneName] or Month-Day-Year Hours:Minutes:Seconds [TimeZoneName] FREQUENCY: Hertz (except where noted.) LIN. VELOCITY: Km/sec. 10.0 EXTERNAL INTERFACE ------------------ Versatrack has a built-in interface for communication with external programs. This interface uses independent execution threads and is based on Windows-NT's "named pipes". When VersaTrack's "Real-time Display" is active, two external programs can simultaneously receive data on the primary satellite's position, and use that information, for example, to control a radio to adjust for doppler, or to steer an antenna. Versatrack uses two regular ASCII text files to determine the titles to display on two of its menu buttons, and the corresponding names of the executables to spawn when those menu buttons are clicked. The format for the "lines" of text in the data files are: Model Drv where is a short name or title that Versatrack will display on a menu button reserved for this purpose, and is the name of an executable program that should exist in one of the directories listed in the PATH environment variable. When the user clicks the button, Versatrack will first check to see if the appropriate named pipe already exists. If the pipe is there, versatrack will assume that the corresponding server is already running. It will start a service thread, and depending on whether the "real-time" mode is running or not, will either write updated data for the primary satellite, or, if the real-time mode is not running, will periodically (approx. every 30 seconds) write a special message to the pipe indicating that no data is available. This will continue until either the server terminates (and consequently the pipe is closed), in which case versatrack closes its end of the pipe and discontinues the service thread, or, versatrack terminates, in which case the server must recognize that the peer writing to the pipe has disconnected, and proceed to undertake any action that the server believes is necessary from that point on, including orderly termination of any provided service, etc. If Versatrack cannot connect to the pipe, it will assume that the server is not already running, and will attempt to spawn the executable module via the CreateProcess() API. It will then proceed to re-connect to the pipe as outlined above. The external module, or "server" as it will be called from here on, is responsible for creating a named pipe, listening on that pipe for an incomming connection from VersaTrack, and then reading the data from the pipe and using it for its tasks. Two such servers can run simultaneously and each uses a different named pipe. The names of the pipes are: \\.\PIPE\_VROTAT_ and \\.\PIPE\_VRADIO_ As can be guessed, one is primarily intended for communication with an external program for controlling a radio, and the other for communication with an external program for controlling an antenna rotator. No provision is currently provided to have "remote" servers, although their implementation is somewhat trivial at the API level. Once a server starts up, it should create "its" pipe as soon as practical, and start listenning on it for a connection. If a connection is made, the server must continously read the pipe until the peer (writer) closes. A sample skeleton "radio" server is provided that shows how that can be done. The sample also has the skeleton code for reading from and writing to one of WinNt's supported COM ports (the right way). The code can be used as the starting point for writing a fancy full-fledged radio or rotator controller. The data VersaTrack sends over the pipe(s) is in ordinary "human-readable" ASCII. All messages are written as fixed 100 byte packets and are in the form of C language strings with at least one null character at the end. A message that is exactly 100 bytes long will not have a terminating null. The first character of a message indicates the basic type of the message. The format of the remaining characters in the message depend on the type. There are presently 4 types of messages. They are "hello", "initialization", "data", and "interruption" messages. The following sections describe each message type in detail. Please note that wherever is specified, one or more space (blank) characters may actually appear. Also, the numerical values whether decimal, hexadecimal or floating point, may have leading zeros. None of the numerical values is in octal. Strings appearing inside double quotes are literals (case sensitive). HELLO MESSAGE: FORMAT: ">""HELLO" "WH" "SEQ".... is versatrack's main window handle as returned by WIN33 API CreateWindow(). It is formatted as a hex value. It can be used by the server to determine the thread-id of versatrack's main window to do periodic PostThreadMessage()'s in order to implement a heart-beat. If the PostThreadMessage fails, the server will know that Versatrack has exited or terminated for some reason. VersaTrack will receive and discard message number WM_USER+27. So this message can be used for implemetation of a heartbeat. is a 2 digit decimal number with the 10's digit being the current VersaTrack major revision number and the One's digit being the current Versatrack minor revision number. is a single digit decimal number indicating the revision level of the messaging protocol. This number is presently 1. is a random decimal value between 0 and 15 (inclusive). Every message that follows will start off with a sequence number with a value one higher than the one in the previous message. This will continue until the end of the session (i.e., another hello message). EXAMPLE: > HELLO 12 1 WH 04003c9f SEQ 011 The HELLO message is sent only once at the start of the activation of versatrack's service thread as soon as it has connected to the server. If one instance of versatrack is terminated and another instance is started (for whatever reason), another HELLO message will be sent. Note, however, that meanwhile, the pipe's client end is closed once, and a new connection is subsequently started. In the example shown, Versatrack version is 1.2 and it is using message format 1. INTERRUPT MESSAGE: FORMAT: "!" ..... The decimal sequence number is the value of the previously sent sequence number plus 1, as a signed 32 bit 2-s complement number. There are currently only two interruption message strings ( for ): a) 'STOPPED' Is sent when Versatrack's Real-time mode has not started yet, or is stopped after it was started. While real-time mode is not running, this interrupt message will be continuously sent approximately every 30 seconds. The same is also true if the real-time display mode is stopped for the primary satellite/site pair (e.g., by clicking the "stop" button in the dialog box of the primary satellite/site display.) In other words, versatrack may be running real-time displays for other satellite/site's, but the user has stopped one or more of them, including the the one for his "primary" selection. b) 'SAT CHANGED' Is sent whenever the user changes the 'primary' satellite/site pair in Versatrack while versatrack's real-time mode is running. It can be used by the server to take any appropriate action needed for proper operation of the server and the device it controls (if any.) The single quotes are parts of the message. In a) and b) above, single quotes are for readability only. The actual message will only have one single quote at the beginning and one at the end of the text string. EXAMPLE: ! 2091 'SAT CHANGED' - or - ! 776 'STOPPED' INITIALIZATION MESSAGE FORMAT: "*""INIT UPD" "MD" "MIE" "SITE""SAT" ..... decimal sequence number is as described before. The Data update interval is the approximate number of seconds (in decimal) between data messages sent by VersaTrack. This number can be used, for example, by the control server for interpolation of the parameters based on prior messages, etc. The satellite's operation mode is a 3 character string that indicates which satellite's transponder is active. Versatrack uses the data supplied in its "modes" data file along with the position of the satellite in its orbit to come up with this string. If no mode is given for the satellite in VersaTrack's modes file, then the data will be either null (i.e., two consecutive single quotes ''), or 'N/A'. Minimum elevation is a decimal floating point value (in units of degrees above site's local horizon). It is one of the attributes specified by the user via the "Settings" dialog box. It can be used by the control server to warn the user and gracefully start or stop the device it controls (such as a radio or antenna otator). Site and Sat names are the corresponding satellite and site names for the currently selected "primary" satellite/site pair in VersaTrack. Every time the user changes the primary satellite/site pair while Versatrack's real-time mode is on, An interrupt message, followed by an initialization message is sent to the control server. EXAMPLE: * INIT 356 UPD 5 MD ' S' MIE 10.0 SITE 'Austin, Texas' SAT 'AO-13' DATA MESSAGE: FORMAT: "+" "AZ" "EL" "RNG" "DV" "PL" .... (note that satellite name is not in single or double quotes). The sequence number is as explained before. and specify the relative position of the bird and are specified as floating point decimal numbers. Azimuth can range from 0.0 to 360.0 (minus epsilon), and Elevation value's range is -90.0 to +90.0. Range is given as a floating point decimal number. It may in some cases be given in exponential format. Satellite's speed is given as a floating point decimal number and can be positive (if satellite is approaching), or negative (if satellite is receding). This value can be used to determinte the doppler shift. The path loss is just a theoretical value that gives a first order indication of the the relative signal attenutation. While its use is limited, it may be used to switch in/out pre-amplifiers, for example. The satellite name follows all other parameters and starts with the first non-blank character after path loss and continues until the end of the string (either the first null character, or end of 100 byte buffer. EXAMPLE: + 077 AZ 261.5 EL 22.7 RNG 789.02331 DV -4.27283121 PL 164.1 DO-17 NOTES: Any of the INTERRUPT messages can occur at any time after the HELLO message. This means they can appear right after hello, before or after INIT, and in the middle of data messages. One type of INTERRUPT message may be followed by another with or without any other intervening message(s). Also, An INIT message is not garanteed to be followed by a data message, but a DATA message will always be sent sometime after an INIT message. Normally a data message will immediately follow an INIT, but sometimes one or more INTERRUPT messages may appear between them. The only type of message that can appear right after an INTERRUPT message with a 'SAT CHANGED' text, is either an INTERRUPT message with a 'STOPPED' text, or an INIT message. TYPICAL SESSION: (The numerical data for the satellites are all made up and may or may not make any sense) > HELLO 12 1 WH 00005e00 SEQ 011 ! 012 'STOPPED' ! 013 'STOPPED' ... ... ! 040 'STOPPED' <- user clicks on RTD in VersaTrack * INIT 041 UPD 5 MD ' FM' MIE 10.0 SITE 'Austin, Texas' SAT 'DO-17' + 042 AZ 220.9 EL -37.2 RNG 5467.92821 DV -2.0187783 PL 240.6 DO-17 + 043 AZ 221.1 EL -37.1 RNG 5453.18010 DV -2.0093974 PL 240.6 DO-17 + 044 AZ 221.1 EL -37.4 RNG 5447.73274 DV -1.9741230 PL 240.6 DO-17 + 045 AZ 221.2 EL -37.6 RNG 5441.86544 DV -1.9690811 PL 240.5 DO-17 + 046 AZ 221.2 EL -37.9 RNG 5436.65155 DV -2.8019801 PL 240.5 DO-17 ... ... <- user selects another sat ... ! 173 'SAT CHANGED' * INIT 174 UPD 120 MD ' S' MIE 15.0 SITE 'Austin, Texas' SAT 'AO-13' + 175 AZ 66.0 EL 28.9 RNG 13389.1 DV 6.2972171 PL 181.9 AO-13 ... ... <- user stops the real-time display for AO-13. ! 176 'STOPPED' ! 177 'STOPPED' ... 11.0 MISC ---- 11.1 Data Files Lines starting with '#' and those containing only spaces or tabs are treated in most data files, as comments. The Two-line Element set file can have duplicate entries for a satellite. VersaTrack will pick up the element set with the highest sequence number. Duplicate satellite names whose catalog number don't agree, or duplicate catalog numbers whose names don't agree will be flagged to the user. Commnet lines are recognized and skipped. The order of the entries are not important as they will be sorted after the entire file is read. The rotator and radio data files can have serveral records. However, only the first record (line of text) will be used. In all cases records must be syntactically correct or the results will be upredictable. Although the entries in the Sites file will sorted by VersaTrack, it is a good idea to keep the alphabetical order intact for easeier modification and management. 11.2 Ground Track Report Start Time ------------------------------ You can append "UTC", "LOC", or your local time zone name to the date and time that you enter for the "Start Time" in the "Settings" dialog box. Versatrack will convert this date/time to UTC and store it in that format. --END OF DOCUMENT--