freebsd-dev/contrib/ntp/html/driver27.htm
1999-12-09 13:01:21 +00:00

635 lines
19 KiB
HTML

<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>&nbsp;
<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.&nbsp; 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.&nbsp; 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=&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>
Look at that spike!
<P>With this defined a typical set of offsets is:
<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>
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&nbsp;
<HR>
<ADDRESS>
Damon Hart-Davis (d@hd.org)</ADDRESS>
</BODY>
</HTML>