The World of Computer Software/World_Of_Computer_Software-02-387-Vol-3of3.iso/p/pb920430.zip/PBNEW.TXT

Windows Setup INFormation | 1992-04-30 | 43KB | 1,018 lines

         "I write so little documentation because so
         few people bother to read it." - Anon.

PB User's Documentation Rev. 0.03

THE PACSAT BROADCAST GROUNDSTATION PROGRAM

This documentation relates to versions of PB with version dates 911220
or newer. Users of older PB versions are strongly encouraged to update!
If you just want to find out what's new in this release, jump to the
REVISION NOTES at the end of this document.

[As of 29/4/92 only UO-22 supports the broadcast directory system used by PB.
The other satellites should follow before the end of may.]

PB is an groundstation program for receiving messages and message directories
from satellites running the PACSAT Protocol Suite.



NECESSARY EQUIPMENT

PB will run on any IBM compatible Personal Computer running MS-DOS. [Version
5.0 and 3.x have been extensively tested.] PB will run well under MS Windows
3.0 and 3.1 if your machine has the computing power. Although PB will run on a
PC or XT machine, serious users of UO-22 will desire at least a 12 MHz AT. A
hard disk (or RAMDISK) is also necessary.

PB requires a terminal node controller (TNC) which supports the KISS interface
mode. TNCs with KISS EPROMs are supported, as are TNCs which recognise the
TAPR-style commands for entering KISS mode.

INSTALLATION

You should make a subdirectory for each PACSAT satellite you expect to
operate. From each of these, there should be a subdirectory called "MSGS." For
example, if you expect to operate PACSAT, LUSAT and UOSAT-5, you might have
the following:

C:\PAC
C:\PAC\MSGS
C:\LU
C:\LU\MSGS
C:\UO22
C:\UO22\MSGS

Copy the default configuration file - PB.CFG - into each of the satellite
directories (C:\PAC, C:\LU and C:\UO22).

Edit the configuration files - specifically, you must set "mycall" in
each file to your callsign. Each configuration file must contain a
different "bdcstcall" line to identify the satellite.

Place a copy of the example select equation file - PB.EQN - into each of the
satellite subdirectories. (To activate this file and any modifications you
make to it, you need the line "select pb.eqn" in your PB.CFG file.)

Place a copy of PBHELP.HHH in each of the satellite directories.

Place the main program - PB.EXE - in a subdirectory where DOS can find it.

Use a terminal program to set your TNC for NO PARITY and 8 DATA BITS. To do
this on a TAPR-like TNC, type the commands

PARITY 0
AWLEN 8
RESTART

If you do not do this, PB will not start up correctly.

To run PB for a particular satellite, you now change to the appropriate
satellite directory and type "PB." Using the example above,

C:\>CD LU
C:\LU>PB

PB will place all of its working files in the satellite subdirectory.


1 PRINCIPALS OF OPERATION

Two aspects of PB and PACSAT operation are unfamiliar to users of terrestrial
packet radio: the client/server relationship and the use of "broadcast mode".
Both of these concepts are essential to an in-depth understanding of PB.

1.1 Client Server Operation

In most terrestrial BBS systems, you use a simple terminal program on your
computer. After instructing your TNC to connect to a BBS, you type commands
which are received and processed by the BBS. The BBS will respond by sending
you messages, menus and help in plain text which is displayed by your terminal
program. You type characters which directly command the BBS.

In PACSAT operations, this direct connection between your commands and the
software running on the satellite is removed. The software running on your PC
is not just a terminal program. At the "front," PB provides a user interface
which allows you view message directories, request and read messages. At the
"back," PB implements the PACSAT Broadcast Protocol, a computer-to-computer
protocol for transferring messages and directory entries from the satellite to
the groundstation. When necessary - because of your keyboard activity or
internal automatic operations - PB requests portions of directories and files
files from the satellite. The satellite software receives requests from many
stations on the uplink, and provides the desired data on the downlink. The
groundstation is the "client," and the satellite is the "server."

PB implements this client/server system in a way that minimises (or removes)
direct, immediate interaction between you and the satellite. These operations
are automated, and controlled by satellite and groundstation software. The
messages and directories received by PB are stored on your hard disk, so you
can view and manipulate them when the satellite is not in range. This means
that you can set to PB automatically download messages while you are
unavailable, and then you can view the new mail later.

1.2 Broadcast Mode

