contrib/ntp/html/driver27.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>Arcron MSF Receiver
   6 </TITLE>
   7 </HEAD>
   8 <BODY>
   9
  10 <H3>
  11 Arcron MSF Receiver</H3>
  12
  13 <HR>
  14 <H4>
  15 Synopsis</H4>
  16 Address: 127.127.27.<I>u</I>
  17 <BR>Reference ID: <TT>MSFa</TT>
  18 <BR>Driver ID: <TT>MSF_ARCRON</TT>
  19 <BR>Serial Port: <TT>/dev/arc<I>u</I></TT>; 300 baud, 8-bits, 2-stop, no
  20 parity
  21 <BR>Features: <TT>tty_clk</TT>
  22 <H4>
  23 Description</H4>
  24 This driver supports the Arcron MSF receiver, and would probably also support
  25 the DCF77 variant of the same clock. The clock reports its ID as ``<TT>MSFa</TT>''
  26 to indicate MSF as a source and the use of the ARCRON driver.
  27
  28 <P>This documentation describes version V1.1 (1997/06/23) of the source
  29 and has been tested (amongst others) against ntpd3-5.90 on Solaris-1 (SunOS
  30 4.1.3_U1 on an SS1 serving as a router and firewall) and against ntpd3-5.90
  31 on Solaris-2.5 (on a SS1+ and TurboSPARC 170MHz). This code will probably
  32 work, and show increased stability, reduced jitter and more efficiency
  33 (fewer context switches) with the <TT>tty_clk</TT> discipline/STREAMS module
  34 installed, but this has not been tested. For a to-do list see the comments
  35 at the start of the code.
  36
  37 <P>This code has been significantly slimmed down since the V1.0 version,
  38 roughly halving the memory footprint of its code and data.
  39
  40 <P>This driver is designed to allow the unit to run from batteries as designed,
  41 for something approaching the 2.5 years expected in the usual stand-alone
  42 mode, but no battery-life measurements have been taken.
  43
  44 <P>Much of this code is originally from the other refclock driver files
  45 with thanks. The code was originally made to work with the clock by <A HREF="mailto:derek@toybox.demon.co.uk">Derek
  46 Mulcahy</A>, with modifications by <A HREF="mailto:d@hd.org">Damon Hart-Davis</A>.
  47 Thanks also to <A HREF="mailto:lyndond@sentinet.co.uk">Lyndon David</A>
  48 for some of the specifications of the clock.
  49
  50 <P>There is support for a Tcl/Tk monitor written by Derek Mulcahy that
  51 examines the output stats; see the <A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC
  52 Rugby MSF Receiver</A> page for more details and the code.
  53
  54 <P>Look at the notes at the start of the code for further information;
  55 some of the more important details follow.
  56
  57 <P>The driver interrogates the clock at each poll (ie every 64s by default)
  58 for a timestamp. The clock responds at the start of the next second (with
  59 the start bit of the first byte being on-time). The time is in `local'
  60 format, including the daylight savings adjustment when it is in effect.
  61 The driver code converts the time back to UTC.
  62
  63 <P>The clock claims to be accurate to within about 20ms of the MSF-broadcast
  64 time, and given the low data transmission speed from clock to host, and
  65 the fact that the clock is not in continuous sync with MSF, it seems sensible
  66 to set the `precision' of this clock to -5 or -4, -4 being used in this
  67 code, which builds in a reported dispersion of over 63ms (ie says ``This
  68 clock is not very good.''). You can improve the reported precision to -4
  69 (and thus reduce the base dispersion to about 31ms) by setting the fudge
  70 <TT>flag3</TT> to <TT>1</TT>.
  71
  72 <P>Even a busy and slow IP link can yield lower dispersions than this from
  73 polls of primary time servers on the Internet, which reinforces the idea
  74 that this clock should be used as a backup in case of problems with such
  75 an IP link, or in the unfortunate event of failure of more accurate sources
  76 such as GPS.
  77
  78 <P>By default this clock reports itself to be at stratum 2 rather than
  79 the usual stratum 0 for a refclock, because it is not really suited to
  80 be used as other than a backup source. The stratum reported can be changed
  81 with the <TT>fudge</TT> directive to be whatever you like. After careful
  82 monitoring of your clock, and appropriate choice of the <TT>time1</TT>
  83 fudge factor to remove systematic errors in the clock's reported time,
  84 you might fudge the clock to stratum 1 to allow a stratum-2 secondary server
  85 to sync to it.
  86
  87 <P>The driver code arranges to resync the clock to MSF at intervals of
  88 a little less than an hour (deliberately avoiding the same time each hour
  89 to avoid any systematic problems with the signal or host). Whilst resyncing,
  90 the driver supplements the normal polls for time from the clock with polls
  91 for the reception signal quality reported by the clock. If the signal quality
  92 is too low (0--2 out of a range of 0--5), we chose not to trust the clock
  93 until the next resync (which we bring forward by about half an hour). If
  94 we don't catch the resync, and so don't know the signal quality, we do
  95 trust the clock (because this would generally be when the signal is very
  96 good and a resync happens quickly), but we still bring the next resync
  97 forward and reduce the reported precision (and thus increase reported dispersion).
  98
  99 <P>If we force resyncs to MSF too often we will needlessly exhaust the
 100 batteries the unit runs from. During clock resync this driver tries to
 101 take enough time samples to avoid <TT>ntpd</TT> losing sync in case this
 102 clock is the current peer. By default the clock would only resync to MSF
 103 about once per day, which would almost certainly not be acceptable for
 104 NTP purposes.
 105
 106 <P>The driver does not force an immediate resync of the clock to MSF when
 107 it starts up to avoid excessive battery drain in case <TT>ntpd</TT> is
 108 going to be repeatedly restarted for any reason, and also to allow enough
 109 samples of the clock to be taken for <TT>ntpd</TT> to sync immediately
 110 to this clock (and not remain unsynchronised or to sync briefly to another
 111 configured peer, only to hop back in a few poll times, causing unnecessary
 112 disturbance). This behaviour should not cause problems because the driver
 113 will not accept the timestamps from the clock if the status flag delivered
 114 with the time code indicates that the last resync attempt was unsuccessful,
 115 so the initial timestamps will be close to reality, even if with up to
 116 a day's clock drift in the worst case (the clock by default resyncs to
 117 MSF once per day).
 118
 119 <P>The clock has a peculiar RS232 arrangement where the transmit lines
 120 are powered from the receive lines, presumably to minimise battery drain.
 121 This arrangement has two consequences:
 122 <UL>
 123 <LI>
 124 Your RS232 interface must drive both +ve and -ve</LI>
 125
 126 <LI>
 127 You must (in theory) wait for an echo and a further 10ms between characters</LI>
 128 </UL>
 129 This driver, running on standard Sun hardware, seems to work fine; note
 130 the use of the <TT>send_slow()</TT> routine to queue up command characters
 131 to be sent once every two seconds.
 132
 133 <P>Three commands are sent to the clock by this driver. Each command consists
 134 of a single letter (of which only the bottom four bits are significant),
 135 followed by a CR (ASCII 13). Each character sent to the clock should be
 136 followed by a delay to allow the unit to echo the character, and then by
 137 a further 10ms. Following the echo of the command string, there may be
 138 a response (ie in the cae of the <TT>g</TT> and <TT>o</TT> commands below),
 139 which in the case of the <TT>o</TT> command may be delayed by up to 1 second
 140 so as the start bit of the first byte of the response can arrive on time.
 141 The commands and their responses are:
 142 <DL>
 143 <DT>
 144 <TT>g</TT> CR</DT>
 145
 146 <DD>
 147 Request for signal quality. Answer only valid during (late part of) resync
 148 to MSF signal. The response consists of two characters as follows:</DD>
 149
 150 <OL>
 151 <DL compact>
 152 <DT>
 153 bit 7</DT>
 154
 155 <DD>
 156 parity</DD>
 157
 158 <DT>
 159 bit 6</DT>
 160
 161 <DD>
 162 always 0</DD>
 163
 164 <DT>
 165 bit 5</DT>
 166
 167 <DD>
 168 always 1</DD>
 169
 170 <DT>
 171 bit 4</DT>
 172
 173 <DD>
 174 always 1</DD>
 175
 176 <DT>
 177 bit 3</DT>
 178
 179 <DD>
 180 always 0</DD>
 181
 182 <DT>
 183 bit 2</DT>
 184
 185 <DD>
 186 always 0</DD>
 187
 188 <DT>
 189 bit 1</DT>
 190
 191 <DD>
 192 always 1</DD>
 193
 194 <DT>
 195 bit 0</DT>
 196
 197 <DD>
 198 = 0 if no reception attempt at the moment, = 1 if reception attempt (ie
 199 resync) in progress</DD>
 200 </DL>
 201
 202 <DL compact>
 203 <DT>
 204 bit 7</DT>
 205
 206 <DD>
 207 parity</DD>
 208
 209 <DT>
 210 bit 6</DT>
 211
 212 <DD>
 213 always 0</DD>
 214
 215 <DT>
 216 bit 5</DT>
 217
 218 <DD>
 219 always 1</DD>
 220
 221 <DT>
 222 bit 4</DT>
 223
 224 <DD>
 225 always 1</DD>
 226
 227 <DT>
 228 bit 3</DT>
 229
 230 <DD>
 231 always 0</DD>
 232
 233 <DT>
 234 bit 2--0</DT>
 235
 236 <DD>
 237 reception signal quality in the range 0--5 (very poor to very good); if
 238 in the range 0--2 no successful reception is to be expected. The reported
 239 value drops to zero when not resyncing, ie when first returned byte is
 240 not `3'.</DD>
 241 </DL>
 242 </OL>
 243
 244 <DT>
 245 <TT>h</TT> CR</DT>
 246
 247 <DD>
 248 Request to resync to MSF. Can take up from about 30s to 360s. Drains batteries
 249 so should not be used excessively. After this the clock time and date should
 250 be correct and the phase within 20ms of time as transmitted from Rugby
 251 MSF (remember to allow for propagation time). By default the clock resyncs
 252 once per day shortly after 2am (presumably to catch transitions to/from
 253 daylight saving time quickly). With this driver code we resync at least
 254 once per hour to minimise clock wander.</DD>
 255
 256 <DT>
 257 <TT>o</TT> CR</DT>
 258
 259 <DD>
 260 Request timestamp. Start bit of first byte of response is on-time, so may
 261 be delayed up to 1 second. Note that when the BST mode is in effect the
 262 time is GMT/UTC +0100, ie an hour ahead of UTC to reflect local time in
 263 the UK. The response data is as follows:</DD>
 264
 265 <OL>
 266 <LI>
 267 hours tens (hours range from 00 to 23)</LI>
 268
 269 <LI>
 270 hours units</LI>
 271
 272 <LI>
 273 minutes tens (minutes range from 00 to 59)</LI>
 274
 275 <LI>
 276 minutes units</LI>
 277
 278 <LI>
 279 seconds tens (seconds presumed to range from 00 to 60 to allow for leap
 280 second)</LI>
 281
 282 <LI>
 283 seconds units</LI>
 284
 285 <LI>
 286 day of week 1 (Monday) to 7 (Sunday)</LI>
 287
 288 <LI>
 289 day of month tens (day ranges from 01 to 31)</LI>
 290
 291 <LI>
 292 day of month units</LI>
 293
 294 <LI>
 295 month tens (months range from 01 to 12)</LI>
 296
 297 <LI>
 298 month units</LI>
 299
 300 <LI>
 301 year tens (years range from 00 to 99)</LI>
 302
 303 <LI>
 304 year units</LI>
 305
 306 <LI>
 307 BST/UTC status</LI>
 308
 309 <DL compact>
 310 <DT>
 311 bit 7</DT>
 312
 313 <DD>
 314 parity</DD>
 315
 316 <DT>
 317 bit 6</DT>
 318
 319 <DD>
 320 always 0</DD>
 321
 322 <DT>
 323 bit 5</DT>
 324
 325 <DD>
 326 always 1</DD>
 327
 328 <DT>
 329 bit 4</DT>
 330
 331 <DD>
 332 always 1</DD>
 333
 334 <DT>
 335 bit 3</DT>
 336
 337 <DD>
 338 always 0</DD>
 339
 340 <DT>
 341 bit 2</DT>
 342
 343 <DD>
 344 = 1 if UTC is in effect (reverse of bit 1)</DD>
 345
 346 <DT>
 347 bit 1</DT>
 348
 349 <DD>
 350 = 1 if BST is in effect (reverse of bit 2)</DD>
 351
 352 <DT>
 353 bit 0</DT>
 354
 355 <DD>
 356 = 1 if BST/UTC change pending</DD>
 357 </DL>
 358
 359 <LI>
 360 clock status</LI>
 361
 362 <DL compact>&nbsp;
 363 <DT>
 364 bit 7</DT>
 365
 366 <DD>
 367 parity</DD>
 368
 369 <DT>
 370 bit 6</DT>
 371
 372 <DD>
 373 always 0</DD>
 374
 375 <DT>
 376 bit 5</DT>
 377
 378 <DD>
 379 always 1</DD>
 380
 381 <DT>
 382 bit 4</DT>
 383
 384 <DD>
 385 always 1</DD>
 386
 387 <DT>
 388 bit 3</DT>
 389
 390 <DD>
 391 = 1 if low battery is detected</DD>
 392
 393 <DT>
 394 bit 2</DT>
 395
 396 <DD>
 397 = 1 if last resync failed (though officially undefined for the MSF clock)</DD>
 398
 399 <DT>
 400 bit 1</DT>
 401
 402 <DD>
 403 = 1 if at least one reception attempt since 0230 for the MSF clock was
 404 successful (0300 for the DCF77 clock)</DD>
 405
 406 <DT>
 407 bit 0</DT>
 408
 409 <DD>
 410 = 1 if the clock has valid time---reset to zero when clock is reset (eg
 411 at power-up), and set to 1 after first successful resync attempt.</DD>
 412 </DL>
 413 </OL>
 414 The driver only accepts time from the clock if the bottom three bits of
 415 the status byte are <TT>011</TT>. The leap-year logic for computing day-in-year
 416 is only valid until 2099, and the clock will ignore stamps from the clock
 417 that claim BST is in effect in the first hour of each year. If the UK parliament
 418 decides to move us to +0100/+0200 time as opposed to the current +0000/+0100
 419 time, it is not clear what effect that will have on the time broadcast
 420 by MSF, and therefore on this driver's usefulness.</DL>
 421 A typical <TT>ntp.conf</TT> configuration file for this driver might be:
 422 <PRE># hostname(n) means we expect (n) to be the stratum at which hostname runs.
 423
 424 #------------------------------------------------------------------------------
 425 # SYNCHRONISATION PARTNERS
 426 # ========================
 427
 428 # Our betters...
 429 server 127.127.27.0 # ARCRON MSF radio clock(1).
 430 # Fudge stratum and other features as required.
 431 # ADJUST time1 VALUE FOR YOUR HOST, CLOCK AND LOCATION!
 432 fudge 127.127.27.0 stratum 1 time1 0.016 flag3 1 flag4 1
 433
 434 peer 11.22.33.9 # tick(1--2).
 435 peer 11.22.33.4 # tock(3), boot/NFS server.
 436
 437 # This shouldn't get swept away unless left untouched for a long time.
 438 driftfile /var/tmp/ntp.drift
 439
 440 #------------------------------------------------------------------------------
 441 # RESTRICTIONS
 442 # ============
 443
 444 # By default, don't trust and don't allow modifications.&nbsp; Ignore in fact.
 445 restrict default ignore notrust nomodify
 446
 447 # Allow others in our subnet to check us out...
 448 restrict 11.22.33.0 mask 255.255.255.0 nomodify notrust
 449
 450 # Trust our peers for time.&nbsp; Don't trust others in case they are insane.
 451 restrict 127.127.27.0 nomodify
 452 restrict 11.22.33.4 nomodify
 453 restrict 11.22.33.9 nomodify
 454
 455 # Allow anything from the local host.
 456 restrict 127.0.0.1</PRE>
 457 There are a few <TT>#define</TT>s in the code that you might wish to play
 458 with:
 459 <DL>
 460 <DT>
 461 <TT>ARCRON_KEEN</TT></DT>
 462
 463 <DD>
 464 With this defined, the code is relatively trusting of the clock, and assumes
 465 that you will have the clock as one of a few time sources, so will bend
 466 over backwards to use the time from the clock when available and avoid
 467 <TT>ntpd</TT> dropping sync from the clock where possible. You may wish
 468 to undefine this, especially if you have better sources of time or your
 469 reception is ropey. However, there are many checks built in even with this
 470 flag defined.</DD>
 471
 472 <DT>
 473 <TT>ARCRON_OWN_FILTER</TT></DT>
 474
 475 <DD>
 476 When defined, the code uses its own median-filter code rather than that
 477 available in <TT>ntp_refclock.c</TT> since the latter seems to have a minor
 478 bug, at least in version 3-5.90. If this bug goes away this flag should
 479 be turned off to avoid duplication of code. (The bug, if that's what it
 480 is, causes the last raw offset to be used rather than the median offset.)</DD>
 481
 482
 483 <P>Without this defined (and without <TT>ARCRON_MULTIPLE_SAMPLES</TT> below)
 484 a typical set of offsets reported and used to drive the clock-filter algorithm
 485 is (oldest last):
 486 <PRE>filtoffset=&nbsp; -4.32&nbsp; -34.82&nbsp;&nbsp; -0.78&nbsp;&nbsp;&nbsp; 0.89&nbsp;&nbsp;&nbsp; 2.76&nbsp;&nbsp;&nbsp; 4.58&nbsp;&nbsp; -3.92&nbsp;&nbsp; -2.17</PRE>
 487 Look at that spike!
 488
 489 <P>With this defined a typical set of offsets is:
 490 <PRE>filtoffset=&nbsp; -7.06&nbsp;&nbsp; -7.06&nbsp;&nbsp; -2.91&nbsp;&nbsp; -2.91&nbsp;&nbsp; -2.91&nbsp;&nbsp; -1.27&nbsp;&nbsp; -9.54&nbsp;&nbsp; -6.70</PRE>
 491 with the repeated values being some evidence of outlyers being discarded.
 492 <DT>
 493 <TT>ARCRON_MULTIPLE_SAMPLES</TT></DT>
 494
 495 <DD>
 496 When is defined, we regard each character in the returned timecode as at
 497 a known delay from the start of the second, and use the smallest (most
 498 negative) offset implied by any such character, ie with the smallest kernel-induced
 499 display, and use that. This helps to reduce jitter and spikes.</DD>
 500
 501 <DT>
 502 <TT>ARCRON_LEAPSECOND_KEEN</TT></DT>
 503
 504 <DD>
 505 When is defined, we try to do a resync to MSF as soon as possible in the
 506 first hour of the morning of the first day of the first and seventh months,
 507 ie just after a leap-second insertion or deletion would happen if it is
 508 going to. This should help compensate for the fact that this clock does
 509 not continuously sample MSF, which compounds the fact that MSF itself gives
 510 no warning of an impending leap-second event. This code did not seem functional
 511 at the leap-second insertion of 30th June 1997 so is by default disabled.</DD>
 512
 513 <DT>
 514 <TT>PRECISION</TT></DT>
 515
 516 <DD>
 517 Currently set to <TT>-4</TT>, but you may wish to set it to <TT>-5</TT>
 518 if you are more conservative, or to <TT>-6</TT> if you have particularly
 519 good experience with the clock and you live on the edge. Note that the
 520 <TT>flag3</TT> fudge value will improve the reported dispersion one notch
 521 if clock signal quality is known good. So maybe just leave this alone.
 522 B^)</DD>
 523
 524 <DT>
 525 <TT>NSAMPLES</TT></DT>
 526
 527 <DD>
 528 Should be at least 3 to help smooth out sampling jitters. Can be more,
 529 but if made too long can make <TT>ntpd</TT> overshoot on clock corrections
 530 and can hold onto bad samples longer than you would like. With this set
 531 to 4 and <TT>NKEEP</TT> set to 3 this allows the occasional bad sample
 532 (in my experience less than 1 value in 10) to be dropped. (Note that there
 533 seems to be some sort of `beat' effect in the offset with a periodicity
 534 of about 7 samples as of this writing (1997/05/11) still under investigation;
 535 a filter of approximately this length should be able to almost completely
 536 suppress this effect.) Note that if the fudge-factor <TT>flag3</TT> is
 537 set to 1, a larger <TT>NSAMPLES</TT> is used.</DD>
 538 </DL>
 539
 540 <H4>
 541 Monitor Data</H4>
 542 Each timecode is written to the <TT>clockstats</TT> file with a signal
 543 quality value appended (`0'--`5' as reported by the clock, or `6' for unknown).
 544
 545 <P>Each resync and result (plus gaining or losing MSF sync) is logged to
 546 the system log at level <TT>LOG_NOTICE</TT>; note that each resync drains
 547 the unit's batteries, so the syslog entry seems justified.
 548
 549 <P>Syslog entries are of the form:
 550 <PRE>May 10 10:15:24 oolong ntpd[615]: ARCRON: unit 0: sending resync command
 551 May 10 10:17:32 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock
 552 May 10 11:13:01 oolong ntpd[615]: ARCRON: unit 0: sending resync command
 553 May 10 11:14:06 oolong ntpd[615]: ARCRON: sync finished, signal quality -1: UNKNOWN, will use clock anyway
 554 May 10 11:41:49 oolong ntpd[615]: ARCRON: unit 0: sending resync command
 555 May 10 11:43:57 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock
 556 May 10 12:39:26 oolong ntpd[615]: ARCRON: unit 0: sending resync command
 557 May 10 12:41:34 oolong ntpd[615]: ARCRON: sync finished, signal quality 3: OK, will use clock</PRE>
 558
 559 <H4>
 560 Fudge Factors</H4>
 561
 562 <DL>
 563 <DT>
 564 <TT>time1 <I>time</I></TT></DT>
 565
 566 <DD>
 567 Specifies the time offset calibration factor, in seconds and fraction,
 568 with default 0.0. On a Sun SparcStation 1 running SunOS 4.1.3_U1, with
 569 the receiver in London, a value of 0.020 (20ms) seems to be appropriate.</DD>
 570
 571 <DT>
 572 <TT>time2 <I>time</I></TT></DT>
 573
 574 <DD>
 575 Not currently used by this driver.</DD>
 576
 577 <DT>
 578 <TT>stratum <I>number</I></TT></DT>
 579
 580 <DD>
 581 Specifies the driver stratum, in decimal from 0 to 15, with default 0.
 582 It is suggested that the clock be fudged to stratum 1 so this it is used
 583 a backup time source rather than a primary when more accurate sources are
 584 available.</DD>
 585
 586 <DT>
 587 <TT>refid <I>string</I></TT></DT>
 588
 589 <DD>
 590 Specifies the driver reference identifier, an ASCII string from one to
 591 four characters, with default <TT>MSFa</TT>.</DD>
 592
 593 <DT>
 594 <TT>flag1 0 | 1</TT></DT>
 595
 596 <DD>
 597 Not used by this driver.</DD>
 598
 599 <DT>
 600 <TT>flag2 0 | 1</TT></DT>
 601
 602 <DD>
 603 Not used by this driver.</DD>
 604
 605 <DT>
 606 <TT>flag3 0 | 1</TT></DT>
 607
 608 <DD>
 609 If set to 1, better precision is reported (and thus lower dispersion) while
 610 clock's received signal quality is known to be good.</DD>
 611
 612 <DT>
 613 <TT>flag4 0 | 1</TT></DT>
 614
 615 <DD>
 616 If set to 1, a longer-than-normal (8-stage rather than 4-stage) median
 617 filter is used, to provide some extra smoothing of clock output and reduction
 618 in jitter, at the cost of extra clock overshoot. Probably not advisable
 619 unless the server using this clock has other sources it can use to help
 620 mitigate the overshoot.</DD>
 621 </DL>
 622
 623 <H4>
 624 Additional Information</H4>
 625 <A HREF="refclock.htm">Reference Clock Drivers</A>
 626
 627 <P><A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC Rugby MSF Receiver</A>
 628 page&nbsp;
 629 <HR>
 630 <ADDRESS>
 631 Damon Hart-Davis (d@hd.org)</ADDRESS>
 632
 633 </BODY>
 634 </HTML>