PROTOCOL.txt 7.7     APRS ON-AIR PROTOCOLS and FORMATS


COPYRIGHT 1992,93,94,95,96:  Amateur radio operators may freely copy and 
use APRS in the Amateur Radio Service.  I have tried to make APRS fully 
capable of receiving and plotting ALL on-the-air packets whether a station 
is registered or not.  The registration contribution only balances the 
headache factor, and to cover myself against un-licensed commercial 
exploitation.  What you get for registering is the ability to interface 
your OWN GPS/WX/DF units and a little convenience in saving your 
configuration.

These APRS formats are provided for use in the amateur radio service.  
HAMS are encouraged to apply the APRS formats in the TRANSMISSION of 
position, weather, and status packets.  However, the author reserves the 
ownership of these protocols for exclusive commercial application and for 
all reception and plotting applications.  APRS is a trademark of Bob 
Bruninga.  Other software engineers desiring to include APRS RECEPTION in 
their software  for sale within or outside of the amateur community will 
require a license from the author.  Also TRANSMISSION of APRS protocols 
in any NON-AMATEUR commercial application or software will require a 
license from the author.  See COMMERCL.txt

     APRS uses UI frames which retain all of the error detection capability 
of standard packets, but without acknowledgment.  In APRS, collisions or 
lost packets are not a problem since information is redundantly transmitted 
(AND effeciently! due to the decaying transmission periods).  UI packets 
are the same type that are sent by a TNC using BEACON and BText commands.  
NOTE, however, that the APRS UI packets are generated internally in the 
APRS software and the TNC BText is not used while APRS is running.

     APRS uses the TNC UNPROTO command to setup the path for the trans-
mission of each packet.  But when we refer to the  UNPROTO command in APRS, 
we are refering to the APRS UNPROTO or OPS-UNPROTO command which then in 
turn issues the hardware UNPROTO commands to the TNC.

TO ADDRESS:   Since APRS operates in a broadcast fashion and does not use 
a connected protocol, the TO ADDRESS is not required.  To help APRS ignore
other non-APRS traffic on the channel, APRS will normally only recognize 
UI packets transmitted to the generic addresses of ID, CQ, QST, BEACON, 
MAIL, SKYWRN, GPS, DFNET, SPCL, TEST, DRILL and APRS.  All other packets 
are ignored.  You can override this filter with the CONTORLS-OTHER command. 
There is also a alt-SETUP-MODES-SPECIAL command which turns off all of the 
above acceptible TO calls and will only accept packets addressed TO: SPCL.  
Similarly, these stations all transmit using the UNPROTO path of SPCL via 
XXXX...  This makes it easy for a sub-group of APRS users to operate a 
special event on the same frequency as other APRS users, but to not be 
encumbered with all of their traffic.  ALso you may use the alt-S-MODES-
altNet to set up a private subnet on an APRS frequency.

APRS FORMATS:  In the following APRS on-air formats, the abbreviations are 
D for degrees (or DAY), M for minutes (Both lat/long and time), h for 
hundredths (or Hours), N for North and W for West.  The APRS symbol is
identified by the character following the Longitude (shown here as a $).  
See SYMBOLS.TXT.  There are three types of time for local, zulu and hhmmss.  


POSITION REPORT:  The first character determines the position report format
except for the FIXED format which may occur anywhere in the packet.  If the
posit begins with @, M or W then either APRS, MacAPRS or WinAPRS is running.
If only a TNC is running, then a / indicates that there is no APRS messaging
capability on line.  In this case, the date-time means the time that APRS
was last running.

FIXED:      ...    !DDMM.hhN/DDDMM.hhW$comments...   (See DIGIS.txt)

TNC:        /DDHHMM/DDMM.hhN/DDDMM.hhW$comments...   (no APRS is running)
MOBILE:     @DDHHMM/DDMM.hhN/DDDMM.hhW$CSE/SPD/comments...
DF:         @DDHHMM/DDMM.hhN/DDDMM.hhW\CSE/SPD/BRG/90Q/Comments ( Q=quality)
            .......z............................. (indicates Zulu date-time)
            ......./............................. (indicates LOCAL date-time)
            .......h............................. (Zulu time in hhmmss)
