xsatcom User Manual

  1. Introduction
  2. Features
  3. Compilation and Installation
  4. Operation
  5. Multi-Satellite/Single-Observer Mode
  6. Single-Satellite/Multi-Observer Mode
  7. Pass Predictions Mode
  8. Illumination Predictions Mode
  9. Manual Commands Mode
  10. Offset Calibration Mode
  11. Full-scale Calibration Mode
  12. Error Messages
  13. Known Bugs
  14. Version History
  15. Acknowledgments

1. Introduction
xsatcom is an X/GTK+-3 based satellite communications application for the console. Satellite position and velocity are calculated using the NORAD SGP4 model for near-earth and SDP4 for deep-space orbits. Other satellite parameters like Azimuth, Elevation, Slant Range, Range Rate, Latitude, Longitude, Altitude, Footprint, Solar Illumination, AOS/LOS time etc are also calculated, using routines mainly ported from Dr. T. S. Kelso's sgp4-plb26a Pascal library and from the 'predict' and 'trk' open-source satellite tracking applications. As a secondary feature, the position of the Moon and Sun are also calculated.

xsatcom has a built-in serial port driver for the Yaesu GS-232 controller of the G-5500 Az/El rotors enabling automatic tracking of antennas, as well as a serial port driver for the Yaesu FT-847 'Earth Station' and Elecraft K2 or K3 transceivers, providing CAT control of Tx/Rx frequencies including independent Tx/Rx Doppler compensation, Tx/Rx frequency tracking and Tx/Rx mode matching.

2. Features

User Interface
xsatcom is an interactive GTK+-3 application and all main "Modes" of operation use GTK+ windows to present data while most of the important functions are activated by buttons. Some buttons are single-action (e.g. trigger some function or new Mode), and others are toggle types (e.g. activate-deactivate some function or enable-disable a feature). Some auxiliary functions like data entry are carried out in pop-up windows opened from a main menu.

Database Operation
xsatcom needs four files in its ~/.xsatcom directory in order to run:

Once these files are properly set up, xsatcom enables the user to choose the satellite to be tracked either from a menu-like tree view or by clicking on appropriate buttons in most "Mode" windows. Whenever a satellite is chosen and antenna tracking and CAT control are enabled, xsatcom will automatically point antennas to the satellite by sending Az/El position commands to the GS-232 rotor controller and will setup the required Tx/Rx frequencies and modes on the FT-847 via the serial port CAT facility. This makes it very easy to select a satellite of interest and prepare for communication through its chosen transponder.

The observer database allows the user to easily select the current observer location so that satellite orbital data can be calculated for different observers, enabling footprint overlap predictions for QSO scheduling. New observers can be entered on the fly by specifying the Maidenhead QTH locator or Latitude/Longitude and can be saved into the observer database file.

NORAD orbital models
xsatcom uses the NORAD SGP4 orbital model for near-earth satellites and the SDP4 orbital model for deep-space satellites. The original FORTRAN routines in NORAD's Spacetrack report #3 have been ported to C and they are used in conjunction with routines ported to C from Dr. T. S. Kelso's sgp4-plb26a Pascal library to calculate various orbital and tracking parameters. Some routines from Lapo Pieri's "trk" and J. Magliacane's "predict" trackers have been adopted to calculate the position of the moon and the accessibility of satellites.

Variety of displayed information
xsatcom calculates a lot of information about the selected satellite and displays it in appropriate windows selected by clicking on buttons in the main window which appears at start-up. The various functions and displays provided, are grouped in "Modes" of operation of xsatcom so that it can be used for specific purposes.

Ham Radio support
xsatcom has built-in support for the Yaesu G-5500 Az/El rotors via the GS-232 controller and CAT control for the Yaesu FT-847 and Elecraft K2 or K3 transceivers, enabling easy operation on the various satellites available to the ham radio community. xsatcom permits automatic tracking of satellites by pointing antennas at the calculated position (Az/El) of the selected satellite with a maximum resolution of 1 deg, although backlash and other errors can be expected to reduce accuracy to a lower level. Manual control of the rotors is also provided with the "Position Rotors" menu item. 'Parking' of the rotors in a predefined (in the ~/.xsatcom/xsatcomrc file) position is also available as a menu item.

xsatcom has built-in CAT control for the Yaesu FT-847 'Earth Station' transceiver's Tx and Rx frequencies and modes, providing automatic Doppler shift compensation and smart Tx/Rx frequency and mode tracking, enabling easy tuning and netting in the satellite's transponder. Transponder mode and uplink/downlink/beacon frequencies are selected by the "Mode" button in the "Transceiver CAT Control" frame from predefined entries in the xsatcom.sat file. The transceiver's Tx/Rx frequencies and modes are calculated taking into account Rx converters or transverters and any errors in the vfo or satellite transponder local oscillators.

