pfh_spec.txt

               Pacsat File Header Definition

                                                
                          Jeff Ward, G0/K8KA
                      Harold E. Price, NK6K
                                               

                            ABSTRACT


     A flexible encoding method for PACSAT file headers is described, 
     and ``Mandatory'', ``Extended'' and ``Optional'' Headers are 
     defined.  These headers are supplied by the programs which send 
     files and/or messages to PACSAT, and by on-board programs which 
     build files/messages intended for downloading.  PACSAT file head-
     ers are present in all files stored on PACSAT.



1.0 BACKGROUND

PACSAT is a file and message switch, a BBS and a data generating device.  
Files may be generated by onboard processes such as telemetry gathering pro-
grams, SEU monitor programs, or imaging cameras.  Files will also be used to 
hold the messages in the PACSAT on-board BBS.  Files and messages will be sent 
and received by many nodes: forwarding gateways, individual user stations, 
command stations, and various on-board tasks.  To conserve on-board storage 
space and communications link time, files may be compressed by a variety of 
compression methods.  

To ensure that these files can be properly identified and processed, each file 
stored on PACSAT will begin with several header items.  Some header items will 
be present on every PACSAT file; these are described below as the Mandatory 
Header.  Another group of items must be present on all files which contain 
``messages''; these are described as the Extended Header.  Additional special-
purpose or user-defined items are described under the Optional Header.

The primary objectives of the PACSAT File Header standard are to 

(1) encode all header items in a standardized manner; 

(2) maintain complete separation between the file/message header and the 
file/message body; 

(3) provide for expansion through easy incorporation of additional header 
items.

1.1  Overview of the PACSAT File Header System

Every PACSAT file will start with the byte 0xaa followed by the byte 0x55.  
This flag is followed by the rest of the PACSAT File Header (PFH).  A valid 
PFH contains all of the items of the Mandatory Header (Section  3), and it may 
also contain all items of the Extended Header (Section 4) and any number of 
Optional Header items (Section 5).  All HEADER ITEMS are encoded using a 
standard syntax, described in Section 2.  

The PFH is terminated by a special header item, after which the file body 
begins.

Thus, there are 3 forms of PACSAT file header:

<0xaa><0x55><Mandatory hdr><Hdr end>

<0xaa><0x55><Mandatory hdr><Extended hdr><Hdr end>

<0xaa><0x55><Mandatory hdr><Extended hdr>[<Optional    Items> . . . ]<Hdr end>


2.0 PACSAT HEADER ITEM SYNTAX

All PACSAT file header items follow a single format, simplifying both specifi-
cation and implementation of the PACSAT File Header.  The format is:

<id><length>[<data> . . . ]
2.1 <id>
The id is a 2-byte integer in which the bits have the following meaning:

bit 15            0 this is an system-defined item.
                 1 this is an experimental, user defined item. 

bits 0-14         form the 15-bit unsigned binary number identifying the 
                 item.

The <id>, allows some 32,000 system-defined and 32,000 user defined items.  
<id> like all multi-byte integers is stored least-significant byte first.  
Refer to the PACSAT Data Specification Standards document for further informa-
tion.

2.2 <length>

This field is an 8-bit unsigned binary integer giving the number of <data> 
bytes present.  Even if the size of the data item is fixed, the length is 
still present.

2.3 <data>

The <data> bytes may hold any type of information.  

Encoding rules for system-defined items are found in this document.  User-
defined items may adopt any internal encoding agreed by all users of the item.

2.4 Presentation

The PACSAT File Header must always be transmitted without data compression, 
even if compression is applied to the body of the attached file.

2.5 Header Termination

The end of the PACSAT File Header will always be indicated by a header item 
with <id> 0 and <length> 0.  The byte sequence is 0x00 0x00 0x00.

3.0 THE PACSAT MANDATORY HEADER

The first two bytes of a PACSAT file should always contain 0xaa followed by 
0x55 to confirm that the file contains a PACSAT file header.  

The 0xaa, 0x55 sequence must be followed immediately by all items of the 
Mandatory Header.

Mandatory Header items must be present in order of ascending value of <id>.

When preparing files for uploading to PACSAT, groundstations must initialize 
header items as specified below.