Every station in the satellite's footprint can hear everything transmitted on
the downlink, and the PACSAT Broadcast Protocol was designed to make the best
use of this information and as much as possible to avoid repeating data. PB
works along with the satellite to capitalize on on the broadcast-nature of the
downlink.

When a PACSAT satellite transmits a message, the message is broken into
chunks, each chunk is put in a packet and the packets are send in UI frames.
(UI frames are not part of connected mode AX.25, but are the frames usually
associated with "beacon" transmissions.) Each of these broadcast packets
carries a chunk of message information, the message ID number, and a number
giving a rough indication of the message type. Of course, when a message is
broken into several of packets, each packet must contain enough information to
tell the groundstation where in the message that packet belongs. For further
information see the PACSAT Broadcast Protocol definition.

By default, PB identifies and stores all new broadcast packets from all
messages which it hears. This way, if someone in your footprint downloads a
message and you later decide that you want to look at that message, PB will
already have a copy of the message stored away for you. This is sometimes
called "message grabbing."

When PB is capturing a message, it might miss some of the message packets.
These missing packets leave "holes" in the message, and usually you won't want
to view a message with holes in it. PB can fill the holes either by waiting
until the holes happen to be transmitted, or by actively requesting that the
PACSAT send the necessary holes. (See "Message Status" below.) Incomplete
messages - ones with holes - are stored in files with the extension .ACT,
along with a list of the holes which has an extension .HOL.

Completed messages are stored in files with the extension .DL.

In general, you will only be interested in .DL files. DL files may contain any
kind of information which can be stored on a computer. Some of the messages
will be text messages like on a terrestrial BBS, but others will be images,
digital voice, computer programs and other binary files. Most long messages
are compressed using programs like ZIP and LHA. When you have received a DL
file, use the program PHS (or the similar program PFH) to convert the DL file
into a standard file for your PC.

1.3 Broadcast Directories

Directories tell you what messages are available on the satellite, and give
some details of each message. Since all groundstations need the message
directory, PACSATs also broadcast their directories in a UI frames which can
be received and used by everyone in the footprint. PB will always listen for
directories on the downlink and save new or updated message directories for
you to view. By viewing message directories (see "Message Status" below), you
can decide whether you want to make sure to get a complete DL file for a
particular message.

1.4 Message Status

The most important window in PB is the Directory View window. You can either
have PB start automatically displaying this window, of you can switch to it by
typing V.

When you are in the Directory View window, you can see a message's status in
the column headed "S". The status markers are interpreted as follows:

n - Never

This message will not be automatically downloaded and filled, nor will it be
saved if it is overheard when another station is downloading it.

g - Grab

This is the next step up from "Never". It means that the message will be saved
if it is overheard when another station is downloading it, but PB will
NOT automatically try to fill all holes in the message to create a .DL file.

A - Automatic

This is the standard automatic status. It means that the message will be
completely downloaded and filled automatically by PB, without your
intervention. When the message is completely filled, the status indicator will
will go to a SQUARE WHITE BLOCK.

P - Priority automatic

This allows you to place some messages "before" others in the automatic
downloading system. All Priority messages will have their holes filled before
any messages with Automatic status.

SQUARE WHITE BLOCK - Downloaded

The message has been completely downloaded. When this first happens, the
message will be in the PB working directory, with the name xxxx.DL, where xxxx
is replaced by the message number.

E - Error (permanent)

The server has indicated that this message cannot be downloaded. Either it is
not there or you are not allowed access to it. This status is permanent, until
you change it manually.

e - Error (temporary)

The server has indicated that the message cannot presently be downloaded, but
might become downloadable later. This status is cleared when you exit PB and
the previous (A/P) status is restored.

N.B. - If you changed the status of a Downloaded message to A/P/g, you will
receive another copy of that message.



2.  CONFIGURING PB

When PB runs, it reads a configuration file. The default file name is PB.CFG,
and it must be in the current DOS directory. Alternatively, you can specify
the complete DOS path to and name of the configuration file as a command line
argument when you run PB. (If you specify the path/filename, you will probably
also need a "pbpath" entry in the config file to make sure that PB actually
looks for and stores all of its files where you want them. See "pbpath"
below.) The configuration file must be a pure ASCII file like AUTOEXEC.BAT or
CONFIG.SYS. It must not be edited with a normal word processor which may
insert control characters.

A sample configuration file comes with the PB program release. Some entries
you must edit. Others you might need to. Others you can if you want to. Others
you are discouraged from editing. All users will need to have the proper
"mycall" entry, and you may also have to use set "port" and "speed" to make
sure that PB can communicate with your TNC. Examine the "Your Station" and "PB
Startup" sections below.

