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.
Ritorna a Software Radioamatoriale by
IW3FQG