NOTE: This release does not include any binaries. More importantly it does
not include the binaries for unzip, lha and xloadimage. These can be found
at most major FTP sites. Alternatively you can download one of the earlier
microsat releases which does include them.


This is a test release of the Microsat suite converted to use the Athena
Widgets. The reason I did the conversion was that on my system with 8MB of
RAM, using programs based on xview caused my system to swap, also the
programs appeared a little sluggish. Having seen the programs run on Johns
own machine at the 1994 AMSAT-UK Colloquium I knew that my problems were
RAM based ... I have a faster CPU.

So I did the conversion. I had done some X11 programming work about four
years ago, but have never used the Athena widgets before. So if you find
any problems in my use of them please drop me a line with a fix. At this
point I would highly recommend that you install the Xaw3d library instead of
the original, as the system looks much better for it.

The programs work very much like the originals that John supplied to me on
a disc labelled as version 0.7, however the following functional changes
have been made by me:


XPB
---

xpb is the only program that needs to be running when a satellite is within
range. This program implements the PACSAT broadcast protocol and is used
to:

1. Capture files that are broadcast
2. Capture directory entries that are broadcast
3. Request files from the satellite
4. Request directory entries from the satellite
5. Optionally log telemetry data
6. Optionally log KISS data
7. Display satellite status messages
8. Display and record statistics

In use, items 1, 2, 7 and 8 occur automatically and do not require any user
intervention. A button is provided to toggle the logging of telemetry
packets to a file named xxxxxxx.tlm for later analysis by xtlm, the label on
the button is changed to reflect the current state. In addition a button is
provided to log all KISS packets to disc, in this case the output file is
named xxxxxxx.kss, the value of xxxxxxx for the telemetry and KISS logs is
determined by the time of that start of the capture and is the time value in
hex.

The statistics displayed can be used as a guide to the health of your PACSAT
receive system. At the end of an xpb session, a summary of the statistics is
appended to a file named pb.log in the current directory, this is a text file.

The requesting of either files or directory entries from the satellite is
controlled by three buttons, marked "Cancel Fill", "Fill Directory" and "Fill
File" along with an enterable text box. Two of these buttons also appear on
the directory screen. To update the directory entries simply press the Fill
Directory button, a request to fill the directory will be sent immediately
and every time a PB status line is received from the satellite. If your request
is accepted your callsign will appear in the PB status line, this will be
detected and further retransmissions for this particular diretory request will
stop. It is also possible to stop these requests manually by pressing the
Cancel Fill button.

The requesting of a file is similar to requesting directory entries except
for two differeneces. Firstly a file number must be entered in the text
box next to the Fill File button, and secondly if the satellite responds
with a "NO -2" response to your request then the request is cancelled. This
response from the satellite indicates a permanent problem associated with
your request, ie the file has been deleted. The file number may be filled
in via the directory program.

Every thirty seconds the contents of the hole file for the directory is
written out. This is done in case the proogram should crash, an out of date
directory hole file can lead to duplicates appearing in the directory. I
have also put code in to flush out the other hole files but have not
enabled it. Unlike the directory hole file, an out of date file hole file
does not cause data corruption.

I think I have fixed the bug that occurred in all versions prior to this one
whereby duplicate directory entries could occur. This mostly occurred when
dealing with the latest directory entry of the satellite. This should not
be confused with the behaviour of some of the on-board log files that
occur many times in the directory. You will notice that they appear with
different Date/Time entries every time, this is normal.


XPG
---

This program will list all of the files that are ready for uploading. If a
file is partially uploaded then a value will appear in the Id column to
indicate the file number allocated to that file. To upload a file you simply
double click on the entry in the list. The program then forks a second process
to actually do the uploading leaving the main window available for other uses.
The program will stop you from trying to upload two files simultaneously. A
pipe is created between the two processes to allow status messages from the
child to appear in the main window. It is possible to call message from xpg,
but you will have to press the Update button to display any new messages that
have been created for uploading.


MESSAGE
-------

This program is designed to produce files in a suitable format for
uploading to the PACSATs. The PACSAT file system is very flexible and allows
for any sort of file to be transferred, there is no restriction as to the
contents of the file. The program itself is very straightforward to use and
requires very little description. The program may be run standalone or
called from downloaded, viewtext and xpg, in the first two cases message
is used to reply to an existing message, message is passed the name of the
message to be replied to and takes the destination callsign, and subject
from the original message. In addition a button labelled Quote appears
which allows the original message to be included in the text window with
each line prefixed by the > character.