Your Station
------------

mycall <call>[-<ssid>]

Your station callsign. <call> is 6 or fewer ASCII characters. <ssid> is an
optional number from 1 to 15. Please do not use an <ssid> unless you have a
very good reason.

alias <string>
     - or -
myaddr <string>

This allows you to set your network address, handle, or whatever you call it.
This can be long and complicated, whereas the "mycall" must be an AX.25
callsign. The select equation system alows you to use your alias when selecting
messages.

"alias" and "myaddr" do the same thing, and the last one in PB.CFG will be the
one that is used.

There is no need to set your alias to "ALL" to get messages addressed to
"ALL," since the Select Equation processor will allow you to do this. The
alias is actually intended to give you another name to use on the satelite, or
a place to put your complete network address. For example, if I wanted to use
my internet address on the satellite, I would set alias to
"[e-mail]." The maximum length of the alias is 40 characters.

bdcstcall <call>[-<ssid>]

This identifies the satellite you want to communicate with. The
distribution file is for UOSAT5-11, so when you make a configuration
file for another satellite, you'll need to change this. Some other
satellite calls are:
     pacsat-11
     lusat-11

port 1|2
          Default COM1

Sets the communications port. Only COM1 and COM2 are supported. This is the
port your TNC should be connected to. If you normally use a TSR serial
communications driver (COMBIOS, MBBIOS, etc) remove it before running PB.

speed <baud rate>
          Default 19200

This is the speed that you have your TNC asynchronous port set to. This
is not directly related to the downlink or uplink speed of the
satellite, although it is recommended that you run your asynchronous
port faster thatn your satellite port. For UO-22 this means running the
asynchronous port at 19200 baud.


PB Startup
----------

screenmode <zoom | dir>

If you want PB to start in the directory view mode, use "screenmode dir." To
start in a zoomed main window use "screenmode zoom." Otherwise, PB will start
in the normal main window mode.

defaultsel <Fx>
     default F1
When you go to view mode, before you type any function keys, the active
selection will be the one associated with the function key specified in the
"defaultsel" entry. For example, if you are using the selection equations
built in to PB, "defaultsel F2" in your PB.CFG file will show only messages
addressed to you. This can be combined with "screenmode" to jump directly to a
desirable directory view when you execute PB.

select <filename>

If you have a "select" line in PB.CFG, PB's built-in select equations will be
replaced by the select equations in the file you have named.

pbpath <dos path>
          Default is the current logged directory

PB will look for and create certain data and message files during its
operation. If you don't have a "pbpath" entry in your configuration file, PB
will use the currently logged DOS directory. If you want to make sure you know
where PB is putting its files, put a "pbpath" entry in the configuration file.
For example

     pbpath c:\pacsats\uosat3

would tell PB to find/put all of its working files in the directory
"\pacsats\uosat3" on drive C.

silent 0|1
          Default 0
Set slient to 1 if you don't want any warning bells.

trace 0|1
          Default 0
Little general importance. Trace is used to monitor connected mode activity on
the downlink.


PB Shutdown
-----------

exitafter <minutes>
          Default 0
If this is not 0, PB will exit if it hasn't heard a packet or received a
keypress for the given number of minutes.

actdays <days>
          Default 3
Tells PB how long to keep incomplete message fragments, e.g. .HOL
and .ACT files.


TNC Oddities
------------

Some TNCs require time delays to get them safely into and out of KISS mode
which is used by PB. The following configuration options should be used. If
all else fails, you can put  KISS-only EPROM in your TNC or put your TNC into
KISS mode yourself before running PB. If you do either of these things, put
"kisstnc 1" into PB.CFG.

restart_delay <delay after restart cmd>
          Default 60  (in 1/18 second increments, e.g. 3.333 seconds)
This delay tells PB how long your TNC takes to get into KISS mode. Most TNCs
flash their lights 3 times while entering KISS mode, and PB must not try to
communicate with the TNC during this time.

aea_delay <delay before restart cmd>
          Default 1 (as above, e.g. 0.055 seconds)
This delay is necessary on some "smart" TNCs. If your TNC won't go into KISS
mode, then try bumping this up a lot to cure it.

break_delay <delay after break>
          Default 9 (as above, e.g. 0.5 seconds)
This delay allows the TNC to get its cmd: processor sorted out before we try
to send commands to the TNC.