Grid Locator calculator
xsatcom has a Maidenhead Grid Locator calculator which enables the calculation of a grid locator from the Longitude and Latitude of a position or vice-versa. The Grid Locator calculator allows quick on-the-fly entry of a new observer for the prediction of satellite position at a remote site for QSO scheduling. It also makes it possible to specify observers in the xsatcom.obs file with just the QTH locator if exact position is not known.

3. Compilation and Installation

Please note that I use Void Linux which is a "bleeding edge" type distribution, so there may be compilation and/or run time difficulties if you are using a relatively old distro. This is mostly true of the basic dependencies like GTK+-3.

To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.

Running "make" in the package's top directory should produce the executable binary in src/. Running "make install" will install the xsatcom binary and the get_tle.sh script into /usr/local/bin by default or under the specified prefix. It will also install the .xsatcom working directory and default configuration file into the user's home directory. This will have to be edited by the user as required. There is also this hypertext documentation file which you can copy to a location of your choice.

4. Operation
Run time files
Before xsatcom can be started, there must be four files with valid entries in the .xsatcom directory, which itself must be in your "home" directory.

The first file is xsatcomrc, the run time config file of xsatcom. It has entries specifying the following data:
The first two entries specify the serial port to which the Yaesu GS-232 computer controller for the G-5500 rotors and the transceiver CAT port are connected. If you do not intend to use these ham radio equipment, you may leave these entries unedited and provided you do not activate rotor control and CAT control, there will be no problems. Otherwise xsatcom will exit with an error message if it cannot open the specified serial port device files.

The next three entries specify the tracking resolution of the G-5500 rotors. The G-5500 Az/El rotors working with the GS-232 controller have a resolution of 1 deg as set up for use with xsatcom. This is too fine for tracking fast, low orbit satellites and probably much more than needed for an average VHF/UHF antenna. xsatcom uses three preset resolutions for tracking different objects: Low resolution for fast, low orbit satellites, medium resolution for slow, high orbit satellites and high resolution for manual position commands and for tracking the moon and sun. These constants have default values of 5, 2 and 1 degrees respectively. These can be customized to suit individual requirements depending on antenna directivity, but please remember that the maximum position error for a given resolution is +- half the resolution so low resolution implies a max error of +- 2.5 deg etc.

The next two entries specify the default "parking" position for the rotors. These can be customized to some other value if needed in the range 0-360 and 0-180 for Az/El respectively. These entries are used by the "Park Rotors" menu item to manually position the rotors when not in use.

The next entry specifies an azimuth offset value needed when the G-5500 rotors are used with the GS-232 controller, because the voltages returned by the position transducers in these rotors are in a range that is not directly compatible with the ADC the GS-232 controller. (The latter was originally designed to be used with other types of antenna rotors like the G-5400, G5600 or G-500). If you intend to use one of these Az/El rotors then this offset should be 0. More details in the Offset and Full-scale calibration procedures.

The next three entries affect the way xsatcom carries out a search for the next AOS or LOS time and horizon crossings of a satellite:
The angle step entry is the Azimuth or Elevation step used when searching for a horizon crossing which is done by a "hunt-and-peck" process. The default value of 2 deg. seems sufficient for detecting most passes but some very low "grazing" passes can be missed or the AOS and LOS times can be incorrectly calculated producing meaningless pass predictions. Reducing the value of this constant can improve the situation but it makes pass predictions more time-consuming.
The time step constant is the step in minutes for carrying out a "hunt-and-peck" search for the next AOS or LOS time of a satellite. The default value of 2 seems satisfactory but short "grazing" passes may be missed if the search process jumps over the pass period. Reducing the value of this constant can improve the situation but it makes pass predictions more time-consuming.

The Horizon entry is the threshold of Elevation below which a satellite is considered to have crossed the horizon. The default value is 0.03 degrees and seems satisfactory.

The second file is xsatcom.obs and should have at least one entry with the default observer's location. Details on the required data and format of this file are provided as comments in the file itself.

The third file is xsatcom.sat and it should contain at least one valid entry regarding a satellite of interest. Again details on the required data and format of this file are provided as comments in the file itself.

Finally the xsatcom.tle file should contain Keplerian elements for at least the satellites that are specified in xsatcom.sat and in the NASA Two Line Elements (TLE) format. Nothing else may be present in this file, e.g. no comments, blank lines etc as xsatcom carries out a strict validation of the TLE data and it will exit with an error message if anything is out of line. A good site for Keplerian elements is Dr T.S. Kelso's site CelesTrak and also AMSAT.

get_tle.sh is a very simple Bash script for downloading and concatenating some Keplerian files into xsatcom.tle from CelesTrak. It is included (in xsatcom/other directory) only as an aid to quick refreshing of the TLE database and will need to be edited if it will be used to download different Keplerian files. This script can be invoked by activating the "Download TLE" menu entry in the xsatcom main pop-up menu, which is opened by right-clicking on an empty part of xsatcom's main (Single-Satellite/Single-Observer) window.

