G4KLX Hercules Graphics Tracking Program (Microtrack) - Version 1.1
-------------------------------------------------------------------

Introduction
------------

The aim of this piece of software is to give the users of PCs with Hercules
graphics adaptors the same sort of facilities as enjoyed by users with CGAs,
EGAs and VGAs with software such as Sat Scan II and QuikTrack. The result is
this program, it has many of the facilities of the other graphical tracking
programs, certainly the most used facilities here in the G4KLX shack.

The files that make up this software are:

DFILE
SFILE
UFILE
HERC.MAP
MSHERC.COM
OSCAR.EXE
READ.ME
TRACK.BAT

DFILE, SFILE and UFILE are the files with information about DX QTHs, Keplerian
Elements, and the current user data. They are in machine readable form and
cannot be listed or edited using normal DOS commands.

HERC.MAP is the file that contains the image of the world used by this program.

MSHERC.COM is the Hercules graphics support program supplied by Microsoft. This
must be run before the main tracking program.

OSCAR.EXE is the actual tracking program.

READ.ME is this file.

TRACK.BAT is the batch file that starts OSCAR.EXE after running MSHERC.COM, it
is important that MSHERC.COM is run before OSCAR.EXE otherwise you will get a
terse error message and the program will stop.


Installation
------------

To install the program on your hard disc, create a sub-directory, and copy all
of the files from the distribution disc into the directory.

This program will happily run on a machine with a single floppy disc. To do
this, copy all of the files from the distribution disc to a new disc.  You
should have enough space to install DOS on the floppy too, so you can have a
complete bootable floppy with this program on.  By putting the TRACK command
into your AUTOEXEC.BAT, you can have a complete plug-in and play system.


Running Microtrack
------------------

Firstly change directory, to where the program files are located. Then at the
DOS command prompt type TRACK and press enter. The screen will clear. A small
title will appear with the name of the program and its version number, below
this will be a list that reflects what the program is reading from the various
files. Once a file has been read, the program will report the number of entries
in the case of the DX Locations and Satellites. A map of the world will then
appear along with a border and the titles for the satellite tracking
information.

Shortly after a large "window" will appear on the screen showing four columns
of satellite names in alphabetical order. This is the main satellite selection
menu. You will see a border around the top left satellite, this is the
selection marker and indicates which satellite is currently chosen. To change
your selection use the four cursor keys to move in the appropriate direction.
If you are on the bottom line of the list, and you press the down cursor key
and there are more satellites in the list which are below the current one, the
list will scroll. To get to the top of the current column press PgUp, to get to
the bottom of the current column press the PgDn key. To get to the first
satellite in the list press the Home key, and to move to the last satellite in
the list press the End key. Once you have chosen your satellite, press Enter.
That satellite will be chosen and the list will disappear.

The program will return you to the map, you will see that your QTH has a little
cross over it, if you QTH is near a shoreline it may be difficult to see. You
should also see a larger cross which represents the satellites Sub Satellite
point, which is the position on the Earths surface on a direct line between the
centre of the Earth and the satellites position in space. You should also see
a line on the screen which represents the footprint of the satellite. The two
lines below the map should appear similar to the ones below.


 Current Track Time------------------------\             /--------Azimuth
 (HH:MM:SS)                                |             |
                                           |             |
 Current Track Date------\                 |             |        Elevation
 (DD-MM-YY)              |                 |             |           |
                         |                 |             |           |
 Satellite Name          |                 |             |           |
     |                   |                 |             |           |
     V                   V                 V             V           V
 Sat:AO-13          Date:06-05-90     Time:18:20:03   Az:67 deg   El:23 deg   
 MA:127   Mode:LS   Range:23567 kms     Sq:34 deg     Orbit:1453     F F1=Help
    ^          ^          ^                ^                ^        ^
    |          |          |                |                |        |
 Mean          |          |                |                |     Fast Track
 Anomoly       |          |                |                |     Indicator
               |          |                |                |
 Current Mode--/          |                |                \--Current Orbit
                          |                |
 Range -------------------/                \-------------------Squint Angle


Most of the above will be familiar to you from other programs.

Satellite Name: This is the name of the satellite that you have chosen from the
                satellite list.

Date:           This is the current track date, this may be the same as the
                current date but as you will see later there are commands to
                change this.

Time:           This is the current track time in UTC. This is also alterable
                from the keyboard if required.

Azimuth:        The angle from true North to the satellite as seen from your
                QTH.

Elevation:      The angle between the satelite and the horizon at your QTH.
                Obviously a negative value indicates that the satellite is
                below your horizon.

