                    XROUTER INTERIM DOCUMENTATION
                    =============================

                         APRS Messaging Shell
                         --------------------

               This revision dated: 14th November 2001


Xrouter contains an APRS messaging shell, which allows NON-APRS users
to exchange messages with APRS / UI-View users, and also to send and
read bulletins and announcements.

Messaging mode is initiated by from the main command prompt by
entering the command "AMSG <port>", where <port> is number of the
radio port on which messages will be sent and received.

Within messaging mode, all commands begin with a forward slash (/),
and anything else is treated as message text for transmission.  The
commands are as follows:

         /A[nnouncements]    Show announcements
         /B[ulletins]        Show bulletins
         /C[ancel] [#]       List / cancel unacked message(s)
         /D[irects]          Show directly heard stations
         /H[elp] [cmd]       Display command help
         /Monitor [on|off]   Query / set traffic Monitor mode
         /Q[uit]             Quit (exit)
         /T[arget] [call]    Query / set target for msg
         /U[iview] [on|off]  Query / set UI-View mode
         /V[ia] [digis]      Query / set digipeater path
         /X                  Exit

Only the first letter of each command needs to be supplied.  Most of
the commands are self-explanatory, but a few are worthy of further
explanation....

The /D command shows a list of all the stations heard directly, i.e.
not via digipeaters or 3rd party networks.

Before any type of message or query can be sent, the user must
specify a "target" address, using the "/T [call]" command.  For
messages, the target will be a callsign.  For bulletins the target
should be BLN#*, where "#" represents a single digit, and "*"
represents the bulletin category of up to 5 characters.  Announcements
use the same format as bulletins, except that "#" represents a non-
digit.  Attempting to send a message without first defining a target
will result in an error response.  The target remains in force until a
new target is specified.  The current target can be displayed by
entering "/T" alone, or cleared by entering an invalid target, e.g.
"/T .".

Outgoing messages and bulletins are re-transmitted at intervals until
either an acknowledgement is received, or too many retries have taken
place.  Bulletins are re-transmitted every 20 minutes for 4 hours,
whilst announcements are re-transmitted every hour for 4 days.
Messages are initially re-transmitted after 10 seconds, then the
interval doubles with each re-send.  When the interval exceeds
approximately 1.5 hours, the message is expired and re-transmission
ceases.  The "cancel" command allows the re-transmission of outgoing
messages and bulletins to be cancelled at any time before expiry.

The /M (Monitor) command allows other APRS and UI-View message traffic
on the channel to be watched.  The default is "off". Entering /M by
itself shows the current state.

The /U (Ui-View mode) command sets the type of outgoing message to be
used.  The default is "off", which means that all outgoing messages
will be in APRS format.  If turned "on", outgoing messages will be in
"UI-View" format.  In either mode, both types of message can be
received.  UI-View messages will display with a tilde (~) between the
message and its ID, whereas APRS-format messages will display with a
curly opening bracket ({) if a message ID was supplied.

/Q (quit) and /X (exit) are identical in function, exiting message
mode and returning the user to the router's main command prompt.

The /V (via) command sets the digipeater path for outgoing messages,
or if used by itself displays the currently set path.  The path
defaults to the port APRSPATH specified in XROUTER.CFG.  In APRS mode,
the destination call is fixed at APZ###, where ### is the 3 digit
router version number, whereas in UI-View mode the destination call is
set by the /Target command.

The /H (help) command is used to display help for the messaging
commands.  If no argument is supplied, a very brief (low bandwidth)
command resume is displayed.  If the help files are installed, "/H *"
will list the help available, and "/H <cmd>" can be used to obtain
more detailed help for <cmd>, e.g. "/H /V". Note that the leading
slash of the argument is ignored, so "/H V" is equally valid.


GENERAL NOTES

If Xrouter receives an APRS message whose target address is a user
currently logged into the APRS messaging shell, the message is
delivered to the user and, if there was a message ID, an
acknowledgement is sent.  Each re-send of the message is acknowledged,
because a re-send probably indicates that the sender didn't receive
the previous ack.

If the same message is received twice within 30 seconds, the second
copy is ignored.  This helps to eliminate duplicates received via
different digipeater routes.

Expired messages are retained for 1 day before being deleted.  During
this interval they will be reactivated if a "?APRSM" query (see below)
is received from the target station.  Outgoing bulletins and
announcements are not retained after expiry.  Incoming bulletins are
retained for 4 hours after last received, and incoming announcements
are retained for 4 days after last received.

The APRS spec limits the maximum message length to 67 characters.
Because a message ID of up to 6 characters is appended to the message,
Xrouter splits messages longer than 61 characters into separate
messages no longer than 61 characters (excluding ID) each.


APRS / UI-View queries
~~~~~~~~~~~~~~~~~~~~~~
Xrouter responds to the following general queries:

         ?APRS?     All stations query.

         ~\xFD~     UI-View general query.

         The response to both of these is the ID beacon for the port,
         which, if my recommendations were followed, should contain
         the APRS position and station type.


The following "directed" queries (directed at portcall) are supported:

         ?APRSD     Directly heard stations list.

                    Responds with a list of stations heard directly on
                    the receiving port (i.e. not via digipeaters or
                    via 3rd party networks)

         ?APRSM     Un-delivered messages query.

                    If there are any un-delivered or expired messages
                    addressed to the sender of the query, they are re-
                    activated and transmitted on the port which
                    received the query.

         ?APRSP     Station Position.

                    If the sysop has defined the router's position, it
                    is sent in response to this query.

         ?APRSS     Station status.

                    The response consists of the software type and
                    version, plus a list of the enabled generic
                    digipeater calls.

         ?PING?
         ?APRST     Trace Route.

                    Both of these return the route by which the query
                    was received.

         ~\xFE~n    UI-View "ping".

                    The response to this query is a UI-View ack for
                    the ping id.

         ~\FC~n     UI-View "DX" query.

                    Responds with a UI-View ack, followed by details
                    of the best DX heard directly by the router
                    (digipeated packets are NOT dx as far as I'm
                    concerned!)


Finally
~~~~~~~
Xrouter's APRS messaging facilities are an ongoing experiment and may
be liable to change as development continues.  I have never used a
"real" APRS program, and as I know virtually nothing about APRS other
than what I've gleaned from the so-called "Protocol Reference" (which
is rather fuzzy in places), and by observation of channel activity, I
am very willing to accept criticisms and suggestions.

73, Paula G8PZT