Single-Satellite/Single-Observer Mode
This is the default Mode at start-up. A selected satellite's orbital data is calculated for one location and if desired the Yaesu G-5500 Az/El rotors can be commanded to track the satellite and/or the FT847 transceiver can be controlled via CAT. To start/stop xsatcom click on the Start toggle button in the left of the first row of buttons near the bottom of this window.

The following location information is calculated and displayed (at default 1 sec intervals):
Location name, Longitude East, Latitude North, Altitude asl.
Local date and time, UTC date and time.
Sun's Azimuth/Elevation, Moon's range, Azimuth and Elevation.

The following satellite information is calculated and displayed (at 1 sec intervals):
Satellite name, Azimuth (deg East), Longitude (deg East).
Tracking Model (NORAD SGP4|SDP4), Elevation (deg North), Latitude (deg North).
Next AOS in UTC date/time, Slant Range in km, Altitude in km.
Next LOS in UTC date/time, Orbital Phase in units per 256, Footprint in km.
Satellite visibility, Doppler shift in Hz/MHz, Revolution number.

Rotor control for Yaesu GS-232/G-5500
Please note: Before the GS-232/G-5500 controller/rotor combination is used for Aerial tracking or other activity, the Offset and Full Scale Calibration procedures must be followed to prepare and calibrate rotor control.

If a GS-232/G-5500 Az/El rotor system is available and connected to a serial port, the "Enable Rotors" button activates satellite tracking and the Rotor Control frame displays the following information: The "Enable Rotors" button's label displays "Rotors Running" in red while one or both rotors are running towards the requested position. When both rotors stop, either "Normal Tracking" in green or "Reverse Tracking" in blue is displayed (this is explained further down). The Azimuth and Elevation demand sent to the GS-232 controller and the Actual position of the Azimuth and Elevation rotors are shown in the entry widgets while a rotor is running. When a rotor reaches the required position, then "Stop" is shown in place of the Demand value but if for some reason data cannot be read from the GS-232 (serial port problem or power off) then "!Data" is shown in red in place of the Actual position and the button displays "SERIAL FAIL!" in red.

Satellite tracking through rotor control is enabled by the "Enable Rotors" button, which has a toggle type action, e.g. enables/disables this function alternately. The position demand in degrees of Azimuth and Elevation is sent by xsatcom to the GS-232 rotor controller via the serial port and it is derived from the satellite Azim/Elev as follows: Depending on the object tracked, the tracking resolution used is selected from one of the three values specified in ~/.xsatcom/xsatcomrc and the defaults are 5 deg for near-earth, 2 deg for deep space orbits and 1 deg for the sun and moon. The object's Azimuth and Elevation are rounded to the nearest (integer) multiple of the resolution and are used as the demand for the rotor position. Thus the maximum error in position demand is half the resolution in use which is 2.5 deg for the lowest resolution. Of course there are other factors like backlash, alignment errors etc that affect the error in the actual position of the rotors and the antennas attached to them.

Since the azimuth rotor is effectively limited in the range 0-360 degrees, if the satellite crosses the location's North direction there will be an abrupt change in Azimuth of about 360 deg, necessitating a near full turn of the Azimuth rotor. To avoid this problem, xsatcom detects North crossing orbits when calculating AOS/LOS and sets a North crossing flag which then instructs the rotor control function to do a "reverse track" by changing Azimuth demand to 360 - Azimuth and Elevation demand to 180 - Elevation. This will then avoid the North-crossing "stumbling" point and the time delay for a ~360 Azimuth rotation. Reverse tracking is indicated by "Reverse Tracking" in blue.

To avoid repeated transmission of position demands to the GS-232 controller, which result in momentary operation of the relays supplying power to the rotors, the rotor control function waits for the rotors to reach the requested position first, before sending another command. This may result in a delay in updating the position demand if one of the rotors is running when a new rotor position is required, as may happen when a low-orbit satellite passes nearly overhead resulting in fast-changing azimuth position.

CAT control of the Yaesu FT-847
Please note: Before CAT control can be operational, the FT-847 serial port speed must be set to 57600 baud using the CAT RATE menu item (menu 37). This highest speed rating is needed to avoid unacceptable slowing of xsatcom.

If a Yaesu FT-847 is in use for communication via amateur radio satellites then xsatcom can provide CAT control of the transmitter and receiver frequencies including Doppler shift correction, Tx/Rx frequency/mode tracking and S-meter and Power-output/ALC indications. CAT control is activated by the "Enable CAT" button in the "Transmitter Status" frame which toggles CAT control on/off. This frame displays the following information:

In the left half of the frame, the Receiver and Downlink status are shown:
Receiver frequency, Receiver mode and the Doppler shift correction required to receive the Downlink frequency as transmitted by the satellite.
The Downlink frequency as output by the satellite, S-meter reading and path loss in db.
The Receiver's S-meter indication is also shown as a simple bar graph.

In the right half of the window, the Transmitter and Uplink status are shown:
Transmitter mode, Transmitter frequency and the Doppler shift correction required so that the signal frequency arriving at the satellite is the required Uplink frequency.
The Uplink frequency arriving at the satellite, the PO or ALC reading and the path loss in db.
The transmitter's PO/ALC indication is also shown as a simple bar graph.

The "Change Mode" button toggles circularly between the available transponder modes as entered in the xsatcom.sat file. The current mode is shown in the button's label but if a mode is not specified for a particular satellite (e.g. no transponder/beacon data) then 'No Mode' is shown instead. If there is a failure in serial port transmission or the transceiver is not powered, then 'SERIAL FAIL!' is shown in red color. This normally requires toggling CAT control off/on by clicking the "Enable CAT" button, since this fault condition normally occurs when the transceiver is not powered on when CAT is enabled, thereby missing the CAT ON command which is issued only when CAT is enabled.

The "Tx/Rx Track" toggle button enables frequency and mode tracking between transmitter and receiver. Tx/Rx tracking provides a very convenient way of tuning across the satellite pass-band, especially when Doppler shift changes quickly. Both Tx and Rx frequencies are Doppler-shift corrected independently and they are set so that the Transmitter is always netted accurately with the Receiver, ready to transmit to a station that has been tuned in.

Initially Tx and Rx frequencies are read from the xsatcom.sat file when CAT is enabled and if data in this file is correct, then Tx and Rx will already be tracked but of course if the Rx or Tx is tuned manually then tracking is lost. To recover and maintain tracking toggle "TxRx Track" On. Due to limitations in the software though, before xsatcom tracks the Tx and Rx frequencies one of the two must be changed manually to signal the tracking function. After this any change in either the Tx or Rx frequency will result in the other being changed to maintain tracking, including any changes to the VFO frequency resulting from a change in operating mode. And please note that when tracking is enabled, xsatcom will also match Tx/Rx operating modes if there is a manual change by the user. If the transponder pass-band is inverting, xsatcom will match USB on Rx with LSB on Tx and vice-versa, otherwise both Tx and Rx will have the same mode. For all other modes (CW, FM etc) the Tx and Rx will be tracked to the same mode regardless of pass-band characteristics since invert/normal operation is irrelevant. This makes tuning and mode change very easy even on low-orbit fast moving satellites.

Accurate Tx/Rx tracking depends on a number of factors like frequency stability in the satellite transponder and the transceiver, accurate Doppler shift calculation and accurate information in the xsatcom.sat file. If for any reason tracking does not seem accurate enough, then it is possible to correct errors using the "Net/Track" button to update tracking. To do this, first tracking must be disabled and then after tuning in the Rx accurately to the downlink frequency produced by the Tx, tracking must be re-enabled with the "Net/Track" button. This will signal xsatcom to maintain the current relationship between Tx and Rx frequencies for the duration of CAT control or until another update is done. The "Doppler" button enables/disables Doppler shift compensation.

Other commands in this Mode
The following buttons activate other Modes

"Multi Satellite": Enables Multi Satellite tracking and opens its relevant window.
"Pass Predictions": Enables the Pass Prediction Mode and opens its window.
"Multi Location": Enables the Multi-Location mode and opens its window.
"Illumination Predict": Enable the Illumination Predictions mode and opens its window.
"Xplanet Plot": Enables plotting of the current satellite's position and footprint on a map of the earth, in a separate window using the "xplanet" program. The xplanet command line options are now included in the ~/.xsatcom/xsatcomrc file.
"Multisat Plot": Plots all the satellites in ~/.xsatcom/xsatcom.sat file on a map of the earth, in a separate window using the "xplanet" program.
The two frames in the bottom of this mode's window have buttons for navigating the satellite and observer databases, going up or down to the next entry or to the first or last

Multi-Satellite/Single-Observer Mode
In this Mode xsatcom displays a summary of all satellites in the xsatcom.sat file together with a summary of the currently selected satellite's and observer's status. At the bottom of this window, the frame on the left has buttons for selecting other Modes and the one on the right buttons for navigating the observer database.

All-satellites tree view
A summary of all satellites in the xsatcom.sat file is listed in a tree view and the information shown is Accessibility, Satellite Name, Azimuth/Elevation in degrees, Range in km, Phase and UTC date/time of next AOS and next LOS.