MA:             This strictly speaking is only of relevance to AMSAT Phase III
                satellites and is used to determine mode switching. It is a
		measure of where the satellite is in its orbit. MA 128 occurs
		at Apogee and MA 0 occurs at Perigee.

Mode:           This will only have a value if any mode information was
                included for this particular satellite.

Range:          The distance between your QTH and the satellite.

Squint Angle:   Is the angle between the main beam of the satellites antenna
                and your QTH. If you specify Alon and Alat entries for this
                particular satellite then the value given here is likely to be
                quite accurate. If you did not specify an Alon and Alat for
                this satellite, the program assumes that the satellites
                antennas always point towards the centre of the Earth.

Orbit Number:   Self explanatory.

Fast Track Indicator: Shows whether the fast track mode is in operation.


If you leave the program as it is, it will track the satellite in real time, at
intervals that you can specify. To save time, the program only redraws the
satellite position and footprint on the map if the Sub Satellite Point (SSP)
moves by more than a degree in either its Latitude or Longitude. When a
satellite such as OSCAR 13 reaches Apogee its SSP does not appear to move very
much, therefore the map will not appear to change for quite long periods,
provided the time is still incrementing correctly then the program is still
working.

The program has a few more facilities that you can use. If you press the F1 key
you will get a brief list of the various keys along with there use. Here is
a more detailed description:

F1      Displays the Help screen. Press Escape to remove it.

F2      Bring up the satellite list to choose another satellite to track.
	Choosing a new satellite switches off the fast track mode (see below)
	and resets the track date/time to UTC.

F3/F4	Pressing F3 subtracts one day from the current tracking date. Pressing
	F4 adds one day to the current tracking date.

F5/F6	Pressing F5 subtracts one hour from the current tracking time. Pressing
	F6 adds one hour to the current tracking time.

F7/F8	Pressing F7 subtracts fifteen minutes from the current tracking time.
	Pressing F8 adds fifteen minutes to the tracking time.

F9/F10	Pressing F9 subtracts one minute from the current tracking time.
	Pressing F10 adds one minute to the current tracking time.

Alt-F	Toggles the fast tracking mode. In this mode the satellite is tracked
	at a faster rate than normal to allow you to see the progress of the
	satellite and its change in footprint.

Alt-T	Resets the tracking date and time back to UTC, it also switches off the
	fast track mode if it is on. This is especially useful when you have
	been using F3-F10 to look at a satellites position at a different date
	and time and you wish to return to the present time.

Alt-E	This displays the updated Keplerian Elements that are used by the
	program to track the satellite. On the same screen, information is
	displayed about the SSP of the satellite. The Latitude and Longitude
	of the SSP are displayed along with the half angle of the satellites
	coverage.

Alt-S	List of DX locations. These are the locations in the DFILE. For each
        one, the program displays the satellites Azimuth, Elevation and Range.
        To move around this list use the Up/Down cursor keys, the PgUp and PgDn
        keys to move a "page" at a time. Home takes you to the top of the list,
        End takes you to the bottom of the list. Press Escape to remove the
        list. If the DFILE is missing, pressing F4 will have no effect.

Alt-D	Enters the data editor. This allows you to modify the Satellite
	Elements, import NASA two-line elements sets, export Satellites, edit
	the DX location data and the user data. This will be covered in a
	seperate section.

Alt-X	Exits the program. A window will appear to ask for confirmation of
	ending the program. A choice of Y or N is required, any other key is
	ignored. This is the recommended way to end the program. Alt-X resets
        the screen to text mode before finishing.

The following sections describe the features of the program in greater detail.


Changing the Date and Time (F3,F4,F5,F6,F7,F8,F9,F10,Alt-T)
-----------------------------------------------------------

If you want to see where the satellite is at some other date and time, you can
change the current Date and Time for tracking. Note, this does NOT alter the
internal clock in your PC. The available increments are one day, one hour,
fifteen minutes and one minute. These are available from the function keys F3
to F10. A full list is given above or by pressing F1 for the help screen. To
return the tracking time back to UTC, press Alt-T.


Fast Track (Alt-F,Alt-T)
------------------------

In addition to manually changing the tracking date and time, the program can be
put into fast track mode. In this mode the program does not track in real time,
but instead increments the time by one minute instead of by the time increment
that you set. This is especially useful with satellites in low Earth orbit
(LEO). This fast track mode is toggled on and off with the Alt-F key. Fast
track is also switched off and the time reset by pressing Alt-T or when
choosing a new satellite from the satellite list (F2).


Updated Keplerian Elements (Alt-E)
----------------------------------