3.1.1 file_number

id              :    0x01      
length          :    4
data            :    unsigned long file_number

<file_number> is a 4-byte unsigned serial number assigned to a file by PACSAT 
when the file is created.  This number uniquely identifies any file.  

Since the PACSAT file system makes no distinction between files and ``mes-
sages'', the file number is analogous to a message serial number.  

INITIALIZATION - Must be initialized to 0.

3.1.2 file_name

id              :    0x02      
length          :    8
data            :    char file_name[8]

<file_name> is the base name of the file as it is stored in the PACSAT file 
system.  If the name is shorter than 8 characters, it is extended on the right 
with ASCII spaces (0x20).

INITIALIZATION - Must be initialized to 8 ASCII spaces (0x20), allowing PACSAT 
to choose its own name for the file.  The <user_filename> Optional item can be 
used to communicate the file's native name to another user.  

3.1.3 file_ext
id              :    0x03      
length          :    3
data            :    char file_ext[3]

<file_ext> is a 3 character file name extension.  If the extension is shorter 
than 3 characters, it is extended on the right with ASCII spaces (0x20).

INITIALIZATION - Must be initialized to 3 ASCII spaces (0x20), allowing PACSAT 
to choose its own name for the file.  The <user_filename> optional item can be 
used to communicate the file's native name to another user.  

3.1.4 file_size      

id              :    0x04
length          :    4
data            :    unsigned long file_size

<file_size> is a 4-byte unsigned integer indicating the total number of bytes 
in the file, including the HEADER_FLAG, all HEADER_FIELD structures, and the 
file body.

INITIALIZATION - Correct <file_size> must be provided.

3.1.5 create_time    

id              :    0x05
length          :    4
data            :    unsigned long create_time

<create_time> is a 4-byte unsigned integer time-stamp telling when the file 
was created.  This time-stamp counts the seconds since Jan 1, 1970.
INITIALIZATION - If <create_time> is initialized to 0, PACSAT will set the 
time upon receiving the file header.  Otherwise PACSAT does not alter this 
item.

3.1.6 last_modified_time
id              :    0x06      
length          :    4
data            :    unsigned long last_modified_time


INITIALIZATION - If <last_modified_time> is initialized to 0, PACSAT will set 
the time upon receiving the file header.  Otherwise PACSAT does not alter this 
item.

3.1.7 seu_flag
id              :    0x07
length          :    1
data            :    unsigned char seu_flag


Files stored on PACSAT may experience Single-Event Upsets, caused by radia-
tion.  <seu_flag> is an unsigned 8-bit integer for which 3 values are current-
ly defined:

0 means there have been no Single Event Upsets detected in this file.  

1 means that one or more correctable Single Event Upsets have occurred and 
been corrected in this file.  It will be possible, though unlikely, that mul-
tiple SEU-caused bit errors in a file block will cause an improper correction.  
An overall file checksum is provided as additional protection.

2 means that an uncorrectable corruption was detected in this file.

INITIALIZATION - this item must be initialized to 0.


3.1.8 file_type

id              :    0x08
length          :    1
data            :    unsigned char file_type

<file_type> is an unsigned 8-bit integer indicating what type of data is 
presented in the file body.  Values for this item are defined in a separate 
document.  The value 0xff is reserved as an escape indicator, in which case an 
Optional item of type <file_description> must be provided.

INITIALIZATION - this item must be appropriately initialized. 

NOTE - It is intended that this item be used to limit the scope of message 
searches, therefore, values will be defined for important types of files such 
as: RLI/MBL compatible single messages, RLI/MBL compatible import files, VITA-
only messages, etc.  See Appendix A for details.

3.1.9 body_checksum

id              :    0x09
length          :    2
data            :    unsigned int body_checksum

A 16 bit checksum formed by adding all bytes in the file body into a 16 bit 
variable, ignoring overflow.  The <body_checksum> does not include the 
bytes comprising the PACSAT file header.

The <body_checksum> is primarily intended to detect mis-corrected multi-bit 
errors caused by Single Event Upsets in the PACSAT memory.

INITIALIZATION - The correct <body_checksum> must be supplied.

3.1.10 header_checksum

