diff options
Diffstat (limited to 'html/driver27.htm')
| -rw-r--r-- | html/driver27.htm | 634 |
1 files changed, 0 insertions, 634 deletions
diff --git a/html/driver27.htm b/html/driver27.htm deleted file mode 100644 index 686e985b1b77..000000000000 --- a/html/driver27.htm +++ /dev/null @@ -1,634 +0,0 @@ -<HTML> -<HEAD> - <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> - <META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (Win95; I) [Netscape]"> - <TITLE>Arcron MSF Receiver -</TITLE> -</HEAD> -<BODY> - -<H3> -Arcron MSF Receiver</H3> - -<HR> -<H4> -Synopsis</H4> -Address: 127.127.27.<I>u</I> -<BR>Reference ID: <TT>MSFa</TT> -<BR>Driver ID: <TT>MSF_ARCRON</TT> -<BR>Serial Port: <TT>/dev/arc<I>u</I></TT>; 300 baud, 8-bits, 2-stop, no -parity -<BR>Features: <TT>tty_clk</TT> -<H4> -Description</H4> -This driver supports the Arcron MSF receiver, and would probably also support -the DCF77 variant of the same clock. The clock reports its ID as ``<TT>MSFa</TT>'' -to indicate MSF as a source and the use of the ARCRON driver. - -<P>This documentation describes version V1.1 (1997/06/23) of the source -and has been tested (amongst others) against ntpd3-5.90 on Solaris-1 (SunOS -4.1.3_U1 on an SS1 serving as a router and firewall) and against ntpd3-5.90 -on Solaris-2.5 (on a SS1+ and TurboSPARC 170MHz). This code will probably -work, and show increased stability, reduced jitter and more efficiency -(fewer context switches) with the <TT>tty_clk</TT> discipline/STREAMS module -installed, but this has not been tested. For a to-do list see the comments -at the start of the code. - -<P>This code has been significantly slimmed down since the V1.0 version, -roughly halving the memory footprint of its code and data. - -<P>This driver is designed to allow the unit to run from batteries as designed, -for something approaching the 2.5 years expected in the usual stand-alone -mode, but no battery-life measurements have been taken. - -<P>Much of this code is originally from the other refclock driver files -with thanks. The code was originally made to work with the clock by <A HREF="mailto:derek@toybox.demon.co.uk">Derek -Mulcahy</A>, with modifications by <A HREF="mailto:d@hd.org">Damon Hart-Davis</A>. -Thanks also to <A HREF="mailto:lyndond@sentinet.co.uk">Lyndon David</A> -for some of the specifications of the clock. - -<P>There is support for a Tcl/Tk monitor written by Derek Mulcahy that -examines the output stats; see the <A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC -Rugby MSF Receiver</A> page for more details and the code. - -<P>Look at the notes at the start of the code for further information; -some of the more important details follow. - -<P>The driver interrogates the clock at each poll (ie every 64s by default) -for a timestamp. The clock responds at the start of the next second (with -the start bit of the first byte being on-time). The time is in `local' -format, including the daylight savings adjustment when it is in effect. -The driver code converts the time back to UTC. - -<P>The clock claims to be accurate to within about 20ms of the MSF-broadcast -time, and given the low data transmission speed from clock to host, and -the fact that the clock is not in continuous sync with MSF, it seems sensible -to set the `precision' of this clock to -5 or -4, -4 being used in this -code, which builds in a reported dispersion of over 63ms (ie says ``This -clock is not very good.''). You can improve the reported precision to -4 -(and thus reduce the base dispersion to about 31ms) by setting the fudge -<TT>flag3</TT> to <TT>1</TT>. - -<P>Even a busy and slow IP link can yield lower dispersions than this from -polls of primary time servers on the Internet, which reinforces the idea -that this clock should be used as a backup in case of problems with such -an IP link, or in the unfortunate event of failure of more accurate sources -such as GPS. - -<P>By default this clock reports itself to be at stratum 2 rather than -the usual stratum 0 for a refclock, because it is not really suited to -be used as other than a backup source. The stratum reported can be changed -with the <TT>fudge</TT> directive to be whatever you like. After careful -monitoring of your clock, and appropriate choice of the <TT>time1</TT> -fudge factor to remove systematic errors in the clock's reported time, -you might fudge the clock to stratum 1 to allow a stratum-2 secondary server -to sync to it. - -<P>The driver code arranges to resync the clock to MSF at intervals of -a little less than an hour (deliberately avoiding the same time each hour -to avoid any systematic problems with the signal or host). Whilst resyncing, -the driver supplements the normal polls for time from the clock with polls -for the reception signal quality reported by the clock. If the signal quality -is too low (0--2 out of a range of 0--5), we chose not to trust the clock -until the next resync (which we bring forward by about half an hour). If -we don't catch the resync, and so don't know the signal quality, we do -trust the clock (because this would generally be when the signal is very -good and a resync happens quickly), but we still bring the next resync -forward and reduce the reported precision (and thus increase reported dispersion). - -<P>If we force resyncs to MSF too often we will needlessly exhaust the -batteries the unit runs from. During clock resync this driver tries to -take enough time samples to avoid <TT>ntpd</TT> losing sync in case this -clock is the current peer. By default the clock would only resync to MSF -about once per day, which would almost certainly not be acceptable for -NTP purposes. - -<P>The driver does not force an immediate resync of the clock to MSF when -it starts up to avoid excessive battery drain in case <TT>ntpd</TT> is -going to be repeatedly restarted for any reason, and also to allow enough -samples of the clock to be taken for <TT>ntpd</TT> to sync immediately -to this clock (and not remain unsynchronised or to sync briefly to another -configured peer, only to hop back in a few poll times, causing unnecessary -disturbance). This behaviour should not cause problems because the driver -will not accept the timestamps from the clock if the status flag delivered -with the time code indicates that the last resync attempt was unsuccessful, -so the initial timestamps will be close to reality, even if with up to -a day's clock drift in the worst case (the clock by default resyncs to -MSF once per day). - -<P>The clock has a peculiar RS232 arrangement where the transmit lines -are powered from the receive lines, presumably to minimise battery drain. -This arrangement has two consequences: -<UL> -<LI> -Your RS232 interface must drive both +ve and -ve</LI> - -<LI> -You must (in theory) wait for an echo and a further 10ms between characters</LI> -</UL> -This driver, running on standard Sun hardware, seems to work fine; note -the use of the <TT>send_slow()</TT> routine to queue up command characters -to be sent once every two seconds. - -<P>Three commands are sent to the clock by this driver. Each command consists -of a single letter (of which only the bottom four bits are significant), -followed by a CR (ASCII 13). Each character sent to the clock should be -followed by a delay to allow the unit to echo the character, and then by -a further 10ms. Following the echo of the command string, there may be -a response (ie in the cae of the <TT>g</TT> and <TT>o</TT> commands below), -which in the case of the <TT>o</TT> command may be delayed by up to 1 second -so as the start bit of the first byte of the response can arrive on time. -The commands and their responses are: -<DL> -<DT> -<TT>g</TT> CR</DT> - -<DD> -Request for signal quality. Answer only valid during (late part of) resync -to MSF signal. The response consists of two characters as follows:</DD> - -<OL> -<DL compact> -<DT> -bit 7</DT> - -<DD> -parity</DD> - -<DT> -bit 6</DT> - -<DD> -always 0</DD> - -<DT> -bit 5</DT> - -<DD> -always 1</DD> - -<DT> -bit 4</DT> - -<DD> -always 1</DD> - -<DT> -bit 3</DT> - -<DD> -always 0</DD> - -<DT> -bit 2</DT> - -<DD> -always 0</DD> - -<DT> -bit 1</DT> - -<DD> -always 1</DD> - -<DT> -bit 0</DT> - -<DD> -= 0 if no reception attempt at the moment, = 1 if reception attempt (ie -resync) in progress</DD> -</DL> - -<DL compact> -<DT> -bit 7</DT> - -<DD> -parity</DD> - -<DT> -bit 6</DT> - -<DD> -always 0</DD> - -<DT> -bit 5</DT> - -<DD> -always 1</DD> - -<DT> -bit 4</DT> - -<DD> -always 1</DD> - -<DT> -bit 3</DT> - -<DD> -always 0</DD> - -<DT> -bit 2--0</DT> - -<DD> -reception signal quality in the range 0--5 (very poor to very good); if -in the range 0--2 no successful reception is to be expected. The reported -value drops to zero when not resyncing, ie when first returned byte is -not `3'.</DD> -</DL> -</OL> - -<DT> -<TT>h</TT> CR</DT> - -<DD> -Request to resync to MSF. Can take up from about 30s to 360s. Drains batteries -so should not be used excessively. After this the clock time and date should -be correct and the phase within 20ms of time as transmitted from Rugby -MSF (remember to allow for propagation time). By default the clock resyncs -once per day shortly after 2am (presumably to catch transitions to/from -daylight saving time quickly). With this driver code we resync at least -once per hour to minimise clock wander.</DD> - -<DT> -<TT>o</TT> CR</DT> - -<DD> -Request timestamp. Start bit of first byte of response is on-time, so may -be delayed up to 1 second. Note that when the BST mode is in effect the -time is GMT/UTC +0100, ie an hour ahead of UTC to reflect local time in -the UK. The response data is as follows:</DD> - -<OL> -<LI> -hours tens (hours range from 00 to 23)</LI> - -<LI> -hours units</LI> - -<LI> -minutes tens (minutes range from 00 to 59)</LI> - -<LI> -minutes units</LI> - -<LI> -seconds tens (seconds presumed to range from 00 to 60 to allow for leap -second)</LI> - -<LI> -seconds units</LI> - -<LI> -day of week 1 (Monday) to 7 (Sunday)</LI> - -<LI> -day of month tens (day ranges from 01 to 31)</LI> - -<LI> -day of month units</LI> - -<LI> -month tens (months range from 01 to 12)</LI> - -<LI> -month units</LI> - -<LI> -year tens (years range from 00 to 99)</LI> - -<LI> -year units</LI> - -<LI> -BST/UTC status</LI> - -<DL compact> -<DT> -bit 7</DT> - -<DD> -parity</DD> - -<DT> -bit 6</DT> - -<DD> -always 0</DD> - -<DT> -bit 5</DT> - -<DD> -always 1</DD> - -<DT> -bit 4</DT> - -<DD> -always 1</DD> - -<DT> -bit 3</DT> - -<DD> -always 0</DD> - -<DT> -bit 2</DT> - -<DD> -= 1 if UTC is in effect (reverse of bit 1)</DD> - -<DT> -bit 1</DT> - -<DD> -= 1 if BST is in effect (reverse of bit 2)</DD> - -<DT> -bit 0</DT> - -<DD> -= 1 if BST/UTC change pending</DD> -</DL> - -<LI> -clock status</LI> - -<DL compact> -<DT> -bit 7</DT> - -<DD> -parity</DD> - -<DT> -bit 6</DT> - -<DD> -always 0</DD> - -<DT> -bit 5</DT> - -<DD> -always 1</DD> - -<DT> -bit 4</DT> - -<DD> -always 1</DD> - -<DT> -bit 3</DT> - -<DD> -= 1 if low battery is detected</DD> - -<DT> -bit 2</DT> - -<DD> -= 1 if last resync failed (though officially undefined for the MSF clock)</DD> - -<DT> -bit 1</DT> - -<DD> -= 1 if at least one reception attempt since 0230 for the MSF clock was -successful (0300 for the DCF77 clock)</DD> - -<DT> -bit 0</DT> - -<DD> -= 1 if the clock has valid time---reset to zero when clock is reset (eg -at power-up), and set to 1 after first successful resync attempt.</DD> -</DL> -</OL> -The driver only accepts time from the clock if the bottom three bits of -the status byte are <TT>011</TT>. The leap-year logic for computing day-in-year -is only valid until 2099, and the clock will ignore stamps from the clock -that claim BST is in effect in the first hour of each year. If the UK parliament -decides to move us to +0100/+0200 time as opposed to the current +0000/+0100 -time, it is not clear what effect that will have on the time broadcast -by MSF, and therefore on this driver's usefulness.</DL> -A typical <TT>ntp.conf</TT> configuration file for this driver might be: -<PRE># hostname(n) means we expect (n) to be the stratum at which hostname runs. - -#------------------------------------------------------------------------------ -# SYNCHRONISATION PARTNERS -# ======================== - -# Our betters... -server 127.127.27.0 # ARCRON MSF radio clock(1). -# Fudge stratum and other features as required. -# ADJUST time1 VALUE FOR YOUR HOST, CLOCK AND LOCATION! -fudge 127.127.27.0 stratum 1 time1 0.016 flag3 1 flag4 1 - -peer 11.22.33.9 # tick(1--2). -peer 11.22.33.4 # tock(3), boot/NFS server. - -# This shouldn't get swept away unless left untouched for a long time. -driftfile /var/tmp/ntp.drift - -#------------------------------------------------------------------------------ -# RESTRICTIONS -# ============ - -# By default, don't trust and don't allow modifications. Ignore in fact. -restrict default ignore notrust nomodify - -# Allow others in our subnet to check us out... -restrict 11.22.33.0 mask 255.255.255.0 nomodify notrust - -# Trust our peers for time. Don't trust others in case they are insane. -restrict 127.127.27.0 nomodify -restrict 11.22.33.4 nomodify -restrict 11.22.33.9 nomodify - -# Allow anything from the local host. -restrict 127.0.0.1</PRE> -There are a few <TT>#define</TT>s in the code that you might wish to play -with: -<DL> -<DT> -<TT>ARCRON_KEEN</TT></DT> - -<DD> -With this defined, the code is relatively trusting of the clock, and assumes -that you will have the clock as one of a few time sources, so will bend -over backwards to use the time from the clock when available and avoid -<TT>ntpd</TT> dropping sync from the clock where possible. You may wish -to undefine this, especially if you have better sources of time or your -reception is ropey. However, there are many checks built in even with this -flag defined.</DD> - -<DT> -<TT>ARCRON_OWN_FILTER</TT></DT> - -<DD> -When defined, the code uses its own median-filter code rather than that -available in <TT>ntp_refclock.c</TT> since the latter seems to have a minor -bug, at least in version 3-5.90. If this bug goes away this flag should -be turned off to avoid duplication of code. (The bug, if that's what it -is, causes the last raw offset to be used rather than the median offset.)</DD> - - -<P>Without this defined (and without <TT>ARCRON_MULTIPLE_SAMPLES</TT> below) -a typical set of offsets reported and used to drive the clock-filter algorithm -is (oldest last): -<PRE>filtoffset= -4.32 -34.82 -0.78 0.89 2.76 4.58 -3.92 -2.17</PRE> -Look at that spike! - -<P>With this defined a typical set of offsets is: -<PRE>filtoffset= -7.06 -7.06 -2.91 -2.91 -2.91 -1.27 -9.54 -6.70</PRE> -with the repeated values being some evidence of outlyers being discarded. -<DT> -<TT>ARCRON_MULTIPLE_SAMPLES</TT></DT> - -<DD> -When is defined, we regard each character in the returned timecode as at -a known delay from the start of the second, and use the smallest (most -negative) offset implied by any such character, ie with the smallest kernel-induced -display, and use that. This helps to reduce jitter and spikes.</DD> - -<DT> -<TT>ARCRON_LEAPSECOND_KEEN</TT></DT> - -<DD> -When is defined, we try to do a resync to MSF as soon as possible in the -first hour of the morning of the first day of the first and seventh months, -ie just after a leap-second insertion or deletion would happen if it is -going to. This should help compensate for the fact that this clock does -not continuously sample MSF, which compounds the fact that MSF itself gives -no warning of an impending leap-second event. This code did not seem functional -at the leap-second insertion of 30th June 1997 so is by default disabled.</DD> - -<DT> -<TT>PRECISION</TT></DT> - -<DD> -Currently set to <TT>-4</TT>, but you may wish to set it to <TT>-5</TT> -if you are more conservative, or to <TT>-6</TT> if you have particularly -good experience with the clock and you live on the edge. Note that the -<TT>flag3</TT> fudge value will improve the reported dispersion one notch -if clock signal quality is known good. So maybe just leave this alone. -B^)</DD> - -<DT> -<TT>NSAMPLES</TT></DT> - -<DD> -Should be at least 3 to help smooth out sampling jitters. Can be more, -but if made too long can make <TT>ntpd</TT> overshoot on clock corrections -and can hold onto bad samples longer than you would like. With this set -to 4 and <TT>NKEEP</TT> set to 3 this allows the occasional bad sample -(in my experience less than 1 value in 10) to be dropped. (Note that there -seems to be some sort of `beat' effect in the offset with a periodicity -of about 7 samples as of this writing (1997/05/11) still under investigation; -a filter of approximately this length should be able to almost completely -suppress this effect.) Note that if the fudge-factor <TT>flag3</TT> is -set to 1, a larger <TT>NSAMPLES</TT> is used.</DD> -</DL> - -<H4> -Monitor Data</H4> -Each timecode is written to the <TT>clockstats</TT> file with a signal -quality value appended (`0'--`5' as reported by the clock, or `6' for unknown). - -<P>Each resync and result (plus gaining or losing MSF sync) is logged to -the system log at level <TT>LOG_NOTICE</TT>; note that each resync drains -the unit's batteries, so the syslog entry seems justified. - -<P>Syslog entries are of the form: -<PRE>May 10 10:15:24 oolong ntpd[615]: ARCRON: unit 0: sending resync command -May 10 10:17:32 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock -May 10 11:13:01 oolong ntpd[615]: ARCRON: unit 0: sending resync command -May 10 11:14:06 oolong ntpd[615]: ARCRON: sync finished, signal quality -1: UNKNOWN, will use clock anyway -May 10 11:41:49 oolong ntpd[615]: ARCRON: unit 0: sending resync command -May 10 11:43:57 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock -May 10 12:39:26 oolong ntpd[615]: ARCRON: unit 0: sending resync command -May 10 12:41:34 oolong ntpd[615]: ARCRON: sync finished, signal quality 3: OK, will use clock</PRE> - -<H4> -Fudge Factors</H4> - -<DL> -<DT> -<TT>time1 <I>time</I></TT></DT> - -<DD> -Specifies the time offset calibration factor, in seconds and fraction, -with default 0.0. On a Sun SparcStation 1 running SunOS 4.1.3_U1, with -the receiver in London, a value of 0.020 (20ms) seems to be appropriate.</DD> - -<DT> -<TT>time2 <I>time</I></TT></DT> - -<DD> -Not currently used by this driver.</DD> - -<DT> -<TT>stratum <I>number</I></TT></DT> - -<DD> -Specifies the driver stratum, in decimal from 0 to 15, with default 0. -It is suggested that the clock be fudged to stratum 1 so this it is used -a backup time source rather than a primary when more accurate sources are -available.</DD> - -<DT> -<TT>refid <I>string</I></TT></DT> - -<DD> -Specifies the driver reference identifier, an ASCII string from one to -four characters, with default <TT>MSFa</TT>.</DD> - -<DT> -<TT>flag1 0 | 1</TT></DT> - -<DD> -Not used by this driver.</DD> - -<DT> -<TT>flag2 0 | 1</TT></DT> - -<DD> -Not used by this driver.</DD> - -<DT> -<TT>flag3 0 | 1</TT></DT> - -<DD> -If set to 1, better precision is reported (and thus lower dispersion) while -clock's received signal quality is known to be good.</DD> - -<DT> -<TT>flag4 0 | 1</TT></DT> - -<DD> -If set to 1, a longer-than-normal (8-stage rather than 4-stage) median -filter is used, to provide some extra smoothing of clock output and reduction -in jitter, at the cost of extra clock overshoot. Probably not advisable -unless the server using this clock has other sources it can use to help -mitigate the overshoot.</DD> -</DL> - -<H4> -Additional Information</H4> -<A HREF="refclock.htm">Reference Clock Drivers</A> - -<P><A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC Rugby MSF Receiver</A> -page -<HR> -<ADDRESS> -Damon Hart-Davis (d@hd.org)</ADDRESS> - -</BODY> -</HTML> |