This will bring up data about the satellite that is true at the moment that the
Alt-E key was pressed. It uses the updated Keplerian elements that are used
internally for calculating the position of the satellite. A typical display
will appear like this:

             Satellite Data

  Epoch Date    : 90217.460904
  SMA           : 7226.2467 kms
  Inclination   : 71.0012 deg
  RAAN          : 207.2314 deg
  Eccentricity  : 0.0016853
  Arg Of Perigee: 236.0180 deg
  Mean Anaomoly : 184.3219 deg
  Mean Motion   : 14.13303817 revs/day
  Decay Rate    : -1.990000E-006 revs/day/day
  Epoch Rev     : 1063
  Catalogue No  : 20625

  SSP Longitude : 243 deg
  SSP Latitude  : 55 deg
  Half Angle    : 28 deg


Most of the entries will be familiar to you from Keplerian elements published
in magazines. A few entries do require some explanation. SMA stands for
Semi-Major Axis and is a measure of the distance between the origin of the
orbit and one focus of the orbit. A much better explanation of SMA may be found
in The Satellite Experimenters Handbook by Martin Davidoff K2UBC.

The SSP Latitude and Longitude describe the position of a point on the surface
of the Earth that is on a direct line between the centre of the Earth and the
satellite. The Half Angle is a measure of the area on the Earth that is covered
by the satellite. A Half Angle of 90 degrees would indicate that half of the
Earth would be covered by the satellite. To convert the Half Angle into
distance multiply it by either 69.06 miles or by 111.2 kms. A Half Angle of 28
degrees gives a potential maximum QSO range of either 3867 miles or 6227 kms.

To remove this screen press Escape, this will return you to the main tracking
screen.


Show DX Locations (Alt-S)
-------------------------

The footprint can be very useful for determining who can see the satellite at
any given time, but sometimess you require more detailed information. The Alt-S
option gives you a list of locations along with the Azimuth and Elevation of
the satellite and the range.

As supplied the list contains most of the capital cities of the world and for
large countries such as the USA there are a number of major cities listed which
are distributed around the country. More locations can be added by the data
editor (see later).

  QTH               Az    El   Range

  Amsterdam         119   76   37131
  Anchorage           7    9   41921
  Ankara            305   77   37109
  Athens            341   81   37044
  .
  .
  .

The list can be scrolled up or down with either the up and down cursor keys or
by the PgUp and PgDn keys. The cursor keys only move one location at a time
whereas the PgUp and PgDn keys move a screenful of data at a time. To move to
the top of the list use the Home key and to move to the bottom of the list use
the End key. To remove the list press Escape.


Tabular Listings (Alt-L)
------------------------

There will be times when you want a text listing of the details of the
satellites position. This is obtained by pressing Alt-L at the main tracking
screen, a large window will appear and a list of satellite data will appear:

 Date      Time      Az   El   Range  Orbit   MA   Mode     Sq  SSP     HA
 05-08-90  10:22:19  179  -36  8665   2790    137           46  0/-26   27
 05-08-90  10:27:19  183  -46  10152  2790    150           39  5/-44   27
 05-08-90  10:32:19  187  -55  11408  2790    163           31  14/-61  27
 .
 .
 .

This data is essentially the data that appears on the bottom two lines of the
main tracking screen. The time increment used is set in the user section of 
the data editor (see later). The SSP column is the sub-satellite point
Longitude and Latitude, and the HA column is the half angle. These were
described in more detail in another section.

This list is capable of being moved both forward and back in time by use of the
up and down cursor keys and the PgUp and PgDn keys. The up and down cursor keys
move the list one entry at a time, the PgUp and PgDn keys move a screenfull at
a time. To remove this screen press Escape, this returns you to the main
tracking screen.


The Data Editor (Alt-D)
-----------------------

The Microtrack data editor is invoked with Alt-D from the main tracking screen.
Its purpose is to allow users to alter, add and update satellite data, DX
location data and user data. When you access the data editor, a menu panel will
appear with the following options:

		  Add Satellite
		 Alter Satellite
		 Remove Satellite
		Update Satellites
		Export Satellites
		 Add DX Location
		Alter DX Location
		Remove DX Location
		 Alter User Data

You select an option by using the up and down cursor keys and pressing Enter on
the required option. If you do not want to choose an option, press Escape to
return you to the main tracking screen.

Before describing each of the options in detail, a few points about using the
data editor which are relevant on the panels. In the Add and Alter options you
will presented with a list of parameters that need values, to move around one
of these panels, the following keys are used:

Cursor Up    - Up one line, unless you are on the top line.
Cursor Down  - Down one line, unless you are on the bottom line.
Cursor Left  - Back one character, go to previous line if at the beginning of
	       the present one.