I have taken the opportunity to change the layout of the screen for message,
and included some new features. I have updated the file type button to
include some new file types. In the case of an unlisted file type being
required the "Other -->" entry should be chosen and a textual description
of the file type should be typed into the text box to the right of the
button. The same comments apply to the compression type button and text
field. The button for choosing to use text from the edit window or from a
named file also operates in the same manner. The Banner button uses the
BANNER environment variable for the name of the banner file to use, failing
that it will attempt to find a file named .sig in your root directory.


XTLM
----

This is a new program. It is designed to display the telemetry either in
real time or from a telemetry capture file, of satellites using the UoSAT
standard for sending telemetry. At present this means that it will only
display telemetry from UO-22, KO-23 and KO-25. The program expects to find
a file called "tlm.cfg" in the current working directory, this means copying
the file kitatlm.cfg to the KO-23 sub-directory, kitbtlm.cfg to the KO-25
sub-directory and uo5tlm.cfg to the UO-22 sub-directory, and renaming them
tlm.cfg.

If the environment variable XTLM is not set then the program will operate in
real time, if XTLM is set then the program expects to find a file containing
captured telemetry data in the file named by XTLM. The file format is that
used by the UoS for capturing telemetry. A two byte length field is written
out in Intel format with the least significant byte first, followed by the
data portion of the telemetry packet.

xtlm offers the facility to capture the telemetry to disc, the "TLM Log"
button works as a toggle alternating between On and Off as indicated by the
label. The data captured is written to a file named xxxxxxx.tlm in the current
working directory, the value of xxxxxxx depends upon the time that the
telemetry capture was started and is the start time in hex. The other buttons
labelled "Page 0" onwards allow you to see different pages of telemetry data.
A line of statistics about the received telemetry is also displayed.

The telemetry configuration files are those that are used by the official
UoS program DTLM. Thanks are due to F1TFQ and IT9DLN for supplying me with
the files for KO-23 and KO-25, I got the file for UO-22 from the freeware
program UO5TLM. The format of the file is quite simple and since my source
code is available I won't describe it. The src directory contains examples
of captured telemetry in the files raw.uo-22, raw.ko-23 and raw.ko-25.


VIEWTEXT
--------

This is usually called by downloaded but can be used directly if needed.
Its purpose is to display downloaded text files, and with this release can
also handle files compressed with PKZIP and LHA provided that the programs
unzip and lha are in your path. To run the program outside of downloaded you
need to specify the name of the .dl file as the first argument. I have left
the text area as editable text, primarily so that it is possible to cut and
paste between viewtext and any other program, such as the text area of
message for example. Any changes to the text in viewtext are not kept. It is
possible to call message from viewtext to enable a reply to be formulated,
the from, to and subject lines are automatically filled in.


VIEWLOG
-------

This is usually called from downloaded, but is actually spawned by phs. This
program will display the contents of the ALxxxxxx, BLxxxxxx, CLxxxxxx,
ELxxxxxx and wdxxxxxx files. The AL files contain details of the FTL0
transactions which are only used for uploads these days. The BL files contain
statistical information about directory broadcasts amonst other things. The CL
files simply list people who have appeared in the PB queue. The EL files
contain information about SEUs that have occured. The wd files contain Whole
Orbit Data and are used to provide information about the values of telemetry
points during the whole of the orbit. Without this mechanism the ground
controllers would have no way of knowing how the performance of the satellite
changed when over unmanned areas. For the WOD function to work, the file
tlm.cfg must be in the current directory, this would usually be the case for
xtlm to work properly.

Like viewtext the display area of viewlog is editable so cut and paste between
viewlog and other programs is possible.

viewlog does not understand the PACSAT file header. This is done so that
viewlog can be used against log files that have been Extract-ed in
downloaded. viewlog can be used outside of downloaded by using command
line arguments, there are two formats to these arguments. The first format
is to simply specify the name of the log file eg AL940817, the file name
will also appear as the title of the window. The second format is to specify
the title as the first argument and the file name as the second arguments,
this was done to allow viewlog to be called by phs and to retain the correct
title.

I would like to thank Andrew G8TZJ for supplying me with the information
needed to view these log files.


PHS
---