GRDSQR:     [XXnnyy]comments to end of line
            [XXnn]comments to end of line
W3AB>FM19SX:Hello there....                       (Space/MScat/Grid-SQ mode)
W3AB>FM19SX:]$[Hi there....                       (Space/MScat with stn symbol
POWER:      ..........................$PHGabcd... (Power,ant/height/Gain.  

OMNI-DF:    ..........................\DFSxbcd... (Same as PHG, but x=sig str)
       
RTTY:       APRS DE WB4APRx/011427/3859.11'07629.11($ ...   This  format
uses only the RTTY subset of the ASCII alphabet where ',)( mean N,S,E & W,
and the x is an SSID number and the $ is the APRS symbol character.  The
... comment field can contain the normal APRS CSE/SPD.  The callsign must
be padded to six spaces.  To enable parsing of this format, use alt-A.


POWER-HEIGHT-GAIN:  This optional field replaces the CSE/SPD fields with a
report of transmitter power, antenna height-above-average-terain and their
antenna gain.  With this information, APRS can plot communication range
circles around all stations.  The following details the format to be used 
in the BText of a TNC dedicated as an APRS digipeater:

    !DDMM.mmN/DDDMM.mmW#PHG5360/WIDE...(identifying comments)...
      |         |      | | ||||  |_____ makes station show up green
      |         |      | | ||||________ Omni (Direction of max gain)
      |         |      | | |||_________ Ant gain in dB
      |         |      | | ||__________ Height = log2(HAAT/10)
     LAT      LONG     | | |___________ Power = SQR(P)
                       | |_____________ Power-Height-Gain identifier *
                       |_______________ # is symbol for digipeater

     As you can see by the integers in the PHG string, there are only 10
     possible values for each of these fields as follows:

     DIGITS   0  1  2   3   4   5   6    7    8    9         Equation
     -------------------------------------------------------------------
     POWER    0, 1, 4,  9, 16, 25, 36,  49,  64,  81  watts  SQR(P)
     HEIGHT  10,20,40, 80,160,320,640,1280,2560,5120  feet   LOG2(H/10)
     GAIN     0, 1, 2,  3,  4,  5,  6,   7,   8,   9  dB
     DIR      0,45,90,135,180,225,270, 315, 360,   .  deg    (D/45)

     The DIRECTIVITY field offsets the PHG circle by one third in the
     indicated direction.  This means a front to back range of 2 to 1.
     Most often this is used to indicate a favored direction or a null
     even though an OMNI antenna is at the site.  Note that 0 means
     OMNI and 8 means 360 or a NORTH offset.

     THESE HIGHTS are ABOVE-AVERAGE TERRAIN!  Not above ground or sea
     level.  Your antenna may be at 1000 ft above sealevel and be on 
     a 100 foot tower.  But if you go out 10 miles in all directions
     and find that the average elevation is 1100 feet, then your
     height-above-averag-terain is ZERO!!!!


OMNI-SIGNAL-STRENGTH DIRECTION FINDING REPORT:  Since APRS can plot range 
circles around all stations, it can also localize jammers by simply 
plotting the overlapping signal strength contours of all stations hearing 
the signal.  This OMNI-DF format replaces the PHG format with DFS to 
indicate DF Signal strength, and the transmitter power field is replaced 
with the relative signal from 0 to 9.  The following beacon would
represent a weak signal heard on an antenna with 3 dB gain at 40 feet:

   @141923/3859,11N/07629.23W\DFS2230/comments

   A report with a signal of ZERO (0), is equally SIGNIFICANT beacuse 
   APRS uses these 0 signal reports to draw BLACK circles where the 
   jammer is KNOWN NOT to be.  These BLACK circles where the transmitter 
   IS NOT are VERY useful, since you will get a lot more reports from
   stations that dont hear the jammer than reports from those that do.  
   The black circles eliminate a lot of territority where the fox is NOT.


WEATHER REPORT:  APRS uses the underline symbol character for WX reports.
For these, the COURSE/SPEED field is used for the WIND and the remainder 
of the comment line contains other weather items.  See WX.TXT 

@DDHHMM/DDMM.hhN/DDDMM.hhW_CSE/SPDgXXXtXXXrXXXbXXXXhXXX/U2k
    r is in hundredths of an inch of rain in the LAST HOUR
    p is in hundredths of an inch of rain in the LAST 24 HOURS
    s is INCHES of snow in the last 24 hours
    b is in tenths of millibars
    h is percent humidity
    /U2k is Ultimeter 2000, /U5 is the 500 and /Dvs is Davis
    

OBJECT POSITION:  OBJECT reports are identical to POSITs except that the
posit is preceeded with a fixed nine character object name and a *.

    OBJECT___*DDHHMM/DDMM.hhN/DDDMM.hhW$CSE/SPD/comments...
    
ALL OTHER PACKETS:  Any packet that does NOT meet any of the above formats
is assumed to be just a status beacon and is placed on the LATEST list.  
This list is time stamped so the receiving station will know when that 
status or beacon was sent.

    @DDHHMM/comments...

MESSAGE:  Station to station messages use the following format, again 
padding the addressee call with spaces to a total of nine characters
followed by a colon:

    W3XYZ____:one line message text......{3 (the {3 is the line counter)

MSG ACK:   An ACK is just a message with the letters ACK# where the # is 
the message line number (following the { character at the end of the line).

    W3XYZ____:ack3

BULLETINS:   BULLETINs are simply messages to the call signs of BLN1, BLN2, 
... BLN#.  They will never be acked, but all APRS stations will capture
and sort them onto the special BULLETINS page.  Bulletins sent to BLN# will 
decay to very long periods but bulletins sent to BLNx will decay down to 
once every 15 minutes and stay at that rate. 

APRS QUERIES: APRS responds to several general queries:

     ?APRS? - All stations respond with all outgoing status, posits, OBJs
              and messages randomly over 2 minutes (4 on HF)
     ?APRS?LLLLLL,OOOOOO,RRRR - Only stations within RRRR miles of the
              LLLLLL Latitude and OOOOOO Longitude respond.  If RRRR is
              less than 8 (64 on HF) then respond immediately
     ?WX? -   All WX stations respond
     MYCALL...:?APRS? - Only the station MYCALL responds immediately

DF REPORTS:  The DF report includes a N0Q field in addition to the
position, course and speed of the vehicle plus the bearing line.
 
     @DDHHMM.xxN/DDDMM.xxW\CSE/SPD/BRG/N0Q/DF report...

     N0Q is a Quality indicator where Q is a quality value (1-8) amd
     N is an optional Number of HITS indicator. If N is 0, then it means 
     nothing.  Values from 1 to 8 give an indication of the number of 
     hits per period relative to the length of the time period.  So 8 
     means 100% of all samples possible, got a hit.  The N is not 
     processed, but is just another indicator from the automatic DF 
     units.  By entering a 9 as the HIT indicator, you can indicate to 
     other users that your report is manual.


DIGIPEATERS, NODES, BBS's AND ALL OTHER PACKET STATIONS:

Since APRS is a generalized position displaying tool, EVERY Packet TNC that
is permanently on the air, and that also transmits a periodic ID beacon,
should be reporting its position in that ID beacon!  This way, stations
monitoring can quickly see a geographical plot of the network.  If you want
to keep the exact location of your transmitter ambiguous, then use
the GRID-SQUARE format, and your position will be ambiguous to a few miles,
but stations can still see that you are on the air.  If you have special
formats for your BEACONS that contain variable information, then APRS is
perfect for grabbing that information and making it available to users...
If you have any uused aliases, set them to RELAY so others can find you.

