source: trunk/third/xntp/html/driver27.htm @ 16192

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