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.
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.
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.
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.
Version 3.2.1: Changed the installation commands in Makefile.am so that all the relevant files (desktop file, application pixmap, configuration file, executable binary etc) are installed under any location specified to the configure script by the --prefix= option. Also modified the program so that on first start up after installation, the application will create its working directory by copying files from the relevant directories under the installation prefix.
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.