The satellites are sorted in the following order:
Accessible (above the horizon) satellites first, indicated by a tick in the AOS check box and ranked according to furthest LOS. (geostationaries are listed last).
Inaccessible (below the horizon satellites), indicated by a blank AOS check box and ranked according to nearest AOS. Therefore an accessible satellite with the furthest LOS is ranked first and an inaccessible satellite with the furthest AOS last. If a satellite is never accessible, then 'No AOS/LOS' is shown instead.
This ranking is carried out by considering all satellites in the database and when the display is scrolled, the order does not change.

The summary listing of all available satellites can be used as a convenient menu-like selector of the current satellite. Clicking on an entry in the tree view selects that satellite as the current (in use) satellite and closes the Multi Satellite mode window. If there are enough satellites in the tree view to fill it, a scroll bar appears but since the display is updated regularly, scrolling down does not work because the redraw moves the scroll bar to home position. Please use the "Freeze" toggle button to stop updating so that you can browse the tree list and select a satellite.

Single-Satellite/Multi-Observer Mode
In this Mode xsatcom displays a summary of information on the currently selected satellite as observed from all locations in the xsatcom.obs file. Information is displayed in an expandable tree view which can act as a menu to select the current (in use) observer location by clicking on a tree view entry. Tracking and location data can be seen by expanding the entry with a click on the little arrow at the start of the line. The following information is displayed for the location:
Location Name, Grid Locator, Longitude East, Latitude North, Altitude in mtr.
UTC Date and Time, sun Azim/Elev, moon Azim/Elev.
Satellite Name, Azimuth, Elevation, Range in km.
For the current location:
Next AOS, next LOS, Longitude East, Latitude North, Altitude in km.
For other ('remote') locations:
Next AOS, next LOS, Footprint overlap with the "current" location, in UTC Date/Time.

Manual Location Entry
It is possible to enter a new location in the tree view by using the "New Location" item in the main pop-up menu. This will open a small window with a form for entering new location data which can be saved permanently with the "Save" button. The "Apply" button enters the new location data into the tree view for the current session only. In both cases the new location appears at the end of the tree view list.

Pass Predictions Mode
In this Mode xsatcom displays a simple graphical display of pass predictions for the currently selected satellite. At the top of the window summary information on the current location and satellite is shown, while in the middle there is a simple graphical display of Elevation and Azimuth over time. The display covers the following situations:

Accessible Pass predictions
This is the default display at start up and it shows the UTC date and time, the satellite's Elevation in deg. and a simple plot of this, the satellite's Azimuth and a simple plot of this, the Phase in units/256 and the satellite's Longitude East and Latitude North in deg. If the satellite is in range, the display is updated in real time so the plots show the progress of the satellite in the sky until it goes below the horizon, when a plot of the next accessible pass is shown. If the satellite is not accessible when this Mode is entered then the next accessible pass is plotted.

Using the "Forward" button the display can be moved forward in time to the next accessible pass. The "Redo" button resets the display to the next AOS. Unfortunately there is no command for back-tracking pass predictions in time as this was rather awkward to implement, so it is necessary to use "Redo" to restart the search and then go forward again to find a pass prediction that was missed. Accessible pass predictions for Elevation are plotted with a green and for Azimuth with a blue point.

Visible Pass predictions
The "Visible" button changes this Mode to the display of visible pass predictions, e.g. passes during which the satellite can be seen either with a naked eye or a telescope if the brightness is too low. The predictions are done using solar illumination of the satellite and local darkness as criteria, so that "seeing" (e.g. weather) conditions are not taken into account. This Mode is useful for visual observation of satellites and searches for visible passes can be made as for accessible passes.
Visible pass predictions for Elevation are plotted with a cyan point when the satellite is in visible, a blue point when the satellite is eclipsed and for Azimuth with a yellow.

Illumination Predictions Mode
In this Mode xsatcom plots a graph of satellite illumination predictions for a period of 30 days as a percentage, starting from the current date and time at start-up. Predictions for the next or previous 30 days can be requested with the "Forward" and "Backward" buttons while the "Redo" button resets the predictions to real time.

Manual Commands
The main pop-up menu has items for carrying out some operations (semi) manually: The antenna rotor can be commanded to rotate to a desired Azimuth/Elevation combination or to move to a "parking" position as specified in the ~/.xsatcom/xsatcomrc file. The polar star can also be tracked a s a reference to the mechanical set-up of the rotors and antennas.

Manual Rotor Control
The "Position Rotors" pop-up menu item is used to command the rotors to the required position. Just enter azimuth and elevation and click "Apply" to send the command or "OK" to send the command and close the window. Blank entry fields are interpreted as zero valued.

Tracking the Moon and Sun
The "Track Moon" and "Track Sun" menu items enable tracking of the moon and sun respectively. Tracking in this Mode is done with the high resolution specified in the ~/.xsatcom/xsatcomrc file and the default value is 1 degree. Moon tracking is useful for EME communications and for testing rotor positioning accuracy. Tracking the sun is useful for testing receiving equipment for sensitivity by measuring solar noise etc. Tracking is disabled by clicking the toggle button in the "Rotor Control" frame.