Cursor Right - Forward one character, go to next line if at end of present
	       line.
Enter        - Down one line, cursor also move to leftmost position.
Tab          - Same as Enter.
Backspace    - Same as Cursor Left.


Add Satellite
-------------

With this option you are given a blank satellite entry screen from where you
can specify the details of a new satellite.


          Add Satellite

  Sat Name      :
  Catalogue No  :
  Epoch Date    :
  Inclination   :
  RAAN          :
  Eccentricity  :
  Arg Of Perigee:
  Mean Anomoly  :
  Mean Motion   :
  Decay Rate    :
  Epoch Orbit   :
  Alon          :
  Alat          :
  Mode List     :
                :
                :


I do not intend to explain Keplerian elements in any depth. Suffice to say that
if your Keplerian elements are correct then they can be typed in and the
program will update its files accordingly. The program does do simple
validation checks on the data entered to ensure that they are reasonable
values, if any entry fails, the program will not save the data and a little
arrow will appear at the side of the incorrect entry.

A couple of the fields need explanation. The Catalogue No entry may be filled
in as 0 if you are not sure of the catalogue number. Alon and Alat are for
information regarding the attitude in space for spin stabilised satellites such
as OSCAR-10 and OSCAR-13. If you are unsure about these values leave these
entries as blanks. The Mode List is where you specify the mode of operation of
the satellite in terms of either MA units or in days of the week. An example of
both is given below. If you are ensure leave this entry as blank.

MA Units:-

Mode List   : 000:OFF 103:B 165:JL
            :  190:LS 195:S 200:BS
            :  205:B 240:OFF

Days of the Week:-

Mode List   : Sun:JD Mon:JA Tue:JA
            : D Wed:OFF Thu:JAD Fr
            : i:JD Sat:JAD

To save the data press Insert, providing no errors are encountered your data
will be saved and you will be returned to the Data Editor main menu. If there
are errors then the data will not be saved and an arrow will appear at the side
of the incorrect entry. If you wish to cancel what you have done, press Escape.


Alter Satellite
---------------

Altering a satellite is very similar to adding a satellite. When you choose
this option you will be given the satellite list to choose an existing
satellite from. Once you have chosen a satellite you will get the same panel as
for adding a satellite except the entries will be filled with the values that
are held on the file for that satellite. You can then alter the required
fields.  The same procedures apply as for adding a satellite.

If you alter the currently tracked satellite, the changes will not take effect
until you choose the F2 option from the main screen and reselect the satellite.


Remove Satellite
----------------

This option allows you to remove a satellite from the files one at a time. When
you choose this option you get the satellite list come up for you to choose a
satellite to remove. Once you have chosen a satellite, you will be given the
option to delete the satellite. The program expects either a Y or an N,
anything else is ignored. After deleting the satellite, or after entering N you
will be returned to the Data Editor main menu.


Update Satellites
-----------------

You use this option when you have access to NASA two-line element sets. They
are available on packet radio in Britain. This option allows you to update the 
Keplerian elements directly from the element sets. It is clever enough to be
able to handle two-line sets interspersed with packet radio mail headers so you
are able to use the download from packet radio directly without editing.

To use this option, you must enter the name, and optionally the path, of the
file which hold the element sets. The program will then update its internal
tables and the files using the following rules:
1) If the Catalogue Numbers match then update the Keplerian Element.
2) If the Microtrack Catalogue Number is zero then compare the Satellite name,
   if they match then update the Keplerian Element.
3) If the satellite in the NASA set is not in the Microtrack tables, it is
   inserted.

At the end of the updating process a report briefly appears to indicate how
many satellites have been updated and how many satellites have been inserted.


Export Satellites
-----------------

This option is useful if you require a print out of the Keplerian Elements that
are held within Microtrack. It generates a file which contains entries for each
satellite in the program in the following form:

Sat_Name = FO-20
Catalogue_No = 20480
Epoch_Year = 90
Epoch_Day  = 110.078373
Inclination = 99.046900
RAAN = 167.545700
Eccentricity = 0.054161
Arg_Of_Perigee = 180.082100
Mean_Anomoly = 180.027200
Mean_Motion = 12.831275
Epoch_Orbit = 929
Drag = 1.070000e-006
Mode = Sun:JD Mon:JA Tue:JAD Wed:OFF Thu:JAD Fri:JA Sat:JD

Where Alon, Alat and Mode are not given, then no lines will be printed for
those parameters. The satellite data is in a form that can be easily parsed by
a program for other uses.

If you start the program with the command:

OSCAR filename