id              :    0x0a
length          :    2
data            :    unsigned int header_checksum

A 16 bit checksum formed by adding ALL bytes in PACSAT File Header, including 
the leading 0x55 0xaa sequence, into a 16 bit variable, ignoring overflow.   
This number is then stored as the <header_checksum>.  When calculating the sum 
the 2 <header_checksum> data bytes are assumed to be 0, and the <body_check-
sum> must have already been calculated.

The <header_checksum> is primarily intended to confirm correct header recep-
tion during file transfers.

INITIALIZATION - the <header_checksum> must be correctly initialized.

3.1.11 <body_offset>

id              :    0x0b
length          :    2
data            :    unsigned int body_offset

<body_offset> provides the byte offset of the first byte of the file body.  
<body_offset> is taken with respect to the first byte of the file, which has 
offset 0.  The byte at offset 0 contains the 0xaa marking the beginning of the 
PFH.  Note also that <body_offset> is equal to the length of the PFH, in 
bytes.

INITIALIZATION - <body_offset> must be correctly initialized.

3.2 Mandatory Header Summary

The PFH Mandatory header will be present on every PACSAT file.  When preparing 
to upload a file or message to PACSAT, groundstation software must create a 
valid Mandatory header and insert it at the beginning of the file/message.

4.0 THE PACSAT EXTENDED HEADER


The PACSAT Mandatory Header defined above is designed for file transfer.  It 
contains sufficient information to reliably upload and download PACSAT files, 
including transfers spread over several satellite passes.  It does not contain 
all the header fields which are desirable for forwarding BBS messages or for 
implementing a complex PACSAT end-user message system.  The additional header 
fields needed for these tasks are placed in the PACSAT file after the Mandato-
ry Header.  

A standard set of message-related header fields called the PACSAT Extended 
Header is described in this section.  All message files uploaded to PACSAT 
should contain both the Mandatory and Extended headers.  

If a Extended Header is present, it must immediately follow the final item in 
the Mandatory Header.

If any Extended Header item is present, all must be present.

Extended Header items must be present in order of ascending value of <id>, 
with the exception that multiple destinations are represented by multiple 
occurrences of items 0x14, 0x15, and 0x16.

4.1  Extended Header Summary

The Extended Header provides necessary information concerning the source and 
destination of a message file.  Source data is encoded in a variable-length 
<source> item, which can contain any type of identifier.  The AX.25 address of 
the station which uploaded the message is also provided, along with the time 
at which the upload was completed.  Destination data is provided in the same 
format, and provisions are made to allow a single message file to have several 
specified destinations.

Three other items useful for PACSAT message handling are defined: 
compression_technique, expire_time, and priority. 

4.2.1 source

id              :    0x10
length          :    variable
data            :    char source[]

<source> is an ASCII string used to identify the originator of the file/mes-
sage.  <source> can be a mixed-case string, containing any character from 0x20 
to 0x7e. 

INITIALIZATION - This item should contain the address of and possibly the 
route to the file originator.  Exact details of the use for this item must be 
agreed among parties using PACSAT for message forwarding.  

Stations using PACSAT as their ``home BBS'' are requested to use the form 
<call> @ OSCAR<num>, e.g. G0K8KA @ OSCAR14.

VITA will devise its own addressing scheme, which should be used by VITA 
groundstation software.

4.2.2 ax25_uploader

id              :    0x11
length          :    6
data            :    char ax25_uploader[]


Contains the ax.25 address of the station which uploaded the file.  The SSID 
is not included in this address.  If the callsign is less than 6 characters 
long, it will be filled to 6 characters by appending spaces (0x20) on the 
right.

INITIALIZATION - No initialization required.

4.2.4 upload_time

id              :    0x12
length          :    4
data            :    unsigned long upload_time

This field tells the time at which the upload was completed.  If the upload is 
still in progress, upload_time will be 0x0000.  <upload_time> is an unsigned 
integer counting the number of seconds since 0000 UTC Jan 1, 1970.

INITIALIZATION - Must be set to 0.  

4.2.5 download_count

id              :    0x13
length          :    1
data            :    unsigned char download_count