kisstnc 0|1
          Default 0
If you have KISS EPROMs in your TNC, or otherwise put your TNC into KISS mode
before running PB, set this to 1.

tncid <id>
          Default 0
Little general importance. Allows you to set a multidrop KISS address.

txd <tx keyup delay msec>
          Default 150 msec
This is the number of msec between the keying of your transmitter and the
transmission of data.

paclen <bytes>
          Default 244
When your station requests something from the satellite, it asks the satellite
to transmit packets of this length. If you have not set up your downlink
receiver for peak performance, you may wish to reduce this length. In
general, you should not change this.

This has no effect on uplink packet size.


Kiss Logs
---------

The next three entries (logbbframes, logdbframes, logothers) control what KISS
frames get stored in the KISS log files. KISS log files are "raw output" from
your KISS TNC. They are stored in files called yymmddhh.KSS, where yymmddhh is
replaced by the current time. These files are useful for debugging, keeping
statistics or using as input to other data processing programs like DTLM.

logbbframes 0|1
          Default 0
If 1, put all broadcast protocol data frames in the KISS log.

logdbframes 0|1
          Default 0
Little general interest. If 1, put all directory broadcast protocol frames in
the KISS log.

logothers 0|1
          Default 0
Some general use. If 1, put all frames which are not broadcast directory or
data frames into a KISS log file. This might be used to capture telemetry
frames for later processing.



Automatic Transmissions
-----------------------

automode <0|1>
          Default 1
If this is set to 0, no automatic transmissions will take place.

dirupdatemins <minutes>
          Default 15
Tells how many minutes after bringing the directory up-to-date, the directory
should be updated again. This is set to some time greater than the average
pass, and allows PB to be left running overnight. The directory will then be
updated every pass, even though you haven't quit and re-run PB.


PFH Files
---------

maxdirfilesize <bytes>
          Default 25 kbytes
The size of individual PB__xxxx.PFH files. Do not increase this value
significantly, as it will interact with "maxdirload" and lead to RAM shortage.

maxdirload <bytes>
          Default 100 kbytes
When PB is executed, it loads the most recent PB__XXXX.PFH files into memory
for your main directory view. PB stops reading .PFH files when maxdirload
bytes have been loaded. This size check is only made after each complete .PFH
file is loaded, hence the warning about "maxdirfilesize."


Batch File Creation
-------------------

To assist in the post processing of newly-received files, PB will create a
batch file containing the file number for every newly-received file.
This batch file can be run after the pass. See the "Automation" section
for more discussion.

If you want to customise the entries in postpass.bat, you can set two
strings: one (bats1) which comes before the file number and one (bats2)
which comes after the file number. For example, if pb.cfg contained the
lines

     bats1 'this is the file number'
     bats2 'just downloaded.'

then each line in postpass.bat would look like

     this is the file number 45ab just downloaded.

The default is for PB not to create postpass.bat. If you want to turn
this feature on, put the line

     makebat 1

into PB.CFG.


Deep Secrets
------------

ndupesearch <depth>
          Default 100
Very little general importance. When a new directory entry is received from
the satellite, it may be for an updated version of a spacecraft log file. PB
will scan the newest <depth> entries in your directory to find out if this is
true.

maxpfhsize <bytes>
          Default 500
Very little general importance. The PFH is the header or envelope which
encloses messages on the PACSAT server. This PFH is also the "directory entry"
which PB stores for the directory view mode. PFHs can be any length. If people
start using really big ones, you might have to increase this number. A message
will show up in the message window if this is ever the case.

autoselect 0|1
          Default 1
When a new or updated directory entry is received, PB will check your select
equations to see if the message should be marked Never, Priority or Auto. The
default select equations make all messages to "mycall" and "alias" Priority
mesages, all reasonable-sized messages to "all" as Auto messages, and leave
everything else alone. There aren't any real reasons to turn this off.

graball 0|1
          Default 1
Because of the way broadcast mode works, you may hear part of a message being
transmitted to someone else before you have received the directory entry (PFH)
for that message. If you have graball on, these bits of messages will be
captured and saved unless they are blocked by a "blockftype" entry. You should
leave this at the default unless you NEVER WANT TO RECEIVE ANYTHING.

blockftype <decimal file type>
          Default none.