Offset Calibration Mode
In this Mode xsatcom displays a simple graphical aid to adjusting the Azimuth and Elevation Offset null controls in the Yaesu GS-232 computer controller. You can refer to the GS-232 manual for some information on this subject, although it is meant for a simpler, lower level approach.

To carry out the Offset Calibration procedure, the GS-232, G-5500 Dual Controller and the Azimuth/Elevation rotors must be connected together as per the user Manual and the GS-232 must be connected to the computer's appropriate serial port as specified in ~/.xsatcom/xsatcomrc. Clicking on the "Offset Calibration" menu item will open a simple graphical aid to this calibration procedure, with a horizontal slider display for the Azimuth and Elevation Offset.

To perform this calibration, first position both rotors at the 0 degrees mechanical position using the manual controls on the G-5500 Controller. DO NOT rely on the analogue meters for this, as they are not accurate enough even when calibrated. If available, use the markers on the rotor cases which normally line up at the 0 deg position otherwise the counter-clockwise mechanical stop can be used as a 0 deg reference. You can then remove the covers from the GS-232 and adjust the trimmers marked AZ and EL until the slider is centralized. Usually there is a +- 1 count ambiguity in the ADC's that measure rotor position so the slider may play one division left or right. When finished, reset the GS-232 by switching off and on to get it out of the Offset calibration Mode and to return xsatcom to the Main screen.

Full-Scale Calibration Mode
In this Mode xsatcom displays a simple graphical aid to adjusting the Azimuth and Elevation Full-scale controls in the Yaesu G-5500 rotor controller. You can refer to the GS-232 manual for some information on this subject, although it is meant for a simpler, lower level approach and it does not apply to the GS-232/G-5500 combination. Please read on for the proper procedure that makes this calibration compatible with xsatcom.

To carry out the Full-scale Calibration procedure, the GS-232, G-5500 Dual Controller and the Azimuth/Elevation rotors must be connected together as per the user Manual and the GS-232 must be connected to the computer's appropriate serial port as specified in ~/.xsatcom/xsatcomrc. Clicking on the "Fullscale Calibration" menu item will open a simple graphical aid to this calibration procedure, with a horizontal slider display for the Azimuth and Elevation Full-Scale offset.

To perform this calibration, first position both rotors at the 0 degrees mechanical position using the manual controls on the G-5500 Controller. DO NOT rely on the analogue meters for this, as they are not accurate enough even when calibrated. If available, use the markers on the rotor cases which normally line up at the 0 deg position otherwise the counter-clockwise mechanical stop can be used as a 0 deg reference. If there are no markers on the Azimuth rotor case, mark the 0 deg reference position with opposing lines on the fixed and moving parts of the rotor using a marker pen. Then use the manual control on the G-5500 to position the Azimuth rotor at 360 deg by re-aligning the markers on the case. The Elevation rotor must be positioned at 180 deg and normally there are markers on the case that can be used for this operation. Then you can adjust the OUTPUT VOLTAGE ADJUST controls on the rear of the G-5500 Controller until the slider is centralized. Usually there is a +- 1 count ambiguity in the ADC's that measure rotor position so the slider may play one division left or right. When finished, reset the GS-232 by switching off and on to get it out of the Full-scale calibration Mode and to return xsatcom to the Main screen.

The Download TLE menu item can be used to start the simple shell script "get_tle.sh" that will download TLE sets from Dr Kelso's website and install them in ~/.xsatcom. This script is in the other/ directory and it should be installed in /usr/local/bin (or /usr/bin) and given execute permission.

Error Messages
Some (fatal) error messages may printed by the system if operations like opening serial port device files or run-time files fail. These will normally appear only if the <~/.xsatcom/xsatcomrc file is not properly customized or if run time files are missing or misnamed.

The following messages are printed by xsatcom before exiting, after receiving the relevant signal from the kernel:
"xsatcom: Exiting via User Interrupt"
"xsatcom: Segmentation Fault"
"xsatcom: Floating Point Exception"
"xsatcom: Abort Signal received"
"xsatcom: Termination Request received"

The following messages are printed when the xsatcom.tle file cannot be read for some reason, when the number of lines in xsatcom.tle is not a multiple of three and when the TLE data for a satellite do not pass the verification tests.
"xsatcom: Error reading ~/.xsatcom/xsatcom.tle file - exiting"
"xsatcom: Incorrect number of lines in ~/.xsatcom/xsatcom.tle file - exiting"
"xsatcom: Invalid TLE set in ~/.xsatcom/xsatcom.tle - exiting"