then Microtrack will load its satellite data from "filename" using the above
format INSTEAD of getting its data from the normal SFILE which uses Microtracks
internal format.


Adding DX Locations
-------------------

If you want to add another location for use in the "Show DX Locations" option
then use this option. You will be presented with an empty input screen like
this:

      Add DX Location

  Location :
  Latitude :
  Longitude:
  Height   :


The location is the name that is shown in the DX Location list, these names are
sorted internally into alphabetical order. The Latitude is in degrees North,
locations in the southern hemisphere should enter Latitude as a negative value.
The Longitude is in degrees West, locations East of Greenwich should either
enter the Longitude as a negative value, or enter them in degrees West. Either
way, the program internally converts them into degrees West. The height should
be in Metres above sea level.

To save the data press Insert, providing no errors are encountered your data
will be saved and you will be returned to the Data Editor main menu. If there
are errors then the data will not be saved and an arrow will appear at the side
of the incorrect entry. If you wish to cancel what you have done, press Escape.


Editing DX Locations
--------------------

Editing a DX Location is very similar to inserting a DX Location above. The
difference being that before the DX Location entry panel you have to choose the
required DX Location from a list, once you have done this the panel will appear
with the location data already in place for you to edit. After deleting the DX
Location, or after pressing N you will be returned to the Data Editor main
menu.


Removing DX Locations
---------------------

This option allows you to delete one DX Location at a time. You are given a
list of DX Locations from which you choose one. You will then be prompted to
give a Y or N response to wether you want to delete the DX Location. Anything
other that a Y or an N will be ignored.


Editing User Information
------------------------

This is where changes to data about your QTH and your program preferences are
entered. A typical entry will appear like this.

        Edit User Data

  Callsign  : G4KLX
  Latitude  : 53.05
  Longitude : 1.55
  Height    : 140
  UTC Offset: -1
  Track Step: 5
  List Step : 5

At present the callsign is not used, but in future versions it may become
important. The Latitude is in degrees North, stations in the southern
hemisphere must enter there Latitudes as negative values. The Longitude is in
degrees West of Greenwich. A station East of Greenwich may either enter there
Longitude as (say) -1 or as 359. The program internally converts the Longitude
into degrees West.

The Height is in Metres ASL. The UTC Offset is used in the program to allow for
the difference between local time and UTC. If you have the clock in your PC on
UTC then you can enter a 0 for this value. Only whole numbers of hours are
allowed here.

Track Step is the time increment in seconds between calculations in the real
time section of the program ie the map with the footprint. It also has some
bearing on the speed of the fast track option. The List Step is the time
increment in minutes between lines in the tabular listing section of the
program.

As before, press Insert to save the data, and Escape to cancel. A quick check
is made on the data and any entries which are invalid have an arrow shown at
the side of them. The changes you make to the user information, do not take
effect until you leave Microtrack and restart the program.


Exiting Microtrack (Alt-X)
--------------------------

The program gives you the option of changing your mind about exiting when you
press Alt-X. A window appears asking you to confirm your decision with a Y or N
response. A Y will terminate the program, an N will return you to the main
tracking screen as if nothing had happened, any other key is ignored.


Limitations
-----------

Although I have tried to make this program as flexible as possible, there are
some limitations that I have had to introduce to simplify the programming,
others are externally imposed. One of the most obvious limitations is the map
used by Microtrack. The map has a cut off at eighty degrees North and at eighty
degrees South, this is especially obvious when a satellite passes near a pole,
the satellite itself will disappear but the outline of its footprint should
still be visible on the remaining part of the map.

There is a limitation on the length of the mode name to four characters. This
length covers all of the available modes on current amateur satellites without
ambiguity. 


Future Developments
-------------------

The development of this program is continuing. Features are added as and when I
feel they are needed. If you can see an area of the program that is lacking, or
a completely new feature that you would like to see, then please contact me. I
have plans in hand for adding a context sensitive help system for the program.
The reasons for this are purely selfish, to enable me to get away with as small
a READ.ME file as possible !

For the programmers out there, the program is written entirely in the C
programming language. It was compliled with full optimisation and a large
memory model with Microsoft C 5.1 and prototyped in Quick C 1.01. I use the
standard Microsoft graphics libraries which I eventually hope to replace with
my own. At present the program has the libraries for other graphics adapters
included which adds to the program size. First I have to find a good book about
Hercules graphics !


Conclusion
----------

I hope you find this program useful. I have done my best to test the program
and to try and induce faults, I have failed, so far at least. If you have
comments, faults, praise etc, drop me an email.

Jonathan Naylor  HB9/G4KLX  <g4klx@g4klx.demon.co.uk>