Introduction 
============

Scope

This note describes the sixth release of PB and  PG for Linux. It 
comprises PB version 1.5, PG version 1.2, some utilities to manage the 
download request list, and a test program SendKiss that may be used to 
send synthetic traffic into a socket.

The present release has been tested on kernel version 2.2.14 and libax25. 

History

PB and PG for Linux are based on the program XPB and XPG which are 
released as parts of the Microsat Suite, originally developed by John 
Melton, G0ORX/N6LYT and now maintained by Jonathan Naylor, G4KLX. XPB and 
XPG run in the X-Windows environment.

XPB and XPG in turn are based on the specifications for PB and PG for MS-DOS.
PB and PG were developed circa 1992 by Jeff Ward, G0/K8KA, then at Surrey 
Satellite Technology Ltd., a company with root in the University of Surrey, 
the birthplace of the UoSATs. Much of the functionality found in these 
programs is present in PB and PG for Linux. The user interface of the 
Linux programs bears heavy resemblance to the user interface of the 
original programs.

Rationale

The existence of PB and PG for Linux is due to a decision in the OZ7SAT 
PacSat group. The goal of this group is to develop an automatic ground 
station for use with the digital satellites. Linux was chosen as the 
platform for the ground station after a MS-DOS based solution proved 
unwieldy and then the rest of the decisions followed almost automatically: 
XPB and XPG were tried but did not have the needed features for unattended 
operation (automatic up- and download requests, persistent requests for 
directory fills, etc.) and the X environment gave a considerable overhead 
which was not needed when running unattended. It was then decided to 
extract the functional part from XPB and  XPG, remove the X interface and 
add the required automatic features. The major part of the XPB conversion 
was done by Peter Scott, OZ2ABA while yours truly (Bent Bagger, OZ6BL) 
converted XPG and added the final touches to PB.

Functional Description
======================

Both PB and PB communicate using sockets. This means that the programs may 
be running simultaneously and that e.g. 'listen' may running at the same 
time. Using the -a option with 'listen' will also display outgoing packets.

PB

PB is used for download of files from the digital satellites (AO-16, 
LO-19, KO-23, etc.) and features automatic directory updates, rules based 
download of files and commands for manually requesting download of wanted 
files. PB uses the broadcast protocol, an AX.25 application developed 
specifically for the pacsats.

As PB 'listens' to the transmissions from the satellite, it receives all 
broadcast packets and builds directories and partial files in the current 
directory. If the contents of the 'subject' line of a directory entry 
matches the download request file (see later), PB sends a download request 
for the particular file to the satellite. This download request may also 
be forced with the utility 'filerequest' (see later). Partially downloaded 
files are stored with the extension .act. When the file is complete, the 
extension is changed to .dl. Information on the missing parts (the 
'holes') is stored in a file with the extension .hol. Directory entries 
are stored in files having names such as pb__001.pfh. The file pfhdir.hol 
contains a list of the 'holes' in the directory. Each directory file is 
approx. 25 KB long.

PG

PG is used for upload to the satellites and it uses the FTL0 protocol for 
the upload.

Files for upload must have a proper FTL0 header added. This can be done 
with utilities such as PFHadd or PHS (not distributed with this release). 
Also, a file for upload must be given the extension .out.

When launched, PG scans the current directory for partially uploaded files 
(files having extension .pul) and new files to upload (files with 
extension .out). It then tries to establish a link to the satellite, either
immediately or, if so configured with the MAXWAIT parameter, when it hears
the satellite. If successful, the file is uploaded and PG searches the current
directory for the next file to upload. If unsuccessful, PG waits for a 
BBSTAT message with contents 'Open'. When this message is heard, the  
program re-attempts to establish a link to the satellite.

This continues until either all files are uploaded or nothing is heard 
from the satellite within a configurable time. In both cases the program 
terminates normally.

A successfully uploaded file is given the extension .ul.

Installation
============

The distribution tar file is placed in a suitable directory, e.g. 
/usr/local/src and unpacked:

	tar xzvf pbpg-1.5.tar.gz

The files from the distribution are now located in directory 
pb_pg-1.4. The SendKiss utility is placed in a subdirectory SendKiss.

Now run 'make' and 'make install'

The latter command will - assuming you do it as 'root' - install PB and 
PG in /usr/local/bin. Note that the UID bit is not set and that both
PB and PG must by run as 'root' as root priviledges are needed for some socket 
operations in the programs.

Run-time Setup
==============

Both PB and PG work on the current directory only. It is recommended that 
you have a separate directory for each satellite you want to access. The 
configuration files are satellite specific and a copy of the configuration 
files must be placed in each directory.

The supplied configuration files may be used as a starting point. Change 
at least my callsign in MYCALL to yours in pb.conf and pg.conf. The 
callsign used for MYCALL must match a callsign for one of the ports 
configured in /etc./ax25/axports.

Configuration File Format
=========================

pb.conf
-------

The sample file supplied in this release is this:

	SATELLITE	PACSAT	
	SATNAME		AO-16
	MYCALL		OZ6BL
	MAXDAYS		5
	UDPPORT		5100
	KISSLOG		yes


The meaning of the parameters is:

SATELLITE <call>

<call> identifies the satellite you want to communicate with. The 
callsigns valid at the time of writing (September 1999) are: 

	Satellite Callsign
 	AO-16     PACSAT
 	LO-19     LUSAT
 	UO-22     UOSAT5
	KO-23     HL01
 	KO-25     HL02
 	IO-26     ITMSAT
 	FO-29     8J1JCS
	TO-31     TMSAT1