The following messages are printed when the xsatcom.obs file cannot be read for some reason, when no observer location name can be found in xsatcom.obs, when the observer location data is incomplete or invalid and when the observer's position data (Longitude/Latitude) do not compare with the Grid Locator specified.
"xsatcom: Error reading ~/.xsatcom/xsatcom.obs file - exiting"
"xsatcom: No valid observer location name found - exiting"
"xsatcom: Invalid observer location data - exiting"
"xsatcom: Conflicting Grid Locator/Position data - exiting"

The following messages are printed when calls to the malloc() function for allocating memory to one of the buffers used by xsatcom, fails. Normally this should never happen.
"xsatcom: Call to malloc() for TLE database failed - exiting"
"xsatcom: Call to malloc() for observer database failed - exiting"
"xsatcom: Call to malloc() for multisat status buffer failed - exiting"
"xsatcom: Call to malloc() for transponder modes buffer failed - exiting"

The following messages are printed when the xsatcom.sat file cannot be read for some reason, when no satellite name can be found in xsatcom.sat and when a satellite name found in xsatcom.sat does not appear in xsatcom.tle.
"xsatcom: Error reading ~/.xsatcom/xsatcom.sat file - exiting"
"xsatcom: No satellite names found in xsatcom.sat - exiting"
"xsatcom: No matching satellite name found in xsatcom.tle - exiting"

The following messages are printed when a satellite's transponder data in the xsatcom.sat file is incomplete and when the pass-band type specified in xsatcom.sat is not recognized.
"xsatcom: Satellite transponder data incomplete - exiting"
"xsatcom: Transponder pass-band flag not recognized - exiting"

Known Bugs
Since version 1.6, the satellite tracking functions in sgp4unit.c have been adopted, after some modification, from the revised SGP4 code accompanying "Revisiting the Spacetrack Report #3" from Center for Space.

I have fixed all true 'bugs' (e.g. coding errors) that I have noticed in xsatcom but there may well be some that got away, waiting for some untested conditions to bring them forth. However there are also some inadequacies and mis-operations in xsatcom that are due to external hardware (rotor controller/transceiver), or due to programming difficulties. Here are these 'bugs', listed for each Mode.

Single-Satellite/Single-Observer Mode

Multi-Satellite/Single-Observer Mode
The 'Sun Az/El" field displays incorrect data momentarily when the current satellite is selected by clicking on a tree view item or when changing the observer location with the navigation buttons, because a search is carried out in time for the next AOS/LOS of the new satellite resulting in a temporary change to the value of the Julian date used in calculations.

Single-Satellite/Multi-Observer Mode
The 'Sun Az/El" field displays incorrect data momentarily when a new satellite is selected by a button click, because a search is carried out in time for the next AOS/LOS of the new satellite resulting in a temporary change to the value of the Julian date used in calculations.

Pass Predictions Mode

Version History
Version 1.0: xsatcom is just a GTK+-3 version of the original ncurses application so when completed I gave it version 1.0 directly!

Version 1.1: Fixed a couple of dormant serious bugs (memory overruns) that surfaced when I upgraded to GTK+-3.22. Also related to these bugs, I modified the structure of some functions related to the Pass Prediction and Illumination Prediction windows.

Version 1.2: Modified the code that reads data from the GS-232 rotor controller to avoid possible buffer overruns when the RS-232 serial communication between the computer and controller introduces errors. Also fixed some oversights in this document.

Version 1.3: Arranged for the xplanet command-line options to be defined in the ~/.xsatcom/xsatcomrc config file so that xplanet can be called with whatever options the user prefers.

Version 1.4: Added another button to the main window to enable plotting of all satellites in ~/.xsatcom/xsatcom.sat on a map of the earth using xplanet.

Version 1.5: Modified the list selection callback routine of the Multisatellite widget since an apparent change in GTK2's list code caused the Multi-satellite display to freeze.

Version 1.6: I have adopted the revised SGP4 code related to "Revisiting the Spacetrack Report #3" from Center for Space and incorporated it in xsatcom, after some necessary changes to the source code of both. There is a slight difference in the results produced now but please don't ask me which version is more correct, I have no way to verify! ;-)

Version 1.7 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in xsatcom source code and changed all "sprintf" commands to "snprintf" just in case. While going through the xsatcom source code, I also fixed some minor bugs like typos and tidied error messages and other aspects of the GUI.

Version 1.8 After a bug report from Pino Zollo ZP4KFX regarding GUI problems with my Hellschreiber program xfhell, I made some changes to the GUI code in most of my GTK2 applications.

Version 1.9 After a bug report from Pino Zollo ZP4KFX, regarding failure of "xdemorse" to start the Morse decoding loop after reading its configuration file, I have modified the functions that read this file so that more detailed error messages are printed if entries are malformed. I have also added a "Start" button to the GUI to enable starting and stopping xsatcom as needed

