freebsd-dev/contrib/ntp/html/driver8.htm
2000-01-28 14:55:50 +00:00

354 lines
13 KiB
HTML

<HTML><HEAD><TITLE>
Generic Reference Driver
</TITLE></HEAD><BODY><H3>
Generic Reference Driver
</H3><HR>
<H4>Synopsis</H4>
Address: 127.127.8.<I>u</I>
<BR>Reference ID: <TT>PARSE</TT>
<BR>Driver ID: <TT>GENERIC</TT>
<BR>Serial Port: <TT>/dev/refclock-<I>u</I></TT>; TTY mode according to
clock type
<H4>Description</H4>
The timecode of these receivers is sampled via a STREAMS module in the
kernel (The STREAMS module has been designed for use with SUN Systems
under SunOS 4.1.x or Solaris 2.3 - 2.6. It can be linked directly into
the kernel or loaded via the loadable driver mechanism). This STREAMS
module can be adapted to be able to convert different time code formats.
If the daemon is compiled without the STREAM definition synchronization
will work without the Sun streams module, though accuracy is
significantly degraded. This feature allows to use PARSE also on non Sun
machines.
<P>The actual receiver status is mapped into various synchronization
states generally used by receivers. The STREAMS module is configured to
interpret the time codes of DCF C51, PZF535, PZF509, GPS166, Trimble SV6
GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see list
below).
<P>The reference clock support in ntp contains the necessary
configuration tables for those receivers. In addition to supporting
several different clock types and 4 devices, the generation a a PPS
signal is also provided as an configuration option. The PPS
configuration option uses the receiver generated time stamps for feeding
the PPS loopfilter control for much finer clock synchronization.
<P>CAUTION: The PPS configuration option is different from the hardware
PPS signal, which is also supported (see below), as it controls the way
ntpd is synchronized to the reference clock, while the hardware PPS
signal controls the way time offsets are determined.
<P>The use of the PPS option requires receivers with an accuracy of
better than 1ms.
<P>Fudge factors
<P>Only two fudge factors are utilized. The time1 fudge factor defines
the phase offset of the synchronization character to the actual time. On
the availability of PPS information the time2 fudge factor defines the
skew between the PPS time stamp and the receiver timestamp of the PPS
signal. This parameter is usually zero, as usually the PPS signal is
believed in time and OS delays should be corrected in the machine
specific section of the kernel driver. time2 needs only be set when the
actual PPS signal is delayed for some reason. The flag1 enables input
filtering. This a median filter with continuous sampling. The flag2
selects averaging of the samples remaining after the filtering. Leap
second-handling is controlled with the flag3. When set a leap second
will be deleted on receipt of a leap second indication from the
receiver. Otherwise the leap second will be added, (which is the
default). flag3 should never be set. PPS handling is enabled by adding
128 to the mode parameter in the server/peer command.
<P>ntpq (8)
<P>timecode variable
<P>The ntpq program can read clock variables command list several
variables.
These hold the following information: refclock_time is the local time
with
the offset to UTC (format HHMM). The currently active receiver flags are
listed in refclock_status. Additional feature flags of the receiver are
optionally listed in parentheses. The actual time code is listed in
timecode.
A qualification of the decoded time code format is following in
refclock_format. The last piece of information is the overall running
time and the accumulated times for the clock event states in
refclock_states. When PPS information is present additional variable are
available. refclock_ppstime lists then the PPS timestamp and
refclock_ppsskew lists the difference between RS232
derived timestamp and the PPS timestamp.
<P>Currently, eighteen clock types (devices /dev/refclock-0 -
/dev/refclock-3) are supported by the PARSE driver.
<BR>A note on the implementations:
<UL><li>These implementations where mainly done <B><I>WITHOUT</I></B>
actual access to the hardware. Thus not all implementations provide full
support. The development was done with the help of many souls who had
the hardware and where so kind to borrow me their time an patience
during the development and debugging cycle. Thus for continued support
and quality direct access to the receivers is a big help. Nevertheless i
am not prepared to buy these reference clocks - donations to <A
HREF="http://www4.informatik.uni-erlangen.de/~kardel">me</A>
(<A HREF="mailto: kardel@acm.org">kardel@acm.org</A>) are welcome as
long as they work within Europe 8-).
<P>Verified implementations are:
<UL>
<LI>
RAWDCF variants
<p>These variants are tested for the decoding with my own homegrown
receivers. Interfacing with specific commercial products may involve
some fiddeling with cables. Especially commericial RAWDCF receivers have
a seemingly unlimited number of ways to draw power from the RS232 port
and to encode the DCF77 datastream. You are mainly on your own here
unless i have a sample of the receiver.
<LI>
<A HREF="http://www.meinberg.de">Meinberg clocks</A>
<p>These implementations are verified by the Meinberg people themselves
and i have access to one of these clocks.</UL>
</UL>
The pictures below refer to the respective clock and where taken from
the vendors web pages. They are linked to the respective vendors.
<UL>
<LI>
<B><TT>server 127.127.8.0-3 mode 0</TT></B>
<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A>PZF535/<A
HREF="http://www.meinberg.de/english/products/pzf509.htm">PZF509 receiver</A> (FM
demodulation/TCXO / 50us)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 1</TT></B>
<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> PZF535/<A
HREF="http://www.meinberg.de/english/products/pzf509.htm">PZF509
receiver</A> (FM demodulation/OCXO / 50us)</TT></B>
<BR><A HREF="http://www.meinberg.de/english/products/pzf509.htm"><IMG
SRC="pic/pzf509.jpg" ALT="BILD PZF509" HEIGHT=300 WIDTH=260
ALIGN=TEXTTOP></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 2</TT></B>
<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> DCF U/A
31/<A HREF="http://www.meinberg.de/english/products/c51.htm">DCF C51 receiver</A>
(AM demodulation / 4ms)</TT></B>
<BR><A HREF="http://www.meinberg.de/english/products/c51.htm"><IMG
SRC="pic/c51.jpg" ALT="BILD C51" HEIGHT=180 WIDTH=330 ALIGN=TEXTTOP></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 3</TT></B>
<p><B><TT><A HREF="http://www.elv.de">ELV</A> DCF7000 (sloppy AM
demodulation
/ 50ms)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 4</TT></B>
<p><B><TT>Walter Schmid DCF receiver Kit (AM demodulation /
1ms)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 5</TT></B>
<p><B><TT>RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module /
5ms)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 6</TT></B>
<p><B><TT>RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module
/ 5ms)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 7</TT></B>
<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> <A
HREF="http://www.meinberg.de/english/products/gps167.htm">GPS166/GPS167
receiver</A> (GPS / &lt;&lt;1us)</TT></B>
<BR><A HREF="http://www.meinberg.de/english/products/gps167.htm"><IMG
SRC="pic/gps167.jpg" ALT="BILD GPS167" HEIGHT=300 WIDTH=280
ALIGN=TEXTTOP></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 8</TT></B>
<p><B><TT><A HREF="http://www.igel.de">IGEL</A> <A
HREF="http://www.igel.de/eigelmn.htm">clock</A></TT></B>
<BR><A HREF="http://www.igel.de/eigelmn.htm"><IMG SRC="pic/igclock.gif"
HEIGHT=174 WIDTH=200></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 9</TT></B>
<p><B><TT><A HREF="http://www.trimble.com">Trimble</A> <A
HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm">SVeeSix
GPS receiver</A>TAIP protocol (GPS / &lt;&lt;1us)</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 10</TT></B>
<p><B><TT><A HREF="http://www.trimble.com">Trimble</A> <A
HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm">SVeeSix
GPS receiver</A> TSIP protocol (GPS / &lt;&lt;1us) (no kernel support
yet)</TT></B>
<BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm"><IMG
SRC="pic/pd_om011.gif" ALT="SVeeSix-CM3" BORDER=0 HEIGHT=100 WIDTH=420
ALIGN=TEXTTOP></A>
<BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om006.htm"><IMG
SRC="pic/pd_om006.gif" ALT="Lassen-SK8" BORDER=0 HEIGHT=100
WIDTH=420></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 11</TT></B>
<p><B><TT>Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master
Clock
support </TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 12</TT></B>
<p><B><TT><A HREF="http://www.hopf-time.com">HOPF</A> <A
HREF="http://www.hopf-time.com/kart6021.htm">Funkuhr
6021</A></TT></B>
<BR><A HREF="http://www.hopf-time.com/engl/kart6021.htm"><IMG
SRC="pic/fg6021.gif" ALT="DCF77-Interface Board" HEIGHT=207 WIDTH=238
ALIGN=TEXTTOP></A>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 13</TT></B>
<p><B><TT>Diem's Computime Radio Clock</TT></B>
<BR>
<LI>
<B><TT>server 127.127.8.0-3 mode 14</TT></B>
<p><B><TT>RAWDCF receiver (DTR=high/RTS=low)</TT></B>
<LI>
<B><TT>server 127.127.8.0-3 mode 15</TT></B>
<p><B><TT>WHARTON 400A Series Clocks with a 404.2 Serial
Interface</TT></B>
<LI>
<B><TT>server 127.127.8.0-3 mode 16</TT></B>
<p><B><TT>RAWDCF receiver (DTR=low/RTS=high)
</TT></B>
<LI>
<B><TT>server 127.127.8.0-3 mode 17</TT></B>
<p><B><TT>VARITEXT Receiver (MSF)
</TT></B>
</UL>
<p>
Actual data formats and set-up requirements of the various clocks can be
found in <A HREF="parsedata.htm">NTP PARSE clock data formats</A>.
<P>The reference clock support carefully monitors the state transitions
of the receiver. All state changes and exceptional events such as loss
of time code transmission are logged via the syslog facility. Every hour
a summary of the accumulated times for the clock states is listed via
syslog.
<P>PPS support is only available when the receiver is completely
synchronized. The receiver is believed to deliver correct time for an
additional period of time after losing synchronizations, unless a
disruption in time code transmission is detected (possible power loss).
The trust period is dependent on the receiver oscillator and thus a
function of clock type. This is one of the parameters in the clockinfo
field of the reference clock implementation. This parameter cannot be
configured by ntpdc.
<P>In addition to the PPS loopfilter control a true PPS hardware signal
can be applied on Sun Sparc stations via the CPU serial ports on the CD
pin. This signal is automatically detected and will be used for offset
calculation. The input signal must be the time mark for the following
time code. (The edge sensitivity can be selected - look into the
appropriate kernel/parsestreams.c for details). Meinberg receivers can
be connected by feeding the PPS pulse of the receiver via a 1488 level
converter to Pin 8 (CD) of a Sun serial zs-port. To select PPS support
the STREAMS driver for PARSE must be loaded and the mode parameter ist
the mode value of above plus 128. If 128 is not added to the mode value
PPS will be detected to be available but it will not be used. For PPS to
be used you MUST add 128 to the mode parameter.
<P>For the Meinberg GPS166/GPS167 receiver is also a special firmware
release available (Uni-Erlangen). This release should be used for proper
operation.
<P>The raw DCF77 pulses can be fed via a level converter directly into
Pin 3 (Rx) of the Sun. The telegrams will be decoded an used for
synchronization. AM DCF77 receivers are running as low as $25. The
accuracy is dependent on the receiver and is somewhere between 2ms
(expensive) to 10ms (cheap). Upon bad signal reception of DCF77
synchronizations will cease as no backup oscillator is available as
usually found in other reference clock receivers. So it is important to
have a good place for the DCF77 antenna. For transmitter shutdowns you
are out of luck unless you have other NTP servers with alternate time
sources available.
<H4>Monitor Data</H4>
Clock states statistics are written hourly the the syslog service.
Online information can be found by examining the clock variable via the
ntpq cv command.
<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 depending on clock type.</DD>
<DT><TT>time2 <I>time</I></TT></DT>
<DD>Specifies the offset if the PPS signal to the actual time. (PPS fine
tuning).</DD>
<DT><TT>stratum <I>number</I></TT></DT>
<DD>Specifies the driver stratum, in decimal from 0 to 15, with default
0.</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 according to current clock type.</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>delete next leap second instead of adding it.</DD>
<DT>
<TT>flag4 0 | 1</TT></DT>
<DD>Delete next leap second instead of adding it - flag will be re-
defined soon - so don't use it. Statistics are provided by more common
means (syslog, clock variable via ntpq)</DD>
</DL>
<H4>Making your own PARSE clocks</H4>
The parse clock mechanismis deviated from the way other ntp reference
clocks work. For a short description how to build parse reference clocks
see <A HREF="parsenew.htm">making PARSE clocks</A>
<P>Additional Information
<P><A HREF="refclock.htm">Reference Clock Drivers</A>
<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
href="mailto:mills@udel.edu"> David L. Mills &lt;mills@udel.edu&gt;</a>
</address></body></html>