"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 [-] Your station callsign. is 6 or fewer ASCII characters. is an optional number from 1 to 15. Please do not use an unless you have a very good reason. alias - or - myaddr 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 "J.W.Ward@ee.surrey.ac.uk." The maximum length of the alias is 40 characters. bdcstcall [-] 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 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 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 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 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 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 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 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 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 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 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 Default 0 Little general importance. Allows you to set a multidrop KISS address. txd Default 150 msec This is the number of msec between the keying of your transmitter and the transmission of data. paclen 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 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 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 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 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 entries in your directory to find out if this is true. maxpfhsize 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 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 " 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.