=head1 NAME
-DXSpiderWeb Orthogonal Communications Protocol
+DXSpiderWeb Orthogonal Communications Protocol
+
+$Revision$
=head1 SYNOPSIS
=head1 ABSTRACT
For many years DX Clusters have used a protocol which was designed
-for a non-looped tree of nodes. This has probably never, reliably,
-been achieved in practice; certainly not recently. This document
-describes a complete replacement for that protocol. It allows a
+for a non-looped tree of nodes. This environment has probably never, reliably,
+been achieved in practice; certainly not recently.
+
+There have always been loops, sometimes bringing the network to its
+knees. In modern usage, both in order to get some resilience and also
+to expedite information flow, we use internet based, deliberately
+looped networks with filtering. Whilst this works, after a fashion, there
+are all sorts of problems that the current PC protocol can never
+address.
+
+This document
+describes a complete replacement for the PC protocol. It allows a
fully looped network, is inherently extensible and should be simple
to implement (especially in perl).
However, as it is envisaged that most messages will be flood routed or,
in the case of directed messages (those that have L</To> and/or
-L</ToUser> fields) down all interfaces showing a route for that
+L</ToUser> fields) down some/most/all interfaces showing a route for that
direction, it is unlikely that messages will be lost in practice.
=head2 Field Description
=over
-=item Origin
+=item B<Origin>
This is a compulsory field. It is the name of the originating node.
The field can contain up to 12 characters in the set [-A-Z0-9_] in
The field must not be changed by any other node.
-=item TimeSeq
+=item B<TimeSeq>
This is a compulsory field. It is a 10 hexadecimal digit string which
-consists of a day no (1-31), seconds within that day (0-86399) [6
-hex digits] that are concatenated with a sequence number (0-65535)
-[4 hex digits] making the total of 10.
+consists of a day no (1-31),
+a flag to indicate NTP syncronisation in use,
+seconds within that day (0-86399) [total of 6 hex digits]
+that are concatenated with a sequence number (0-65535)
+[4 hex digits] making the total of 10 hexadecimal digits.
The date portion is constructed as:
- my $date = ((gmtime)[3] << 18) | (time % 86400);
+ my $date = ((((gmtime)[3] < 1) | $ntpflag) < 18) | (time % 86400);
The sequence number is simply an unsigned short (or 16 bit) number
starting at 0.
Each message originated at this node will increment the sequence
number.
-=item Hop
+=item B<Hop>
This is a compulsory field. It is the number of hops from the
originating node. It is incremented immediately on receipt and
silently drop incoming messages with a L</Hop> count greater than the
limit.
-=item FrmUser
+=item B<FrmUser>
This field is optional. It is the identifier of the originating
user. If it is missing then the message is
It can consist of up to 12 characters in the set [-A-Z0-9_]
in any order. Higher layers may restrict this further.
-=item To
+=item B<To>
This field is optional. It is a string of up to 12 characters
in the set [-A-Z0-9_] in any order.
it down more than one, likely looking, interface - depending on any
network policies that may pertain.
-=item ToUser
+=item B<ToUser>
This field is optional. It is a string of up to 12 characters
in the set [-A-Z0-9_] in any order. Higher layers may restrict
=head2 Examples
- # on link startup
- GB7TLH,3D02350001,0|HELLO
+ # on link startup from GB7BAA (both sides hello)
+ GB7TLH,3D02350001,0,GB7BAA|HELLO,Aranea,1.2,24.123
+ GB7BAA,3D02355421,1,GB7TLH|HELLO,Aranea,1.1,23.245
- # on user startup
- GB7TLH,3D042506F2,0,G1TLH|HELLO
+ # on user startup to GB7TLH
+ GB7TLH,3D042506F2,0,G1TLH|HELLO,PClient,1.3
# on user disconnection
GB7TLH,3D9534F32D,0,G1TLH|BYE
GB7TLH,1512346543,0,G1TLH,GB7DJK,G7BRN|PING,35DE
# A possible reply, same ID as ping followed by the no of hops on the
- # received ping
+ # ping that was received
GB7DJK,1512450534,3,G7BRN,GB7TLH,G1TLH|PONG,35DE,3
The L</Command Section> of the message contains the actual data being
passed. It is called the Command Section because all commands
-are identified with a L</Tag> which is implemented by
-the software using this protocol.
+are identified with a L</Tag> each of which is implemented by
+the software using this protocol. Each </Tag> (usually) is followed by one
+or more L</Fields>.
+
+=head2 Tag
+
+The L</Tag> consists of string of uppercase letters and digits, starting
+with a leading, uppercase, letter. Tags should be as short as is meaningful.
+
+Valid tags would be:
+
+ DX
+ PC23
+ ANN
+
+Invalid tags include:
-The L</Tag> is separated from its data by a comma ','. All fields
+ 1AAA
+ dx
+ Ann
+
+The L</Tag> is separated from its data L</Fields> by a comma ','.
+
+=head2 Fields
+
+All fields
in any subsequent data shall be separated by a comma ','.
All fields shall
be HTTP encoded such that reserved characters (comma ',',
There is no maximum size specified for a message. It is up to each
implimentation to enforce one (if only for their own protection).
-=head2 Tag
+=head2 Standard Commands
-The L</Tag> consists of string of uppercase letters and digits, starting
-with a leading, uppercase, letter. Tags should be as short as is meaningful.
+There are a number of L</Standard Commands> which must be accepted by
+all implementations.
-Valid tags would be:
+=over
- DX
- PC23
- ANN
+=item B<HELLO>
-Invalid tags include:
+ HELLO,<software name>,<version>,<build>,<comments>
- 1AAA
- dx
- Ann
+Command sent on connection to another node. Both sides send their information
+to the other. All the possible arguments are optional, although some of the
+arguments should be sent in order to help diagnose problems. This command is
+broadcast.
-=head2 Standard Commands
+=item B<BYE>
-There are a number of L</Standard Commands> which must be accepted by
-all implementations.
+ BYE,<comments>
+
+Command sent to all connections when the software is shutting down. This is sent
+by the node just before shutdown occurs. This is really only used to help the
+network prune its routing tables. It isn't a requirement. The <comment> field
+is optional.
+
+=item B<DISC>
+
+ DISC,<node name>,<comments>
+
+Command sent when a node has disconnected from this node. This message is sent when
+an interface shuts down. It need not be sent if a L<BYE> from an interface for
+that node has just been received. This command should be broadcast.
+
+The <node name> is mandatory and is the name of the interface that has just
+disconnected.
+
+=item B<PING>
+
+ PING,<ping id>
+
+Command to send a ping to a node or user. This command is used both by the software
+and users to determine a) whether a node or user exists and b) how good the path is
+between them.
+
+The <ping id> is a unique string which is usually the hexadecimal equivalent of an
+integer that is incremented every time it is used. But it can be anything that
+will identify this ping using the tuple (L<Origin>,<ping id>) as unique.
+
+=item B<PONG>
+
+ PONG,<ping id>,<no of hops on ping>
+
+Command to reply to a ping. This is sent as a reply to an incoming ping command.
+The <ping id> is the one supplied and the <no of hops on ping> is the number of
+hops it took for the ping to arrive.
+
+=item B<T>
+
+ T,<text>
+
+All implementations must be able to send "text" (encoded as specified in
+L</Fields>). There would be little point in doing all this otherwise!
+
+=back
=head1 AUTHOR
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
+$Revision$
+
=cut
projects / spider.git / blobdiff