SATNAME <satellite name>

This is a descriptive text which is placed in the background frame on the 
screen. 

MYCALL <callsign>

Used as source address in packets sent to the satellite. Must match a 
callsign in one of the ports configured in /etc./ax25/axports.

MAXDAYS <no of days>

Directory entries older than <no of days> will be ignored by PB

UDPPORT <port number>

PB listens on this port for controlling commands. Presently the only 
command implemented is the quit command. The program 'stoppb' may be used 
to send this command. Using this command rather than Ctrl-C assures that 
all files are closed and that the statistics are written to the log file.

KISSLOG <any parameter>

If this parameter is present, a KISS log file is written to disk. The file 
is given a name of the form yymmddhh.kss, e.g. 97061918.kss for a KISS log 
file created on June 19, 1997 between 18:00 and 19:00 UTC.

The parameters SATELLITE and MYCALL are required, the rest are optional 
and have the following defaults:
	SATNAME: null
	MAXDAYS: 5
	UDPPORT: 5100
	KISSLOG: no KISS log generated

pg.conf
-------

The configuration file supplied with this release is this:

	SATELLITE	PACSAT	
	SATNAME		AO-16
	MYCALL		OZ6BL
	MAXIDLE		30
	MAXWAIT		0

The parameters SATELLITE, SATNAME, and MYCALL have the same meaning as 
listed for pb.conf.

MAXIDLE <seconds>

Determines how long PG will wait without hearing anything from the 
satellite before exiting. The default value is 60 seconds.

MAXWAIT <seconds>

If present and nonzero this parameter will cause PG to wait until it 
actually hears the satellite before it attemps to establish a 
connection to the satellite. The parameter sets the maximum wait period. 
PG exits if the wait expires without hearing the satellite.

Command Line Options
====================

Most of the parameters of the configuration files may be overridden by 
command line options. The options are:

pb [-s satellite] [-m mycall] [-n satname] [-M maxdays] [-U UDPport] [-k kissfile][-v]

pg [-s satellite] [-m mycall] [-n satname] [-i maxidle] [-a maxWaitforAOS] [-v]

Keyboard Input
==============

PB honors a few single stroke keyboard commands:

Q or q: quit - terminate normally
D or d: send a directory fill request to the satellite
R or r: re-initialize download control
t:      (toggle) trace the incoming packets
T:      (toggle) expanded trace
U or u: refresh (update) the screen

PG has no keyboard commands.

Automatic Download Request Format
=================================

PB has facilities for automatic request of file downloads. The list of 
files to be downloaded is kept in a file named 'download.req'. The 
autorequest file 'autoload.dat' defines which files should be 
automatically downloaded. It has the following format:

<destination> <source> <title> <keyword> <size> 

where the fields are separated by white space.

The first four fields are used for substring searches (strstr) in the 
following PACSAT file header items:

	<destination>:	destination (the To: field)
	<source>:	source (the From: field)
	<title>:    	title (the Subject: field)
	<keyword>: 	keywords

The <size> field sets an upper limit on the size of the file in question.

A sample file is supplied with this distribution:

	OZ6BL	*	*	*	0
	*	OZ6BL	*	*	0
	*	*	DSP-12	*	0
	ALL	*	*	*	10000

This autoload file will request all files to and from OZ6BL, all files 
concerning the DSP-12 modem and all files addressed to ALL and being less 
than 10 KB long.

Note that an asterisk is used as a 'don't care' character.

If autoload.dat is absent, no files will be downloaded automatically and a 
file with the following line

	*	*	*	*	0 

will download (or try to download) all files from the satellite.

The routines for download control are placed in file download.c. If desired,
these routines may be replaced by other routines. The only requirement is
that the interface conventions - including the routine names - must be
adhered to.

Facilities for re-initialization of the download control are provided: A
keyboard command ('r'); sending a SIGHUP signal to PB; using program 
'download_init'.

'download.req' Management
=========================

The file 'download.req' is automatically created and maintained by PB. It 
may, however, be manipulated by the operator by means of the following 
utilities:

	filerequest <fileID>
	filecancel <fileID>
	filelist
	filecheck <fileID>

<fileID> is the hexadecimal file number assigned to a file by the 
satellite. It is the number used in directory entries.

'filerequest' adds the named file to the list of files to download from 
the satellite.

'filecancel' deletes the named file from the list.

'filelist' provides a list of all files present in the download request 
file.

'filecheck' provides information on whether or not the named file is 
present in the list.

Log Files
=========

Both PB and PG writes entries to log files. The entries are appended to 
the log files.

pb.log

On exit PB writes a log entry to the file 'pb.log' The entry tell the 
start and end time of the pass (or rather when the first and last packet 
were heard from the satellite); the total number of bytes received during 
the pass; how many of these bytes were files, directory entries and 
telemetry respectively; the download throughput averaged over the entire 
duration of the pass; and the number of CRC error encountered on the input.

pg.log

PG appends a log entry for all state changes and error situations to 
'pg.log'. Each log entry is time stamped.

The SendKiss Utility
====================

SendKiss is a small test program I wrote when I tested PB and PG. It takes 
a KISS log file as produced by e.g. PB and writes its contents into a 
socket in such a way that other programs connected to the socket believes 
that the data actually arrives from the satellite. I needed the program 
because I did not have the patience to sit and wait until an actual 
satellite arrived at my QTH.

SendKiss is based on the mkiss utility. Thanks to Jonathan, G4KLX for 
giving me the hint.

The best way to use SendKiss is to use the script start-test, which should 
be pretty self explanatory.

A sample KISS log file is included in this distribution.