<download_count> is an 8-bit unsigned integer incremented each time the asso-
ciated file is successfully downloaded.  

INITIALIZATION - set to 0.

4.2.6 destination

id              :    0x14
length          :    variable
data            :    char destination[]

<destination> is an ASCII string used to identify the originator of the 
file/message.  <destination> can be a mixed-case string, containing any char-
acter from 0x20 to 0x7f. 

INITIALIZATION - PACSAT makes no attempt to interpret this item.  It must be 
initialized to an address which will be recognized by the station intended to 
download the message.  When addressing messages to stations using PACSAT as a 
``home bbs'', please use <callsign> @ OSCAR<num>, e.g. NK6K @ OSCAR16.

4.2.7 ax25_downloader

id              :    0x15
length          :    6
data            :    char ax25_downloader[6]

<ax25_downloader> is the ASCII address of the groundstation which has down-
loaded this file for the recipient specified in the immediately preceding 
<destination> item.

A <destination> item  must be immediately followed by an <ax25_downloader> 
item.

INITIALIZATION - Must be initialized to six ASCII blanks - 0x20.

4.2.8 download_time

id              :    0x16
length          :    4
data            :    unsigned long download_time

<download_time> is the time at which the message was completely downloaded by 
the immediately preceding <ax25_downloader> groundstation.  <download_time> is 
an unsigned integer counting the number of seconds since 0000 UTC January 1, 
1970.

An <ax25_downloader> item must be immediately followed by a <download_time> 
item.

INITIALIZATION - Set to 0.

NOTE - A message may have several intended destinations.  For each destina-
tion, the PFH Extended header must contain header items 0x14, 0x15 and 0x16.  
Multiple destinations are numbered in the order of occurrence; the first 
<destination> <ax25_downloader> <download_time> set is destination 0, the next 
destination 1, etc.

4.2.11 expire_time

id              :    0x17
length          :    4
data            :    unsigned long expire_time

<expire_time> is the time after which this file should be considered inactive.  
As with other timestamps, this field is an unsigned long integer counting 
seconds since Jan 1, 1970.  Expired files may be purged by the PACSAT when 
more free file space is needed.

INITIALIZATION - Groundstations may set this field in uploaded files, or may 
leave it set to 0.  If a groundstation-selected <expire_time> is within system 
limits, it will be retained, otherwise the PACSAT will choose its own 
<expire_time>.

4.2.12 priority

id              :    0x18
length          :    1
data            :    unsigned char priority

This field carries the message priority field.  Higher numbers are considered 
higher priority than lower numbers.  

INITIALIZATION - The groundstation must initialize this field.  Groundstation 
software should exercise some control over the user's abuse of this field, so 
that it retains some meaning in operation!  Over use of high priorities re-
duces the utility of this field.

5.0 OPTIONAL HEADER ITEMS

The Mandatory Header and Extended Header may be followed by any number of 
Optional Header items.  It is intended that any expansion of the PFH defini-
tion will involve only addition of Optional Items

Optional Header items need not be presented in increasing order of <id>.

5.1 System-defined Optional Header Fields

5.1.1 compression_type

id              :    0x19
length          :    1
data            :    unsigned char compression_technique

The body of a PACSAT message may be compressed to reduce the communications 
bandwidth and on-board storage required for the message.  Groundstations, and 
not PACSAT, must compress and de-compress PACSAT files.  

The <compression_type> item is a 1-byte unsigned binary integer.  Values are  
available for assignment to common compression schemes.  <compression_type> 
0xff is reserved as an escape code indicating that additional information is 
to be found in a <compression_description> item.

Currently assigned values can be found in Appendix B.

INITIALIZATION - If present, must be correctly set by the uploading station.  

5.1.1 bbs_message_type

id              :    0x20
length          :    1
data            :    char bbs_message_type

This field carries the single ASCII character used to indicate message type on 
RLI/MBL BBS messages.  

5.1.2 bulletin_id_number 

id              :    0x21
length          :    variable
data            :    char bid[]

The <bid> item holds an ASCII string uniquely identifying the file/message.  
This field is used by terrestrial BBSs to stop the duplication of flood bulle-
tins. 


