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

Scope

This note describes PB and  PG for Linux. The release comprises PB and PG, 
PBCTRL and some utilities to manage the download request list.

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 PG 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.

PB does not produce any visible output - except possible error messages. 
Instead it listens on a control FIFO (/etc/pbpg/pb-fifo).  If it receives 
a monitor command on this FIFO, it will begin transmitting status and other 
data on another FIFO specified in the monitor command. Please refer to the 
section on PBCTRL.

Details on the control of PB is found in the document 'Controlling_PB'.

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' from the PacsatTools package by John
Magliacane, KD2BD. Pfhadd will give the upload file the required 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.

PBCTRL
------

The program 'pbctrl' is one implementation of a program that exploits the
control FIFO mentioned earlier. The supplied pbctrl implements the functions
that previously were implemented by PB proper, i.e. it displays a running
account of what happens.


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

Please refer to file INSTALL


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

Both PB and PG work on the current directory only. The File Hierarchy Standard
(FHS) recommends /var/spool/pbpg for this. It is recommended that you have a 
separate directory for each satellite you want to access, e.g. 
/var/spool/pbpg/TO-31.

The configuration file is common to PB and PG. It is located in /etc/pbpg/. 

The supplied configuration file is installed as /etc/pbpg/pb.conf.example. 
Rename it to pb.conf and use it as a starting point. Change at least my 
callsign in MYCALL to yours. The callsign used for MYCALL must match a 
callsign for one of the ports configured in /etc/ax25/axports.


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

The sample file supplied in this release is this:

MYCALL		OZ6BL
MAXDAYS		5
KISSLOG		yes
MAXIDLE		60
MAXWAIT		0

Satellite	PACSAT
SATNAME		AO-16

SATELLITE	LUSAT
SATNAME		LO-19

SATELLITE	UOSAT5
SATNAME		UO-22

SATELLITE	HL01
SATNAME		KO-23

SATELLITE	HL02
SATNAME		KO-25

SATELLITE	ITMSAT
SATNAME		IO-26

SATELLITE	8J1JCS
SATNAME		FO-29

SATELLITE	TMSAT1
SATNAME		TO-31

SATELLITE	4XTECH
SATNAME		GO-32

SATELLITE	UO122
MAXDAYS		10
SATNAME		UO-36

It is divided into sections. The first section list the parameters that are 
considered station specific. They may be given satellite specific values in
one of the following sections as exemplified by MAXDAYS for UO-36. Each of
the following sections is headed by a line SATELLITE <callsign>.

The satellite of interest is defined either on the command line (parameter
-s) or by setting environment variable SATELLITE to the desired <callsign>

PB configuration parameters
---------------------------

The parameters that are valid for PB are exemplified by these:

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


The meaning of the parameters is:

SATELLITE <callsign>

<callsign> 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
	GO-32     4XTECH
	UO-36     UO122

SATNAME <satellite name>

This is a descriptive text which is placed in the background frame on the 
'pbctrl' 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>

MAXDAYS defines a time window from 'now' and MAXDAYS into the past. Broadcast
directory entries older than <no of days> will be ignored by PB

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. 2002061918.kss for a KISS log 
file created on June 19, 2002 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
	KISSLOG: no KISS log generated

PG configuration parameters
---------------------------

The following parameters are defined for PG:

	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.

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 attempts 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] 
   [-k kissfile][-v]

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


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

PBCTRL 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
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 
auto-request 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 
with the word "DSP-12" in the subject line 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' in pbctrl); 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. The log files are kept in the current directory.

pb.log

On exit PB writes a log entry to the file 'pb.log' The entry tells 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.

(version: $Id: README,v 1.10 2003/01/28 03:26:04 bent Exp $)

