html/newprot.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2     "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html">
   6   <title>DXSpider Protocol</title>
   7   <meta name="Keywords"
   8   content="DX Cluster, DXSpider, Spider, Packet Cluster, DXCluster, Pavillion Software, AK1A, AX25, AX.25, WWV, Packet Radio, Amateur Radio, Propagation, DX, DXing, G1TLH, GB7TLH, Dirk Koopman, Mailing list, Linux, RedHat, PERL">
   9   <meta name="Description"
  10   content="Software and systems for realtime digital communications between amateur radio stations for the provision of information on propagation conditions and stations operating">
  11   <meta name="Author" content="Dirk Koopman G1TLH">
  12   <link rel="stylesheet" href="style.css" type="text/css"
  13   title="default stylesheet">
  14 </head>
  15
  16 <body>
  17 <hr>
  18
  19 <h2>DXSpider Protocol</h2>
  20 <hr>
  21 <address>
  22   <a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a>
  23 </address>
  24 <!-- standard footer -->
  25
  26
  27 <h3>Introduction</h3>
  28
  29 <p><br>
  30 For some time now it has become obvious that the original AK1A protocol has
  31 become stretched to beyond breaking point. Some attempts have been made to
  32 extend it, but none have done what is actually required: which is to throw it
  33 away completely and start from scratch.</p>
  34
  35 <p>This is an attempt at starting again.</p>
  36
  37 <h3>Design Criteria</h3>
  38 <ul>
  39   <li>The protocol shall be open, published and available for any author to
  40     use.</li>
  41   <li>The protocol shall versioned, to allow easy upgrade.</li>
  42   <li>The protocol shall be layered to allow the use of different transport
  43     mechanisms (eg: radio, UDP, TCP, multicast).</li>
  44   <li>Sentences in the protocol shall be capable of being verified as being
  45     unaltered.</li>
  46   <li>all sentences shall have an originating node, a serial number and a
  47     destination. These fields must not be altered by intermediate nodes.</li>
  48   <li>all sentences shall have similar fields in the same order.</li>
  49   <li>sentences shall be in latin-1 and must not contain any characters other
  50     than those between 0x20 and 0x7e. Any characters outside of this range
  51     will be HTML escaped (viz: converted into the form '%', hex digit, hex
  52     digit; eg: carriage return (0x0d) is converted to '%0D').</li>
  53   <li>There shall be a mechanism for verifying "sensitive" information and/or
  54     connections.</li>
  55 </ul>
  56
  57 <h3>Definitions</h3>
  58 <dl>
  59   <dt>&lt;callsign&gt;</dt>
  60     <dd>A callsign can contain the characters [0-9A-Z\-/]. It is always in
  61       upper case.</dd>
  62   <dt>&lt;nodecall&gt;</dt>
  63     <dd>A callsign of a node. It can contain the same characters as a
  64       &lt;callsign&gt;</dd>
  65   <dt>&lt;origin&gt;</dt>
  66     <dd>The callsign of the originating node, it is a &lt;nodecall&gt;.</dd>
  67   <dt>&lt;destination&gt;</dt>
  68     <dd>The callsign of the destination node, this could be a
  69       &lt;nodecall&gt; or empty (which implies that this is a broadcast).</dd>
  70   <dt>&lt;touser&gt;</dt>
  71     <dd>The callsign of a user to which this sentence is directed. It is a
  72       &lt;callsign&gt; or empty.</dd>
  73   <dt>&lt;fromuser&gt;</dt>
  74     <dd>The callsign of the user from which this sentence originally come
  75       came from. It is a &lt;callsign&gt;.</dd>
  76   <dt>&lt;serial&gt;</dt>
  77     <dd>The serial number of this sentence. It is a number between 0 and
  78     9999.</dd>
  79   <dt>&lt;time&gt;</dt>
  80     <dd>A time in standard 'time_t' format, the number of seconds since 00:00
  81       1st Jan 1970 (the 'epoch'), the output of the standard system 'time()'
  82       subroutine call in both unix and MS-Dos/Windows.</dd>
  83   <dt>&lt;minutes&gt;</dt>
  84     <dd>The number of minutes since the epoch. This is actually &lt;time&gt;
  85       / 60 with no remainder.</dd>
  86   <dt>&lt;flags&gt;</dt>
  87     <dd>A bit field containing various binary values.</dd>
  88   <dt>&lt;digit&gt;</dt>
  89     <dd>A character, representing a numeral, befween '0' and '9'.</dd>
  90   <dt>&lt;hex digit&gt;</dt>
  91     <dd>A character, representing a hexadecimal numeral (a value between
  92       0-&gt;15 [a nibble]), '0'-&gt;'9' and 'A'-&gt;'F'.</dd>
  93   <dt>&lt;field&gt;</dt>
  94     <dd>A part of a protocol sentence.</dd>
  95   <dt>&lt;freq&gt;</dt>
  96     <dd>A frequency, in kilohertz with an optional (single digit) decimal
  97       part (ie both 14001 and 14325.1 are valid).</dd>
  98   <dt>&lt;text&gt;</dt>
  99     <dd>Some text in ISO-Latin-1 in both upper and lower case.</dd>
 100   <dt>&lt;cs&gt;</dt>
 101     <dd>A checksum of two &lt;hex digits&gt;</dd>
 102   <dt>&lt;cr&gt;</dt>
 103     <dd>A carriage return character (0x0d)</dd>
 104   <dt>&lt;lf&gt;</dt>
 105     <dd>A line feed character (0x0a)</dd>
 106 </dl>
 107
 108 <p></p>
 109
 110 <h3>The Protocol</h3>
 111
 112 <p></p>
 113
 114 <p>Each protocol line is separate and distinct. This is a "datagram" style
 115 protocol. Each protocol line is called a "sentence" and begins with the
 116 string "DX" in upper case, followed by two digits. The sentence is terminated
 117 by a &lt;cr&gt; or a &lt;lf&gt; character or both. Internally, the
 118 terminating characters should be discarded completely and the sentence
 119 processed without.</p>
 120
 121 <p>The character set used shall be ISO-Latin-1, with only the characters 0x20
 122 -&gt; 0x7e permitted within a sentence. All other characters shall be "HTML
 123 Escaped" which is that they shall be replaced by the three character scheme
 124 of '%', &lt;hex digit&gt;, &lt;hex digit&gt;.</p>
 125
 126 <p>The sentence is split up into &lt;fields&gt; which are delimited by the
 127 '|' character (0x7c). If the '|' character occurs within a &lt;field&gt; it
 128 shall be replaced by the string '%7C'.</p>
 129
 130 <p>There is no intrinsic maximum length of a sentence. Having said that,
 131 there will be some underlying maximum lengths implied by the transport
 132 mechanisms employed. Because one of those transport mechanisms is likely to
 133 be AX25 in UI mode. It is recommended that broadcast sentences shall be no
 134 more than 200 bytes in length.</p>
 135
 136 <p>All sentences shall have a &lt;checksum&gt; in a separate &lt;field&gt; at
 137 the end. The checksum is simply the sum, modulo 256, of all the characters of
 138 the sentence except for the final &lt;field&gt; separator and the two &lt;hex
 139 digits&gt; of the checksum itself.  The purpose of the checksum is to check
 140 that no intermediate node has changed the sentence. It is assumed that the
 141 underlying transport mechanisms will deal with communications errors.</p>
 142
 143 <p>All sentences shall have an &lt;origin&gt;, a &lt;serial&gt; and a
 144 &lt;destination&gt; number. The &lt;destination&gt; can be empty which implies
 145 that this sentence is to be broadcast. The &lt;serial&gt; number is a global
 146 number, which is used for all sentences originating at a node, that is
 147 incremented modulo 10000, and is used to determine duplicate or out of date
 148 sentences.</p>
 149
 150 <p>So the generic form of a sentence is:-</p>
 151
 152 <p></p>
 153
 154 <blockquote class="code">
 155   DX99|&lt;origin&gt;|&lt;serial&gt;|&lt;destination&gt;|...|&lt;cs&gt;</blockquote>
 156
 157 <p></p>
 158
 159 <p>Some examples:-</p>
 160
 161 <blockquote class="code">
 162   DX01|GB7TLH|0|GB7DJK|DXSpider 1.48/53.287|DE450A30|F4<br>
 163   DX01|GB7DJK|345|GB7TLH|DXSpider 1.49/60.45|4532DA56|A1<br>
 164   DX11|GB7TLH|1||G1TLH|FR0G|164563|14001.1|Easy|53<br>
 165   DX10|GB7TLH|2||G1TLH|SYSOP|GB7TLH rebooting|4A<br>
 166   DX02|GB7TLH|3|GB7MBC|1|98012349|5D<br>
 167   DX02|GB7MBC|9356|GB7TLH|0|GB7DJK/0.76,GB7BAA/1.2|AE<br>
 168 </blockquote>
 169
 170 <p></p>
 171 <hr>
 172 <span class="copy">Copyright © 2001 by Dirk Koopman G1TLH. All Rights
 173 Reserved</span>
 174  <br>
 175 <span class="id">$Id: index.html,v 1.19 2001/04/17 20:44:11 g0vgs Exp
 176 $</span></body>
 177 </html>