There is a select equation which specifies message which you Never want to
download. However, the select equation can only mark a message "N" when the
directory entry for that message is received. PB may receive data packets from
a message before receiving the message directory entry. By default, these
message packets would be saved in a .ACT file. To make sure that bits of
unwanted message types do not sneak in before PB receives directory entry, use
"blockftype" entries in your PB.CFG file. For example, to make sure that you
never receive any fragments of BBS traffic messages, put
     blockftype 2
into your PB.CFG. You may have up to 20 blocked file types. It is considered
antisocial to block file types that you later download, since this causes
unnecessary downlink traffic.

Remember that blocked file types can become selected if they meet your Auto or
Priority select equation criterea.

showgrabs 1|0
          Default 0
Setting this to 1 tells PB to print a message explaining why each message
heard on the downlink is being grabbed or not grabbed.



3.0 MENU SELECTIONS

There are two menus. One is the "Main Menu" and the other is the "Directory
View Menu". You will generally want to interact with PB through the Directory
View Menu. Each menu has a (H)elp option which you should read.

3.1 Directory View Menu

P, A, G, or N to change the status of the message currently hilighted by the
cursor. See "Message Status" above for descriptions of the various status
settings.

Right Arrow to see an expanded view of the Subject and Keywords fields.

Left Arrow to return to the normal view.

ENTER to see a more extensive display of the message header (PFH).

Up and Down Arrows move the cursor.

Page Up and Page Down. To change the display page.

Q to Quit the program, that is to leave PB completely.

X to Quit the program and return an error code of 1, useful in .BAT files.

M or ESC to return to the Main Menu.

H to see the help screen for Directory View mode.

V to view a downloaded message. (See "Message Viewing")

R to see archived directory files. (See "Archived Directories")

F to find a particular numbered message. (See "Finding a Message")

The function keys are programmed by the select equation system. The built in
select equations assign the function keys to

F1 - to show all non-BBS and non F4 messages.
F2 - show only those entries with your call or alias in the To field.
F3 - show only those entries with "all" in the To field.
F4 - show only spacecraft log files.
F5 - show Downloaded messages
F6 - show Requested (A or N) messages
F7 - show Keplerian element files
F8 - show Image files (UO-22 CCD or those with "IMAGE" in keywords)
F9 - show messages with "NEWS" in the keywords
F10- show messages with PB or PG in the keywords
F11- show BBS traffic.
F12- show messages with high precedence (e.g. PFH "priority" > 0)

3.1.1 Message Viewing

Once a file has been downloaded (indicated by a WHITE SQUARE WHITE BLOCK in
the status column) you can try to view it from within PB. Place the
cursor onto the message and type V. If possible, PB will display the
message text, one screenfull at a time, allowing you to use the PAGE
DOWN key to see more text.

The advantage of PB's crude built-in file viewer over more comprehensive
commercial and shareware viewers is that while you view a file PB still
processes data from the satellite downlink and pursues any automated
operations you have requested. Shelling out to another viewer would
suspend PB and cause loss of downlink data.

Message viewing is a feature in the process of being implemented and its
internal workings may be completely revamped soon. It does, however,
depend on some basic assumptions which will remain fixed. It assumes
that there is a subdirectory called "MSGS" off of the satellite
subdirectory, and that .DL files are in the satellite subdirectory, and
files without their PFHs are in the MSGS subdirectory. All file base
names are hexadecimal message numbers. File name extensions for
uncompressed text messages are .MSG, and ZIP files are .ZIP.

Presently, view does the following in an attempt to view the message:

If a .DL file for the message exists, PB calls the DOS batch file called
DOFILE.BAT, giving the message number as an argument. If no .DL file is found,
this step is skipped.

If a .MSG file for the message is found in the subdirectory called MSGS off of
the current directory, that file will be viewed as an ASCII file.

If a .ZIP file for the message is found in the subdirectory called MSGS off of
the current directory, the batch file ZIPVIEW.BAT is executed, with the
message number as an argument. The batch file should leave an ASCII file
called TEMP in the MSGS subdirectory. This TEMP file will be viewed.


3.1.2 Archived Directories

New or updated directory entries recieved from the satellite are stored in a
file with a name like PB__nnnn.PFH, where nnnn is replaced by an ID number.
When the current .PFH file is too big, a new file, with the next higher
ID number, is opened.

When you run PB, the .PFH files are read into memory starting with the file
with the highest number (the newest directories). PB stops reading in .PFH
files after about 100 kbytes (by default). This means that you will usually
have 100 kbytes of the most recent directory entries to view in your Directory
View. Obviously, some of the older .PFH files will not have been read into
RAM.