Version 2.0 I re-wrote the Calculate_Moon_Position() and Calculate_Solar_Position() functions in solar_lunar.c to agree with the algorithm for the position of the Sun and Moon as given in the book "Astronomical Algorithms" by Jean Meeus. The original Calculate_Moon_Position() function had some bugs that resulted in slight errors in the calculation of the Moon's azimuth and elevation.

Version 2.1 I made some changes to the transceiver and rotor CAT code to improve error handling.

Version 2.2 I made some changes to the code that enables display of satellites by using "xplanet". These changes have resulted in a slowing of the xplanet's response due to the 5 second wait between updates. This can be changed in the xsatcomrc file in the xplanet options line (the -wait 5 option) but shorter waits can cause heavy loading of the processor, at least when performing a multi-satellite display.

Version 2.3 Added CAT support for my Elecraft K3. This is likely to work with the K2 but I cannot verify this. The CAT functions had to be modified to a large extend, and as I do not have my FT847 any longer I cannot verify that they work properly. The new code has been tested on my FT857 but this rig does not have the "satellite mode" of the FT847 so testing is incomplete.
I replaced the GDK drawing primitives (gdk_draw_line() etc) with similar functions from the Cairo library. this gives a nicer anti-aliased display of the Pass Predictions and Illumination Predictions displays.

Version 2.4 I made extensive modifications to the source code to silence a large number of warnings generated by the LLVM clang compiler when used with the -Weverything option. These were mostly cases of implicit conversions between variable types, like int to char or uint to int etc. I have also updated the basic files of the GNU Autotools build system, to be compatible with the current version of these tools at the time of writing (February 2013).

Version 2.5 I have fixed a number of defects reported by the source code auditing tools of the Coverity Scan website. These were mainly related to programming practices and did not affect the operation of this application.

Version 2.6: After a bug report form Richard Lawn, regarding faulty CAT control of his FT847 by xsatcom, I borrowed back my old FT847 and after a lot of changes to the xsatcom CAT code, I fixed whatever bugs I found and tested xsatcom on my old rig. These bugs were a result of adding support to my ham radio applications for the Elecraft K3, without testing them on an FT847 as I no longer had my old rig then.

Version 2.7: After a report from Giorgio Folle, about xsatcom not reading correctly data files in ~/.xsatcom/, I have modified the code that reads decimal (floating point) numbers from these files. The problem was the use of the ',' character as a decimal point character in some locales. xsatcom can now read numbers with both '.' and ',' as the decimal point character.

Version 2.8: With help from Richard Lawn, who with patience and perseverance compiled and tested many edited versions of xsatcom, I have, to the best of my knowledge and local testing on some satellites, got xsatcom to work properly with the FT847. There still seem to be some difficulties with FO-29 with Rick, but we will have to wait for the next summer season for Rick to be able to test again. So be warned!

Version 2.9: I made some changes to the Strlcat() function and its usage in the xsatcom code, to improve safe handling of string concatenation operations. Hopefully this has not broken the handling of various strings in xsatcom! ;-)

Version 3.0: I fixed a bug that caused a "Redo" in the Pass Predict and Illumination Predict displays when the Multisat Display window is kept open.

Version 3.1: I updated the GUI code to the latest GTK+-3.22. This made it necessary to make minor changes to the User Interface but functionality remains the same. An advantage of this version is that the GUI specification is in a Glade-3 XML file in the ~/.xsatcom/ folder (xsatcom.glade), and this can be edited in Glade-3 if some cosmetic changes are desired. I migrated the internationalization system from "intltoolize" to GNU GetText, as the former is now considered obsolete. Also replaced the autogen.sh script with a newer version.

Version 3.1.1: I edited Makefile.am so that make install will now place relevant application files (documentation, pixmaps, desktop file, glade UI file etc) into the right places.

Version 3.2: I made a number of changes to the source code to mitigate defect reports from Coverity Scan. None of these reported defects were of consequence to the correct and safe operation of xsatcom.
I also changed the Pass Predicitons display so that it now uses Mono-space fonts, to make tabbed results more regular and I removed the column displaying the Phase of the satellite, since it is not really very useful.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details:
http://www.gnu.org/copyleft/gpl.txt

Acknowledgments
The original SGP4 and SDP4 tracking functions in sgp4sdp4.c were translated to C from the FORTRAN routines in NORAD Spacetrack Report #3. Since version 1.6 I have adopted the revised SGP4 code accompanying "Revisiting the Spacetrack Report #3" from Center for Space, after some modification.

Many functions in date_time.c, input.c, math.c, observer.c and solar_lunar.c were ported or adapted from Dr. T.S. Kelso's sgp4-plb26a Pascal library of satellite tracking and related routines.

Some functions relating to AOS/LOS predictions were adopted from John Magliacane's predict tracker.

The moon tracking routine in solar_lunar.c was adapted from Lapo Pieri's trk tracker, which I have also used for comparisons with xsatcom.