contrib/ntp/html/driver18.htm

   1 <HTML>
   2 <HEAD>
   3    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   4    <META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (Win95; I) [Netscape]">
   5    <TITLE>NIST Modem Time Service
   6 </TITLE>
   7 </HEAD>
   8 <BODY>
   9
  10 <H3>
  11 NIST Modem Time Service</H3>
  12
  13 <HR>
  14 <H4>
  15 Synopsis</H4>
  16 Address: 127.127.18.<I>u</I>
  17 <BR>Reference ID: <TT>NIST</TT>
  18 <BR>Driver ID: <TT>ACTS_NIST</TT>
  19 <BR>Serial Port: <TT>/dev/acts<I>u</I></TT>; 1200 baud, 8-bits, no parity
  20 <BR>Features: <TT>tty_clk</TT>
  21 <BR>Requires: <TT>/usr/include/sys/termios.h</TT> header file with modem
  22 control
  23 <H4>
  24 Description</H4>
  25 This driver supports the NIST Automated Computer Time Service (ACTS). It
  26 periodically dials a prespecified telephone number, receives the NIST timecode
  27 data and calculates the local clock correction. It designed primarily for
  28 use when neither a radio clock nor connectivity to Internet time servers
  29 is available. For the best accuracy, the individual telephone line/modem
  30 delay needs to be calibrated using outside sources.
  31
  32 <P>The ACTS is located at NIST Boulder, CO, telephone 303 494 4774. A toll
  33 call from Newark, DE, costs between three and four cents, although it is
  34 not clear what carrier and time of day discounts apply. The modem dial
  35 string will differ depending on local telephone configuration, etc., and
  36 is specified by the phone command in the configuration file. The argument
  37 to this command is an AT command for a Hayes compatible modem.
  38
  39 <P>The driver can operate in either of two modes, as determined by the
  40 mode parameter in the server configuration command. In mode 0 the driver
  41 operates continuously at intervals determined by the fudge time1 parameter,
  42 as described above. In mode 1 the driver is enabled only when no other
  43 sources of synchronization are available and when we have gone more than
  44 MAXOUTAGE (3600 s) since last synchronized by other sources of synchronization.
  45
  46 <P>The accuracy produced by this driver should be in the range of a millisecond
  47 or two, but may need correction due to the delay characteristics of the
  48 individual modem involved. For undetermined reasons, some modems work with
  49 the ACTS echo-delay measurement scheme and some don't. This driver tries
  50 to do the best it can with what it gets. Initial experiments with a Practical
  51 Peripherals 9600SA modem here in Delaware suggest an accuracy of a millisecond
  52 or two can be achieved without the scheme by using a fudge time1 value
  53 of 65.0 ms. In either case, the dispersion for a single call involving
  54 ten samples is about 1.3 ms.
  55
  56 <P>For reliable call management, this driver requires a 1200-bps modem
  57 with a Hayes-compatible command set and control over the modem data terminal
  58 ready (DTR) control line. Present restrictions require the use of a POSIX-compatible
  59 programming interface, although other interfaces may work as well. The
  60 ACTS telephone number and modem setup string are hard-coded in the driver
  61 and may require changes for nonstandard modems or special circumstances.
  62
  63 <P>The fudge time1 parameter represents a propagation-delay correction
  64 factor which is added to the value computed by ACTS when the echo-delay
  65 scheme is used. This scheme does not work with all modems; for those that
  66 don't, fudge flag2 should be set to disable the feature. In this case the
  67 fudge time1 parameter represents the total propagation delay due to all
  68 causes and must be determined by external calibration.
  69
  70 <P>The ACTS call interval is determined by a counter initially set to the
  71 fudge time2 parameter. At each poll interval, minpoll (usually 64 s) is
  72 subtracted from the counter. When the counter is equal to or less than
  73 zero, the fudge flag1 is set, which causes up to three call attempts to
  74 be made to ACTS. The fudge flag1 is reset after a valid clock update has
  75 been determined or by a device fault, timeout or manually using <TT>ntpdc</TT>.
  76 After a valid clock update, the counter is reset for the next interval.
  77 Setting the <TT>fudge time2</TT> parameter to zero disables automatic call
  78 attempts. Manual call attempts can be made at any time by setting <TT>fudge
  79 flag1</TT> using ntpdc.
  80
  81 <P>The NIST timecode message is transmitted at 1200 bps in the following
  82 format:
  83 <PRE>
  84 jjjjj yy-mm-dd hh:mm:ss tt l uuu mmmmm UTC(NIST) *
  85
  86 jjjjj = modified Julian day
  87 yy-mm-dd = year, month, day
  88 hh:mm:ss = hours, minutes, seconds
  89 tt = DST indicator (see driver listing)
  90 l = leap-second warning (see driver listing)
  91 uuu = DUT1 correction (see driver listing)
  92 mmmmm = modem calibration (see driver listing)
  93 on-time = '*'</PRE>
  94 The timecode message is transmitted continuously after a signon banner,
  95 which this driver ignores. The driver also ignores all but the yy-mm-dd,
  96 hh:mm:ss and on-time character '*' fields, although it checks the format
  97 of all fields of the message. A timestamp is captured at the '*' character,
  98 as required by the ACTS specification, and used as the reference time of
  99 the timecode. If a message with an on-time character of '#' is received,
 100 the driver updates the propagation delay. The driver disconnects when (a)
 101 ten valid messages have been received, (b) no message has been received
 102 for 15 s, (c) an on-time character of '#' is received. These messages are
 103 processed by a trimmed-mean filter to reduce timing noise and then by the
 104 usual NTP algorithms to develop the clock correction.
 105
 106 <P>Since the accumulated error grows with the interval between calls, it
 107 is important that the intrinsic frequency error be minimized. This can
 108 be done by observing difference in offsets between two calls placed some
 109 hours apart and calculating the uncorrected frequency error. This error,
 110 as a fixed-point value in parts-per-million, should be installed in the
 111 ntp.drift file before the daemon is started. Some experimentation may be
 112 necessary in order to reduce the intrinsic frequency error to the order
 113 of 1 ppm.
 114
 115 <P>The behavior of the clock selection algorithm is modified when this
 116 driver is in use. The algorithm is designed so that this driver will never
 117 be selected unless no other discipline source is available. This can be
 118 overridden with the prefer keyword of the server configuration command,
 119 in which case only this driver will be selected for synchronization and
 120 all other discipline sources will be ignored.
 121
 122 <P>Unlike other drivers, each ACTS call generates one clock correction
 123 and that correction is processed immediately. There is no wait to allow
 124 the clock filter to accumulate samples. In addition, the watchdog timeout
 125 of the local clock algorithm is disabled, so that a correction received
 126 from this driver that exceeds CLOCK_MAX (128 ms) causes an immediate step/slew.
 127
 128 <P>Since the interval between updates can be much longer than used with
 129 ordinary NTP peers, the local clock procedure has been modified to operate
 130 in either of two modes, depending on whether the interval between updates
 131 is less than or greater than CLOCK_MAXSEC (1200 s). If less than this value,
 132 the local clock procedure operates using the standard NTP phase-lock loop
 133 as with other NTP peers. If greater than this value, the procedure operates
 134 using a modified frequency-lock loop suggested by Judah Levine in his lockclock
 135 algorithm designed specifically for ACTS.
 136 <H4>
 137 Call Management</H4>
 138 Since ACTS will be a toll call in most areas of the country, it is necessary
 139 to carefully manage the call frequency. This can be done in two ways, by
 140 specifying the interval between calls, or by setting a flag bit manually
 141 or via a cron job. The call interval is determined by a counter initially
 142 set to the fudge time2 parameter. At each poll interval, minpoll (usually
 143 64 s) is subtracted from the counter. When the counter is equal to or less
 144 than zero, the fudge flag1 is set, which causes up to three call attempts
 145 to be made. The fudge flag1 is reset after ten offset samples have been
 146 determined in a single call or by a device fault, timeout or manually using
 147 ntpdc. Upon successful completion of a call, the eight samples have been
 148 shifted into the clock filter, the local clock updated and the counter
 149 reset for the next interval. Setting the fudge time2 parameter to zero
 150 disables automatic call attempts.
 151
 152 <P>Manual call attempts can be made at any time by setting fudge flag1
 153 using ntpdc. For example, the ntpdc command
 154 <PRE>
 155 fudge 127.127.18.1 flags 1</PRE>
 156 will ask for a key identifier and password and, if authenticated by the
 157 server, will set flag1. There may be a short delay until the expiration
 158 of the current poll timeout.
 159
 160 <P>The flag1 can be set from a cron job in the following way. Construct
 161 a file with contents
 162 <PRE>keyid 11
 163 passwd dialup
 164 fudge 127.127.18.1 flags 1
 165 quit</PRE>
 166 Then, run the following program at specified times as required.
 167 <PRE>/usr/local/bin/ntpdc &lt;file</PRE>
 168
 169 <H4>
 170 Monitor Data</H4>
 171 When enabled by the <TT>flag4</TT> fudge flag, every received timecode
 172 is written as-is to the <TT>clockstats</TT> file.
 173 <H4>
 174 Fudge Factors</H4>
 175
 176 <DL>
 177 <DT>
 178 <TT>time1 <I>time</I></TT></DT>
 179
 180 <DD>
 181 Specifies the time offset calibration factor, in seconds and fraction,
 182 with default 0.0.</DD>
 183
 184 <DT>
 185 <TT>time2 <I>time</I></TT></DT>
 186
 187 <DD>
 188 Not used by this driver.</DD>
 189
 190 <DT>
 191 <TT>stratum <I>number</I></TT></DT>
 192
 193 <DD>
 194 Specifies the driver stratum, in decimal from 0 to 15, with default 0.</DD>
 195
 196 <DT>
 197 <TT>refid <I>string</I></TT></DT>
 198
 199 <DD>
 200 Specifies the driver reference identifier, an ASCII string from one to
 201 four characters, with default <TT>NIST</TT>.</DD>
 202
 203 <DT>
 204 <TT>flag1 0 | 1</TT></DT>
 205
 206 <DD>
 207 Not used by this driver.</DD>
 208
 209 <DT>
 210 <TT>flag2 0 | 1</TT></DT>
 211
 212 <DD>
 213 Not used by this driver.</DD>
 214
 215 <DT>
 216 <TT>flag3 0 | 1</TT></DT>
 217
 218 <DD>
 219 Not used by this driver.</DD>
 220
 221 <DT>
 222 <TT>flag4 0 | 1</TT></DT>
 223
 224 <DD>
 225 Not used by this driver.</DD>
 226 </DL>
 227 Additional Information
 228
 229 <P><A HREF="refclock.htm">Reference Clock Drivers</A>&nbsp;
 230 <HR>
 231 <ADDRESS>
 232 David L. Mills (mills@udel.edu)</ADDRESS>
 233
 234 </BODY>
 235 </HTML>