You can view these older files, one at a time, by using the aRchive view. From
the Directory View menu, type "R". This will read the next older directory
file into memory. You can filter this view using the function keys, and you
can even select files for Auto or Priority downloading (if they are still on
the satellite).

To read an older .PFH file, use the "-" (minus) key.

To read a newer .PFH file, use the "+" key.

To return to the main, current directory, type "M."

3.1.3 Finding A Message

If you type "F," you will be prompted for a message number. Type the number,
followed by return. PB will search your directory for the message you want. If
it is found and it is selected by your current Function key selection, the
directory window will be redisplayed with the message on the top line. If it
is not found, or found but not in the current selection, an error message will
be displayed.


3.2 The Main Menu

Download: Priority Auto Grab Never Fill Dir   Info. View dir. Quit! Help.

3.2.1 Priority, Auto, Grab and Never

These operate the same as they do on the Directory View Menu, except that you
will be prompted to enter the desired message number. This is primarily used
to request messages before you have received their Directory entries, and is
of little use.

3.2.2 Fill

This is a manual command which tells PB to request a particular message from
the If you have not yet received any part of the message, Fill will request
that the satellite transmit the entire message for you. satellite. If you
already have part of the message, Fill will request only the missing portions
("holes"). Fill does not alter the message status, and the message will not
automatically be completely filled unless it is already marked by the A or P
command.

If you want to use Fill instead of allowing PB to operate automatically, type
ctrl-A to turn automatic mode off. This will be indicated by "Auto: Disabled"
on the Status Bar.

3.2.3 Dir

This sends a directory request to the satellite, to update your directory.
This is an immediate, manual command. Generally, the directory will be updated
when you run PB, after PB has downloaded any messages with Automatic or
Priority status. It is best to let PB automatically update your directory
after Automatic and Priority operations are complete, since this gives you the
best opportunity to re-use other people's directory entries.

3.2.4 eXit

You can type "X" to exit PB and cause it to return errorlevel 1. This is
useful if you use a POSTPASS.BAT file and you sometimes don't want to go
through all of the post pass processing.


3.3 PB Performance Monitoring

3.3.1 On-Screen Status Indicators

There are several status indicators which are displayed along the bottom
of the screen. For example, you might see:

DIR: Old         AUTO: Idle                  s:0900  b:121234  d:083452 e:1

The "DIR:" entry tells you whether your directory is complete and up to date.
If it says "DIR: Old" then you have a complete directory, but it hasn't been
updated since you started PB this time.  "DIR: Up-to-Date." tells you that the
directory is complete and up to date. "DIR: Part (10)" tells you that you do
not have a complete directory - e.g. you have a partial directory - and that
there are 10 missing holes in the directory. Each hole in the directory may
contain any number of files.

The "AUTO:" entry tells you what the automatic hole-filling processor is
doing. "AUTO: Idle" means that the directory is up to date, and there are no
files marked for Priority or Automatic downloading. "AUTO: Dir" tells you that
PB is trying to fill your directory holes. "AUTO: 234b" tells you that PB is
filling holes in file 234b. "AUTO: Disabled" indicates that the automatic hole
filler has been disabled. You can re-enable it by typing Control-A.

The "s:" indicator tells the speed at which you have been receiving data on
the downlink, in bytes per second. This is calculated roughly every five
seconds. Thus, "s:0900" means that you have received 45000 bytes in the last 5
seconds.

The "b:" counter counts the number of bytes in message broadcast frames you
have received since starting PB. This includes all message broadcasts on the
downlink, not just those which were important to your station.

The "d:" counter counts the number of bytes in directory broadcast frames you
have received since starting PB. This includes all directory broadcasts on the
downlink, not just those which were important to your station.

Both the "b:" and the "d:" counter include Broadcast Protocol overhead of
about 11 bytes per packet, but they do not include the AX.25 overhead, which
is near 18 bytes per frame.

The "e:" indicator counts the number of broadcast message data or directory
packets which were corrupted between reception by your TNC and processing by
the PB program. "e:" can increase because PB runs too slowly on your PC,
because some other TSR program running on your PC is turning hardware
interrupts off for too long, or because of faults in your serial cable. You
can sometimes tell which by examining the messages printed when PB exits. Do
not worry if you get a few "e:" counts during a pass, especially if you are
using the directory and message views a lot - keyboard activity can cause
missed characters or buffer overruns.


3.3.2 On-Exit Status Message

When you exit from PB, you will see a message like the following:

Serial I/O performance:
Missed interrupts (overrun errors) :    0
Slow PB execution (4K buffer full) :    0

Missed interrupts are when PB's serial interrupt driver did not get a chance
to remove the one character from your serial port before another character
arrived. This is because interrupts were disabled for more than one character-
period. PB does not disable interrupts. DOS, the BIOS, or a TSR program must
be responsible.

PB has a 4096 byte buffer in which its interrupt driver stores incoming data
from the TNC. If PB is occupied writing to the disk or talking to the user for
too long, this interrupt buffer will overflow and data will be lost. The exact
number following this message is somewhat meaningless. These errors are
usually caused by you lingering at PB prompts or doing something that takes a
lot of disk access.

3.3.3 Througput Log

When you exit from PB, PB writes a log entry to the file PB.LOG. The entry
tells the start and end time of the pass, the maximum downlink throughput
reached during the pass (in a 5-second window), the total number of bytes
received during the pass, and the downlink througput averaged over the entire
duration of the pass. An example of a PB.LOG message is shown below.

92/04/29 17:10:41 - 17:10:47 : Max=1222 Bps  Gross=1188 Bps  Total Bytes=7128

3.3.4 Error Logs

PB may create a file called PBERROR.LOG. This indicates a critical error which
may be caused by something as simple as a write-protected .PFH file or
something as unlikely as a program bug. Examine the file and/or send it on to
the program developers at SSTL.


4.0 CONTROL KEYS

Control keys are now used to toggle ON/OFF certain aspects of PB operation.

ctrl-a     Toggle automatic operations on/off.
ctrl-z     Zoom/Unzoom the Downlink Window.
ctrl-d     Toggle the display of data bytes in the Downlink Window.
ctrl-t     Toggle trace mode in the Downlink Window.
ctrl-h     Toggle the display of AX.25 headers in the Downlink Window.
ctrl-x     Toggle the hexadecimal display of data in the Downlink Window.



5.0 SELECTION EQUATIONS

For a complete description of the select-equation system, see the accompanying
documentation "PB Select Equations." If you use the PB.CFG file which is
distributed with PB, you will get the select equations built in to PB.

These include equations for each of the function keys:

F1 - to show all non-BBS and non F4 messages.
F2 - show only those entries with your call or alias in the To field.
F3 - show only those entries with "all" in the To field.
F4 - show only spacecraft log files.
F5 - show Downloaded messages
F6 - show Requested (A or N) messages
F7 - show Keplerian element files
F8 - show Image files (UO-22 CCD or those with "IMAGE" in keywords)
F9 - show messages with "NEWS" in the keywords
F10- show messages with PB or PG in the keywords
F11- show BBS traffic.
F12- show messages with high precidence (e.g. PFH precedence > 0)

and two equations for automatic downloading of messages:

priority = messages to "mycall", "myaddr" or "alias."

automatic = messages to "all" that are less than 10 kbytes long.

If you wish to define your own select equations, you may begin by modifying
the supplied PB.EQN file. You must add the line "select pb.eqn" to your PB.CFG
file in order to activate this file.

6.0 AUTOMATION

Since its initial release, features have steadily been added to PB
allowing automated operation. (PB does not currently support message
uploading, so these features have necessarily been related to
downloading and post-processing of received mail.)

Automatic downloading of the appropriate messages is an integral part of
PB. If you use only the built-in select equations, your station will
automatically get complete copies of all short (< 10 kbytes) bulletins
and all mail addressed to you. By re-defining the select equations
"auto" and "priority," you can select virtually any subset of messages
on the satellite for automatic downloading. Downloaded messages will end
up in the satellite's subdirectory, with file names xxxxxxxx.DL, where
"xxxxxxxx" is replaced by a hexadecimal representation of the messgage
number.

You will want to process messages after the pass - removing their
satellite headers (PACSAT File Headers or "PFHs"), decompressing them,
and perhaps moving them to different parts of your hard disk and running
other programs.

6.1 Automatic Exit

You will need to exit PB after each pass for for your post pass
processing to begin. You can tell PB that you to automatically exit a
certain number of minutes after it last hears the satellite. This is
done with a line in the PB.CFG file:

exitafter x

where "x" is the number of minutes. If PB hears no data for "x" minutes,
and you haven't typed any keys, PB will exit.


6.2 Post Pass Processing

During a pass, PB can create a batch file to help with
this post processing.