I wrote this program to allow programs that do not understand the PACSAT
file header to be called from downloaded. However I think I have made its
syntax powerful enough to be used in other circumstances. In essence phs
will remove a PACSAT file header, call unzip or lha if needed to decompress
the file contents, and then call the named program with the resultant file
information. It is a command line driven utility that does not require X to
be running. Its syntax is as follows:

phs <.dl file> <program to run> <arg1> <arg2> ...

arg1 and arg2 and all following arguments are passed to the named program,
followed by the filename of the extracted file body. This file will have
a name based upon the current time and its file type, ie a GIF image file
will have a suffix of .gif etc. This was done for programs that parse the
input file name as a guide to the file contents, the default is to give the
file a .txt suffix. After the called program has ended the temporary file
containing the file body is deleted.


XWEBER
------

I know very little about this program. I am not active on the PSK satellites
at present and so xweber is untested, I did the conversion to the Athena
Widgets and that was all. Feedback on xweber would be appreciated.


DIRECTORY
---------

This program displays up to 2000 of the latest satellite directory entries.
They are displayed in date order, and the list can be restricted by changing
the button by the side of the View label. The options are to view all of the
directory entries "All", entries either addressed to you or sent by you "My
Mail", entries that have ALL appearing in the to field "Broadcast", log files 
"Logs" and entries created by the camera "EIS". When receiving the satellite
with xpb the directory will potentially be updated every few seconds, these
changes will not appear until the Update button is pressed.

The Fill Directory and Cancel Fill buttons have the same effect as the
buttons on xpb. They send a request to the xpb program (if it is running) to
perform the action. To request one of the files appearing in the list box
you simply double click on the entry, if xpb is running the file number will
appear in the enterable text box in xpb just as if entered manually.

A new feature of this program is the Order button. This allows the directory
entries to be re-ordered depending on the visible fields in the list. When
sorting on "From", "To" and "Title" the sorting is case independant so
"G4KLX" will appear next to "g4klx", in cases where the main sorting field
is identical, then the "Date/Time" field is used for ordering the two
entries.


DOWNLOADED
----------

This program displays all of the downloaded files from satellite. It has a
limit of 2000 entries ! The list can be reduced by using the View selection
button, this has the same entries and actions and the similarly named button
in directory above. Like directory, when receiving files from the satellite
via xpb it is possible that the list will not reflect what has actually been
downloaded, pressing the Update button should get the program into sync with
the downloaded files.

To view the contents of downloaded file you simply double click on the entry
in the list box. The program will use the file type entry in the file header
to determine how to display a file, unfortunately some operators are rather
poor at filling these entries in and so you may not get the desired results.
At the moment the program can display most text messages via viewtext, most
image files via xloadimage, and some log files via viewlog. If the file type
is not recognised you should see an error box appearing.

The Extract button allows the file body to be extracted from the downloaded
file and places in the msgs sub-directory with its original name, a
confirmation message appears to inform you of the name of the extracted
file. The Reply button calls message with the correct arguments to allow a
reply to be formulated.

A new feature of this program is the Order button. This allows the directory
entries to be re-ordered depending on the visible fields in the list. When
sorting on "From", "To" and "Title" the sorting is case independant so
"G4KLX" will appear next to "g4klx", in cases where the main sorting field
is identical, then the "Date/Time" field is used for ordering the two
entries.



It was not possible to change the source in such a way that the same source
could be used for Open Look and the Athena widgets at the change of a
define. Maybe that will happen one day, but the increased flexibility of the
Athena widgets has meant that some of the code is now smaller and simpler.
It is my hope that it will be possible to have the same code used for Open
Look, Athena and Motif one day.

For those thinking of porting these programs to other platforms, I wish you
luck. The code is very dependant upon having connected mode AX25 in the
kernel. If you were thinking of just porting the broadcast code to another
platform then things will be easier. Putting the async and KISS layers into
the code would not be too difficult. But beware, much of the code assumes
that these programs are running on an Intel platform which has the same byte
ordering as the Microsats. With a little effort the code could be made
platform independant in the same way that KA9Q is.

Please be aware that Linux kernel release 1.1.39 is a bad one. Both me and
John G0ORX have had problems with this version. Version 1.1.41 and later
are fine, and presumably later ones will be too. We both use Alan Cox's
AX25.024 on our machines.

Jonathan G4KLX

PACSATs: @ UO-22   @ KO-23   @KO-25
Internet: g4klx@g4klx.demon.co.uk