INITIALIZATION - PACSAT will not itself initialize <bid> on an uploaded file.  
It is the responsibility of the uploading station to initialize this field, if 
the message is a bulletin intended for introduction into the Amateur Radio 
PBBS network.

5.1.3 title

id              :    0x22
length          :    variable
data            :    char title[]

This field carries the ASCII string message title.  Most messages will have a 
<title>, initialized by the user to indicate the contents of the message.  In 
some systems, this is called the Subject.

5.1.4 keywords

id              :    0x23
length          :    variable
data            :    char keywords[]

This field carries one or more ASCII keywords describing the file/message.  
Multiple keywords must be separated by at least one ASCII space character 
(0x20).

5.1.5 file_description 
id              :    0x24
length          :    variable
data            :    char file_description[]

The <file_description> item is used only if none of the system standard 
<file_type> values can adequately describe the file body.

A <file_description> item is up to 255 ASCII characters describing the format 
of the file body.  This field must be included if the <file_type> field in the 
Mandatory Header is set to 0xff.  

For example, an uploading station might set the <file_type> to 0xff and 
<file_description> to ``This body contains all of the files associated with a 
Ventura Publisher document''.

5.1.6 compression_description 

id              :    0x25
length          :    variable
data            :    char compression_description[]

A compression_description item is used when a non-standard method of file-body 
compression has been used.  

The item is up to 255 ASCII characters describing the method or (preferably) 
providing a reference to further information concerning the method.  The field 
must be present when compression_technique in the fixed portion of the Extend-
ed File Header is set to 0xff.

For example, an uploading station might set compression_technique 0xff and 
compression_description to ``Compressed using bmpack version 1.4, see file 
with title = ``BMPACK specification''.

5.1.7 user_file_name

id              :    0x26
length          :    variable
data            :    char user_file_name[]

This field is used by groundstations using PACSAT as a file switch to transfer 
named files.  The originating station places the desired file name in a 
user_file_name field, and the destination station uses this field as the name 
of the file after it has been received.  

This field is included in addition to the file_name field because the 
file_name field is strictly constrained by PACSAT (e.g. no two files may have 
the same file_name, and the name must be no longer than 8 characters with a 3 
character extension).  The file_name is used by PACSAT for internal purposes, 
and this item, user_file_name is used for end-to-end transparent communication 
of a file name.

6.0 Implementation Status

Files with these headers are currently in use on the PACSATs.  Additional 
system header items may be added from time to time, as well as file and com-
pression types.  To suggest new standard items, contact the authors.

Address comments to:

Telemail:            HPRICE or UOSAT
Compuserve:          71635,1174
Packet:              NK6K @ WB6YMH
                    or G0K8KA @ GB2UP
Internet:            71635.1174
                    @COMPUSERVE.COM
Mail:               Jeff Ward
                    UoSAT Unit
                    University of Surrey
                    Guildford, Surrey  GU2 5XH
                    UK

APPENDIX A - PACSAT FILE TYPES 

Unless explicitly stated, a file of any <file_type> can have a compressed 
body.  If the body is compressed, its PFH must contain the optional <compres-
sion_type> item.  The PFH is never compressed.

0x00           ASCII  text  file intended for  display/printing.  Not  Com-
               pressed.
0x01           RLI/MBL message body. Single message. 
0x02           RLI/MBL import/export file.  Multiple message.
0x03           UoSAT Whole Orbit Data 
0x04           Microsat Whole Orbit Data 
0x05           UoSAT CPE Data
0x06           MS/PC-DOS .exe file
0x07           MS/PC-DOS .com file
0x08           Keplerian elements NASA 2-line format
0x09           Keplerian elements ``AMSAT'' format
0x0a           Simple ASCII text file, but compressed.
0xff           ESCAPE - indicates that the message header includes a varia-
               ble- length body_description item (see below) describing the 
               body type, or providing a reference for further information.  
               This code will be used for new techniques, until they can be 
               assigned a formal identifier.



APPENDIX B - PACSAT COMPRESSION TYPES (PROPOSED)

0x00           body not compressed
0x01           body compressed using PKARC
0x02           body compressed using PKZIP

There is no intent to limit compression types to the IBM-PC.  The prototype 
implementation of the ground station software is PC based.