To turn on the batch file generation, put the line "makebat 1" into your
PB.CFG file. This tells PB to make an entry in the file "POSTPASS.BAT"
for every downloaded file. Each entry in POSTPASS.BAT is in the form

call dofile xxxxxxxx

where xxxxxxxx is replaced by the message number in HEX. This allows you
to write your own batch file called DOFILE.BAT which then actually
processes the messages.

We believe that this is much simpler than attempting to process the
messages by using the DOS batch file directive

"for %a in (*.dl) do <command>"

An example DOFILE.BAT file is included with the PB release. This shows
how you can use the utility PFH_VAL to find the values of various header
items and process the .DL file based on these values. The example
DOFILE.BAT only properly processes uncompressed text messages and text
messages compressed by PKZIP. You will want to customize DOFILE.BAT for
your own uses.

Note that by leaving a text file called file xxxxxxxx.MSG or a PKZIP
file called xxxxxxxx.ZIP in the subdirectory MSGS, you can take
advantage of PB's built-in file view feature.

You can customize the contents of the POSTPASS.BAT file by using "bats1"
and "bats2" lines in your PB.CFG file. "bats1" should be set to a string
which will replace "call dofile" in the POSTPASS.BAT entries, and
"bats2" will be placed after the message number in each entry. For
example, having the lines

bats1 'call myprog'
bats2 '.dl'

in your PB.CFG will cause the POSTPASS.BAT entries to look like:

call myprog xxxxxxxx.dl

Note that strings for bats1 and bats2 are enclosed in single quotes.


6.3 Putting It Together

To put all of this automation to work, you must run PB from a batch file
constructed for your particular station. An example called RUNPB.BAT has
been provided in the PB release. This file first runs PG to take care of
any uploading, then runs PB, and then calls POSTPASS to handle any
new .DL files.



7  GUIDE TO FILES

PB.EXE          The main executable program.
PFH_VAL.EXE     A program used to extract PFH values as errorlevels.
PHS.EXE         A program used to display and remove PFHs from .DL files.
PFHADD.EXE      A program used to add PFHs to files for uploading

nnnnnnnn.DL     A downloaded message number nnnnnnnn WITH ITS PFH ON.

PB__nnnn.PFH     Contain PFHs used for directory view. Higher numbers are
               newer files. Not all files need be present. Don't use any
               other file names matching PB__????.PFH.
PFHDIR.HOL      Contains the list of "holes" missing from your directory.

SLIST.DAT       Contains entries for the 1000 messages most recently
               downloaded, marked for downloading, or marked N. Each entry
               is 16-bit message number, 16-bit status, 16 bit timestamp.

nnnnnnnn.ACT     Contains fragments of message nnnnnnnn.
nnnnnnnn.HOL     Contains a list of holes missing from message nnnnnnnn.

PB.LOG          Contains a station performance log.
PBERROR.LOG     Contains critical error reports.
PBDEBUG.LOG     Contains debug information.
yymmddhh.KSS     Contains raw KISS frames as received from your TNC.
POSTPASS.BAT     A file created by PB for post-pass use.
DOFILE.BAT      A file supplied with PB or customised by you to process a
               single .DL file.
RUNPB.BAT       A file showing how to automate station operation, assuming
               you have some way of detecting the times of passes and
               execute RUNPB.BAT.
PB.EQN          A file supplied with PB or customised by you containing
               select equations.


8  A FINAL NOTE

This software and documentation Copyright (C) 1991, 1992 Surrey
Satellite Technology, Ltd.

The PB software was written by engineers working for Surrey Satellite
Technology (SSTL), which is a company formed by the UoSAT Unit and the
University of Surrey to fund UoSAT missions and research into low-cost
satellite technology. This software is provided free-of-charge for use
by amateurs on amateur satellites because UoSAT and SSTL were founded by
radio amateurs and have always worked closely with AMSAT-UK.

Although you pay nothing for this software, it was fairly expensive to
develop. AMSAT-UK supports the UoSAT Unit with periodic donations toward
specific projects, and we strongly encourage you to support AMSAT-UK and
your national AMSAT group. Contact AMSAT-UK at

94 Herongate Road
Wanstead Park
London, E12 5EQ
United Kingdom.

This software may not be used for communications by non-amateurs or
outside the amateur bands without the explicit consent of:

Surrey Satellite Technology Limited
Senate House
The University of Surrey
Guildford,
Surrey, GU2 5XH
United Kingdom.

This software must be distributed free-of-charge, with the sole
exception that the distributor may recover the cost of disks and
postage.