contrib/ntp/html/driver8.htm

   1 <HTML><HEAD><TITLE>
   2 Generic Reference Driver
   3 </TITLE></HEAD><BODY><H3>
   4 Generic Reference Driver
   5 </H3><HR>
   6
   7 <H4>Synopsis</H4>
   8
   9 Address: 127.127.8.<I>u</I>
  10 <BR>Reference ID: <TT>PARSE</TT>
  11 <BR>Driver ID: <TT>GENERIC</TT>
  12 <BR>Serial Port: <TT>/dev/refclock-<I>u</I></TT>; TTY mode according to
  13 clock type
  14
  15 <H4>Description</H4>
  16
  17 The timecode of these receivers is sampled via a STREAMS module in the
  18 kernel (The STREAMS module has been designed for use with SUN Systems
  19 under SunOS 4.1.x or Solaris 2.3 - 2.6. It can be linked directly into
  20 the kernel or loaded via the loadable driver mechanism). This STREAMS
  21 module can be adapted to be able to convert different time code formats.
  22 If the daemon is compiled without the STREAM definition synchronization
  23 will work without the Sun streams module, though accuracy is
  24 significantly degraded. This feature allows to use PARSE also on non Sun
  25 machines.
  26
  27 <P>The actual receiver status is mapped into various synchronization
  28 states generally used by receivers. The STREAMS module is configured to
  29 interpret the time codes of DCF C51, PZF535, PZF509, GPS166, Trimble SV6
  30 GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see list
  31 below).
  32
  33 <P>The reference clock support in ntp contains the necessary
  34 configuration tables for those receivers. In addition to supporting
  35 several different clock types and 4 devices, the generation a a PPS
  36 signal is also provided as an configuration option. The PPS
  37 configuration option uses the receiver generated time stamps for feeding
  38 the PPS loopfilter control for much finer clock synchronization.
  39
  40 <P>CAUTION: The PPS configuration option is different from the hardware
  41 PPS signal, which is also supported (see below), as it controls the way
  42 ntpd is synchronized to the reference clock, while the hardware PPS
  43 signal controls the way time offsets are determined.
  44
  45 <P>The use of the PPS option requires receivers with an accuracy of
  46 better than 1ms.
  47
  48 <P>Fudge factors
  49
  50 <P>Only two fudge factors are utilized. The time1 fudge factor defines
  51 the phase offset of the synchronization character to the actual time. On
  52 the availability of PPS information the time2 fudge factor defines the
  53 skew between the PPS time stamp and the receiver timestamp of the PPS
  54 signal. This parameter is usually zero, as usually the PPS signal is
  55 believed in time and OS delays should be corrected in the machine
  56 specific section of the kernel driver. time2 needs only be set when the
  57 actual PPS signal is delayed for some reason. The flag1 enables input
  58 filtering. This a median filter with continuous sampling. The flag2
  59 selects averaging of the samples remaining after the filtering. Leap
  60 second-handling is controlled with the flag3. When set a leap second
  61 will be deleted on receipt of a leap second indication from the
  62 receiver. Otherwise the leap second will be added, (which is the
  63 default). flag3 should never be set. PPS handling is enabled by adding
  64 128 to the mode parameter in the server/peer command.
  65
  66 <P>ntpq (8)
  67 <P>timecode variable
  68
  69 <P>The ntpq program can read clock variables command list several
  70 variables.
  71 These hold the following information: refclock_time is the local time
  72 with
  73 the offset to UTC (format HHMM). The currently active receiver flags are
  74 listed in refclock_status. Additional feature flags of the receiver are
  75 optionally listed in parentheses. The actual time code is listed in
  76 timecode.
  77 A qualification of the decoded time code format is following in
  78 refclock_format. The last piece of information is the overall running
  79 time and the accumulated times for the clock event states in
  80 refclock_states. When PPS information is present additional variable are
  81 available. refclock_ppstime lists then the PPS timestamp and
  82 refclock_ppsskew lists the difference between RS232
  83 derived timestamp and the PPS timestamp.
  84
  85 <P>Currently, eighteen clock types (devices /dev/refclock-0 -
  86 /dev/refclock-3) are supported by the PARSE driver.
  87 <BR>A note on the implementations:
  88 <UL><li>These implementations where mainly done <B><I>WITHOUT</I></B>
  89 actual access to the hardware. Thus not all implementations provide full
  90 support. The development was done with the help of many souls who had
  91 the hardware and where so kind to borrow me their time an patience
  92 during the development and debugging cycle. Thus for continued support
  93 and quality direct access to the receivers is a big help. Nevertheless i
  94 am not prepared to buy these reference clocks - donations to <A
  95 HREF="http://www4.informatik.uni-erlangen.de/~kardel">me</A>
  96 (<A HREF="mailto: kardel@acm.org">kardel@acm.org</A>) are welcome as
  97 long as they work within Europe 8-).
  98
  99 <P>Verified implementations are:
 100 <UL>
 101 <LI>
 102 RAWDCF variants
 103
 104 <p>These variants are tested for the decoding with my own homegrown
 105 receivers. Interfacing with specific commercial products may involve
 106 some fiddeling with cables. Especially commericial RAWDCF receivers have
 107 a seemingly unlimited number of ways to draw power from the RS232 port
 108 and to encode the DCF77 datastream. You are mainly on your own here
 109 unless i have a sample of the receiver.
 110 <LI>
 111 <A HREF="http://www.meinberg.de">Meinberg  clocks</A>
 112
 113 <p>These implementations are verified by the Meinberg people themselves
 114 and i have access to one of these clocks.</UL>
 115 </UL>
 116 The pictures below refer to the respective clock and where taken from
 117 the vendors web pages. They are linked to the respective vendors.
 118 <UL>
 119 <LI>
 120 <B><TT>server 127.127.8.0-3 mode 0</TT></B>
 121
 122 <p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A>PZF535/<A
 123 HREF="http://www.meinberg.de/english/products/pzf509.htm">PZF509 receiver</A> (FM
 124 demodulation/TCXO / 50us)</TT></B>
 125 <BR>
 126 <LI>
 127 <B><TT>server 127.127.8.0-3 mode 1</TT></B>
 128
 129 <p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> PZF535/<A
 130 HREF="http://www.meinberg.de/english/products/pzf509.htm">PZF509
 131 receiver</A> (FM demodulation/OCXO / 50us)</TT></B>
 132 <BR><A HREF="http://www.meinberg.de/english/products/pzf509.htm"><IMG
 133 SRC="pic/pzf509.jpg" ALT="BILD PZF509" HEIGHT=300 WIDTH=260
 134 ALIGN=TEXTTOP></A>
 135 <BR>
 136 <LI>
 137 <B><TT>server 127.127.8.0-3 mode 2</TT></B>
 138
 139 <p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> DCF U/A
 140 31/<A HREF="http://www.meinberg.de/english/products/c51.htm">DCF C51 receiver</A>
 141 (AM demodulation / 4ms)</TT></B>
 142 <BR><A HREF="http://www.meinberg.de/english/products/c51.htm"><IMG
 143 SRC="pic/c51.jpg" ALT="BILD C51" HEIGHT=180 WIDTH=330 ALIGN=TEXTTOP></A>
 144 <BR>
 145 <LI>
 146 <B><TT>server 127.127.8.0-3 mode 3</TT></B>
 147
 148 <p><B><TT><A HREF="http://www.elv.de">ELV</A> DCF7000 (sloppy AM
 149 demodulation
 150 / 50ms)</TT></B>
 151 <BR>
 152 <LI>
 153 <B><TT>server 127.127.8.0-3 mode 4</TT></B>
 154
 155 <p><B><TT>Walter Schmid DCF receiver Kit (AM demodulation /
 156 1ms)</TT></B>
 157 <BR>
 158 <LI>
 159 <B><TT>server 127.127.8.0-3 mode 5</TT></B>
 160
 161 <p><B><TT>RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module /
 162 5ms)</TT></B>
 163 <BR>
 164 <LI>
 165 <B><TT>server 127.127.8.0-3 mode 6</TT></B>
 166
 167 <p><B><TT>RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module
 168 / 5ms)</TT></B>
 169 <BR>
 170 <LI>
 171 <B><TT>server 127.127.8.0-3 mode 7</TT></B>
 172
 173 <p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> <A
 174 HREF="http://www.meinberg.de/english/products/gps167.htm">GPS166/GPS167
 175 receiver</A> (GPS / &lt;&lt;1us)</TT></B>
 176 <BR><A HREF="http://www.meinberg.de/english/products/gps167.htm"><IMG
 177 SRC="pic/gps167.jpg" ALT="BILD GPS167" HEIGHT=300 WIDTH=280
 178 ALIGN=TEXTTOP></A>
 179 <BR>
 180 <LI>
 181 <B><TT>server 127.127.8.0-3 mode 8</TT></B>
 182 <p><B><TT><A HREF="http://www.igel.de">IGEL</A> <A
 183 HREF="http://www.igel.de/eigelmn.htm">clock</A></TT></B>
 184 <BR><A HREF="http://www.igel.de/eigelmn.htm"><IMG SRC="pic/igclock.gif"
 185 HEIGHT=174 WIDTH=200></A>
 186 <BR>
 187 <LI>
 188 <B><TT>server 127.127.8.0-3 mode 9</TT></B>
 189
 190 <p><B><TT><A HREF="http://www.trimble.com">Trimble</A> <A
 191 HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm">SVeeSix
 192 GPS receiver</A>TAIP protocol (GPS / &lt;&lt;1us)</TT></B>
 193 <BR>
 194 <LI>
 195 <B><TT>server 127.127.8.0-3 mode 10</TT></B>
 196
 197 <p><B><TT><A HREF="http://www.trimble.com">Trimble</A> <A
 198 HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm">SVeeSix
 199 GPS receiver</A> TSIP protocol (GPS / &lt;&lt;1us) (no kernel support
 200 yet)</TT></B>
 201 <BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm"><IMG
 202 SRC="pic/pd_om011.gif" ALT="SVeeSix-CM3" BORDER=0 HEIGHT=100 WIDTH=420
 203 ALIGN=TEXTTOP></A>
 204 <BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om006.htm"><IMG
 205 SRC="pic/pd_om006.gif" ALT="Lassen-SK8" BORDER=0 HEIGHT=100
 206 WIDTH=420></A>
 207 <BR>
 208 <LI>
 209 <B><TT>server 127.127.8.0-3 mode 11</TT></B>
 210
 211 <p><B><TT>Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master
 212 Clock
 213 support </TT></B>
 214 <BR>
 215 <LI>
 216 <B><TT>server 127.127.8.0-3 mode 12</TT></B>
 217
 218 <p><B><TT><A HREF="http://www.hopf-time.com">HOPF</A> <A
 219 HREF="http://www.hopf-time.com/kart6021.htm">Funkuhr
 220 6021</A></TT></B>
 221 <BR><A HREF="http://www.hopf-time.com/engl/kart6021.htm"><IMG
 222 SRC="pic/fg6021.gif" ALT="DCF77-Interface Board" HEIGHT=207 WIDTH=238
 223 ALIGN=TEXTTOP></A>
 224 <BR>
 225 <LI>
 226 <B><TT>server 127.127.8.0-3 mode 13</TT></B>
 227
 228 <p><B><TT>Diem's Computime Radio Clock</TT></B>
 229 <BR>
 230 <LI>
 231 <B><TT>server 127.127.8.0-3 mode 14</TT></B>
 232
 233 <p><B><TT>RAWDCF receiver (DTR=high/RTS=low)</TT></B>
 234
 235 <LI>
 236 <B><TT>server 127.127.8.0-3 mode 15</TT></B>
 237
 238 <p><B><TT>WHARTON 400A Series Clocks with a 404.2 Serial
 239 Interface</TT></B>
 240 <LI>
 241 <B><TT>server 127.127.8.0-3 mode 16</TT></B>
 242
 243 <p><B><TT>RAWDCF receiver (DTR=low/RTS=high)
 244 </TT></B>
 245 <LI>
 246 <B><TT>server 127.127.8.0-3 mode 17</TT></B>
 247
 248 <p><B><TT>VARITEXT Receiver (MSF)
 249 </TT></B>
 250 </UL>
 251 <p>
 252 Actual data formats and set-up requirements of the various clocks can be
 253 found in <A HREF="parsedata.htm">NTP PARSE clock data formats</A>.
 254
 255 <P>The reference clock support carefully monitors the state transitions
 256 of the receiver. All state changes and exceptional events such as loss
 257 of time code transmission are logged via the syslog facility. Every hour
 258 a summary of the accumulated times for the clock states is listed via
 259 syslog.
 260
 261 <P>PPS support is only available when the receiver is completely
 262 synchronized. The receiver is believed to deliver correct time for an
 263 additional period of time after losing synchronizations, unless a
 264 disruption in time code transmission is detected (possible power loss).
 265 The trust period is dependent on the receiver oscillator and thus a
 266 function of clock type. This is one of the parameters in the clockinfo
 267 field of the reference clock implementation. This parameter cannot be
 268 configured by ntpdc.
 269
 270 <P>In addition to the PPS loopfilter control a true PPS hardware signal
 271 can be applied on Sun Sparc stations via the CPU serial ports on the CD
 272 pin. This signal is automatically detected and will be used for offset
 273 calculation. The input signal must be the time mark for the following
 274 time code. (The edge sensitivity can be selected - look into the
 275 appropriate kernel/parsestreams.c for details). Meinberg receivers can
 276 be connected by feeding the PPS pulse of the receiver via a 1488 level
 277 converter to Pin 8 (CD) of a Sun serial zs-port. To select PPS support
 278 the STREAMS driver for PARSE must be loaded and the mode parameter ist
 279 the mode value of above plus 128. If 128 is not added to the mode value
 280 PPS will be detected to be available but it will not be used. For PPS to
 281 be used you MUST add 128 to the mode parameter.
 282
 283 <P>For the Meinberg GPS166/GPS167 receiver is also a special firmware
 284 release available (Uni-Erlangen). This release should be used for proper
 285 operation.
 286
 287 <P>The raw DCF77 pulses can be fed via a level converter directly into
 288 Pin 3 (Rx) of the Sun. The telegrams will be decoded an used for
 289 synchronization. AM DCF77 receivers are running as low as $25. The
 290 accuracy is dependent on the receiver and is somewhere between 2ms
 291 (expensive) to 10ms (cheap). Upon bad signal reception of DCF77
 292 synchronizations will cease as no backup oscillator is available as
 293 usually found in other reference clock receivers. So it is important to
 294 have a good place for the DCF77 antenna. For transmitter shutdowns you
 295 are out of luck unless you have other NTP servers with alternate time
 296 sources available.
 297
 298 <H4>Monitor Data</H4>
 299
 300 Clock states statistics are written hourly the the syslog service.
 301 Online information can be found by examining the clock variable via the
 302 ntpq cv command.
 303
 304 <H4>Fudge Factors</H4>
 305
 306 <DL>
 307
 308 <DT><TT>time1 <I>time</I></TT></DT>
 309 <DD>Specifies the time offset calibration factor, in seconds and
 310 fraction, with default depending on clock type.</DD>
 311
 312 <DT><TT>time2 <I>time</I></TT></DT>
 313 <DD>Specifies the offset if the PPS signal to the actual time. (PPS fine
 314 tuning).</DD>
 315
 316 <DT><TT>stratum <I>number</I></TT></DT>
 317 <DD>Specifies the driver stratum, in decimal from 0 to 15, with default
 318 0.</DD>
 319
 320 <DT><TT>refid <I>string</I></TT></DT>
 321 <DD>Specifies the driver reference identifier, an ASCII string from one
 322 to four characters, with default according to current clock type.</DD>
 323
 324 <DT><TT>flag1 0 | 1</TT></DT>
 325 <DD>Not used by this driver.</DD>
 326
 327 <DT><TT>flag2 0 | 1</TT></DT>
 328 <DD>Not used by this driver.</DD>
 329
 330 <DT><TT>flag3 0 | 1</TT></DT>
 331 <DD>delete next leap second instead of adding it.</DD>
 332
 333 <DT>
 334 <TT>flag4 0 | 1</TT></DT>
 335 <DD>Delete next leap second instead of adding it - flag will be re-
 336 defined soon - so don't use it. Statistics are provided by more common
 337 means (syslog, clock variable via ntpq)</DD>
 338
 339 </DL>
 340
 341 <H4>Making your own PARSE clocks</H4>
 342
 343 The parse clock mechanismis deviated from the way other ntp reference
 344 clocks work. For a short description how to build parse reference clocks
 345 see <A HREF="parsenew.htm">making PARSE clocks</A>
 346
 347 <P>Additional Information
 348
 349 <P><A HREF="refclock.htm">Reference Clock Drivers</A>
 350
 351 <hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
 352 href="mailto:mills@udel.edu"> David L. Mills &lt;mills@udel.edu&gt;</a>
 353 </address></body></html>